WSPSend

9/8/2008

Essa função envia dados em um Soquete conectado.

Syntax

int WSPSend(
  SOCKET s,
  LPWSABUF lpBuffers,
  DWORD dwBufferCount,
  LPDWORD lpNumberOfBytesSent,
  DWORD dwFlags,
  LPWSAOVERLAPPED lpOverlapped,
  LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine,
  LPWSATHREADID lpThreadId,
  LPINT lpErrno 
);

Parameters

• s
  [no] Descritor identificando um Soquete conectado.

• lpBuffers
  [no] Ponteiro para uma matriz de WSABUFestruturas. 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.

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

• 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).

• lpThreadId
  [no] Ponteiro para um WSATHREADID estrutura a ser usado, o provedor para determinar o segmento para executar.

• lpErrno
  [out] Ponteiro para o código de erro.

Return Value

Se nenhum erro e a operação de envio 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.

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 parâmetro não é totalmente contido em um válido parte espaço de endereço o usuário.
WSAENETRESET	Conexão foi interrompida devido a o remoto hospedar redefinição.
WSAENOBUFS	Conexão foi interrompida detectar uma falha enquanto a operação foi atividade keep-alive devido a em andamento.
WSAENOTCONN	Soquete não conectado.
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 WSPSend 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.
WSA_OPERATION_ABORTED	Sobreposto operação foi cancelada devido a o encerramento da Soquete.

Remarks

A seguinte função é usada para gravar de saída dados de um ou mais buffers em um Soquete Connection-Oriented especificado por s. Ele pode também ser usado, no entanto, em sem conexão soquetes que têm um endereço ponto usar como padrão stipulated estabelecido através de WSPConnect função.

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 WSPSend adota a regular síncrono semântica. Dados são copiados a partir de buffer(s) fornecido 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, WSPSend Retornará com apenas parte dos buffers de fornecido ter sido consumido. Recebe a mesma situação reserva e um bloqueio Soquete, WSPSend Será bloco até que todo o conteúdo fornecido reserva 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 provedor, 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 WSPSend Não indica que os dados foi entregue com êxito.

dwFlags 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 para mensagens que não suporte parcial mensagem transmissões.

Sobreposto Soquete E/S

Se uma operação sobreposta conclui imediatamente, WSPSend 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 WSPSend 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. O cliente Windows Sockets SPI pode 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.

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 para um nome função cliente fornecido. 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

See Also

Reference

WSPSocket
WSPGetOverlappedResult