LPFN_WSARECVMSG função de retorno de chamada (mswsock.h)

Artigo
03/16/2023

LPFN_WSARECVMSG é um tipo de ponteiro de função. Você implementa uma função de retorno de chamada WSARecvMsg correspondente em seu aplicativo. O sistema usa sua função de retorno de chamada para transmitir dados na memória, ou dados de arquivo, por meio de um soquete conectado.

Sua função de retorno de chamada WSARecvMsg recebe informações auxiliares de dados/controle com uma mensagem, de soquetes conectados e não conectados.

Observação

Essa função é uma extensão específica da Microsoft para a especificação do Windows Sockets.

Sintaxe

LPFN_WSARECVMSG LpfnWsarecvmsg;

INT LpfnWsarecvmsg(
  SOCKET s,
  LPWSAMSG lpMsg,
  LPDWORD lpdwNumberOfBytesRecvd,
  LPWSAOVERLAPPED lpOverlapped,
  LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
)
{...}

Parâmetros

s

Tipo: _In_ SOCKET

Um descritor que identifica o soquete.

lpMsg

Tipo: _Inout_ LPWSAMSG

Um ponteiro para uma estrutura WSAMSG com base na especificação Posix.1g para a estrutura msghdr.

lpdwNumberOfBytesRecvd

Tipo: _Out_opt_ LPDWORD

Um ponteiro para um DWORD que contém o número de bytes recebidos por essa chamada se a operação WSARecvMsg for concluída imediatamente.

Para evitar resultados potencialmente incorretos, passe NULL para esse parâmetro se o parâmetro lpOverlapped não for NULL . Esse parâmetro só poderá ser NULL se o parâmetro lpOverlapped não for NULL.

lpOverlapped

Tipo: _Inout_opt_ LPWSAOVERLAPPED

Um ponteiro para uma estrutura WSAOVERLAPPED . Ignorado para estruturas não sobrepostas.

lpCompletionRoutine

Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Um ponteiro para a rotina de conclusão chamado quando a operação de recebimento é concluída. Ignorado para estruturas não sobrepostas.

Retornar valor

Se nenhum erro ocorrer e a operação de recebimento for concluída imediatamente, WSARecvMsg retornará zero. Nesse caso, a rotina de conclusão já terá sido agendada para ser chamada quando o thread de chamada estiver no estado alertável. Caso contrário, um valor de SOCKET_ERROR será retornado e um código de erro específico poderá ser recuperado chamando WSAGetLastError. O código de erro WSA_IO_PENDING indica que a operação sobreposta foi iniciada com êxito e que a conclusão será indicada posteriormente.

Qualquer outro código de erro indica que a operação não foi iniciada com êxito e nenhuma indicação de conclusão ocorrerá se uma operação sobreposta tiver sido solicitada.

Código do erro	Significado
WSAECONNRESET	Para um soquete de datagrama UDP, esse erro indicaria que uma operação de envio anterior resultou em uma mensagem "Porta Inacessível" ICMP.
WSAEFAULT	O parâmetro lpBuffers, lpFlags, lpFrom, lpNumberOfBytesRecvd, lpFromlen, lpOverlapped ou lpCompletionRoutine não está totalmente contido em uma parte válida do espaço de endereço do usuário: o buffer lpFrom era muito pequeno para acomodar o endereço par. Esse erro também será retornado se um membro de nome da estrutura WSAMSG apontado pelo parâmetro lpMsg for um ponteiro NULL e o membro namelen da estrutura WSAMSG não estiver definido como zero. Esse erro também será retornado se um membro Control.buf da estrutura WSAMSG apontado pelo parâmetro lpMsg for um ponteiro NULL e o membro Control.len da estrutura WSAMSG não estiver definido como zero.
WSAEINPROGRESS	Uma chamada de bloqueio do Windows Sockets 1.1 está em andamento ou o provedor de serviços ainda está processando uma função de retorno de chamada.
WSAEINTR	Uma chamada de bloqueio do Windows Socket 1.1 foi cancelada por meio de WSACancelBlockingCall.
WSAEINVAL	O soquete não foi associado (com associação, por exemplo).
WSAEMSGSIZE	A mensagem era muito grande para caber no buffer especificado e (somente para protocolos não confiáveis) qualquer parte à direita da mensagem que não se encaixasse no buffer foi descartada.
WSAENETDOWN	O subsistema de rede falhou.
WSAENETRESET	Para um soquete de datagrama, este erro indica que a vida útil venceu.
WSAENOTCONN	O soquete não está conectado (somente soquetes orientados à conexão).
WSAETIMEDOUT	O soquete atingiu o tempo limite. Esse erro será retornado se o soquete tiver um tempo limite de espera especificado usando a opção de soquete SO_RCVTIMEO e o tempo limite tiver sido excedido.
WSAEOPNOTSUPP	Não há suporte para a operação de soquete. Esse erro será retornado se o membro dwFlags da estrutura WSAMSG apontada pelo parâmetro lpMsg incluir o sinalizador de controle MSG_PEEK em um soquete não datagrama.
WSAEWOULDBLOCK	Windows NT: Soquetes sobrepostos: há muitas solicitações de E/S sobrepostas pendentes. Soquetes não sobrepostos: o soquete é marcado como não desbloqueio e a operação de recebimento não pode ser concluída imediatamente.
WSANOTINITIALISED	Uma chamada WSAStartup bem-sucedida deve ocorrer antes de usar essa função.
WSA_IO_PENDING	Uma operação sobreposta foi iniciada com êxito e a conclusão será indicada posteriormente.
WSA_OPERATION_ABORTED	A operação sobreposta foi cancelada devido ao fechamento do soquete.

Comentários

A função WSARecvMsg pode ser usada no lugar das funções WSARecv e WSARecvFrom para receber dados e informações de controle opcionais de soquetes conectados e não conectados. A função WSARecvMsg só pode ser usada com datagramas e soquetes brutos. O descritor de soquete no parâmetro s deve ser aberto com o tipo de soquete definido como SOCK_DGRAM ou SOCK_RAW.

Nota O ponteiro de função para a função WSARecvMsg deve ser obtido em tempo de execução fazendo uma chamada para a função WSAIoctl com o SIO_GET_EXTENSION_FUNCTION_POINTER opcode especificado. O buffer de entrada passado para a função WSAIoctl deve conter WSAID_WSARECVMSG, um GUID (identificador global exclusivo) cujo valor identifica a função de extensão WSARecvMsg . Em caso de êxito, a saída retornada pela função WSAIoctl contém um ponteiro para a função WSARecvMsg . O GUID WSAID_WSARECVMSG é definido no arquivo de cabeçalho Mswsock.h .

O membro dwFlags da estrutura WSAMSG apontada pelo parâmetro lpMsg pode conter apenas o sinalizador de controle MSG_PEEK na entrada.

Soquetes sobrepostos são criados com uma chamada de função WSASocket que tem o sinalizador WSA_FLAG_OVERLAPPED definido. Para soquetes sobrepostos, o recebimento de informações usa E/S sobreposta, a menos que os parâmetros lpOverlapped e lpCompletionRoutine sejam NULL. O soquete é tratado como um soquete não sobreposto quando os parâmetros lpOverlapped e lpCompletionRoutine são NULL.

Uma indicação de conclusão ocorre com soquetes sobrepostos. Depois que o buffer ou buffers tiverem sido consumidos pelo transporte, uma rotina de conclusão será disparada ou um objeto de evento será definido. Se a operação não for concluída imediatamente, o status de conclusão final será recuperado por meio da rotina de conclusão ou chamando a função WSAGetOverlappedResult.

Para soquetes sobrepostos, WSARecvMsg é usado para postar um ou mais buffers nos quais os dados de entrada serão colocados à medida que ficam disponíveis, após o qual ocorre a indicação de conclusão especificada pelo aplicativo (invocação da rotina de conclusão ou configuração de um objeto de evento). Se a operação não for concluída imediatamente, o status de conclusão final será recuperado por meio da rotina de conclusão ou da função WSAGetOverlappedResult.

Para soquetes não sobrepostos, a semântica de bloqueio é idêntica à da função recv padrão e os parâmetros lpOverlapped e lpCompletionRoutine são ignorados. Todos os dados que já foram recebidos e armazenados em buffer pelo transporte serão copiados para os buffers de usuário especificados. No caso de um soquete de bloqueio sem dados recebidos e armazenados em buffer pelo transporte, a chamada será bloqueada até que os dados sejam recebidos. O Windows Sockets 2 não define nenhum mecanismo de tempo limite de bloqueio padrão para essa função. Para protocolos que atuam como protocolos de fluxo de bytes, a pilha tenta retornar o máximo de dados possível sujeito ao espaço de buffer disponível e à quantidade de dados recebidos disponíveis. No entanto, o recebimento de um único byte é suficiente para desbloquear o chamador. Não há nenhuma garantia de que mais de um único byte será retornado. Para protocolos que atuam como orientados a mensagens, uma mensagem completa é necessária para desbloquear o chamador.

Nota A opção de soquete SO_RCVTIMEO aplica-se somente a soquetes de bloqueio.

Os buffers são preenchidos na ordem em que aparecem na matriz apontada pelo membro lpBuffers da estrutura WSAMSG apontada pelo parâmetro lpMsg e os buffers são empacotados para que nenhum buraco seja criado.

Se essa função for concluída de maneira sobreposta, será responsabilidade do provedor de serviços Winsock capturar essa estrutura WSABUF antes de retornar dessa chamada. Isso permite que os aplicativos criem matrizes WSABUF baseadas em pilha apontadas pelo membro lpBuffers da estrutura WSAMSG apontada pelo parâmetro lpMsg .

Para soquetes orientados a mensagens (um tipo de soquete de SOCK_DGRAM ou SOCK_RAW), uma mensagem de entrada é colocada nos buffers até o tamanho total dos buffers e a indicação de conclusão ocorre para soquetes sobrepostos. Se a mensagem for maior que os buffers, os buffers serão preenchidos com a primeira parte da mensagem e os dados em excesso serão perdidos e WSARecvMsg gerará o erro WSAEMSGSIZE.

Quando a opção de soquete IP_PKTINFO é habilitada em um soquete IPv4 do tipo SOCK_DGRAM ou SOCK_RAW, a função WSARecvMsg retorna informações de pacote na estrutura WSAMSG apontada pelo parâmetro lpMsg . Um dos objetos de dados de controle na estrutura WSAMSG retornada conterá uma estrutura in_pktinfo usada para armazenar informações de endereço de pacote recebidas.

Para datagrams recebidos por IPv4, o membro Control da estrutura WSAMSG recebida conterá uma estrutura WSABUF que contém uma estrutura WSACMSGHDR . O membro cmsg_level dessa estrutura WSACMSGHDR conteria IPPROTO_IP, o membro cmsg_type dessa estrutura conteria IP_PKTINFO e o membro cmsg_data conteria uma estrutura in_pktinfo usada para armazenar informações de endereço de pacote IPv4 recebidas. O endereço IPv4 na estrutura in_pktinfo é o endereço IPv4 do qual o pacote foi recebido.

Quando a opção de soquete IPV6_PKTINFO é habilitada em um soquete IPv6 do tipo SOCK_DGRAM ou SOCK_RAW, a função WSARecvMsg retorna informações de pacote na estrutura WSAMSG apontada pelo parâmetro lpMsg . Um dos objetos de dados de controle na estrutura WSAMSG retornada conterá uma estrutura in6_pktinfo usada para armazenar informações de endereço de pacote recebidas.

Para datagrams recebidos por IPv6, o membro Control da estrutura WSAMSG recebida conterá uma estrutura WSABUF que contém uma estrutura WSACMSGHDR . O membro cmsg_level dessa estrutura WSACMSGHDR conteria IPPROTO_IPV6, o membro cmsg_type dessa estrutura conteria IPV6_PKTINFO e o membro cmsg_data conteria uma estrutura in6_pktinfo usada para armazenar informações de endereço de pacote IPv6 recebidas. O endereço IPv6 na estrutura in6_pktinfo é o endereço IPv6 do qual o pacote foi recebido.

Para um soquete de datagrama de pilha dupla, se um aplicativo exigir que a função WSARecvMsg retorne informações de pacote em uma estrutura WSAMSG para datagramas recebidos por IPv4, IP_PKTINFO opção de soquete deverá ser definida como true no soquete. Se apenas a opção IPV6_PKTINFO estiver definida como true no soquete, as informações do pacote serão fornecidas para datagramas recebidos por IPv6, mas podem não ser fornecidas para datagramas recebidos por IPv4.

Observe que o arquivo de cabeçalho Ws2ipdef.h é incluído automaticamente no Ws2tcpip.h e nunca deve ser usado diretamente.

Nota Todas as E/S iniciadas por um determinado thread são canceladas quando esse thread é encerrado. Para soquetes sobrepostos, as operações assíncronas pendentes podem falhar se o thread for fechado antes da conclusão das operações. Para obter mais informações, consulte ExitThread.

Windows Phone 8: essa função tem suporte para aplicativos da Windows Phone Store no Windows Phone 8 e posterior.

Windows 8.1 e Windows Server 2012 R2: essa função tem suporte para aplicativos da Windows Store em Windows 8.1, Windows Server 2012 R2 e posteriores.

dwFlags

Na entrada, o membro dwFlags da estrutura WSAMSG apontada pelo parâmetro lpMsg pode ser usado para influenciar o comportamento da invocação de função além das opções de soquete especificadas para o soquete associado. Ou seja, a semântica dessa função é determinada pelas opções de soquete e pelo membro dwFlags da estrutura WSAMSG . O único valor de entrada possível para o membro dwFlags da estrutura WSAMSG apontada pelo parâmetro lpMsg é MSG_PEEK.

Valor	Significado
MSG_PEEK	Inspeção dos dados de entrada. Os dados são copiados para o buffer, mas não são removidos da fila de entrada. Esse sinalizador é válido apenas para soquetes não sobrepostos.

Os valores possíveis para o membro dwFlags na entrada são definidos no arquivo de cabeçalho Winsock2.h .

Na saída, o membro dwFlags da estrutura WSAMSG apontada pelo parâmetro lpMsg pode retornar uma combinação de qualquer um dos valores a seguir.

Valor	Significado
MSG_BCAST	O datagrama foi recebido como uma transmissão de camada de link ou com um endereço IP de destino que é um endereço de difusão.
MSG_CTRUNC	Os dados de controle (auxiliares) foram truncados. Mais dados de controle estavam presentes do que a sala alocada para o processo.
MSG_MCAST	O datagrama foi recebido com um endereço IP de destino que é um endereço multicast.
MSG_TRUNC	O datagrama foi truncado. Mais dados estavam presentes do que a sala alocada para o processo.

No Microsoft Software Development Kit do Windows (SDK do Windows) (SDK) lançado para Windows Vista e posteriores, a organização de arquivos de cabeçalho foi alterada e os valores possíveis para o membro dwFlags na saída são definidos no arquivo de cabeçalho Ws2def.h que é incluído automaticamente pelo arquivo de cabeçalho Winsock2.h.

Em versões do SDK (Platform Software Development Kit) para Windows Server 2003 e anteriores, os valores possíveis para o membro dwFlags na saída são definidos no arquivo de cabeçalho Mswsock.h .

Nota Ao emitir uma chamada Winsock de bloqueio, como WSARecvMsg , com o parâmetro lpOverlapped definido como NULL, Winsock pode precisar aguardar um evento de rede antes que a chamada possa ser concluída. O Winsock executa uma espera alertável nessa situação, que pode ser interrompida por uma APC (chamada de procedimento assíncrona) agendada no mesmo thread. Emitir outra chamada winsock de bloqueio dentro de um APC que interrompeu uma chamada Winsock de bloqueio contínuo no mesmo thread levará a um comportamento indefinido e nunca deve ser tentado pelos clientes winsock.

E/S de soquete sobreposto

Se uma operação sobreposta for concluída imediatamente, WSARecvMsg retornará um valor igual a zero e o parâmetro lpNumberOfBytesRecvd será atualizado com o número de bytes recebidos e os bits de sinalizador indicados pelo parâmetro lpFlags também serão atualizados . Se a operação sobreposta for iniciada com êxito e for concluída posteriormente, WSARecvMsg retornará SOCKET_ERROR e indicará o código de erro WSA_IO_PENDING. Nesse caso, lpNumberOfBytesRecvd não é atualizado. Quando a operação sobreposta é concluída, a quantidade de dados transferidos é indicada por meio do parâmetro cbTransferred na rotina de conclusão (se especificada) ou por meio do parâmetro lpcbTransfer em WSAGetOverlappedResult. Os valores de sinalizador são obtidos examinando o parâmetro lpdwFlags de WSAGetOverlappedResult.

A função WSARecvMsg usando E/S sobreposta pode ser chamada de dentro da rotina de conclusão de uma função anterior WSARecv, WSARecvFrom, WSARecvMsg, WSASend, WSASendMsg ou WSASendTo . Para um determinado soquete, as rotinas de conclusão de E/S não serão aninhadas. Isso permite que transmissões de dados sensíveis ao tempo ocorram inteiramente em um contexto preemptivo.

O parâmetro lpOverlapped deve ser válido durante a operação sobreposta. Se várias operações de E/S estiverem simultaneamente pendentes, cada uma deverá referenciar uma estrutura WSAOVERLAPPED separada.

Se o parâmetro lpCompletionRoutine for NULL, o parâmetro hEvent de lpOverlapped será sinalizado quando a operação sobreposta for concluída se contiver um identificador de objeto de evento válido. Um aplicativo pode usar WSAWaitForMultipleEvents ou WSAGetOverlappedResult para aguardar ou sondar o objeto de evento.

Se lpCompletionRoutine não for NULL, o parâmetro hEvent será ignorado e poderá ser usado pelo aplicativo para passar informações de contexto para a rotina de conclusão. Um chamador que passa um lpCompletionRoutine não NULL e chama posteriormente WSAGetOverlappedResult para a mesma solicitação de E/S sobreposta pode não definir o parâmetro fWait para essa invocação de WSAGetOverlappedResult como TRUE. Nesse caso, o uso do parâmetro hEvent é indefinido e tentar aguardar o parâmetro hEvent produziria resultados imprevisíveis.

A rotina de conclusão segue as mesmas regras estipuladas para rotinas de conclusão de E/S de arquivo do Windows. A rotina de conclusão não será invocada até que o thread esteja em um estado de espera alertável, como pode ocorrer quando a função WSAWaitForMultipleEvents com o parâmetro fAlertable definido como TRUE for invocada.

O protótipo da rotina de conclusão é o seguinte:


void CALLBACK CompletionRoutine(
  IN DWORD dwError, 
  IN DWORD cbTransferred, 
  IN LPWSAOVERLAPPED lpOverlapped, 
  IN DWORD dwFlags
);

CompletionRoutine é um espaço reservado para um nome de função definido pelo aplicativo ou definido pela biblioteca. O parâmetro dwError especifica o status de conclusão para a operação sobreposta, conforme indicado pelo parâmetro lpOverlapped. O parâmetro cbTransferred especifica o número de bytes recebidos. O parâmetro dwFlags contém informações que também são retornadas no membro dwFlags da estrutura WSAMSG apontada pelo parâmetro lpMsg se a operação de recebimento tiver sido concluída imediatamente. A função CompletionRoutine não retorna um valor.

Retornar dessa função permite a invocação de outra rotina de conclusão pendente para esse soquete. Ao usar WSAWaitForMultipleEvents, todas as rotinas de conclusão de espera são chamadas antes que a espera do thread alertável seja satisfeita com um código de retorno de WSA_IO_COMPLETION. As rotinas de conclusão podem ser chamadas em qualquer ordem, não necessariamente na mesma ordem em que as operações sobrepostas são concluídas. No entanto, os buffers postados têm a garantia de serem preenchidos na mesma ordem em que são especificados.

Se você estiver usando portas de conclusão de E/S, lembre-se de que a ordem das chamadas feitas para WSARecvMsg também é a ordem na qual os buffers são preenchidos. A função WSARecvMsg não deve ser chamada no mesmo soquete simultaneamente de threads diferentes, pois pode resultar em uma ordem de buffer imprevisível.