Função WSASendMsg (winsock2.h)

Artigo
07/16/2024

A função WSASendMsg envia dados e informações de controle opcionais 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

int WSAAPI WSASendMsg(
  [in]  SOCKET                             Handle,
  [in]  LPWSAMSG                           lpMsg,
  [in]  DWORD                              dwFlags,
  [out] LPDWORD                            lpNumberOfBytesSent,
  [in]  LPWSAOVERLAPPED                    lpOverlapped,
  [in]  LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

Parâmetros

[in] Handle

Um descritor que identifica o soquete.

[in] lpMsg

Uma estrutura de WSAMSG armazenando a estrutura de do Posix.1g msghdr.

[in] dwFlags

Os sinalizadores usados para modificar o comportamento da chamada de função WSASendMsg. Para obter mais informações, consulte Using dwFlags in the Remarks section.

[out] lpNumberOfBytesSent

Um ponteiro para o número, em bytes, enviado por essa chamada se a operação de E/S for concluída imediatamente.

Use NULL para esse parâmetro se o parâmetro lpOverlapped não estiver NULL para evitar resultados potencialmente incorretos. Esse parâmetro poderá ser NULL somente se o parâmetro lpOverlapped não estiver NULL.

[in] lpOverlapped

Um ponteiro para uma estrutura de WSAOVERLAPPED . Ignorado para soquetes não sobrepostos.

[in] lpCompletionRoutine

Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Um ponteiro para a rotina de conclusão chamado quando a operação de envio é concluída. Ignorado para soquetes não sobrepostos.

Valor de retorno

Retorna zero quando ocorre uma conclusão bem-sucedida e imediata. Quando zero é retornado, a rotina de conclusão especificada é chamada quando o thread de chamada está no estado alertável.

Um valor retornado de SOCKET_ERRORe uma chamada subsequente para WSAGetLastError que retorna WSA_IO_PENDING indica que a operação sobreposta foi iniciada com êxito; em seguida, a conclusão é indicada por outros meios, como por meio de eventos ou portas de conclusão.

Após a falha, retorna SOCKET_ERROR e uma chamada subsequente para WSAGetLastError retorna um valor diferente de WSA_IO_PENDING. A tabela a seguir lista códigos de erro.

Código de erro	Significado
WSAEACCES	O endereço solicitado é um endereço de difusão, mas o sinalizador apropriado não foi definido.
WSAECONNRESET	Para um soquete de datagrama UDP, esse erro indicaria que uma operação de envio anterior resultou em uma mensagem de "Porta Inacessível" do ICMP.
WSAEFAULT	OlpMsg , lpNumberOfBytesSent, lpOverlappedou lpCompletionRoutine não está totalmente contido em uma parte válida do espaço de endereço do usuário. Esse erro também será retornado se um nome membro da estrutura de do WSAMSG apontado pelo parâmetro lpMsg for um ponteiro de NULL e o membro namelen da estrutura de do WSAMSG não foi definido como zero. Esse erro também será retornado se um membro Control.buf da estrutura de WSAMSG apontado pelo parâmetro lpMsg for um ponteiro NULL e o membro control.len da estrutura de WSAMSG não foi 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çãoou o soquete não foi criado com o sinalizador sobreposto.
WSAEMSGSIZE	O soquete é orientado à mensagem e a mensagem é maior do que o máximo suportado pelo transporte subjacente.
WSAENETDOWN	O subsistema de rede falhou.
WSAENETRESET	Para um soquete de datagrama, esse erro indica que o tempo de vida útil expirou.
WSAENETUNREACH	A rede é inacessível.
WSAENOBUFS	O provedor de Soquetes do Windows relata um deadlock de buffer.
WSAENOTCONN	O soquete não está conectado.
WSAENOTSOCK	O descritor não é um soquete.
WSAEOPNOTSUPP	Não há suporte para a operação de soquete. Esse erro será retornado se o dwFlags membro da estrutura de do WSAMSG apontado pelo parâmetro lpMsg incluir quaisquer sinalizadores de controle inválidos para WSASendMsg.
WSAESHUTDOWN	O soquete foi desligado; não é possível chamar a função WSASendMsg em um soquete depois que de desligamento foi invocado com como definido como SD_SEND ou SD_BOTH.
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_SNDTIMEO e o tempo limite for excedido.
WSAEWOULDBLOCK	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 envio 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 ou devido à execução do comando SIO_FLUSH em WSAIoctl.

Observações

A função WSASendMsg pode ser usada no lugar das funções WSASend e WSASendTo . A função WSASendMsg só pode ser usada com datagramas e soquetes brutos. O descritor de soquete no parâmetro do deve ser aberto com o tipo de soquete definido como SOCK_DGRAM ou SOCK_RAW.

O parâmetro dwFlags só pode conter uma combinação dos seguintes sinalizadores de controle: MSG_DONTROUTE, MSG_PARTIALe MSG_OOB. O membro dwFlags da estrutura WSAMSG apontado pelo parâmetro lpMsg é ignorado na entrada e não é usado na saída.

Observação O ponteiro de função para a função WSASendMsg 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_WSASENDMSG, um GUID (identificador global exclusivo) cujo valor identifica a função de extensão WSASendMsg. Com êxito, a saída retornada pela função WSAIoctl contém um ponteiro para a função WSASendMsg. O GUID WSAID_WSASENDMSG é definido no arquivo de cabeçalho Mswsock.h.

Soquetes sobrepostos são criados com uma chamada de função WSASocket que tem o sinalizador WSA_FLAG_OVERLAPPED definido. Para soquetes sobrepostos, o envio de informações usa E/S sobreposta, a menos que lpOverlapped e lpCompletionRoutine sejam NULL; quando lpOverlapped e lpCompletionRoutine são NULL, o soquete é tratado como um soquete não sobreposto. 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 não sobrepostos, os parâmetros lpOverlapped e lpCompletionRoutine são ignorados e WSASendMsg adota a mesma semântica de bloqueio que o enviar função: os dados são copiados do buffer ou buffers para o buffer do transporte. Se o soquete não estiver sendo desbloqueado e orientado ao fluxo e não houver espaço suficiente no buffer do transporte, WSASendMsg retornará com apenas parte dos buffers do aplicativo sendo consumidos. Por outro lado, essa situação de buffer em um soquete de bloqueio resulta em bloqueio de WSASendMsg até que todo o conteúdo do buffer do aplicativo tenha sido consumido.

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

Para soquetes orientados a mensagens, deve-se tomar cuidado para não exceder o tamanho máximo da mensagem do provedor subjacente, que pode ser obtido obtendo obtendo o valor da opção de soquete SO_MAX_MSG_SIZE. Se os dados forem muito longos para passar atomicamente pelo protocolo subjacente, o erro WSAEMSGSIZE será retornado e nenhum dado será transmitido.

Em um soquete IPv4 do tipo SOCK_DGRAM ou SOCK_RAW, um aplicativo pode especificar o endereço de origem IP local a ser usado para enviar com a função WSASendMsg. Um dos objetos de dados de controle passados na estrutura WSAMSG para a função WSASendMsg pode conter uma estrutura in_pktinfo usada para especificar o endereço de origem IPv4 local a ser usado para envio.

Em um soquete IPv6 do tipo SOCK_DGRAM ou SOCK_RAW, um aplicativo pode especificar o endereço de origem IP local a ser usado para enviar com a função WSASendMsg. Um dos objetos de dados de controle passados na estrutura de WSAMSG para a função WSASendMsg pode conter uma estrutura in6_pktinfo usada para especificar o endereço de origem IPv6 local a ser usado para envio.

Para um soquete de pilha dupla ao enviar datagramas com a função WSASendMsg e um aplicativo deseja especificar um endereço de origem IP local específico a ser usado, o método para lidar com isso depende do endereço IP de destino. Ao enviar para um endereço de destino IPv4 ou um endereço de destino IPv6 mapeado por IPv4, um dos objetos de dados de controle passados na estrutura de WSAMSG apontado pelo parâmetro lpMsg deve conter uma estrutura in_pktinfo que contém o endereço de origem IPv4 local a ser usado para envio. Ao enviar para um endereço de destino IPv6 que não é um endereço IPv6 mapeado para IPv4, um dos objetos de dados de controle passados na estrutura de WSAMSG apontado pelo parâmetro lpMsg deve conter uma estrutura in6_pktinfo que contém o endereço de origem IPv6 local a ser usado para envio.

Observação A opção de soquete SO_SNDTIMEO se aplica somente a soquetes de bloqueio.

Observação A conclusão bem-sucedida de um WSASendMsg não indica que os dados foram entregues com êxito.

Observação Ao emitir uma chamada winsock de bloqueio, como WSASendMsg com o parâmetro lpOverlapped definido como NULL, o 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íncrono) agendada no mesmo thread. A emissão de 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 tentada pelos clientes winsock.

dwFlags

O parâmetro de entrada dwFlags pode ser usado para influenciar o comportamento da invocação de função além das opções especificadas para o soquete associado. Ou seja, a semântica dessa função é determinada pelas opções de soquete e pelo parâmetro dwFlags. Este último é construído usando o operador OR bit a bit com qualquer um dos valores a seguir.

Valor	Significado
MSG_DONTROUTE	Especifica que os dados não devem estar sujeitos ao roteamento. Um provedor de serviços do Windows Sockets pode optar por ignorar esse sinalizador.
MSG_PARTIAL	Especifica que lpMsg->lpBuffers contém apenas uma mensagem parcial. Observe que o código de erro WSAEOPNOTSUPP será retornado por transportes que não dão suporte a transmissões parciais de mensagens.

Os valores possíveis para parâmetro dwFlags são definidos no arquivo de cabeçalho Winsock2.h.

Na saída, o dwFlags membro da estrutura de do WSAMSG apontado pelo parâmetro lpMsg não é usado.

E/S do soquete sobreposto

Se uma operação sobreposta for concluída imediatamente, WSASendMsg retornará um valor igual a zero e o parâmetro lpNumberOfBytesSent será atualizado com o número de bytes enviados. Se a operação sobreposta for iniciada com êxito e for concluída posteriormente, WSASendMsg retornará SOCKET_ERROR e indicará o código de erro WSA_IO_PENDING. Nesse caso, lpNumberOfBytesSent 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 especificado) ou por meio do parâmetro lpcbTransfer em WSAGetOverlappedResult .

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

A função WSASendMsg usando E/S sobreposta pode ser chamada dentro da rotina de conclusão de umWSARecv anterior, WSARecvFrom, LPFN_WSARECVMSG (WSARecvMsg), WSASend, WSASendMsg ou função WSASendTo. 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 de 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 umNULL não lpCompletionRoutine e chamadas posteriores WSAGetOverlappedResult para a mesma solicitação de E/S sobreposta pode não definir o parâmetro fWait para essa invocação de WSAGetOverlappedResult para 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, por exemplo, com WSAWaitForMultipleEvents chamado com o parâmetro fAlertable definido como TRUE.

Os provedores de transporte permitem que um aplicativo invoque operações de envio e recebimento de dentro do contexto da rotina de conclusão de E/S do soquete e garantam que, 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 protótipo da rotina de conclusão é o seguinte.


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

A função 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 da operação sobreposta, conforme indicado pelo parâmetro lpOverlapped. O parâmetro cbTransferred indica o número de bytes enviados. Atualmente, não há valores de sinalizador definidos e o parâmetro dwFlags será zero. A função CompletionRoutine não retorna um valor.

O retorno dessa função permite a invocação de outra rotina de conclusão pendente para o soquete. 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 enviados na mesma ordem em que são especificados.

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

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 8.1, Windows Vista [aplicativos da área de trabalho \| Aplicativos UWP]
servidor com suporte mínimo	Windows Server 2008 [aplicativos da área de trabalho \| Aplicativos UWP]
da Plataforma de Destino	Windows
cabeçalho	winsock2.h (inclua Mswsock.h)
biblioteca	Ws2_32.lib
de DLL	Ws2_32.dll