Função WSARecvEx (mswsock.h)

Artigo
08/25/2023

A função WSARecvEx recebe dados de um soquete conectado ou de um soquete sem conexão associado. A função WSARecvEx é semelhante à função recv , exceto que o parâmetro flags é usado apenas para retornar informações. Quando uma mensagem parcial é recebida durante o uso do protocolo de datagram, o bit MSG_PARTIAL é definido no parâmetro flags no retorno da função.

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

Sintaxe

int WSARecvEx(
  [in]      SOCKET s,
  [out]     char   *buf,
  [in]      int    len,
  [in, out] int    *flags
);

Parâmetros

[in] s

Um descritor que identifica um soquete conectado.

[out] buf

Um ponteiro para o buffer para receber os dados de entrada.

[in] len

O comprimento, em bytes, do buffer apontado pelo parâmetro buf .

[in, out] flags

Um indicador que especifica se a mensagem é totalmente ou parcialmente recebida para soquetes de datagrama.

Retornar valor

Se nenhum erro ocorrer, WSARecvEx retornará o número de bytes recebidos. Se a conexão tiver sido fechada, ela retornará zero. Além disso, se uma mensagem parcial foi recebida, o bit MSG_PARTIAL será definido no parâmetro flags . Se uma mensagem completa tiver sido recebida, MSG_PARTIAL não será definido em sinalizadores

Caso contrário, um valor de SOCKET_ERROR é retornado e um código de erro específico pode ser recuperado chamando WSAGetLastError.

Importante Para um protocolo de transporte orientado a fluxo, MSG_PARTIAL nunca é definido no retorno de WSARecvEx. Essa função se comporta de forma idêntica à função recv para protocolos de transporte de fluxo.

Código do erro	Significado
WSAECONNABORTED	O circuito virtual foi encerrado por causa do tempo limite ou outra falha. O aplicativo deve fechar o soquete porque ele não pode ser mais usado.
WSAECONNRESET	O circuito virtual foi redefinido pelo lado remoto executando um fechamento forçado ou por anulação. O aplicativo deve fechar o soquete porque ele não pode ser mais usado. Em um soquete de datagrama UPD este erro indicaria uma operação de envio anterior que resultou em uma mensagem de "Porta ICPM Inacessível".
WSAEFAULT	O parâmetro buf não está completamente contido em uma parte válida do espaço de endereço do usuário.
WSAEINPROGRESS	Uma chamada do Windows Sockets 1.1 de bloqueio está em andamento ou o provedor de serviços ainda está processando uma função de retorno de chamada.
WSAEINTR	A chamada (bloqueio) foi cancelada pela chamada WSACancelBlockingCall .
WSAEINVAL	O soquete não foi associado à associação ou um sinalizador desconhecido foi especificado ou MSG_OOB foi especificado para um soquete com SO_OOBINLINE habilitado ou (somente para soquetes de fluxo de bytes) len era zero ou negativo.
WSAENETDOWN	O subsistema de rede falhou.
WSAENETRESET	Para um soquete orientado à conexão, esse erro indica que a conexão foi interrompida devido à atividade keep alive que detectou uma falha enquanto a operação estava em andamento. Para um soquete de datagrama, este erro indica que a vida útil venceu.
WSAENOTCONN	O soquete não está conectado.
WSAENOTSOCK	O descritor não é um soquete.
WSAEOPNOTSUPP	MSG_OOB foi especificado, mas o soquete não é estilo de fluxo, como tipo SOCK_STREAM, não há suporte para dados OOB no domínio de comunicação associado a esse soquete ou o soquete é unidirecional e dá suporte apenas a operações de envio.
WSAESHUTDOWN	O soquete foi desligado; Não é possível usar WSARecvEx em um soquete depois que o desligamento foi invocado com a definição de SD_RECEIVE ou SD_BOTH.
WSAETIMEDOUT	A conexão foi cancelada porque houve falha na rede ou porque o sistema falhou ao responder ao peer system.
WSAEWOULDBLOCK	O soquete é marcado como não desbloqueado e a operação de recebimento seria bloqueada.
WSANOTINITIALISED	Uma chamada WSAStartup bem-sucedida deve ocorrer antes de usar essa função.

Comentários

A função WSARecvEx que faz parte da implementação da Microsoft do Windows Sockets 2 é semelhante à função recv mais comum, exceto que o parâmetro flags é usado para uma única finalidade específica. O parâmetro flags é usado para indicar se uma mensagem parcial ou completa é recebida quando um protocolo orientado a mensagens está sendo usado.

O valor apontado pelo parâmetro flags é ignorado na entrada. Portanto, nenhum sinalizador pode ser passado para a função WSARecvEx para modificar seu comportamento. O valor apontado pelo parâmetro flags é definido na saída. Isso difere das funções recv e WSARecv em que o valor apontado pelo parâmetro flags na entrada pode modificar o comportamento da função.

As funções WSARecvEx e recv se comportam de forma idêntica para protocolos orientados a fluxo.

O parâmetro flags acomoda duas situações comuns em que uma mensagem parcial será recebida:

Quando o tamanho do buffer de dados do aplicativo é menor que o tamanho da mensagem e a mensagem coincidentemente chega em duas partes.
Quando a mensagem é bastante grande e deve chegar em várias partes.

O bit MSG_PARTIAL é definido no valor apontado pelo parâmetro flags no retorno de WSARecvEx quando uma mensagem parcial foi recebida. Se uma mensagem completa tiver sido recebida, MSG_PARTIAL não será definido no valor apontado pelo parâmetro flags .

A função recv é diferente da
As funções WSARecvEx e WSARecv em que a função recv sempre recebe uma única mensagem para cada chamada para protocolos de transporte orientados a mensagens. A função recv também não tem meios para indicar ao aplicativo que os dados recebidos são apenas uma mensagem parcial. Um aplicativo deve criar seu próprio protocolo para verificar se uma mensagem é parcial ou concluída verificando o código de erro WSAEMSGSIZE após cada chamada para recv. Quando o buffer de aplicativo é menor que os dados que estão sendo enviados, a maior parte da mensagem que caberá é copiada no buffer do usuário e o recv retorna com o código de erro WSAEMSGSIZE. Uma chamada subsequente para recv obterá a próxima parte da mensagem.

Os aplicativos gravados para protocolos de transporte orientados a mensagens devem ser codificados para essa possibilidade se o dimensionamento de mensagens não for garantido pelo protocolo de transferência de dados do aplicativo. Um aplicativo pode usar recv e gerenciar o próprio protocolo. Como alternativa, um aplicativo pode usar WSARecvEx e marcar que o bit MSG_PARTIAL é definido no parâmetro flags.

A função WSARecvEx fornece ao desenvolvedor uma maneira mais eficaz de verificar se uma mensagem recebida é parcial ou completa quando uma mensagem muito grande chega incrementalmente. Por exemplo, se um aplicativo enviar uma mensagem de um megabyte, o protocolo de transporte deverá interromper a mensagem para enviá-la pela rede física. Teoricamente, é possível que o protocolo de transporte no lado receptor faça buffer de todos os dados na mensagem, mas isso seria bastante caro em termos de recursos. Em vez disso, o WSARecvEx pode ser usado, minimizando a sobrecarga e eliminando a necessidade de um protocolo baseado em aplicativo.

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. Consulte a função ExitThread para obter mais informações.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	mswsock.h (inclua Mswsock.h)
Biblioteca	Mswsock.lib
DLL	Mswsock.dll