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

Artigo
02/07/2025

A função WskReceive recebe dados por meio de um soquete de fluxo ou orientado à conexão de um endereço de transporte remoto.

Sintaxe

PFN_WSK_RECEIVE PfnWskReceive;

NTSTATUS PfnWskReceive(
  [in]      PWSK_SOCKET Socket,
  [in]      PWSK_BUF Buffer,
  [in]      ULONG Flags,
  [in, out] PIRP Irp
)
{...}

Parâmetros

[in] Socket

Um ponteiro para uma estrutura WSK_SOCKET que especifica o objeto socket para o soquete do qual receber os dados.

[in] Buffer

Um ponteiro para uma estrutura de WSK_BUF inicializada que descreve o buffer de dados que recebe os dados do soquete.

[in] Flags

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

WSK_FLAG_WAITALL

Aguarde até que o buffer de dados seja completamente preenchido. Se esse sinalizador for especificado, o IRP especificado no parâmetro Irp não será concluído até que um dos seguintes eventos ocorra:

O buffer de dados descrito pela estrutura de WSK_BUF que é apontado pelo parâmetro Buffer está completamente preenchido.
A conexão é desconectada normalmente pelo remetente remoto.
A conexão é desconectada de forma anulativa pelo aplicativo WSK ou pelo remetente remoto.
O IRP especificado é cancelado.

Esse sinalizador é compatível com o protocolo de transporte TCP/IP da Microsoft. Esse sinalizador pode não ser suportado por outros protocolos de transporte.

WSK_FLAG_DRAIN

Aguarde até que o soquete seja desconectado, descartando todos os dados recebidos no soquete. Se esse sinalizador for especificado, o IRP especificado não será concluído até que um dos seguintes eventos ocorra:

A conexão é desconectada normalmente pelo remetente remoto.
A conexão é desconectada de forma anulativa pelo aplicativo WSK ou pelo remetente remoto.
O IRP especificado é cancelado.

Todos os dados recebidos são descartados pelo subsistema do WSK. Nenhum dado recebido será copiado para o buffer de dados. O parâmetro buffer ainda é necessário quando esse sinalizador é especificado, mas o comprimento do buffer descrito pela estrutura de WSK_BUF deve ser zero.

Esse sinalizador é compatível com o protocolo de transporte TCP/IP da Microsoft. Esse sinalizador pode não ser suportado por outros protocolos de transporte.

Os sinalizadores WSK_FLAG_WAITALL e WSK_FLAG_DRAIN são mutuamente exclusivos. Um aplicativo WSK não deve especificar ambos os sinalizadores ao mesmo tempo.

[in, out] Irp

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

Valor de retorno

WskReceive retorna um dos seguintes códigos NTSTATUS:

Código de retorno	Descrição
STATUS_SUCCESS	Os dados foram recebidos com êxito do soquete. O IRP será concluído com o status de êxito. O campo IoStatus.Information do IRP contém o número de bytes recebidos.
STATUS_PENDING	O subsistema do WSK não pôde receber os dados do soquete imediatamente. O subsistema WSK concluirá o IRP depois de receber os dados do soquete. O status da operação de recebimento será retornado no campo IoStatus.Status do IRP. Se a operação for bem-sucedida, o campo IoStatus.Information do IRP conterá o número de bytes recebidos.
STATUS_FILE_FORCED_CLOSED	O soquete não está mais funcional. O IRP será concluído com o status de falha. O aplicativo WSK deve chamar a função WskCloseSocket para fechar o soquete o mais rápido possível.
STATUS_NOT_SUPPORTED	Não há suporte para um sinalizador especificado pelo transporte de rede subjacente.
Outros códigos de status	Ocorreu um erro. O IRP será concluído com o status de falha.

Observações

Um aplicativo WSK pode chamar a função WskReceive somente em um soquete de fluxo ou orientado para conexão que tenha sido conectado anteriormente a um endereço de transporte remoto. Um soquete orientado à conexão é conectado a um endereço de transporte remoto por um dos seguintes métodos:

O aplicativo WSK conecta o soquete chamando a função WskConnect.
O aplicativo WSK cria, associa e conecta o soquete chamando a função WskSocketConnect.
O subsistema WSK conecta o soquete quando o aplicativo WSK aceita uma solicitação de conexão de entrada em um soquete de escuta.

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 para conexão, em seguida, 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 chama a função de retorno de chamada de evento WskReceiveEvent do aplicativo somente se não houver IRPs enfileirados 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 à 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 o aplicativo WSK WskReceiveEvent função de retorno de chamada de evento 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 à conexão é desabilitar a função de retorno de chamada de evento WskReceiveEvent do aplicativo no soquete.

Um aplicativo WSK pode chamar a função WskReceive com um comprimento zero especificado no membro comprimento da estrutura de WSK_BUF que é apontado pelo parâmetro do Buffer de. Especificar um comprimento zero neste membro é útil nas seguintes situações:

Ao habilitar novamente a função de retorno de chamada de evento WskReceiveEvent para um soquete após a função de retorno de chamada de evento WskReceiveEvent retornada anteriormente STATUS_DATA_NOT_ACCEPTED
Ao especificar o sinalizador WSK_FLAG_DRAIN para descartar quaisquer dados adicionais recebidos no soquete

Se a função WskReceive retornar STATUS_PENDING, a cadeia de MDL descrita na estrutura WSK_BUF apontada pelo parâmetro Buffer deverá permanecer bloqueada na memória até que o IRP seja concluído.

Requisitos

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