WSPSendTo
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
9/8/2008
Essa função envia dados para um destino específico usando E/S sobrepostos.
Syntax
int WSPSendTo(
SOCKET s,
LPWSABUF lpBuffers,
DWORD dwBufferCount,
LPDWORD lpNumberOfBytesSent,
DWORD dwFlags,
const struct sockaddr FAR* lpTo,
int iTolen,
LPWSAOVERLAPPED lpOverlapped,
LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine,
LPWSATHREADID lpThreadId,
LPINT lpErrno
);
Parameters
- s
[no] Um descritor identificando um Soquete.
- lpBuffers
[no] Um ponteiro para uma matriz de WSABUF estruturas. Cada WSABUF estrutura contém um ponteiro para uma reserva e o comprimento da reserva. Esta matriz deve permanecer válido para a duração da operação de envio.
- dwBufferCount
[no] O número de WSABUF Estruturas in a lpBuffers matriz.
- lpNumberOfBytesSent
[out] Um ponteiro para o número de bytes enviados por este chamar.
- dwFlags
[no] Especifica a maneira na qual o chamar é feita.
- lpTo
[no] Um opcional ponteiro para o endereço de Soquete de destino.
- iTolen
[no] O tamanho do endereço em lpTo.
- lpOverlapped
[no] Um ponteiro para um WSAOVERLAPPED estrutura (ignorada para Soquetes nonoverlapped).
- lpCompletionRoutine
[no] Um ponteiro para o rotina chamado de conclusão quando a operação de envio for concluída (ignorado para Soquetes nonoverlapped).
- lpThreadId
[no] Um ponteiro para um WSATHREADID estrutura a ser usado, o provedor para determinar o segmento para executar.
- lpErrno
[out] Um ponteiro para o código de erro.
Return Value
Se nenhum erro e o operação de recebimento concluiu imediatamente, essa função retornará zero. Observe que neste maiúsculas e minúsculas a rotina de conclusão, se especificado, será já foram enfileirado. Caso contrário, será retornado um valor de SOCKET_ERROR e um código de erro específico está disponível em lpErrno. O código de erro WSA_IO_PENDING indica que a operação sobreposta foi iniciada com êxito e que conclusão será indicada em um tempo posterior. Quaisquer outros código de erro indica que nenhuma operação sobreposta foi iniciada e nenhuma indicação de conclusão será ocorrer.
A seguinte tabela mostra os códigos de erro possível.
| Valor de erro | Descrição |
|---|---|
WSAENETDOWN |
falha no subsistema de rede. |
WSAEACCES |
Solicitada endereço é um transmitir endereço, mas o apropriado sinalizador não foi definido. |
WSAEINPROGRESS |
Bloquear chamar Soquetes do Windows é em andamento, ou o serviço provedor ainda é processamento um função callback. |
WSAEFAULT |
O lpBuffers Ou lpTo Parâmetros não fazem parte de espaço de endereço de usuário, ou a lpTo parâmetro é muito pequeno. |
WSAENETRESET |
Conexão foi interrompida detectar uma falha enquanto a operação foi atividade keep-alive devido a em andamento. |
WSAENOBUFS |
Provedor Soquetes do Windows reporta um bloqueio reserva. |
WSAENOTCONN |
Soquete não está conectados (orientado à conexão soquetes somente). |
WSAENOTSOCK |
O descritor não é um Soquete. |
WSAEOPNOTSUPP |
MSG_OOB foi especificado, mas o Soquete não é transmitir-estilo such as tipo SOCK_STREAMDados, OOB Não Não com suporte no associado domínio a comunicação com este Soquete, MSG_PARTIAL não é com suporte, ou o Soquete está unidirecional e oferece suporte a receber somente operações. |
WSAESHUTDOWN |
Soquete foi desligado; Não é possível usar WSPSendTo Em um Soquete depois WSPShutdown Tem sido chamado com Como Definido como SD_SEND ou SD_BOTH. |
WSAEWOULDBLOCK |
Soquetes sobrepostos: Há muitos pendente sobreposto solicitações E/S. Nonoverlapped soquetes: O Soquete está marcado como de não bloqueio e a operação de envio não pode ser concluída imediatamente. |
WSAEMSGSIZE |
Soquete é orientado a mensagem, e a mensagem é maior do que o máximo com suporte pela subjacente transporte. |
WSAEINVAL |
Soquete não foi ligado com WSPBind, ou o Soquete não é criado com o sinalizador sobrepostos. |
WSAECONNABORTED |
Circuito virtual foi finalizado devido a um tempo limite ou outra falha. |
WSAECONNRESET |
Circuito virtual foi redefinir pelo remoto lado. |
WSAEADDRNOTAVAIL |
Endereço remoto não é um válido endereço (por exemplo, ADDR_ANY). |
WSAEAFNOSUPPORT |
Endereços de família especificado não podem ser usados com este Soquete. |
WSAEDESTADDRREQ |
Endereço de destino é exigido. |
WSAENETUNREACH |
Rede não pode ser alcançada a partir este hospedar nesse tempo. |
WSA_OPERATION_ABORTED |
Sobreposto operação foi cancelada devido a o encerramento da Soquete. |
Remarks
Essa função é geralmente usado em um sem conexão Soquete especificado por s Para enviar uma datagrama contida em um ou mais buffers para um Soquete ponto específico identificado pelo lpTo parâmetro. Mesmo se o sem conexão Soquete tenha sido previamente conectado a um endereço específico com o conectar função, lpTo Substitui o endereço destino para que datagrama específico somente. Em um Soquete Connection-Oriented, o lpTo e iToLen Os parâmetros são ignorados; Nesta maiúsculas e minúsculas o WSPSendTo função é equivalente a WSPSend.
Para sobreposto soquetes (criados usando WSPSocket com sinalizador WSA_FLAG_OVERLAPPED) isso irá ocorrer usando sobreposto E/S, a menos que ambas lpOverlapped e lpCompletionRoutine São NULL na qual maiúsculas e minúsculas o Soquete é tratado como um Soquete nonoverlapped. Uma indicação de conclusão irá ocorrer (chamada de rotina de conclusão) ou configuração de um objeto evento quando o buffer(s) fornecido tem sido consumida pelo transporte. Se a operação não completo imediatamente, o status de conclusão finais é recuperado por meio de rotina de conclusão ou WSPGetOverlappedResult.
Para soquetes nonoverlapped, os parâmetros lpOverlapped, lpCompletionRoutine, e lpThreadId são ignorados e WSPSendTo adota a regular síncrono semântica. Dados são copiados dos buffers fornecidos para reserva do transporte. Se for o Soquete de não bloqueio e transmitir orientados e não há espaço suficiente na reserva do transporte, WSPSendTo Retornará com somente parte de Buffers do cliente de Windows Sockets SPI ter sido consumido. Recebe a mesma situação reserva e um bloqueio Soquete, WSPSendTo Será bloco até que todo o conteúdo reserva do cliente de Windows Sockets SPI ter sido consumido.
A matriz de WSABUF Estruturas apontado pelo lpBuffers parâmetro é temporário. Se essa operação for concluída de uma maneira sobreposta, é responsabilidade do provedor de serviços para captura essas WSABUF Estruturas antes de retornar deste chamar. Isso permite que aplicativos compilar stack-based WSABUF matrizes.
Para soquetes orientado a mensagem, deve ter cuidado para não exceder o tamanho máximo de mensagem do subjacente transporte, que pode ser obtido por obter o valor da opção Soquete SO_MAX_MSG_SIZE. Se a dados é muito longo para transmitir atomicamente através de subjacente protocolo WSAEMSGSIZE o erro é retornado, e não dados são transmitidos.
Observação
O bem-sucedido conclusão de uma WSPSendTo Não indica que os dados foi entregue com êxito.
iFlags Pode ser usado para influenciam o comportamento da chamada de função além de opções especificadas para o associado Soquete. Isto é, a semântica desta função é determinada pelas opções de Soquete e o dwFlags parâmetro. O segundo é construído usando o operador bit a bit OR com valores específicos. A seguinte tabela mostra esses valores.
| Valor | Descrição |
|---|---|
MSG_DONTROUTE |
Especifica que os dados não devem ser assunto para roteamento. Um provedor serviço Soquetes do Windows pode escolher para ignorar este sinalizador. |
MSG_OOB |
Envia dados OOB (transmitir-estilo Soquete such as SOCK_STREAM Somente). |
MSG_PARTIAL |
Especifica que lpBuffers Contém apenas uma mensagem parcial. Observe que a código de erro WSAEOPNOTSUPP será retornado por transportes que não suporte parcial mensagem transmissões. |
.gif)
Sobreposto Soquete E/S
Se uma operação sobreposta conclusão imediatamente, essa função retorna um valor de zero e o lpNumberOfBytesSent parâmetro é atualizado com o número de bytes enviados. Se a operação sobreposta é iniciada com êxito e serão posteriormente, completo WSPSendTo Retorna SOCKET_ERROR e indica código de erro WSA_IO_PENDING. Neste maiúsculas e minúsculas, lpNumberOfBytesSent não é atualizado. Quando a operação sobreposta conclui a quantidade de dados transferidos é indicada através de cbTransferred parâmetro na rotina de conclusão (se especificado) ou por meio de lpcbTransfer parâmetro no WSPGetOverlappedResult.
Provedores devem permitir que esta função seja chamado de dentro da rotina de conclusão de uma anterior WSPRecv, WSPRecvFrom, WSPSend Ou WSPSendTo função. No entanto, para um determinado Soquete, não podem ser aninhadas rotinas de conclusão E/S. Isso permite tempo-confidencial transmissões dados para ocorrer inteiramente em um contexto preemptiva.
O lpOverlapped parâmetro deve ser válido para a duração da operação sobreposta. Se múltiplo operações E/S são simultaneamente pendente, cada deve fazer referência um separar sobreposto estrutura. O seguinte mostra amostra de código o WSAOVERLAPPED formato estrutura.
typedef struct _WSAOVERLAPPED {
DWORD Internal; // reserved
DWORD InternalHigh; // reserved
DWORD Offset; // reserved
DWORD OffsetHigh; // reserved
WSAEVENT hEvent;
} WSAOVERLAPPED, FAR * LPWSAOVERLAPPED;
Se a pasta lpCompletionRoutine parâmetro é NULL, os sinais provedor serviço o hEvent membro de lpOverlapped Quando a operação sobreposta conclui se ela contiver um válido evento objeto identificador. Os clientes SPI Soquetes do Windows podem usar WSPGetOverlappedResult Para esperar ou pesquisar no objeto de evento.
Se lpCompletionRoutine não é NULL, o hEvent membro será ignorado e pode ser usado pelo cliente de Windows Sockets SPI para transmitir informações contexto para a rotina de conclusão. Um cliente que passa um não-NULL lpCompletionRoutine e chamadas posteriores WSAGetOverlappedResult para o mesmo E/S sobreposto solicitação não pode ser definido de fWait parâmetro para essa chamada de WSAGetOverlappedResult para TRUE. Neste maiúsculas e minúsculas o uso das hEvent membro é indefinido e tentando esperar na hEvent membro poderia gerar resultados imprevisíveis.
É responsabilidade do provedor de serviços para organizar de invocação de rotina specified–completion a cliente quando concluir a operação sobreposta. Porque a rotina de conclusão deve ser executado no contexto do mesmo segmento que iniciou a operação sobreposta, ele não pode ser chamado diretamente do provedor de serviço.
O seguinte amostra de código mostra o protótipo para a rotina de conclusão Client-supplied.
void CALLBACK CompletionRoutine (
IN DWORD dwError,
IN DWORD cbTransferred,
IN LPWSAOVERLAPPED lpOverlapped,
IN DWORD dwFlags
);
CompletionRoutine é um espaço reservado um nome função Client-supplied. dwError Especifica o status de conclusão para a operação sobreposta conforme indicado pelo lpOverlapped. cbTransferred Especifica o número de bytes enviados. Há valores sinalizador são definidos no momento e o dwFlags valor será zero. Essa função não retorna um valor.
As rotinas de conclusão podem ser chamado em qualquer ordem, embora não necessariamente na mesma ordem que as operações sobrepostas são concluídas. No entanto, as garantias provedor serviço para o cliente que lançado buffers são enviadas na mesma ordem que eles são fornecidos.
Requirements
| Header | ws2spi.h |
| Library | Ws2.lib |
| Windows Embedded CE | Windows CE .NET 4.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |