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 de WSAMSG
[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
[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 |
---|---|
O endereço solicitado é um endereço de difusã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 de "Porta Inacessível" do ICMP. | |
OlpMsg |
|
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 com associaçãoou o soquete não foi criado com o sinalizador sobreposto. | |
O soquete é orientado à mensagem e a mensagem é maior do que o máximo suportado pelo transporte subjacente. | |
O subsistema de rede falhou. | |
Para um soquete de datagrama, esse erro indica que o tempo de vida útil expirou. | |
A rede é inacessível. | |
O provedor de Soquetes do Windows 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 |
|
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. | |
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. | |
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 em WSAIoctl. |
Observações
A função WSASendMsg
O parâmetro
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
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
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
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
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
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.Na saída, o
E/S do soquete sobreposto
Se uma operação sobreposta for concluída imediatamente,A função
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
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
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
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
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 |
Consulte também
WSACancelBlockingCall
do Winsock Functions
referência Winsock