Compartilhar via

LPFN_RIORECEIVEEX função de retorno de chamada (mswsock.h)

  • Artigo

A função RIOReceiveEx recebe dados de rede em um soquete TCP de E/S registrado conectado ou em um soquete UDP de E/S registrado associado com opções adicionais para uso com as extensões de E/S registradas do Winsock.

Sintaxe

LPFN_RIORECEIVEEX LpfnRioreceiveex;

int LpfnRioreceiveex(
                                                                                                                     RIO_RQ SocketQueue,
                                                                                                                     PRIO_BUF pData,
                                                                                                                     ULONG DataBufferCount,
                                                                                                                     PRIO_BUF pLocalAddress,
                                                                                                                     PRIO_BUF pRemoteAddress,
                                                                                                                     PRIO_BUF pControlContext,
                                                                                                                     PRIO_BUF pFlags,
                                                                                                                     DWORD Flags,
                                                                                                                     PVOID RequestContext
)
{...}

Parâmetros

SocketQueue

Um descritor que identifica um soquete UDP de E/S registrado conectado ou um soquete UDP de E/S associado.

pData

Uma descrição da parte do buffer registrado na qual receber dados.

Esse parâmetro poderá ser NULL para um soquete UDP de E/S associado se o aplicativo não precisar receber uma carga de dados no datagrama UDP.

DataBufferCount

Um parâmetro de contagem de buffer de dados que indica se os dados devem ser recebidos no buffer apontado pelo parâmetro pData .

Esse parâmetro deverá ser definido como zero se o pData for NULL. Caso contrário, esse parâmetro deve ser definido como 1.

pLocalAddress

Um segmento de buffer que, após a conclusão, conterá o endereço local no qual os dados de rede foram recebidos.

Esse parâmetro poderá ser NULL se o aplicativo não quiser receber o endereço local. Se esse parâmetro não for NULL, o segmento de buffer deverá ter pelo menos o tamanho de uma estrutura SOCKADDR_INET .

pRemoteAddress

Um segmento de buffer que, após a conclusão, conterá o endereço remoto do qual os dados de rede foram recebidos.

Esse parâmetro poderá ser NULL se o aplicativo não quiser receber o endereço remoto. Se esse parâmetro não for NULL, o segmento de buffer deverá ter pelo menos o tamanho de uma estrutura SOCKADDR_INET .

pControlContext

Uma fatia de buffer que, após a conclusão, conterá informações de controle adicionais sobre a operação de recebimento.

Esse parâmetro poderá ser NULL se o aplicativo não quiser receber as informações de controle adicionais.

pFlags

Flags

Um conjunto de sinalizadores que modificam o comportamento da função RIOReceiveEx .

O parâmetro Flags pode conter uma combinação das seguintes opções, definidas no arquivo de Mswsockdef.h cabeçalho:

RIO_MSG_COMMIT_ONLY

As solicitações anteriores adicionadas com RIO_MSG_DEFER sinalizador serão confirmadas.

Quando o sinalizador RIO_MSG_COMMIT_ONLY é definido, nenhum outro sinalizador pode ser especificado. Quando o sinalizador RIO_MSG_COMMIT_ONLY é definido, os argumentos pData, pLocalAddress, pRemoteAddress, pControlContext, pFlags e RequestContext devem ser NULL e o argumento DataBufferCount deve ser zero.

Normalmente, esse sinalizador seria usado ocasionalmente depois que várias solicitações fossem emitidas com o sinalizador RIO_MSG_DEFER definido. Isso elimina a necessidade ao usar o sinalizador RIO_MSG_DEFER para fazer a última solicitação sem o sinalizador RIO_MSG_DEFER , o que faz com que a última solicitação seja concluída muito mais lentamente do que outras solicitações.

Ao contrário de outras chamadas para a função RIOReceiveEx , quando o sinalizador RIO_MSG_COMMIT_ONLY é definido, as chamadas para a função RIOReceiveEx não precisam ser serializadas. Para um único RIO_RQ, a função RIOReceiveEx pode ser chamada com RIO_MSG_COMMIT_ONLY em um thread ao chamar a função RIOReceiveEx em outro thread.

RIO_MSG_DONT_NOTIFY

A solicitação não deve disparar a função RIONotify quando a conclusão da solicitação é inserida em sua fila de conclusão.

RIO_MSG_DEFER

A solicitação não precisa ser executada imediatamente. Isso inserirá a solicitação na fila de solicitações, mas pode ou não disparar a execução da solicitação.

A recepção de dados pode ser atrasada até que uma solicitação de recebimento seja feita na RIO_RQ passada no parâmetro SocketQueue sem o sinalizador RIO_MSG_DEFER definido. Para disparar a execução de todos os recebimentos em uma fila de solicitação, chame a função RIOReceive ou RIOReceiveEx sem o sinalizador RIO_MSG_DEFER definido.

Observação

A solicitação de recebimento é cobrada contra a capacidade de E/S pendente na RIO_RQ passada no parâmetro SocketQueue , independentemente de RIO_MSG_DEFER ser definida.

RIO_MSG_WAITALL

A função RIOReceiveEx não será concluída até que ocorra um dos seguintes eventos:

  • A fatia de buffer fornecida pelo chamador no parâmetro pData está completamente cheia.
  • A conexão foi fechada.
  • A solicitação foi cancelada ou ocorreu um erro.

Não há suporte para esse sinalizador em soquetes de datagrama ou em soquetes sem conexão orientados a mensagens.

RequestContext

O contexto de solicitação a ser associado a essa operação de recebimento.

Retornar valor

Se nenhum erro ocorrer, a função RIOReceiveEx retornará TRUE. Nesse caso, a operação de recebimento é iniciada com êxito e a conclusão já terá sido enfileirada ou a operação foi iniciada com êxito e a conclusão será enfileirada posteriormente.

Um valor false indica que a função falhou, a operação não foi iniciada com êxito e nenhuma indicação de conclusão será enfileirada. Um código de erro específico pode ser recuperado chamando a função WSAGetLastError .

Código de retorno Descrição
WSAEFAULT O sistema detectou um endereço de ponteiro inválido ao tentar usar um argumento de ponteiro em uma chamada. Esse erro será retornado se um identificador de buffer for desregistrado ou um buffer for liberado para qualquer uma das estruturas de RIO_BUF passadas em parâmetros antes que a operação seja enfileirada ou invocada.
WSAEINVAL Um parâmetro inválido foi passado para a função.
Esse erro será retornado se o parâmetro SocketQueue não for válido, o parâmetro dwFlags contiver um valor inválido para uma operação de recebimento ou a integridade da fila de conclusão tiver sido comprometida. Esse erro também pode ser retornado para outros problemas com parâmetros.
WSAENOBUFS Não foi possível alocar memória suficiente. Esse erro será retornado se a fila de conclusão de E/S associada ao parâmetro SocketQueue estiver cheia ou a fila de conclusão de E/S tiver sido criada sem entradas de recebimento.
WSA_OPERATION_ABORTED A operação foi cancelada enquanto a operação de recebimento estava pendente. Esse erro será retornado se o soquete for fechado local ou remotamente ou o comando SIO_FLUSH no WSAIoctl for executado.

Comentários

Um aplicativo pode usar a função RIOReceiveEx para receber dados de rede em qualquer buffer completamente contido em um único buffer registrado. Os membros Offset e Length da estrutura RIO_BUF apontada pelo parâmetro pData determinam onde os dados de rede são recebidos no buffer.

Depois que a função RIOReceiveEx for chamada, o buffer passado no parâmetro pData , incluindo o RIO_BUFFERID no membro BufferId da estrutura RIO_BUF deve permanecer válido durante a operação de recebimento.

Para evitar condições de corrida, um buffer associado a uma solicitação de recebimento não deve ser lido ou gravado antes da conclusão da solicitação. Isso inclui o uso do buffer como a origem de uma solicitação de envio ou o destino de outra solicitação de recebimento. Partes de um buffer registrado não associadas a nenhuma solicitação de recebimento não estão incluídas nessa restrição.

O parâmetro pLocalAddress pode ser usado para recuperar o endereço local em que os dados foram recebidos. O parâmetro pRemoteAddress pode ser usado para recuperar o endereço remoto do qual os dados foram recebidos. Os endereços locais e remotos são retornados como estruturas SOCKADDR_INET . Como resultado, o membro Length do RIO_BUF apontado pelos parâmetros pLocalAddress ou pRemoteAddress deve ser igual ou maior que o tamanho de uma estrutura SOCKADDR_INET .

A tabela a seguir resume os vários usos de dados de controle disponíveis para uso com as informações de controle no membro pControlContext .

Protocolo cmsg_level cmsg_type Descrição
IPv4 IPPROTO_IP IP_ORIGINAL_ARRIVAL_IF Recebe a interface de chegada IPv4 original em que o pacote foi recebido para soquetes de datagrama. Esses dados de controle são usados por firewalls quando um túnel Teredo, 6to4 ou ISATAP é usado para passagem NAT IPv4.
O membro cmsg_data[] é um ULONG que contém o IF_INDEX definido no arquivo de cabeçalho ifdef.h .
Para obter mais informações, consulte as Opções de soquete IPPROTO_IP para a opção de soquete IP_ORIGINAL_ARRIVAL_IF.
IPv4 IPPROTO_IP IP_PKTINFO Especifica/recebe informações de pacote.
Para obter mais informações, consulte as Opções de soquete IPPROTO_IP para a opção de soquete IP_PKTINFO.
IPv6 IPPROTO_IPV6 IPV6_DSTOPTS Especifica/recebe opções de destino.
IPv6 IPPROTO_IPV6 IPV6_HOPLIMIT Especifica/recebe o limite de salto.
Para obter mais informações, consulte as Opções de soquete IPPROTO_IPV6 para a opção de soquete IPV6_HOPLIMIT.
IPv6 IPPROTO_IPV6 IPV6_HOPOPTS Especifica/recebe opções de salto por salto.
IPv6 IPPROTO_IPV6 IPV6_NEXTHOP Especifica o endereço do próximo salto.
IPv6 IPPROTO_IPV6 IPV6_PKTINFO Especifica/recebe informações de pacote.
Para obter mais informações, consulte as Opções de soquete IPPROTO_IPV6 para a opção de soquete IPV6_PKTINFO.
IPv6 IPPROTO_IPV6 IPV6_RTHDR Especifica/recebe o cabeçalho de roteamento.

Os dados de controle são compostos por um ou mais objetos de dados de controle, cada um começando com uma estrutura WSACMSGHDR , definida como o seguinte:

} WSACMSGHDR;

Os membros da estrutura WSACMSGHDR são os seguintes:

Termo Descrição
cmsg_len O número de bytes de dados que começam desde o início do WSACMSGHDR até o final dos dados (excluindo bytes de preenchimento que podem seguir os dados).
cmsg_level O protocolo que originou as informações de controle.
cmsg_type O tipo específico de protocolo de informações de controle.

O parâmetro Flags pode ser usado para influenciar o comportamento da invocação da função RIOReceiveEx além das opções especificadas para o soquete associado. O comportamento dessa função é determinado por uma combinação de todas as opções de soquete definidas no soquete associado ao parâmetro SocketQueue e aos valores especificados no parâmetro Flags .

Observação

O ponteiro de função para a função RIOReceiveEx deve ser obtido em tempo de execução fazendo uma chamada para a função WSAIoctl com o SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER opcode especificado. O buffer de entrada passado para a função WSAIoctl deve conter WSAID_MULTIPLE_RIO, um GUID (identificador global exclusivo) cujo valor identifica as funções de extensão de E/S registradas do Winsock. Em caso de êxito, a saída retornada pela função WSAIoctl contém um ponteiro para a estrutura RIO_EXTENSION_FUNCTION_TABLE que contém ponteiros para as funções de extensão de E/S registradas do Winsock. O SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER IOCTL é definido no arquivo de cabeçalho Ws2def.h . O GUID WSAID_MULTIPLE_RIO é definido no arquivo de cabeçalho Mswsock.h .

Windows Phone 8: essa função tem suporte para aplicativos da Windows Phone Store no Windows Phone 8 e posterior.

Windows 8.1 e Windows Server 2012 R2: essa função tem suporte para aplicativos da Windows Store em Windows 8.1, Windows Server 2012 R2 e posteriores.

Requisitos

Requisito Valor
Cabeçalho mswsock.h