Função de retorno de chamada LPWSPSEND (ws2spi.h)
A função LPWSPSend envia dados em um soquete conectado.
Sintaxe
LPWSPSEND Lpwspsend;
int Lpwspsend(
[in] SOCKET s,
[in] LPWSABUF lpBuffers,
[in] DWORD dwBufferCount,
[out] LPDWORD lpNumberOfBytesSent,
[in] DWORD dwFlags,
[in] LPWSAOVERLAPPED lpOverlapped,
[in] LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine,
[in] LPWSATHREADID lpThreadId,
[out] LPINT lpErrno
)
{...}
Parâmetros
[in] s
Um descritor que identifica um soquete conectado.
[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 LPWSPSend é 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] 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 envio for concluída imediatamente, LPWSPSend 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. | |
| 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. | |
| O parâmetro lpBuffers não está totalmente contido em uma parte válida do espaço de endereço do usuário. | |
| A conexão foi interrompida devido à redefinição do host remoto. | |
| A conexão foi interrompida porque a atividade de manutenção de funcionamento detectou uma falha enquanto a operação estava em andamento. | |
| O soquete não está conectado. | |
| 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 LPWSPSend em um soquete depois que LPWSPShutdown tiver sido invocado com a configuração como SD_SEND ou SD_BOTH. | |
| **Soquetes sobrepostos do Windows NT:**: 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. | |
| 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 LPWSPSend é usada para gravar dados de saída de um ou mais buffers em um soquete orientado à conexão especificado por s. Ele também pode ser usado, no entanto, em soquetes sem conexão que têm um endereço par padrão estipulado estabelecido por meio da função LPWSPConnect .
Para soquetes sobrepostos (criados usando LPWSPSocket com sinalizador WSA_FLAG_OVERLAPPED) isso ocorrerá usando E/S sobreposta, a menos que lpOverlapped e lpCompletionRoutine sejam nulos, 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 LPWSPSend 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, LPWSPSend retornará com apenas parte dos buffers fornecidos sendo consumidos. Dada a mesma situação de buffer e um soquete de bloqueio, LPWSPSend será bloqueado até que todo o conteúdo do buffer fornecido tenha sido 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 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.
Observe que a conclusão bem-sucedida de um LPWSPSend não indica que os dados foram entregues com êxito.
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_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 para mensagens que não dão suporte a transmissões parciais de mensagens. |
Se uma operação sobreposta for concluída imediatamente, LPWSPSend 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, LPWSPSend 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 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 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. O cliente SPI do Windows Sockets pode 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 chama posteriormente 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.
Um provedor de serviços organiza uma função a ser executada no contexto adequado de thread e processo chamando WPUQueueApc. Essa função pode ser chamada de qualquer contexto de processo e thread, até mesmo um contexto diferente do thread e do processo que foi usado para iniciar a operação sobreposta.
Um provedor de serviços organiza uma função a ser executada no thread adequado chamando WPUQueueApc. Observe que essa função deve ser invocada enquanto estiver no contexto do mesmo processo (mas não necessariamente o mesmo thread) que foi usado para iniciar a operação sobreposta. É responsabilidade do provedor de serviços organizar para que esse contexto de processo esteja ativo antes de chamar WPUQueueApc.
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
);
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 podem 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 |