WSPRecvFrom

9/8/2008

Essa função recebe uma datagrama e armazena o endereço origem.

Syntax

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

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.

• lpFlags
  [in, Out] Ponteiro para sinalizadores.

• lpFrom
  [out] Um 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).

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

• lpErrno
  [in, 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 foi iniciado 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.
WSAEFAULT	O lpFromlen parâmetro era inválido porque o lpFrom reserva era muito pequena para acomodar o endereço de mesmo nível ou lpbuffers não é totalmente contidos dentro um válido parte espaço de endereço o usuário.
WSAEINPROGRESS	Bloquear chamar Soquetes do Windows é em andamento, ou o serviço provedor ainda é processamento um função callback.
WSAEINVAL	Soquete não foi ligado (de exemplo, com WSPBind) ou o Soquete não é criado com o sinalizador sobrepostos.
WSAEISCONN	Soquete está conectado. Essa função não é permitida com um Soquete conectado, se o Soquete é orientado por conexão ou sem conexão.
WSAENETRESET	Conexão foi interrompida detectar uma falha enquanto a operação foi atividade keep-alive devido a em andamento.
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 executar WSPRecvFrom 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.
WSAECONNRESET	O circuito virtual foi redefinir pelo remoto lado executar fechar um disco rígido ou abortive. O aplicativo deve fechar o Soquete como ele não é mais utilizada. Em um soquete de datagrama UDP esse erro indicaria que uma operação de envio anterior resultou em um ICMP "PORT Unreachable" mensagem.
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 principalmente em um sem conexão Soquete especificado por s. O Soquete não deve estar conectado. O local endereço do Soquete deve ser conhecido. Isso pode ser feito explicitamente através WSPBind ou implicitamente através de WSPSendTo Ou WSPJoinLeaf.

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 Client-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 WSPGetOverlappedResult. Detalhes também que os valores apontados pelo lpFrom e lpFromlen Não serão atualizados até que a conclusão é indicada. Aplicativos não devem usar ou interfira forma esses valores até que eles tenham sido atualizados, portanto o cliente 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 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 de acordo com o bloqueio atribuído semântica para WSPRecv.

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 sem conexão Soquete tipos, o endereço do qual os dados se originou são copiados para a reserva apontada por lpFrom. Na entrada, o valor apontado pelo lpFromlen é inicializada com 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 cliente de Windows Sockets SPI. O lpFrom e lpFromlen parâmetros são ignorados para Soquetes orientado por conexão.

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 soquetes orientado a mensagem, um único 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 Para o Soquete e subseqüentes recebem operações irá recuperar o resto da mensagem. Se não for MSG_PARTIAL com suporte, mas o protocolo é seguro, WSPRecvFrom 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 WSPRecvFrom Gera o Erro WSAEMSGSIZE.

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 valores específicos. A seguinte tabela mostra esses 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.

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 a conclusão tem sido indicada o cliente Windows Sockets SPI deve chamar WSPGetOverlappedResult e examine os sinalizadores apontados pelo lpdwFlags parâmetro.

Sobreposto Soquete E/S

Se uma operação sobreposta conclusão imediatamente, essa função 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 WSPRecv 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 por meio de lpcbTransfer parâmetro no WSPGetOverlappedResult. Valores de sinalizador são obtidos examinando o 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. Um 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. É 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, embora não necessariamente na mesma ordem que as operações sobrepostas são concluídas. No entanto, os buffers postados são garantidos ser preenchido a 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