WSARecvFrom

9/8/2008

Essa função recebe dados em um Soquete e armazena o endereço origem.

Syntax

int WSARecvFrom(
  SOCKET s,
  LPWSABUF lpBuffers,
  DWORD dwBufferCount,
  LPDWORD lpNumberOfBytesRecvd,
  LPDWORD lpFlags,
  struct sockaddr FAR* lpFrom,
  LPINT lpFromlen,
  LPWSAOVERLAPPED lpOverlapped,
  LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

Parameters

• s
  [no] Descritor identificando um Soquete.

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

• lpFrom
  [out] Opcional ponteiro para uma reserva que conterá o endereço origem na conclusão a operação sobreposta.

• lpFromlen
  [in, Out] Ponteiro para o tamanho das a partir reserva, exigido apenas se lpFrom foi especificado.

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

Remarks

Essa função fornece funcionalidade over and Above o padrão recvfrom 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 é uma entrada e um parâmetro de saída, permitindo que os aplicativos perceberão o estado saída do bit de sinalizador MSG_PARTIAL. Observe, no entanto, que o bit sinalizador MSG_PARTIAL não é com suporte por todos os protocolos.

Essa função é usada principalmente em um sem conexão Soquete especificado pelo Soquete s. Local do Soquete o endereço deve ser conhecido. Para aplicativos servidor, isso geralmente é feito explicitamente através BIND. Ligação explícita não é recomendada para aplicativos cliente. Para aplicativos cliente usando essa função, o Soquete pode se tornar ligado implicitamente para um local endereço através de SendTo Ou WSASendTo função.

Para soquetes sobrepostos, essa função é usada para postagem um ou mais buffers em que de entrada dados serão colocados como ele se torna disponível em um Soquete possivelmente conectado, 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. Além disso, os valores indicados por lpFrom e lpFromlen não são atualizados até que a conclusão é indicado. Aplicativos não devem usar ou interfira forma esses valores até que eles tenham sido atualizados, portanto o aplicativo não deve usar automática (isto é, baseado em pilha) variáveis para esses parâmetros.

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 WSARecv 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. 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.

Os buffers fornecidos são concluídos na ordem em que eles aparecem na matriz indicada por 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 sem conexão Soquete tipos, o endereço do qual os dados se originou são copiados para a reserva indicada por lpFrom. O valor apontado pelo lpFromlen é inicializado para o tamanho desta reserva e é modificado na conclusão para indicar o real tamanho do endereço armazenado lá. Conforme observado anteriormente para Soquetes sobrepostos, o lpFrom e lpFromlen Parâmetros não são atualizados até após o E/S sobreposto foi concluída. A memória apontada por esses parâmetros deve, portanto, permanecer disponível para o provedor serviço e não pode ser alocado no quadro pilha do aplicativo. O lpFrom e lpFromlen parâmetros são ignorados para Soquetes orientado por conexão.

Para os soquetes estilo fluxo de bytes (por exemplo, tipo SOCK_STREAM), de entrada dados são colocados dentro de buffers até determinados eventos ocorrer. A seguinte lista mostra esses eventos:

• Os buffers estão preenchidos.
• A conexão será fechada.
• O 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 soquetes orientado a mensagem, um 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, WSARecvFrom 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 WSARecvFrom Gera o Erro WSAEMSGSIZE.

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 que são usados com o operador bit a bit OR para construção de lpFlags parâmetro.

Como um parâmetro de entrada, este sinalizador indica que o operação de recebimento deve completo mesmo if only parte de uma mensagem foi recebida pelo provedor de serviç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 apontados pelo lpdwFlags parâmetro.

Sobreposto Soquete E/S

Se uma operação sobreposta conclui imediatamente, WSARecvFrom 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ão posteriormente, completo WSARecvFrom Retorna SOCKET_ERROR e indica código de erro WSA_IO_PENDING. Neste maiúsculas e minúsculas, lpNumberOfBytesRecvd e lpFlags 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. Valores de sinalizador são obtidos através de dwFlags parâmetro de rotina de conclusão ou examinando a lpdwFlags parâmetro de WSAGetOverlappedResult.

O WSARecvFrom função pode ser chamado de dentro da rotina de conclusão de uma anterior WSARecv, WSARecvFrom, WSASend, ou WSASendTo chamada de 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 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 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.

O seguinte amostra de código 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 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