Função de retorno de chamada LPWSPSENDTO (ws2spi.h)
A função LPWSPSendTo envia dados para um destino específico usando E/S sobreposta.
Sintaxe
LPWSPSENDTO Lpwspsendto;
int Lpwspsendto(
[in] SOCKET s,
[in] LPWSABUF lpBuffers,
[in] DWORD dwBufferCount,
[out] LPDWORD lpNumberOfBytesSent,
[in] DWORD dwFlags,
[in] const sockaddr *lpTo,
[in] int iTolen,
[in] LPWSAOVERLAPPED lpOverlapped,
[in] LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine,
[in] LPWSATHREADID lpThreadId,
[out] LPINT lpErrno
)
{...}
Parâmetros
[in] s
Um descritor que identifica um soquete.
[in] lpBuffers
Um ponteiro para uma matriz de estruturas WSABUF . Cada estrutura WSABUF contém um ponteiro para um buffer e o comprimento do buffer, em bytes. Para um aplicativo Winsock, depois que a função LPWSPSendTo é chamada, o sistema possui esses buffers e o aplicativo pode não acessá-los. Os buffers de dados referenciados em cada estrutura WSABUF pertencem ao sistema e seu aplicativo pode não acessá-los durante o tempo de vida da chamada.
[in] dwBufferCount
O número de estruturas WSABUF na matriz lpBuffers .
[out] lpNumberOfBytesSent
Um ponteiro para o número de bytes enviados por essa chamada.
[in] dwFlags
Um conjunto de sinalizadores que especifica a maneira como a chamada é feita.
[in] lpTo
Um ponteiro opcional para o endereço do soquete de destino na estrutura sockaddr .
[in] iTolen
O tamanho, em bytes, do endereço apontado pelo parâmetro lpTo .
[in] lpOverlapped
Um ponteiro para uma estrutura WSAOverlapped (ignorada 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 foi concluída (ignorado para soquetes não sobrepostos).
[in] lpThreadId
Um ponteiro para uma estrutura WSATHREADID a ser usada pelo provedor em uma chamada subsequente para WPUQueueApc. O provedor deve armazenar a estrutura WSATHREADID referenciada (não o ponteiro para o mesmo) até que a função WPUQueueApc retorne.
[out] lpErrno
Um ponteiro para o código de erro.
Valor retornado
Se nenhum erro ocorrer e a operação de recebimento for concluída imediatamente, LPWSPSendTo retornará zero. Observe que, nesse caso, a rotina de conclusão, se especificada, já terá sido enfileirada. Caso contrário, um valor de SOCKET_ERROR será retornado e um código de erro específico estará disponível no lpErrno. 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 nenhuma operação sobreposta foi iniciada e nenhuma indicação de conclusão ocorrerá.
| Código do Erro | Significado |
|---|---|
| O subsistema de rede falhou. | |
| O endereço solicitado é um endereço de transmissão, mas o sinalizador apropriado não foi definido. | |
| A chamada (Bloqueio) foi cancelada por meio de LPWSPCancelBlockingCall. | |
| O bloqueio da chamada do Windows Sockets está em andamento ou o provedor de serviços ainda está processando uma função de retorno de chamada. | |
| Os parâmetros lpBuffers ou lpTo não fazem parte do espaço de endereço do usuário ou o parâmetro lpTo é muito pequeno. | |
| A conexão foi interrompida porque a atividade de manutenção de funcionamento detectou uma falha enquanto a operação estava em andamento. | |
| O provedor do Windows Sockets relata um deadlock de buffer. | |
| O soquete não está conectado (somente soquetes orientados à conexão). | |
| O descritor não é um soquete. | |
| 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, MSG_PARTIAL não tem suporte ou o soquete é unidirecional e dá suporte apenas a operações de recebimento. | |
| Soquete foi desligado; Não é possível usar LPWSPSendTo em um soquete depois que LPWSPShutdown tiver sido invocado com a definição de como SD_SEND ou SD_BOTH. | |
| Windows NT: soquetes sobrepostos: há muitas solicitações de E/S sobrepostas pendentes. Soquetes não sobrepostos: o soquete é marcado como não desbloqueado e a operação de envio não pode ser concluída imediatamente. | |
| O soquete é orientado a mensagens e a mensagem é maior do que o máximo suportado pelo transporte subjacente. | |
| O soquete não foi associado ao LPWSPBind ou o soquete não é criado com o sinalizador sobreposto. | |
| O circuito virtual foi encerrado devido a um tempo limite ou outra falha. | |
| O circuito virtual foi redefinido pelo lado remoto. | |
| O endereço remoto não é um endereço válido (por exemplo, ADDR_ANY). | |
| Os endereços na família especificada não podem ser usados com este soquete. | |
| O endereço de destino é necessário. | |
| A rede não pode ser alcançada através deste host neste momento. | |
| A operação sobreposta foi cancelada devido ao fechamento do soquete ou à execução do comando SIO_FLUSH em LPWSPIoctl. |
Comentários
A função LPWSPSendTo normalmente é usada em um soquete sem conexão especificado por s para enviar um datagrama contido em um ou mais buffers para um soquete par específico identificado pelo parâmetro lpTo . Mesmo que o soquete sem conexão tenha sido conectado anteriormente a um endereço específico com a função LPWSPConnect , lpTo substituirá o endereço de destino somente para esse datagrama específico. Em um soquete orientado para conexão, os parâmetros lpTo e iToLen são ignorados; nesse caso, a função LPWSPSendTo é equivalente a LPWSPSend.
Para soquetes sobrepostos (criados usando LPWSPSocket com sinalizador WSA_FLAG_OVERLAPPED) isso ocorrerá usando E/S sobreposta, a menos que lpOverlapped e lpCompletionRoutine sejam NULL , nesse caso, o soquete é tratado como um soquete não sobreposto. Ocorrerá uma indicação de conclusão (invocação da rotina de conclusão ou configuração de um objeto de evento) quando os buffers fornecidos forem consumidos pelo transporte. 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 LPWSPGetOverlappedResult.
Para soquetes não sobrepostos, os parâmetros lpOverlapped, lpCompletionRoutine e lpThreadId são ignorados e LPWSPSendTo adota a semântica síncrona regular. Os dados são copiados dos buffers fornecidos 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, LPWSPSendTo retornará com apenas parte dos buffers do cliente SPI do Windows Sockets sendo consumidos. Dada a mesma situação de buffer e um soquete de bloqueio, LPWSPSendTo será bloqueado até que todo o conteúdo do buffer do cliente SPI do Windows Sockets seja consumido.
A matriz de estruturas WSABUFapontadas pelo parâmetro lpBuffers é transitória. Se essa operação for concluída de maneira sobreposta, será responsabilidade do provedor de serviços capturar essas estruturas WSABUF antes de retornar dessa chamada. Isso permite que os aplicativos criem matrizes WSABUF baseadas em pilha.
Para soquetes orientados a mensagens, deve-se tomar cuidado para não exceder o tamanho máximo da mensagem do transporte 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.
Observe que a conclusão bem-sucedida de um LPWSPSendTo não indica que os dados foram entregues com êxito.
O parâmetro iFlags 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_OOB | Envia dados OOB (soquete no estilo de fluxo, como somente SOCK_STREAM). |
| MSG_PARTIAL | Especifica que 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. |
Se uma operação sobreposta for concluída imediatamente, LPWSPSendTo 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, LPWSPSendTo retornará SOCKET_ERROR e indicará o código de erro WSA_IO_PENDING. Nesse caso, lpNumberOfBytesSent não é atualizado. Quando a operação sobreposta conclui, 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 LPWSPGetOverlappedResult.
Os provedores devem permitir que essa função seja chamada de dentro da rotina de conclusão de uma função LPWSPRecv, LPWSPRecvFrom, LPWSPSend ou LPWSPSendTo anterior. No entanto, para um determinado soquete, as rotinas de conclusão de E/S não podem ser aninhadas. 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 sobreposta separada. A estrutura WSAOverlapped é definida em sua própria página de referência.
Se o parâmetro lpCompletionRoutine for nulo, o provedor de serviços sinalizará o membro hEvent de lpOverlapped quando a operação sobreposta for concluída se contiver um identificador de objeto de evento válido. Os clientes SPI do Windows Sockets podem usar LPWSPGetOverlappedResult para aguardar ou sondar o objeto de evento.
Se lpCompletionRoutine não for nulo, o membro hEvent será ignorado e poderá ser usado pelo cliente SPI do Windows Sockets para passar informações de contexto para a rotina de conclusão. Um cliente que passa um lpCompletionRoutine não nulo 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 membro hEvent é indefinido e a tentativa de aguardar o membro hEvent produziria resultados imprevisíveis.
É responsabilidade do provedor de serviços organizar a invocação da rotina de conclusão especificada pelo cliente quando a operação sobreposta for concluída. Como a rotina de conclusão deve ser executada no contexto do mesmo thread que iniciou a operação sobreposta, ela não pode ser invocada diretamente do provedor de serviços. O Ws2_32.dll oferece um mecanismo de APC (chamada de procedimento assíncrono) para facilitar a invocação de rotinas de conclusão.
Um provedor de serviços organiza uma função a ser executada no thread adequado chamando WPUQueueApc. Essa função pode ser chamada de qualquer contexto de processo e thread, até mesmo de um contexto diferente do thread e do processo que foi usado para iniciar a operação sobreposta.
A função WPUQueueApc usa como parâmetros de entrada um ponteiro para uma estrutura WSATHREADID (fornecida ao provedor por meio do parâmetro de entrada lpThreadId ), um ponteiro para uma função APC a ser invocada e um valor de contexto que é posteriormente passado para a função APC. Como apenas um único valor de contexto está disponível, a função APC em si não pode ser a rotina de conclusão especificada pelo cliente. Em vez disso, o provedor de serviços deve fornecer um ponteiro para sua própria função APC, que usa o valor de contexto fornecido para acessar as informações de resultado necessárias para a operação sobreposta e, em seguida, invoca a rotina de conclusão especificada pelo cliente.
O protótipo para a rotina de conclusão fornecida pelo cliente é o seguinte.
void CALLBACK
CompletionRoutine(
IN DWORD dwError,
IN DWORD cbTransferred,
IN LPWSAOVERLAPPED lpOverlapped,
IN DWORD dwFlags
);
O CompletionRoutine é um espaço reservado para um nome de função fornecido pelo cliente. dwError especifica o status de conclusão para a operação sobreposta, conforme indicado por lpOverlapped. cbTransferred especifica o número de bytes enviados. Nenhum valor de sinalizador está definido no momento e o valor dwFlags será zero. Essa função não retorna um valor.
As rotinas de conclusão podem ser chamadas em qualquer ordem, embora não necessariamente na mesma ordem em que as operações sobrepostas sejam concluídas. No entanto, o provedor de serviços garante ao cliente que os buffers postados sejam enviados na mesma ordem em que são fornecidos.
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 poderão falhar se o thread for fechado antes da conclusão das operações. Consulte ExitThread para obter mais informações.
Requisitos
| 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] |
| Cabeçalho | ws2spi.h |