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

Artigo
08/08/2023

A função WskReceive recebe dados por meio de um soquete de fluxo ou orientado para 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 de soquete 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 ocorra um dos seguintes eventos:

O buffer de dados descrito pela estrutura WSK_BUF apontada pelo parâmetro Buffer é completamente preenchido.
A conexão é normalmente desconectada pelo remetente remoto.
A conexão é desconectada abortivamente 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 ocorra um dos seguintes eventos:

A conexão é normalmente desconectada pelo remetente remoto.
A conexão é desconectada abortivamente 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 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 pelo 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 WSK, consulte Usando IRPs com funções de kernel Winsock.

Retornar valor

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 êxito status. O campo IoStatus.Information do IRP contém o número de bytes recebidos.
STATUS_PENDING	O subsistema 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 falha status. 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 status	Ocorreu um erro. O IRP será concluído com falha status.

Comentários

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 à conexã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 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 à 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 à 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 Length da estrutura WSK_BUF apontado pelo parâmetro Buffer . 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 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
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