LPFN_RIORECEIVEEX função de retorno de chamada (mswsock.h)
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 |
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de