PFN_WSK_RECEIVE_FROM função de retorno de chamada (wsk.h)
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 socket para o soquete de datagrama do qual receber o datagram.
[in] Buffer
Um ponteiro para uma estrutura de WSK_BUF inicializada que descreve o buffer de dados que recebe o datagram 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 se originou. 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 datagram. 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 por chamador que recebe as informações de controle associadas ao datagrama recebido. Os dados de informações de controle associados a um datagram são compostos por um ou mais objetos de dados de controle, cada um deles começa com uma estrutura de 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 datagram 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 datagram 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 do 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 do 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 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
WskReceiveFrom retorna um dos seguintes códigos NTSTATUS:
| Código de retorno | Descrição |
|---|---|
|
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. |
|
O subsistema do WSK não pôde receber o datagram do soquete imediatamente. O subsistema WSK concluirá o IRP depois de receber o datagram 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. |
|
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. |
|
Ocorreu um erro. O IRP será concluído com o status de falha. |
Observações
Se o aplicativo WSK tiver definido um endereço de transporte remoto fixo para o soquete de datagram, 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 datagram, 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 datagram e o aplicativo também tiver uma chamada pendente para a função WskReceiveFrom no mesmo soquete de datagram, em seguida, 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 datagram que tenha uma chamada pendente para a função WskReceiveFrom. Existem condições de corrida em que o subsistema WSK ainda pode chamar o aplicativo WSK WskReceiveFromEvent 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 WskReceiveFromEvent do aplicativo em um soquete de datagram é 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 de MDL descrita na estrutura de WSK_BUF apontada pelo parâmetro do Buffer deverá permanecer bloqueada na memória até que o IRP seja concluído. Além disso, a variável que é apontada pelo parâmetro ControlInfoLength, o buffer apontado pelo parâmetro ControlInfo e a variável apontada pelo parâmetro ControlFlags também deve permanecer válida 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 |
|---|---|
| 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 |