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á.

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.

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.

Requisitos

Confira também

WPUQueueApc

LPWSPGetOverlappedResult

LPWSPSocket