Função WSASendMsg (winsock2.h)
A função WSASendMsg envia dados e informações de controle opcionais de soquetes conectados e não conectados.
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 WSAMSG que armazena a estrutura msghdr Posix.1g.
[in] dwFlags
Os sinalizadores usados para modificar o comportamento da chamada de função WSASendMsg . Para obter mais informações, consulte Usando dwFlags na seção Comentários.
[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 for NULL para evitar resultados potencialmente incorretos. Esse parâmetro só poderá ser NULL se o parâmetro lpOverlapped não for NULL.
[in] lpOverlapped
Um ponteiro para uma estrutura 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.
Retornar valor
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_ERROR e 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 os códigos de erro.
| Código do erro | Significado |
|---|---|
| O endereço solicitado é um endereço de transmissão, mas o sinalizador apropriado não foi definido. | |
| Para um soquete de datagrama UDP, esse erro indicaria que uma operação de envio anterior resultou em uma mensagem "Porta Inacessível" ICMP. | |
| O parâmetro lpMsg, lpNumberOfBytesSent, lpOverlapped ou 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 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. | |
| 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. | |
| Uma chamada de bloqueio do Windows Socket 1.1 foi cancelada por meio de WSACancelBlockingCall. | |
| O soquete não foi associado à associação ou o soquete não foi criado com o sinalizador sobreposto. | |
| O soquete é orientado a mensagens e a mensagem é maior do que o máximo suportado pelo transporte subjacente. | |
| O subsistema de rede falhou. | |
| Para um soquete de datagrama, este erro indica que a vida útil venceu. | |
| A rede está inacessível. | |
| O provedor do Windows Sockets relata um deadlock de buffer. | |
| O soquete não está conectado. | |
| O descritor não é um soquete. | |
| 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 quaisquer sinalizadores de controle inválidos para WSASendMsg. | |
| O soquete foi desligado; Não é possível chamar a função WSASendMsg em um soquete após o desligamento ter sido invocado com a definição de SD_SEND ou SD_BOTH. | |
| 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 tiver sido excedido. | |
| 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. | |
| Uma chamada WSAStartup bem-sucedida deve ocorrer antes de usar essa função. | |
| Uma operação sobreposta foi iniciada com êxito e a conclusão será indicada posteriormente. | |
| A operação sobreposta foi cancelada devido ao fechamento do soquete ou devido à execução do comando SIO_FLUSH no WSAIoctl. |
Comentários
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 s 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_PARTIAL e MSG_OOB. O membro dwFlags da estrutura WSAMSG apontada pelo parâmetro lpMsg é ignorado na entrada e não é usado na saída.
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 a função send : os dados são copiados do buffer ou buffers para o buffer do transporte. Se o soquete não estiver sendo desbloqueado e orientado a fluxo e não houver espaço suficiente no buffer do transporte, WSASendMsg retornará com apenas parte dos buffers do aplicativo que foram consumidos. Por outro lado, essa situação de buffer em um soquete de bloqueio resulta em bloqueio WSASendMsg até que todo o conteúdo do buffer do aplicativo tenha sido consumido.
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, é necessário ter cuidado para não exceder o tamanho máximo da mensagem do provedor subjacente, que pode ser obtido 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 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 WSAMSG apontada 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 seja um endereço IPv6 mapeado por IPv4, um dos objetos de dados de controle passados na estrutura WSAMSG apontada 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.
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. |
Na saída, o membro dwFlags da estrutura WSAMSG apontada pelo parâmetro lpMsg não é usado.
E/S de soquete sobreposta
Se uma operação sobreposta for concluída imediatamente, WSASendMsg retornará um valor 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, o 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 especificada) ou por meio do parâmetro lpcbTransfer em WSAGetOverlappedResult.A função WSASendMsg usando E/S sobreposta pode ser chamada de dentro da rotina de conclusão de uma função anterior , WSARecv, WSARecvFrom, LPFN_WSARECVMSG (WSARecvMsg),WSASend, WSASendMsg ou WSASendTo. Isso permite que transmissões de dados sensíveis ao tempo ocorram inteiramente dentro de 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 pendentes simultaneamente, 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, posteriormente, chama 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 a tentativa de 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 dentro de 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 para a 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 em Windows 8.1, Windows Server 2012 R2 e posteriores.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows 8.1, Windows Vista [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2008 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | winsock2.h (inclua Mswsock.h) |
| Biblioteca | Ws2_32.lib |
| DLL | Ws2_32.dll |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de