WSARecv

9/8/2008

Essa função recebe dados de uma Soquete conectado.

Syntax

int WSARecv(
  SOCKET s,
  LPWSABUF lpBuffers,
  DWORD dwBufferCount,
  LPDWORD lpNumberOfBytesRecvd,
  LPDWORD lpFlags,
  LPWSAOVERLAPPED lpOverlapped,
  LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

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 se o operação de recebimento conclui imediatamente.

• lpFlags
  [in, Out] Ponteiro para sinalizadores.

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

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

Return Value

Se nenhum erro e o operação de recebimento 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 ocorrer um erro, será retornado um valor de SOCKET_ERROR e um código de erro específicos podem ser recuperadas por chamado de WSAGetLastError função. 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.
WSAENOTCONN	O Soquete não está conectado.
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.
WSAENETRESET	A conexão foi interrompida porque a atividade de manutenção de funcionamento detectou uma falha enquanto a operação estava em andamento.
WSAENOTSOCK	O descritor não é um Soquete.
WSAEFAULT	O lpBuffers parâmetro não está completamente contido em um válido parte espaço de endereço o usuário.
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 domínio de comunicação associado com este Soquete, ou o Soquete é unidirecional e oferece suporte a operações de envio somente.
WSAESHUTDOWN	O Soquete foi desligado. Não é possível chamar WSARecv Em um Soquete depois desligamento Tem sido chamado com Como Definido como SD_RECEIVE 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 o operação de recebimento não pode ser concluída imediatamente.
WSAEMSGSIZE	A 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	O Soquete não foi ligado (de exemplo, com BIND (Soquetes do Windows)).
WSAECONNABORTED	O circuito virtual foi finalizado devido a um tempo limite ou outra falha.
WSAECONNRESET	O 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	A operação sobreposta foi cancelada devido a o encerramento da Soquete.

Remarks

Essa função fornece funcionalidade over and Above o padrão Recv função no seguinte três áreas importantes:

• Ele pode ser usado em conjunto com soquetes sobrepostos para executar sobreposto recebe operações.
• Ele permite múltiplo Receber buffers sejam especificadas, ativando um dispersão/tipo coletar de E/S.
• O lpFlags parâmetro é dois uma entrada e parâmetro de saída, permitindo que os aplicativos perceberão o estado saída do bit de sinalizador MSG_PARTIAL. No entanto, não é o bit sinalizador MSG_PARTIAL com suporte por todos os protocolos.

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. Para aplicativos servidor, isso geralmente é feito explicitamente através BIND (Soquetes do Windows) ou implicitamente através de aceitar (Soquetes do Windows) Ou WSAAccept função. Ligação explícita não é recomendada para aplicativos cliente. Para aplicativos cliente, o Soquete pode se tornar ligado implicitamente para um local endereço através de conectar (Soquetes do Windows), WSAConnect, ou SendTo, WSASendTo função.

Para conectarsem conexão Ed 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, WSARecv é usado para 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 Application-specified (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 a WSAGetOverlappedResult função.

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

Para soquetes nonoverlapped, o bloqueio semântica é idêntica às que o padrão Recv função e a lpOverlapped e lpCompletionRoutine 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. Na 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. Sockets do Windows (Winsock) não define qualquer padrão bloqueio mecanismo tempo limite para esta função. Para protocolos atuando como byte-transmitir protocolos, a pilha tenta retornar tantos dados como assunto possível para o espaço do buffer fornecido e a 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.

Se um protocolo está atuando como fluxo de bytes é determinado pela configuração de XP1_MESSAGE_ORIENTED e XP1_PSEUDO_STREAM no seu WSAPROTOCOL_INFO estrutura e a configuração do sinalizador de MSG_PARTIAL passado para essa função (para protocolos que suporte ele). A seguinte tabela resume 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	*	*	fluxo de bytes
*	Definir	*	fluxo de bytes
Definir	Não definido	Definir	fluxo de bytes
Definir	Não definido	Não definido	mensagem orientada

Os buffers fornecidos são concluídos 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 essas WSABUF Estruturas antes de retornar deste chamar. Isso permite que aplicativos compilar stack-based WSABUF matrizes.

Para os soquetes estilo fluxo de bytes (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 a internamente armazenada em buffer dados estão esgotados. Independentemente se 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 pela subjacente provedor serviço, o sinalizador MSG_PARTIAL é definido no lpFlags e os subseqüentes se receber será operações recuperar o resto da mensagem. Se não for MSG_PARTIAL com suporte, mas o protocolo é seguro, WSARecv 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 WSARecv Gera o Erro WSAEMSGSIZE.

Para soquetes orientado à conexão, WSARecv Pode indicar a terminação normal do circuito virtual de uma destas duas maneiras que dependem se o Soquete é fluxo de bytes ou message-oriented. Para fluxos byte, zero bytes tendo sido ler (conforme indicado por um zero valor de retorno para indicar êxito e um lpNumberOfBytesRecvd valor de zero) indica encerramento normal e que há mais bytes nunca será ler. Para soquetes orientado a mensagem, onde um zero byte mensagem geralmente é permitida, uma falha com um código de erro de WSAEDISCON é usada 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.

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

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

O sinalizador MSG_PARTIAL não é com suporte pelo provedor de Windows Embedded CE usar como padrão. Para soquetes orientado a mensagem, o bit MSG_PARTIAL é definido na lpFlags parâmetro se uma mensagem parcial é recebida. Se um completo mensagem é recebida, MSG_PARTIAL está desmarcada na lpFlags. Na maiúsculas e minúsculas de conclusão atrasada, o valor apontado pelo lpFlags não é atualizado. Quando conclusão tenha sido indicada, o aplicativo deve chamar WSAGetOverlappedResult e examine os sinalizadores indicados pelo lpdwFlags parâmetro.

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, WSARecv Retorna um valor de zero e o lpNumberOfBytesRecvd parâmetro é atualizado com o número de bytes recebidos e os bits sinalizador indicados pelo lpFlags parâmetro também são atualizadas. Se a operação sobreposta é iniciada com êxito e serão posteriormente, completo WSARecv 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 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. Valores de sinalizador são obtidos examinando o lpdwFlags parâmetro de WSAGetOverlappedResult.

O WSARecv função pode ser chamado de dentro da rotina de conclusão de uma anterior WSARecv, WSARecvFrom, WSASend, ou WSASendTo função. Para um determinado Soquete, E/S conclusão rotinas não irão ser aninhadas. 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 o WSAGetOverlappedResult função 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 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 uma determinada 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
);

CompletionRoutine é 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 recebidos. O dwFlags parâmetro 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.

Retornando desta função permite invocação de pendente outra rotina de conclusão para este 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