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

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

Sintaxe

LPFN_RIORECEIVE LpfnRioreceive;

BOOL LpfnRioreceive(
  RIO_RQ SocketQueue,
  PRIO_BUF pData,
  ULONG DataBufferCount,
  DWORD Flags,
  PVOID RequestContext
)
{...}

Parâmetros

SocketQueue

Um descritor que identifica um soquete TCP 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 o conteúdo 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.

Flags

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

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 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 RIOReceive , quando o sinalizador RIO_MSG_COMMIT_ONLY é definido, as chamadas para a função RIOReceive não precisam ser serializadas. Para um único RIO_RQ, a função RIOReceive pode ser chamada com RIO_MSG_COMMIT_ONLY em um thread ao chamar a função RIOReceive 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 RIOReceive não será concluída até que ocorra um dos seguintes eventos:

• O segmento de buffer fornecido pelo chamador no parâmetro pData está completamente cheio.
• A conexão foi fechada.
• A solicitação foi cancelada ou ocorreu um erro.

Não há suporte para esse sinalizador em soquetes UDP.

RequestContext

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

Retornar valor

Se nenhum erro ocorrer, a função RIOReceive 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 Flags 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 nesse soquete.

Comentários

Um aplicativo pode usar a função RIOReceive 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 RIOReceive é 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 Flags pode ser usado para influenciar o comportamento da invocação da função RIOReceive 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 RIOReceive 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