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

  • Artigo

A função RIOCreateRequestQueue cria um descritor de soquete de E/S registrado usando um soquete especificado e filas de conclusão de E/S para uso com as extensões de E/S registradas do Winsock.

Sintaxe

LPFN_RIOCREATEREQUESTQUEUE LpfnRiocreaterequestqueue;

RIO_RQ LpfnRiocreaterequestqueue(
  SOCKET Socket,
  ULONG MaxOutstandingReceive,
  ULONG MaxReceiveDataBuffers,
  ULONG MaxOutstandingSend,
  ULONG MaxSendDataBuffers,
  RIO_CQ ReceiveCQ,
  RIO_CQ SendCQ,
  PVOID SocketContext
)
{...}

Parâmetros

Socket

Um descritor que identifica o soquete.

MaxOutstandingReceive

O número máximo de recebimentos pendentes permitidos no soquete.

Esse parâmetro geralmente é um número pequeno para a maioria dos aplicativos.

MaxReceiveDataBuffers

O número máximo de buffers de dados de recebimento no soquete.

Observação

Para Windows 8 e Windows Server 2012 , esse parâmetro deve ser 1.

MaxOutstandingSend

O número máximo de envios pendentes permitidos no soquete.

MaxSendDataBuffers

O número máximo de buffers de dados de envio no soquete.

Observação

Para Windows 8 e Windows Server 2012 , esse parâmetro deve ser 1.

ReceiveCQ

Um descritor que identifica a fila de conclusão de E/S a ser usada para receber conclusões de solicitação.

SendCQ

Um descritor que identifica a fila de conclusão de E/S a ser usada para enviar conclusões de solicitação.

Esse parâmetro pode ter o mesmo valor que o parâmetro ReceiveCQ .

SocketContext

O contexto de soquete a ser associado a essa fila de solicitação.

Retornar valor

Se nenhum erro ocorrer, a função RIOCreateRequestQueue retornará um descritor referenciando uma nova fila de solicitação. Caso contrário, um valor de RIO_INVALID_RQ é retornado e um código de erro específico pode ser recuperado chamando a função WSAGetLastError .

Código de retorno Descrição
WSAEINVAL
 Um parâmetro inválido foi passado para a função.
Esse erro será retornado se os parâmetros ReceiveCQ ou SendCQ contidos RIO_INVALID_CQ. Esse erro será retornado se os parâmetros MaxOutstandingReceive e MaxOutstandingSend forem zero. Esse erro também será retornado se o soquete passado no parâmetro Socket estiver em processo de inicialização ou fechamento.
WSAENOBUFS
 Memória suficiente não pôde ser alocada. Esse erro será retornado se não houver memória suficiente para alocar a fila de solicitação com base nos parâmetros. Esse erro também será retornado se o limite da sessão de rede tiver sido excedido.
WSAENOTSOCK
 O descritor não é um soquete. Esse erro será retornado se o parâmetro Socket não for um soquete válido.
WSAEOPNOTSUPP
 Não há suporte para a tentativa de operação para o tipo de objeto referenciado. Esse erro é retornado para um soquete no parâmetro Socket para um tipo de soquete sem suporte (SOCK_RAW, por exemplo)

Comentários

A função RIOCreateRequestQueue cria um descritor de soquete de E/S registrado usando um soquete especificado e filas de conclusão de E/S. Um aplicativo deve chamar RIOCreateRequestQueue para obter um RIO_RQ para um soquete Winsock antes que o aplicativo possa usar as funções RIOSend, RIOSendEx, RIOReceive ou RIOReceiveEx . Para obter um RIO_RQ, o soquete Winsock deve ser associado às filas de conclusão para envio e recebimento, embora a mesma fila de conclusão possa ser usada para ambos.

Devido ao tamanho finito das filas de conclusão, um soquete só poderá ser associado a uma fila de conclusão para operações de envio e recebimento se garantir que não exceda a capacidade para o total de conclusões enfileiradas. Portanto, os limites específicos do soquete são estabelecidos pela chamada para a função RIOCreateRequestQueue . Esses limites são usados durante a chamada RIOCreateRequestQueue para verificar espaço suficiente nas filas de conclusão para acomodar as solicitações de soquete e durante o tempo de início da solicitação para garantir que a solicitação não faça com que o soquete exceda seus limites.

As filas de envio e recebimento podem ser associadas a vários soquetes. Os tamanhos das filas de envio e recebimento devem ser maiores ou iguais aos tamanhos de envio e recebimento de todos os soquetes anexados. À medida que as filas de solicitação são fechadas fechando os soquetes usando a função closesocket , esses slots serão liberados para uso por outros soquetes.

Observação

Para fins de eficiência, o acesso às filas de conclusão (RIO_CQ structs) e às filas de solicitação (RIO_RQ structs) não são protegidos por primitivos de sincronização. Se você precisar acessar uma fila de conclusão ou solicitação de vários threads, o acesso deverá ser coordenado por uma seção crítica, bloqueio de gravação de leitor fino ou mecanismo semelhante. Esse bloqueio não é necessário para acesso por um único thread. Threads diferentes podem acessar filas de solicitações/conclusão separadas sem bloqueios. A necessidade de sincronização ocorre somente quando vários threads tentam acessar a mesma fila. A sincronização também será necessária se vários threads forem enviados e recebidos no mesmo soquete porque as operações de envio e recebimento usarão a fila de solicitação do soquete.

 

Quando um aplicativo terminar de usar o RIO_RQ, o aplicativo deverá chamar a função closesocket para fechar o soquete e liberar os recursos associados.

Observação

O ponteiro de função para a função RIOCreateRequestQueue 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. Com ê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