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

Artigo
08/08/2023

A função de retorno de chamada de evento WskReceiveEvent notifica um aplicativo WSK de que os dados foram recebidos em um soquete orientado à conexão.

Sintaxe

PFN_WSK_RECEIVE_EVENT PfnWskReceiveEvent;

NTSTATUS PfnWskReceiveEvent(
  [in, optional] PVOID SocketContext,
  [in]           ULONG Flags,
  [in, optional] PWSK_DATA_INDICATION DataIndication,
  [in]           SIZE_T BytesIndicated,
  [in, out]      SIZE_T *BytesAccepted
)
{...}

Parâmetros

[in, optional] SocketContext

Um ponteiro para o contexto de soquete para o soquete orientado à conexão que recebeu os dados. O aplicativo WSK forneceu esse ponteiro para o subsistema WSK de uma das seguintes maneiras:

Ele chamou a função WskSocket para criar o soquete.
Ele chamou a função WskSocketConnect para criar o soquete.
Ele chamou a função WskAccept para aceitar o soquete como uma conexão de entrada.
Sua função de retorno de chamada de evento WskAcceptEvent foi chamada para aceitar o soquete como uma conexão de entrada.

[in] Flags

Um valor ULONG que contém um OR bit a bit de uma combinação dos seguintes sinalizadores:

Valor	Significado
WSK_FLAG_RELEASE_ASAP	Os buffers de dados que contêm os dados recebidos não devem ser retidos pelo aplicativo WSK, se possível. Se o aplicativo WSK reter os buffers, ele deverá liberá-los assim que possível chamando a função WskRelease .
WSK_FLAG_ENTIRE_MESSAGE	Os buffers de dados contêm uma mensagem inteira ou a parte final de uma mensagem. A interpretação do que constitui uma mensagem inteira é específica do protocolo de transporte. Para TCP, esse sinalizador indica que o bit de push foi definido para um ou mais segmentos TCP que constituem os dados nos buffers de dados.
WSK_FLAG_AT_DISPATCH_LEVEL	O subsistema WSK chamou a função de retorno de chamada de evento WskReceiveEvent 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 WskReceiveEvent em qualquer

[in, optional] DataIndication

Um ponteiro para uma lista vinculada de estruturas de WSK_DATA_INDICATION que descrevem os dados recebidos. Se esse parâmetro for NULL, o soquete não estará mais funcional e o aplicativo WSK deverá chamar a função WskCloseSocket para fechar o soquete o mais rápido possível.

[in] BytesIndicated

O número de bytes de dados recebidos descritos pela lista vinculada de estruturas de WSK_DATA_INDICATION .

[in, out] BytesAccepted

Um ponteiro para uma variável do tipo SIZE_T que recebe o número de bytes de dados recebidos que é aceito pelo aplicativo WSK. Essa variável só precisará ser definida se o aplicativo WSK aceitar uma parte do número total de bytes de dados recebidos. Se o aplicativo WSK aceitar todos os dados recebidos, ele não precisará definir essa variável. Se a função de retorno de chamada de evento WskReceiveEvent retornar um status diferente de STATUS_SUCCESS, o subsistema WSK ignorará o valor dessa variável.

Retornar valor

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

Código de retorno	Descrição
STATUS_SUCCESS	O aplicativo WSK aceitou pelo menos alguns dos dados recebidos. Se o aplicativo WSK aceitou todos os dados recebidos, o subsistema WSK poderá chamar a função de retorno de chamada de evento WskReceiveEvent novamente quando novos dados forem recebidos no soquete. No entanto, se o aplicativo WSK aceitou apenas uma parte dos dados recebidos, o subsistema WSK não chamará a função de retorno de chamada de evento WskReceiveEvent novamente até que o aplicativo WSK chame a função WskReceive . Depois que o aplicativo WSK chamar a função WskReceive , o subsistema WSK retomará a chamada da função de retorno de chamada de evento WskReceiveEvent com quaisquer dados armazenados em buffer restantes e quando novos dados forem recebidos no soquete. Um aplicativo WSK pode chamar a função WskReceive com um buffer de comprimento zero, o que fará com que o subsistema WSK retome a chamada à função de retorno de chamada de evento WskReceiveEvent sem chamar WskReceive para receber dados do soquete.
STATUS_PENDING	O aplicativo WSK aceitou os dados, mas não recuperou todos os dados contidos na lista vinculada de estruturas de WSK_DATA_INDICATION . O aplicativo WSK mantém a lista vinculada de estruturas de WSK_DATA_INDICATION até que todos os dados sejam recuperados. Depois que o aplicativo WSK tiver recuperado todos os dados, ele chamará a função WskRelease para liberar a lista vinculada de estruturas de WSK_DATA_INDICATION de volta para o subsistema WSK. O subsistema WSK pode chamar a função de retorno de chamada de evento WskReceiveEvent novamente quando novos dados são recebidos no soquete.
STATUS_DATA_NOT_ACCEPTED	O aplicativo WSK não aceitou os dados. Nessa situação, o subsistema WSK terá o buffer de transporte subjacente dos dados, se possível ou, se necessário, pelo protocolo. O subsistema WSK não chamará a função de retorno de chamada de evento WskReceiveEvent novamente até que o aplicativo WSK chame a função WskReceive . Depois que o aplicativo WSK chamar a função WskReceive , o subsistema WSK retomará a chamada da função de retorno de chamada de evento WskReceiveEvent com quaisquer dados armazenados em buffer restantes e quando novos dados forem recebidos no soquete. Um aplicativo WSK pode chamar a função WskReceive com um buffer de comprimento zero, o que fará com que o subsistema WSK retome a chamada à função de retorno de chamada de evento WskReceiveEvent sem chamar WskReceive para receber dados do soquete.

Comentários

O subsistema WSK chama a função de retorno de chamada de evento WskReceiveEvent de um aplicativo WSK quando novos dados são recebidos em um soquete orientado à conexão somente se a função de retorno de chamada de evento tiver sido 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 WskReceiveEvent de um aplicativo WSK estiver habilitada em um soquete orientado à conexão e o aplicativo também tiver uma chamada pendente para a função WskReceive no mesmo soquete orientado à conexão, então, quando os dados chegarem, a chamada pendente para a função WskReceive terá precedência sobre a função de retorno de chamada de evento WskReceiveEvent . O subsistema WSK chamará a função de retorno de chamada de evento WskReceiveEvent do aplicativo somente se não houver NENHUM IRPs na fila de chamadas pendentes para a função WskReceive . 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 WskReceiveEvent do aplicativo para um soquete orientado a conexão que tenha uma chamada pendente para a função WskReceive . Existem condições de corrida em que o subsistema WSK ainda pode chamar a função de retorno de chamada de evento WskReceiveEvent 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 WskReceiveEvent do aplicativo para um soquete orientado a conexão é desabilitar a função de retorno de chamada de evento WskReceiveEvent do aplicativo no soquete.

Observação

O WSK (Winsock Kernel) chama esse retorno de chamada em série, portanto, nem sempre é invocado assim que os dados são recebidos.

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

A função de retorno de chamada de evento WskReceiveEvent 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