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

Artigo
08/08/2023

A função de retorno de chamada de evento WskAcceptEvent notifica um aplicativo WSK de que uma conexão de entrada em um soquete de escuta foi aceita.

Sintaxe

PFN_WSK_ACCEPT_EVENT PfnWskAcceptEvent;

NTSTATUS PfnWskAcceptEvent(
  [in, optional] PVOID SocketContext,
  [in]           ULONG Flags,
  [in]           PSOCKADDR LocalAddress,
  [in]           PSOCKADDR RemoteAddress,
  [in, optional] PWSK_SOCKET AcceptSocket,
  [out]          PVOID *AcceptSocketContext,
  [out]          const WSK_CLIENT_CONNECTION_DISPATCH **AcceptSocketDispatch
)
{...}

Parâmetros

[in, optional] SocketContext

Um ponteiro para o contexto de soquete para o soquete de escuta no qual a conexão de entrada foi aceita. O aplicativo WSK forneceu esse ponteiro para o subsistema WSK quando chamou a função WskSocket para criar o soquete de escuta.

[in] Flags

Um valor ULONG que contém o seguinte sinalizador ou zero:

WSK_FLAG_AT_DISPATCH_LEVEL

O subsistema WSK chamou a função de retorno de chamada de evento WskAcceptEvent em IRQL = DISPATCH_LEVEL. Se esse sinalizador não estiver definido, o subsistema WSK poderá ter chamado a função de retorno de chamada de evento WskAcceptEvent em qualquer IRQL <= DISPATCH_LEVEL.

[in] LocalAddress

Um ponteiro para um buffer que contém o endereço de transporte local no qual a conexão de entrada chegou. O buffer contém o tipo de estrutura SOCKADDR específico que corresponde à família de endereços que o aplicativo WSK especificou quando criou o soquete de escuta.

[in] RemoteAddress

Um ponteiro para um buffer que contém o endereço de transporte remoto do qual a conexão de entrada se originou. O buffer contém o tipo de estrutura SOCKADDR específico que corresponde à família de endereços que o aplicativo WSK especificou quando criou o soquete de escuta.

[in, optional] AcceptSocket

Um ponteiro para uma estrutura WSK_SOCKET que é o objeto de soquete para o soquete aceito. Se esse ponteiro for NULL, o soquete de escuta não será mais funcional e o aplicativo WSK deverá chamar a função WskCloseSocket para fechar o soquete de escuta o mais rápido possível.

[out] AcceptSocketContext

Um ponteiro para uma variável que recebe um ponteiro para um contexto fornecido pelo aplicativo WSK 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 WSK e 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, o aplicativo deverá definir a variável apontada pelo parâmetro AcceptSocketContext como NULL.

[out] AcceptSocketDispatch

Um ponteiro para uma variável que recebe 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, o aplicativo 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 a variável apontada pelo parâmetro AcceptSocketDispatch como NULL.

Retornar valor

A função de retorno de chamada de evento WskAcceptEvent de um aplicativo WSK pode retornar um dos seguintes códigos NTSTATUS:

Código de retorno	Descrição
STATUS_SUCCESS	O aplicativo WSK aceitou a conexão de entrada.
STATUS_REQUEST_NOT_ACCEPTED	O aplicativo WSK rejeitou a conexão de entrada. Se esse valor for retornado, o subsistema WSK fechará o soquete aceito em nome do aplicativo WSK.

Comentários

O subsistema WSK chama a função de retorno de chamada de evento WskAcceptEvent de um aplicativo WSK quando uma conexão de entrada é aceita no soquete de escuta somente se a função de retorno de chamada de evento foi habilitada anteriormente com a opção de soquete SO_WSK_EVENT_CALLBACK . Para obter mais informações sobre como habilitar as funções de retorno de chamada de evento de um soquete, consulte Habilitando e desabilitando funções de retorno de chamada de evento.

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 chama a função de retorno de chamada de evento WskAcceptEvent do aplicativo somente se não houver NENHUM IRPs na fila de chamadas pendentes para a função 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 o subsistema WSK chama a função de retorno de chamada de evento WskAcceptEvent de um aplicativo WSK, todas as funções de retorno de chamada de evento no soquete aceito são desabilitadas por padrão. Se um aplicativo WSK habilitar qualquer uma das funções de retorno de chamada de evento de soquete orientado à conexão em um soquete de escuta, essas funções de retorno de chamada de evento serão habilitadas por padrão em todos os soquetes orientados à conexão aceitos nesse soquete de escuta. 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.

As estruturas SOCKADDR que são apontadas pelos parâmetros LocalAddress e RemoteAddress são válidas apenas durante a chamada para a função de retorno de chamada de evento WskAcceptEvent . Se um aplicativo WSK precisar desses endereços de transporte posteriormente, ele poderá copiar o conteúdo dessas estruturas para suas próprias estruturas SOCKADDR antes de retornar da função de retorno de chamada de evento WskAcceptEvent ou, posteriormente, chamar as funções WskGetLocalAddress e WskGetRemoteAddress no soquete aceito.

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.

O subsistema WSK chama a função de retorno de chamada de evento WskAcceptEvent de um aplicativo WSK em IRQL <= DISPATCH_LEVEL.

A função de retorno de chamada de evento WskAcceptEvent de um aplicativo WSK não deve aguardar a conclusão de outras solicitações do WSK no contexto de funções de conclusão do WSK ou retorno de chamada de evento. O retorno de chamada pode iniciar outras solicitações do WSK (supondo que não gaste muito tempo no DISPATCH_LEVEL), mas não deve aguardar a conclusão, mesmo quando o retorno de chamada é chamado em IRQL = PASSIVE_LEVEL.

Requisitos

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