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

Artigo
08/08/2023

A função de retorno de chamada de evento WskReceiveFromEvent notifica um aplicativo WSK de que um ou mais datagramas foram recebidos em um soquete de datagrama.

Sintaxe

PFN_WSK_RECEIVE_FROM_EVENT PfnWskReceiveFromEvent;

NTSTATUS PfnWskReceiveFromEvent(
  [in, optional] PVOID SocketContext,
  [in]           ULONG Flags,
  [in, optional] PWSK_DATAGRAM_INDICATION DataIndication
)
{...}

Parâmetros

[in, optional] SocketContext

Um ponteiro para o contexto de soquete para o soquete de datagrama que recebeu os datagrams. O aplicativo WSK forneceu esse ponteiro para o subsistema WSK quando chamou a função WskSocket para criar o soquete de datagram.

[in] Flags

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

MSG_BCAST

Os datagramas foram recebidos como uma transmissão de camada de link ou com um endereço de transporte de destino que é um endereço de transmissão.

MSG_MCAST

Os datagramas foram recebidos com um endereço de transporte de destino que é um endereço multicast.

WSK_FLAG_AT_DISPATCH_LEVEL

O subsistema WSK chamado função de retorno de chamada de evento WskReceiveFromEvent 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 WskReceiveFromEvent em qualquer IRQL <= DISPATCH_LEVEL.

[in, optional] DataIndication

Um ponteiro para uma lista vinculada de estruturas de WSK_DATAGRAM_INDICATION que descrevem os datagramas 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.

Retornar valor

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

Código de retorno	Descrição
STATUS_SUCCESS	O aplicativo WSK aceitou os datagramas e recuperou todos os datagramas da lista vinculada de WSK_DATAGRAM_INDICATION estruturas. O subsistema WSK pode chamar a função de retorno de chamada de evento WskReceiveFromEvent novamente quando novos datagramas são recebidos no soquete.
STATUS_PENDING	O aplicativo WSK aceitou os datagramas, mas não recuperou todos os datagrams da lista vinculada de WSK_DATAGRAM_INDICATION estruturas. O aplicativo WSK mantém a lista vinculada de estruturas de WSK_DATAGRAM_INDICATION até que todos os datagrams sejam recuperados. Depois que o aplicativo WSK tiver recuperado todos os datagrams, ele chamará a função WskRelease para liberar a lista vinculada de estruturas de WSK_DATAGRAM_INDICATION de volta para o subsistema do WSK. O subsistema WSK pode chamar a função de retorno de chamada de evento WskReceiveFromEvent novamente quando novos datagramas são recebidos no soquete.
STATUS_DATA_NOT_ACCEPTED	O aplicativo WSK não aceitou os datagramas. Se um aplicativo WSK retornar esse código status, o subsistema WSK responderá de forma diferente dependendo de como o aplicativo WSK habilitou a função de retorno de chamada de evento WskReceiveFromEvent. Se o aplicativo WSK tiver habilitado a função de retorno de chamada de evento WskReceiveFromEvent usando a opção de soquete SO_WSK_EVENT_CALLBACK , o subsistema WSK terá o buffer de transporte subjacente dos datagrams, se possível ou, se necessário, pelo protocolo. O subsistema WSK desabilitará a função de retorno de chamada de evento WskReceiveFromEvent e não chamará a função de retorno de chamada de evento WskReceiveFromEvent novamente até que o aplicativo WSK habilite novamente essa função de retorno de chamada de evento com a opção de soquete SO_WSK_EVENT_CALLBACK. Depois que o aplicativo WSK tiver habilitado novamente a função de retorno de chamada de evento WskReceiveFromEvent , o subsistema WSK retomará a chamada da função de retorno de chamada de evento WskReceiveFromEvent com quaisquer datagramas armazenados em buffer restantes e quando novos datagramas forem recebidos no soquete. Se o aplicativo WSK habilitou a função de retorno de chamada de evento WskReceiveFromEvent usando o WSK_SET_STATIC_EVENT_CALLBACKS operação de controle do cliente, o subsistema WSK não desabilitará a função de retorno de chamada de evento WskReceiveFromEvent . O subsistema WSK continuará chamando a função de retorno de chamada de evento WskReceiveFromEvent quando novos datagramas forem recebidos no soquete.

Comentários

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

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

A função de retorno de chamada de evento WskReceiveFromEvent de um aplicativo WSK não deve aguardar a conclusão de outras solicitações do WSK no contexto de funções de retorno de chamada de evento ou de conclusão do WSK. O retorno de chamada pode iniciar outras solicitações do WSK (supondo que ele não gaste muito tempo em 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