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

Artigo
08/08/2023

A função WskReceiveFrom recebe um datagrama e quaisquer informações de controle associadas de um endereço de transporte remoto.

Sintaxe

PFN_WSK_RECEIVE_FROM PfnWskReceiveFrom;

NTSTATUS PfnWskReceiveFrom(
  [in]            PWSK_SOCKET Socket,
  [in]            PWSK_BUF Buffer,
                  ULONG Flags,
  [out, optional] PSOCKADDR RemoteAddress,
  [in, out]       PULONG ControlLength,
  [out, optional] PCMSGHDR ControlInfo,
  [out, optional] PULONG ControlFlags,
  [in, out]       PIRP Irp
)
{...}

Parâmetros

[in] Socket

Um ponteiro para uma estrutura WSK_SOCKET que especifica o objeto de soquete para o soquete de datagrama do qual receber o datagrama.

[in] Buffer

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

Flags

Esse parâmetro é reservado para uso do sistema. Um aplicativo WSK deve definir esse parâmetro como zero.

[out, optional] RemoteAddress

Um ponteiro para um buffer alocado pelo chamador que recebe o endereço de transporte remoto do qual o datagrama recebido foi originado. O buffer deve estar localizado na memória não paginada. O buffer também deve ser grande o suficiente para conter o tipo de estrutura SOCKADDR específico que corresponde à família de endereços especificada pelo aplicativo WSK ao criar o soquete de datagrama. Esse ponteiro é opcional e pode ser NULL.

[in, out] ControlLength

Um ponteiro para um ULONG que especifica o tamanho do buffer apontado pelo parâmetro ControlInfo . Quando a operação de recebimento é concluída, a variável recebe o tamanho das informações de controle associadas ao datagrama recebido. Se o valor retornado for zero, não haverá informações de controle presentes para o datagrama. Esse ponteiro é opcional e pode ser NULL. Se esse parâmetro for NULL, o parâmetro ControlInfo será ignorado.

[out, optional] ControlInfo

Um ponteiro para um buffer alocado pelo chamador que recebe as informações de controle associadas ao datagrama recebido. Os dados de informações de controle associados a um datagrama são compostos por um ou mais objetos de dados de controle, cada um dos quais começa com uma estrutura CMSGHDR . Se não houver informações de controle presentes para o datagrama recebido, o conteúdo do buffer será indefinido. Esse ponteiro é opcional e pode ser NULL. Se o parâmetro ControlInfoLength for NULL, o parâmetro ControlInfo deverá ser NULL.

[out, optional] ControlFlags

Um ponteiro para uma variável do tipo ULONG que recebe o OR bit a bit de uma combinação dos seguintes sinalizadores:

MSG_BCAST

O datagrama foi recebido como uma transmissão de camada de link ou com um endereço de transporte de destino que é um endereço de difusão.

MSG_MCAST

O datagrama foi recebido com um endereço de transporte de destino que é um endereço multicast.

MSG_TRUNC

O datagrama foi truncado porque o tamanho do datagrama era maior que o tamanho do buffer especificado pelo parâmetro Buffer .

MSG_CTRUNC

Os dados de informações de controle foram truncados porque o número de bytes de informações de controle foi maior que o tamanho do buffer especificado pelo parâmetro ControlInfo .

Esse parâmetro é opcional e pode ser NULL.

[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

WskReceiveFrom 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 o datagrama do soquete imediatamente. O subsistema WSK concluirá o IRP depois de receber o datagrama 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 é mais funcional. O IRP será concluído com status de falha. O aplicativo WSK deve chamar a função WskCloseSocket para fechar o soquete o mais rápido possível.
Outros códigos de status	Ocorreu um erro. O IRP será concluído com status de falha.

Comentários

Se o aplicativo WSK tiver definido um endereço de transporte remoto fixo para o soquete de datagrama, os datagramas recebidos de qualquer outro endereço de transporte remoto serão descartados pelo subsistema WSK. Para obter mais informações sobre como definir o endereço de transporte remoto para um soquete de datagrama, consulte SIO_WSK_SET_REMOTE_ADDRESS.

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 NENHUM 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.

Se a função WskReceiveFrom 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. Além disso, a variável apontada pelo parâmetro ControlInfoLength , o buffer apontado pelo parâmetro ControlInfo e a variável apontada pelo parâmetro ControlFlags também devem permanecer válidas até que o IRP seja concluído. Se o aplicativo WSK alocou esses buffers ou variáveis com uma das funções ExAllocateXxx , ele não poderá liberar a memória com a função ExFreeXxx correspondente até que o IRP seja concluído. Se o aplicativo WSK alocou esses buffers ou variáveis na pilha, ele não poderá retornar da função que chama a função WskReceiveFrom 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