LPFN_RIOCREATECOMPLETIONQUEUE função de retorno de chamada (mswsock.h)
A função RIOCreateCompletionQueue cria uma fila de conclusão de E/S de um tamanho específico para uso com as extensões de E/S registradas do Winsock.
Sintaxe
LPFN_RIOCREATECOMPLETIONQUEUE LpfnRiocreatecompletionqueue;
RIO_CQ LpfnRiocreatecompletionqueue(
DWORD QueueSize,
PRIO_NOTIFICATION_COMPLETION NotificationCompletion
)
{...}
Parâmetros
QueueSize
O tamanho, em número de entradas, da fila de conclusão a ser criada.
NotificationCompletion
O tipo de conclusão de notificação a ser usado com base no membro Type da estrutura de RIO_NOTIFICATION_COMPLETION (conclusão de E/S ou notificação de evento).
Se o membro Type estiver definido como RIO_EVENT_COMPLETION, o membro Event da estrutura RIO_NOTIFICATION_COMPLETION deverá ser definido.
Se o membro Type estiver definido como RIO_IOCP_COMPLETION, o membro Iocp da estrutura RIO_NOTIFICATION_COMPLETION deverá ser definido e o membro Iocp.Overlapped da estrutura RIO_NOTIFICATION_COMPLETION não deverá ser NULL.
Se o parâmetro NotificationCompletion for NULL, isso especificará que nenhuma conclusão de notificação é usada e que a sondagem deve ser usada para determinar a conclusão.
Retornar valor
Se nenhum erro ocorrer, a função RIOCreateCompletionQueue retornará um descritor referenciando uma nova fila de conclusão. Caso contrário, um valor de RIO_INVALID_CQ é retornado e um código de erro específico pode ser recuperado chamando a função WSAGetLastError .
| Código de retorno | Descrição |
|---|---|
| O sistema detectou um endereço de ponteiro inválido ao tentar usar um argumento de ponteiro em uma chamada. |
|
| Um parâmetro inválido foi passado para a função. Esse erro será retornado se o parâmetro QueueSize for menor que 1 ou maior que RIO_MAX_CQ_SIZE definido no arquivo de cabeçalho Mswsockdef.h . |
|
| 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 conclusão solicitada com base no parâmetro QueueSize . |
Comentários
A função RIOCreateCompletionQueue cria uma fila de conclusão de E/S de um tamanho específico. O tamanho da fila de conclusão restringe o conjunto de soquetes de E/S registrados que podem ser associados à fila de conclusão. Para obter mais informações, consulte a função RIOCreateRequestQueue .
Ao criar um RIO_CQ, a estrutura de RIO_NOTIFICATION_COMPLETION apontada pelo parâmetro NotificationCompletion determina como o aplicativo receberá notificações de fila de conclusão. Se uma estrutura RIO_NOTIFICATION_COMPLETION for fornecida ao criar a fila de conclusão, o aplicativo poderá chamar a função RIONotify para solicitar uma notificação de fila de conclusão. Normalmente, essa notificação ocorre quando a fila de conclusão não está vazia. Isso pode acontecer imediatamente ou quando a próxima entrada de conclusão é inserida na fila de conclusão. No entanto, as solicitações de envio e recebimento podem ser sinalizadas como RIO_MSG_DONT_NOTIFY. Notificação de fila de conclusão e nunca será disparada como resultado dessas solicitações. Se a fila de conclusão contiver apenas entradas com o sinalizador RIO_MSG_DONT_NOTIFY definido, a notificação da fila de conclusão não será disparada. Além disso, quando uma nova entrada entra na fila de conclusão, a notificação da fila de conclusão só é disparada se o sinalizador RIO_MSG_DONT_NOTIFY não foi definido na solicitação associada. Todas as solicitações concluídas ainda podem ser recuperadas sondando usando a função RIODequeueCompletion . Depois que uma notificação de fila de conclusão for emitida, o aplicativo deverá chamar a função RIONotify para receber outra notificação de fila de conclusão. Quando ocorre uma notificação de fila de conclusão, o aplicativo normalmente chama a função RIODequeueCompletion para desativar as solicitações de envio ou recebimento concluídas.
Duas opções estão disponíveis para notificação de fila de conclusão.
- Identificadores de evento.
- Portas de conclusão de E/S
Se o membro Type da estrutura RIO_NOTIFICATION_COMPLETION estiver definido como RIO_EVENT_COMPLETION, um identificador de evento será usado para sinalizar notificações de fila de conclusão. Um identificador de evento é fornecido como o membro EventNotify.EventHandle na estrutura RIO_NOTIFICATION_COMPLETION passada para a função RIOCreateCompletionQueue . O membro Event.EventHandle deve conter o identificador de um evento criado pela função WSACreateEvent ou CreateEvent . Para receber a conclusão do RIONotify , o aplicativo deve aguardar o identificador de evento especificado usando WSAWaitForMultipleEvents ou uma rotina de espera semelhante. A conclusão da função RIONotify para esse RIO_CQ sinalizará o evento. O membro Event.NotifyReset na estrutura RIO_NOTIFICATION_COMPLETION passada para a função RIOCreateCompletionQueue indica se o evento deve ou não ser redefinido como parte de uma chamada para a função RIONotify . Se o aplicativo planeja redefinir e reutilizar o evento, o aplicativo poderá reduzir a sobrecarga definindo o membro Event.NotifyReset como um valor diferente de zero. Isso faz com que o evento seja redefinido automaticamente pela função RIONotify quando a notificação ocorre. Isso atenua a necessidade de chamar a função WSAResetEvent para redefinir o evento entre chamadas para a função RIONotify .
Se o membro Type da estrutura RIO_NOTIFICATION_COMPLETION estiver definido como RIO_IOCP_COMPLETION, uma porta de conclusão de E/S será usada para sinalizar notificações de fila de conclusão. Um identificador de porta de conclusão de E/S é fornecido como membro Iocp.IocpHandle na estrutura RIO_NOTIFICATION_COMPLETION passada para a função RIOCreateCompletionQueue . A conclusão da função RIONotify para esse RIO_CQ enfileirará uma entrada para a porta de conclusão de E/S que pode ser recuperada usando a função GetQueuedCompletionStatus ou GetQueuedCompletionStatusEx . Uma entrada enfileirada terá o valor de parâmetro lpCompletionKey retornado definido como o valor especificado em Iocp.CompletionKey membro da estrutura RIO_NOTIFICATION_COMPLETION e o membro Iocp.Overlapped na estrutura RIO_NOTIFICATION_COMPLETION será um valor não NULL.
Em termos de uso, a notificação de fila de conclusão foi projetada para ativar um thread de aplicativo em espera para que o thread possa examinar a fila de conclusão. Acordar e agendar um thread tem um custo, portanto, se isso acontecer com muita frequência, isso terá um impacto negativo no desempenho do aplicativo. O sinalizador RIO_MSG_DONT_NOTIFY é fornecido para que o aplicativo possa controlar a frequência desses eventos e limitar o impacto sobre o desempenho.
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.
Observação
O ponteiro de função para a função RIOCreateCompletionQueue 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 |