WSPRecv

9/8/2008

Essa função recebe dados em um Soquete.

Syntax

int WSPRecv(
  SOCKET s,
  LPWSABUF lpBuffers,
  DWORD dwBufferCount,
  LPDWORD lpNumberOfBytesRecvd,
  LPDWORD lpFlags,
  LPWSAOVERLAPPED lpOverlapped,
  LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine,
  LPWSATHREADID lpThreadId,
  LPINT lpErrno 
);

Parameters

• s
  [no] Descritor identificando um Soquete conectado.

• lpBuffers
  [in, Out] Ponteiro para uma matriz de WSABUF estruturas. Cada WSABUF estrutura contém um ponteiro para uma reserva e o comprimento da reserva.

• dwBufferCount
  [no] Número de WSABUF Estruturas in a lpBuffers matriz.

• lpNumberOfBytesRecvd
  [out] Ponteiro para o número de bytes recebidos por este chamar.

• lpFlags
  [in, Out] Ponteiro para sinalizadores.

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

• lpCompletionRoutine
  [no] Ponteiro para o rotina chamado de conclusão quando o operação de recebimento for concluída (ignorado para estruturas 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 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 há operações sobrepostas foram iniciadas 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.
WSAENOTCONN	Soquete não conectado.
WSAEINPROGRESS	Bloquear chamar Soquetes do Windows é em andamento, ou o serviço provedor ainda é processamento um função callback.
WSAENETRESET	Conexão foi interrompida detectar uma falha enquanto a operação foi atividade keep-alive devido a em andamento.
WSAEFAULT	O lpBuffers parâmetro não é totalmente contido em um válido parte espaço de endereço o usuário.
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 domínio de comunicação associado com este Soquete, ou o Soquete é unidirecional e oferece suporte a operações de envio somente.
WSAESHUTDOWN	Soquete foi desligado; Não é possível receber através WSPRecv Em um Soquete depois WSPShutdown Tem sido chamado com Como Definido como SD_RECEIVE 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 o operação de recebimento não pode ser concluída imediatamente.
WSAEMSGSIZE	Mensagem era muito grande para caber na reserva especificada e (para não confiável protocolos somente) qualquer parte posterior da mensagem que não encaixam a reserva tenha sido descartado.
WSAEINVAL	Soquete não foi ligado (de exemplo, 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.
WSAEDISCON	Soquete s é orientado a mensagem e o circuito virtual normalmente foi fechado pelo remoto lado.
WSA_IO_PENDING	Uma operação sobreposta foi iniciada com êxito e conclusão será indicada em um tempo posterior.
WSA_OPERATION_ABORTED	Sobreposto operação foi cancelada devido a o encerramento da Soquete.

Remarks

Essa função é usada em soquetes conectados ou ligado sem conexão soquetes especificados pela s parâmetro e é usado para ler de entrada dados. Local do Soquete o endereço deve ser conhecido. Isso pode ser feito explicitamente através WSPBind ou implicitamente através de WSPAccept,WSPConnect,WSPSendTo, ou WSPJoinLeaf.

Para conectado, sem conexão soquetes, essa função restringe os endereços da qual as mensagens recebidas serão aceitas. A função retornará somente mensagens do remoto endereço especificado na conexão. Mensagens de outros endereços (silenciosamente) são descartadas.

Para os soquetes sobrepostos, essa função é usedto postagem um ou mais buffers em que de entrada dados serão colocados como ele se torna disponível, após o qual a indicação de conclusão Client-specified Windows Sockets SPI (chamada de rotina de conclusão) ou configuração de um objeto evento ocorre. Se a operação não completo imediatamente, o status de conclusão finais é recuperado por meio de rotina de conclusão ou WSPGetOverlappedResult.

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

Para nonoverlapped soquetes, o lpOverlapped, lpCompletionRoutine, e lpThreadId Os parâmetros são ignorados. Quaisquer dados que já foi recebidos e armazenada em buffer pelo transporte serão copiados buffers de usuário fornecido. Para a maiúsculas e minúsculas de um bloqueio Soquete com nenhum dados atualmente ter recebidos e armazenada em buffer pelo transporte, o chamar será bloco até dados são recebidos. 2 Soquetes do Windows não definir qualquer padrão bloqueio mecanismo tempo limite para esta função. Para protocolos atuando como byte-protocolos transmitir a pilha tenta retornar tantos dados como assunto possível ao espaço do buffer fornecido e quantidade de dados recebidos disponível. No entanto, o recebimento de um único byte é suficiente para desbloquear o chamador. Não há nenhuma garantia que more than um único byte será retornado. Para protocolos atuando como orientado a mensagem, uma mensagem completa é exigido para desbloquear o chamador.

Um protocolo está atuando como byte ou não - transmitir é determinada pela configuração de XP1_MESSAGE_ORIENTED e XP1_PSEUDO_STREAM em sua estrutura WSAPROTOCOL_INFO e a configuração do sinalizador de MSG_PARTIAL passado para essa função (para protocolos que suporte ele). A seguinte tabela mostra as combinações relevantes; Um asterisco (*) indica que a configuração desse bit não importa neste maiúsculas e minúsculas.

XP1_MESSAGE _ORIENTED	XP1_PSEUDO _STREAM	MSG_PARTIAL	Atua como
Não definido	*	*	byte-transmitir
*	Definir	*	byte-transmitir
Definir	Não definido	Definir	byte-transmitir
Definir	Não definido	Não definido	orientado a mensagem

Os buffers fornecidos são preenchidos a ordem em que eles aparecem na matriz apontado pelo lpBuffers, e os buffers são compactados para que nenhum buracos são criados.

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 essa matriz de ponteiros para WSABUF Estruturas antes de retornar deste chamar. Isso permite que os clientes SPI Soquetes do Windows para compilar stack-based WSABUF matrizes.

Para fluxo de bytes-soquetes estilo (por exemplo, tipo SOCK_STREAM), de entrada dados são colocados dentro de buffers até os buffers são preenchidos, a conexão é fechada, ou internamente armazenada em buffer dados estão esgotados. Independentemente se deve ou não a de entrada dados preenche todos os buffers, ocorre a indicação de conclusão para Soquetes sobrepostos. Para os soquetes orientado a mensagem (por exemplo, tipo SOCK_DGRAM), uma de entrada mensagem é colocada nos buffers fornecidos, up to o tamanho total de buffers fornecidos, e a indicação de conclusão ocorre para Soquetes sobrepostos. Se a mensagem é maior do que os buffers fornecidos, os buffers estão preenchidos com a primeira parte de mensagem. Se estiver MSG_PARTIAL com suporte pelo provedor de serviço, o sinalizador MSG_PARTIAL é definido no lpflags and subsequent receive operation(s) can be used to retrieve the rest of the message. Se não for MSG_PARTIAL com suporte, mas o protocolo é seguro, WSPRecv Gera o Erro WSAEMSGSIZE e um operação de recebimento subseqüentes com uma maior reserva pode ser usada para recuperar a mensagem inteira. Caso contrário, (ou seja, o protocolo é não confiável e faz não suporte MSG_PARTIAL), o dados em excesso é perdida, e WSPRecv Gera o Erro WSAEMSGSIZE.

Para soquetes orientado à conexão, WSPRecv Pode indicar a terminação normal do circuito virtual de uma destas duas maneiras, depending on se o Soquete é um fluxo de bytes ou orientado a mensagem. Para fluxos byte, zero bytes tendo sido ler indica encerramento normal e que há mais bytes nunca será ler. Para soquetes orientado a mensagem, onde um zero byte mensagem geralmente é permitida, um código de erro de retorno de WSAEDISCON é usado para indicar encerramento normal. Em qualquer maiúsculas e minúsculas um código de erro de WSAECONNRESET de retorno indica que um fechar abortive ocorreu.

lpFlags 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 lpFlags parâmetro. O segundo é construído usando o operador bit a bit OR com qualquer um do seguinte valores.

Valor	Descrição
MSG_PEEK	Exibe a de entrada dados. Os dados são copiados para a reserva, mas não são removidos da entrada fila. Este sinalizador é válido somente para os soquetes nonoverlapped.
MSG_OOB	Processa dados OOB.
MSG_PARTIAL	Este sinalizador é apenas soquetes orientado a mensagem. Na saída, indica que os dados fornecidos é uma parte da mensagem transmitida pelo remetente. Restante partes de mensagem será fornecida no subseqüentes operações de recebimento. Um operação de recebimento subseqüentes com sinalizador MSG_PARTIAL desmarcada indica fim da mensagem do remetente. Como um parâmetro de entrada, MSG_PARTIAL indica que o operação de recebimento deve completo mesmo if only parte de uma mensagem foi recebida pelo provedor de serviço.

Sobreposto Soquete E/S

Se uma operação sobreposta conclui imediatamente, WSPRecv Retorna um valor de zero e o lpNumberOfBytesRecvd parâmetro é atualizado com o número de bytes recebidos e os bits sinalizador apontados pelo lpFlags parâmetro também são atualizadas. Se a operação sobreposta é iniciada com êxito e será completo mais recente, essa função retorna SOCKET_ERROR e indica código de erro WSA_IO_PENDING. Neste maiúsculas e minúsculas, lpNumberOfBytesRecvd e lpFlags não são atualizados. 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. Valores de sinalizador são obtidos através de dwFlags parâmetro de rotina de conclusão ou examinando a lpdwFlags parâmetro de 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.

É 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 recebidos. dwFlags contém informações que seria exibida em lpFlags Se o operação de recebimento tinha concluída imediatamente. Essa função não retorna um valor.

As rotinas de conclusão podem ser chamado em qualquer ordem, mas não necessariamente a mesma ordem na qual as operações sobrepostas são concluídas. No entanto, os buffers postados são garantidos ser preenchido a mesma ordem em 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

WPUCloseEvent
WPUCreateEvent
WSPGetOverlappedResult
WSPSocket