WSASendTo

9/8/2008

Essa função envia dados para um destino específico, usando sobreposto E/S onde aplicável.

Syntax

int WSASendTo(
  SOCKET s,
  LPWSABUF lpBuffers,
  DWORD dwBufferCount,
  LPDWORD lpNumberOfBytesSent,
  DWORD dwFlags,
  const struct sockaddr FAR* lpTo,
  int iToLen,
  LPWSAOVERLAPPED lpOverlapped,
  LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

Parameters

• s
  [no] Descritor identificando um Soquete possivelmente conectado.

• lpBuffers
  [no] 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] Número de WSABUF Estruturas in a lpBuffers matriz.

• lpNumberOfBytesSent
  [out] Ponteiro para o número de bytes enviados por este chamar se a operação E/S conclui imediatamente.

• dwFlags
  [no] Indicador especificando a maneira na qual o chamar é feita.

• lpTo
  [no] Ponteiro opcional para o endereço de Soquete de destino.

• iToLen
  [no] Tamanho do endereço na lpTo parâmetro.

• lpOverlapped
  [no] Ponteiro para um WSAOVERLAPPED estrutura (ignorada para Soquetes nonoverlapped).

• lpCompletionRoutine
  [no] Ponteiro para o rotina chamado de conclusão quando a operação de envio for concluída (ignorado para Soquetes nonoverlapped).

Return Value

Se nenhum erro e a operação de envio concluiu imediatamente, essa função retornará zero. As estruturas sobrepostas são atualizadas com os resultados de recebimento e o associado evento é signalled.

Em Windows Embedded CE, o objeto de conclusão não vai ser signalled. Se um erro ocorrer, será retornado um valor de SOCKET_ERROR, e um código de erro específicos podem ser recuperadas por chamado WSAGetLastError. 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 a operação sobreposta não foi iniciada com êxito e nenhuma indicação de conclusão será ocorrer. A seguinte tabela mostra uma lista dos códigos de erro possível.

Código de erro	Descrição
WSANOTINITIALISED	Um bem-sucedido WSAStartup chamar deve ocorrer antes de usar essa função.
WSAENETDOWN	Falha no subsistema da rede.
WSAEACCES	O endereço solicitado é um transmitir endereço, mas o apropriado sinalizador não foi definido.
WSAEINTR	O Soquete foi fechada.
WSAEINPROGRESS	Um bloqueio é chamar sockets do Windows (Winsock) em andamento, ou o serviço provedor ainda é processamento um função callback.
WSAEFAULT	O lpBuffers, lpTo, lpOverlapped, lpNumberOfBytesSent, ou lpCompletionRoutine parâmetro não for parte de espaço de endereço de usuário, ou a lpTo argumento é muito pequeno.
WSAENETRESET	A conexão foi interrompida porque a atividade de manutenção de funcionamento detectou uma falha enquanto a operação estava em andamento.
WSAENOBUFS	O provedor Soquetes do Windows reporta um bloqueio reserva.
WSAENOTCONN	O 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 é estilo transmitir such as tipo SOCK_STREAM, out of banda (OOB) dados 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	O Soquete foi desligado. Não é possível chamar WSASendTo Em um Soquete depois desligamento Tem sido chamado com Como Definido como SD_SEND ou SD_BOTH.
WSAEWOULDBLOCK	Para soquetes sobrepostos, há muitos pendente sobreposto solicitações E/S. Para 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	O Soquete é orientado a mensagem e a mensagem é maior do que o máximo com suporte pela subjacente transporte.
WSAEINVAL	O Soquete não foi ligado com BIND (Soquetes do Windows), ou o Soquete não é criado com o sinalizador sobrepostos.
WSAECONNABORTED	O circuito virtual foi finalizado devido a um tempo limite ou outra falha.
WSAECONNRESET	O circuito virtual foi redefinir pelo remoto lado.
WSAEADDRNOTAVAIL	O remoto endereço não é um válido endereço (such as ADDR_ANY).
WSAEAFNOSUPPORT	Endereços de família especificado não podem ser usados com este Soquete.
WSAEDESTADDRREQ	Um endereço destino é exigido.
WSAENETUNREACH	A rede não pode ser alcançada através deste host neste momento.
WSA_IO_PENDING	Uma operação sobreposta foi iniciada com êxito e conclusão será indicada em um tempo posterior.
WSA_OPERATION_ABORTED	A operação sobreposta foi cancelada devido a o encerramento da Soquete.

Remarks

Essa função fornece funcionalidade over and Above o padrão SendTo função no seguinte Duas áreas importantes:

• Ele pode ser usado em conjunto com soquetes sobrepostos para executar sobreposto envia operações.
• Ele permite múltiplo enviar buffers sejam especificadas, ativando um dispersão/tipo coletar de E/S.

Essa função é geralmente usado em um sem conexão Soquete especificado pelo Soquete 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 usando o conectar (Soquetes do Windows) função para um endereço específico, 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; Neste maiúsculas e minúsculas, o WSASendTo é equivalente a WSASend.

Para sobreposto soquetes (criados usando WSASocket Com o sinalizador WSA_FLAG_OVERLAPPED), enviar dados usa E/S sobreposto, a menos que ambas lpOverlapped e lpCompletionRoutine são NULL, no qual maiúsculas e minúsculas o Soquete é tratado como um Soquete nonoverlapped. Uma indicação de conclusão irá ocorrer (chamando a rotina de conclusão ou configuração de um objeto evento) quando os buffers fornecidos tem sido consumidos 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 WSAGetOverlappedResult.

Se os dois lpOverlapped e lpCompletionRoutine São NULL, o Soquete nessa função será tratado como um Soquete nonoverlapped.

Para nonoverlapped soquetes, (os dois últimos parâmetroslpOverlapped e lpCompletionRoutine) são ignorados e WSASendTo Adota os mesmos bloqueio semântica como envio. Dados são copiados dos buffers fornecidos para reserva do transporte. Se for o Soquete de não bloqueio e fluxo-orientação, e não há espaço suficiente na reserva do transporte, WSASendTo Retorna com somente parte de buffers do aplicativo ter sido consumido. Recebe a mesma situação reserva e um bloqueio Soquete, WSASendTo Será bloco até que todo o conteúdo reserva do aplicativo a ter sido consumido.

A matriz de WSABUF Estruturas indicado pelo lpBuffers parâmetro é temporário. Se essa operação é 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, o erro é retornado WSAEMSGSIZE e não dados é transmitida.

O bem-sucedido conclusão de uma WSASendTo chamar não indica que os dados foi entregue com êxito.

O dwFlags parâmetro 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. A seguinte tabela mostra os valores que são usados com o operador bit a bit OR para construção de dwFlags parâmetro.

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	Enviar out of dados banda (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.

Sobreposto Soquete E/S

Observação

Para Windows Embedded CE, evite especificando rotinas de conclusão para operações E/S sobrepostas.Porque Windows Embedded CE não suporte assíncrono chamadas procedimento (APCs), que ocorrer no segmento de chamado, tem o OS Para girar um segmento para cada chamar que especifica uma rotina de conclusão.Com um segmento criado por função chamar, Usando rotinas de conclusão com E/S sobreposto rapidamente pode ficar muito consumindo memória.Usar eventos é recomendado em vez disso.

Se uma operação sobreposta conclui imediatamente, WSASendTo 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 WSASendTo Retorna SOCKET_ERROR e indica código de erro WSA_IO_PENDING. Neste maiúsculas e minúsculas, lpNumberOfBytesSent não é atualizado. Quando concluir a operação sobreposta, a quantidade de dados transferidos é indicada através de cbTransferred parâmetro na rotina de conclusão (se especificado) ou através de lpcbTransfer parâmetro no WSAGetOverlappedResult.

O WSASendTo função pode ser chamado de dentro da rotina de conclusão de uma anterior WSARecv, WSARecvFrom, WSASend, ou WSASendTo função. Isso permite tempo-confidencial transmissões dados para ocorrer inteiramente em um contexto Pre-emptive.

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 WSAOVERLAPPED estrutura.

Se a pasta lpCompletionRoutine parâmetro é NULL, o hEvent parâmetro de lpOverlapped é sinalizado quando concluir a operação sobreposta se ela contiver um válido evento objeto identificador. Um aplicativo pode usar WSAGetOverlappedResult Para esperar ou pesquisar no objeto de evento.

Se lpCompletionRoutine não é NULL, o hEvent parâmetro será ignorado e pode ser usado, o aplicativo para transmitir informações contexto para a rotina de conclusão. Um chamador que passa um não-NULL lpCompletionRoutine parâmetro 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 parâmetro é indefinido e tentando esperar na hEvent parâmetro poderia gerar resultados imprevisíveis.

Provedores de transporte permitem que um aplicativo para invocar enviar e receber operações de dentro de contexto da rotina de conclusão Soquete E/S e garante que, para um determinado Soquete, E/S conclusão rotinas serão não ser aninhadas. Isso permite tempo-confidencial transmissões dados para ocorrer inteiramente em um contexto Pre-emptive.

A seguinte sintaxe mostra o protótipo da rotina de conclusão.

void CALLBACK CompletionRoutine(
  IN DWORD dwError, 
  IN DWORD cbTransferred, 
  IN LPWSAOVERLAPPED lpOverlapped, 
  IN DWORD dwFlags
);

O CompletionRoutine função é um espaço reservado para um nome função Application-defined ou Library-defined. O dwError parâmetro especifica o status de conclusão para a operação sobreposta conforme indicado pelo lpOverlapped. O cbTransferred parâmetro especifica o número de bytes enviados. Atualmente existem há valores sinalizador definidos e dwFlags Será zero. Essa função não retorna um valor.

Retornando desta função permite invocação de pendente outra rotina de conclusão para este Soquete. Todos os aguardando conclusão rotinas são chamado antes espera do segmento de alertable está satisfeita com um código de retorno de WSA_IO_COMPLETION. As rotinas de conclusão podem ser chamado em qualquer ordem, não necessariamente na mesma ordem na qual as operações sobrepostas são concluídas. No entanto, os buffers postados são garantidos para serem enviados na mesma ordem que eles são fornecidos.

Observação

Windows Embedded CE não permite operações sobrepostas e nonoverlapped para ser usado simultaneamente em um Soquete.

Requirements

Header	winsock2.h
Library	Ws2.lib
Windows Embedded CE	Windows CE .NET 4.0 and later
Windows Mobile	Windows Mobile Version 5.0 and later