PFN_WSK_ACCEPT função de retorno de chamada (wsk.h)

Artigo
08/08/2023

A função WskAccept aceita uma conexão de entrada em um soquete de escuta.

Sintaxe

PFN_WSK_ACCEPT PfnWskAccept;

NTSTATUS PfnWskAccept(
  [in]            PWSK_SOCKET ListenSocket,
                  ULONG Flags,
  [in, optional]  PVOID AcceptSocketContext,
  [in, optional]  const WSK_CLIENT_CONNECTION_DISPATCH *AcceptSocketDispatch,
  [out, optional] PSOCKADDR LocalAddress,
  [out, optional] PSOCKADDR RemoteAddress,
  [in, out]       PIRP Irp
)
{...}

Parâmetros

[in] ListenSocket

Um ponteiro para uma estrutura WSK_SOCKET que especifica o objeto de soquete para o soquete de escuta ou fluxo que está sendo verificado para uma conexão de entrada.

Flags

Esse parâmetro é reservado para uso do sistema. Um aplicativo WSK deve definir esse parâmetro como zero.

[in, optional] AcceptSocketContext

Um ponteiro para um contexto fornecido pelo chamador para o soquete que está sendo aceito. O subsistema WSK passa esse ponteiro para as funções de retorno de chamada de evento do soquete aceito. As informações de contexto são opacas para o subsistema do WSK. As informações de contexto devem ser armazenadas na memória não paginada. Se o aplicativo WSK não estiver habilitando nenhuma função de retorno de chamada de evento no soquete aceito, ele deverá definir esse ponteiro como NULL.

[in, optional] AcceptSocketDispatch

Um ponteiro para uma constante WSK_CLIENT_CONNECTION_DISPATCH estrutura. Essa estrutura é uma tabela de expedição que contém ponteiros para as funções de retorno de chamada de evento para o soquete aceito. Se o aplicativo WSK não estiver habilitando todas as funções de retorno de chamada de evento para o soquete aceito, ele deverá definir os ponteiros na tabela de expedição como NULL para as funções de retorno de chamada de evento que ele não habilita. Se o aplicativo WSK não estiver habilitando nenhuma função de retorno de chamada de evento no soquete aceito, ele deverá definir esse ponteiro como NULL.

[out, optional] LocalAddress

Um ponteiro para um buffer alocado pelo chamador que recebe o endereço de transporte local no qual a conexão de entrada chegou. O buffer deve estar localizado na memória não paginada. O buffer também deve ser grande o suficiente para conter o tipo de estrutura SOCKADDR específico que corresponde à família de endereços especificada pelo aplicativo WSK ao criar o soquete de escuta. Esse ponteiro é opcional e pode ser NULL.

[out, optional] RemoteAddress

Um ponteiro para um buffer alocado pelo chamador que recebe o endereço de transporte remoto do qual a conexão de entrada se originou. O buffer deve estar localizado na memória não paginada. O buffer também deve ser grande o suficiente para conter o tipo de estrutura SOCKADDR específico que corresponde à família de endereços especificada pelo aplicativo WSK ao criar o soquete de escuta. Esse ponteiro é opcional e pode ser NULL.

[in, out] Irp

Um ponteiro para um IRP alocado pelo chamador que o subsistema WSK usa para concluir a operação de aceitação de forma assíncrona. Para obter mais informações sobre como usar IRPs com funções WSK, consulte Usando IRPs com funções de kernel Winsock.

Retornar valor

WskAccept retorna um dos seguintes códigos NTSTATUS:

Código de retorno	Descrição
STATUS_SUCCESS	Uma conexão de entrada foi aceita com êxito. O IRP será concluído com êxito status.
STATUS_PENDING	O IRP foi enfileirado pelo subsistema WSK, que está aguardando uma conexão de entrada no soquete de escuta.
STATUS_FILE_FORCED_CLOSED	O soquete não está mais funcional. O IRP será concluído com falha status. O aplicativo WSK deve chamar a função WskCloseSocket para fechar o soquete o mais rápido possível.
Outros códigos status	Ocorreu um erro. O IRP será concluído com falha status.

Comentários

Um aplicativo WSK pode chamar a função WskAccept em um soquete de escuta ou soquete de fluxo que ele vinculou anteriormente a um endereço de transporte local chamando a função WskBind .

O comportamento da função WskAccept depende se uma conexão de entrada está esperando para ser aceita no soquete de escuta:

Se uma conexão de entrada já tiver chegado ao soquete de escuta e estiver aguardando para ser aceita, a função WskAccept retornará STATUS_SUCCESS. Nessa situação, o IRP é concluído com êxito status e o campo IoStatus.Information do IRP contém um ponteiro para o objeto de soquete do soquete aceito.
Se uma conexão de entrada não estiver esperando para ser aceita no soquete de escuta, WskAccept retornará STATUS_PENDING e o subsistema WSK enfileirará o IRP até que uma conexão de entrada seja recebida. Quando uma conexão de entrada é recebida, o subsistema WSK conclui de forma assíncrona o IRP com êxito status. Nessa situação, o campo IoStatus.Information do IRP contém um ponteiro para o objeto socket do soquete aceito.

Se a função de retorno de chamada de evento WskAcceptEvent de um aplicativo WSK estiver habilitada em um soquete de escuta e o aplicativo tiver uma chamada pendente para a função WskAccept no mesmo soquete de escuta, quando uma conexão de entrada chegar, a chamada pendente para WskAccept terá precedência sobre a função de retorno de chamada de evento WskAcceptEvent . O subsistema WSK chamará a função de retorno de chamada de evento WskAcceptEvent do aplicativo somente se não houver IRPs na fila de chamadas pendentes para WskAccept. No entanto, um aplicativo WSK não deve assumir que o subsistema WSK não chamará a função de retorno de chamada de evento WskAcceptEvent do aplicativo para um soquete de escuta que tenha uma chamada pendente para a função WskAccept . Existem condições de corrida em que o subsistema WSK ainda pode chamar a função de retorno de chamada de evento WskAcceptEvent do aplicativo WSK para o soquete. A única maneira de um aplicativo WSK garantir que o subsistema WSK não chame a função de retorno de chamada de evento WskAcceptEvent do aplicativo para um soquete de escuta é desabilitar a função de retorno de chamada de evento WskAcceptEvent do aplicativo no soquete.

Quando a função WskAccept aceita com êxito uma conexão de entrada, todas as funções de retorno de chamada de evento no soquete aceito são desabilitadas por padrão. Para obter mais informações sobre como habilitar qualquer uma das funções de retorno de chamada de evento do soquete aceito, consulte Habilitando e desabilitando funções de retorno de chamada de evento.

Se um aplicativo WSK especificar um ponteiro não NULL no parâmetro LocalAddress , no parâmetro RemoteAddress ou em ambos os parâmetros, e se WskAccept retornar STATUS_PENDING, os buffers apontados por esses parâmetros deverão permanecer válidos até que o IRP seja concluído. Se o aplicativo WSK alocou os buffers com uma das funções ExAllocateXxx , ele não poderá liberar a memória com a função ExFreeXxx correspondente até que o IRP seja concluído. Se o aplicativo WSK alocou os buffers na pilha, ele não poderá retornar da função que chama a função WskAccept até que o IRP seja concluído.

O subsistema WSK aloca a memória para a estrutura do objeto de soquete ( WSK_SOCKET) para a conexão aceita em nome do aplicativo WSK. O subsistema WSK desaloca essa memória quando o soquete é fechado.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível no Windows Vista e versões posteriores dos sistemas operacionais Windows.
Plataforma de Destino	Universal
Cabeçalho	wsk.h (inclua Wsk.h)
IRQL	<= DISPATCH_LEVEL