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

  • Artigo

A função RIONotify registra o método a ser usado para o comportamento de notificação com uma fila de conclusão de E/S para uso com as extensões de E/S registradas do Winsock.

Sintaxe

LPFN_RIONOTIFY LpfnRionotify;

INT LpfnRionotify(
  RIO_CQ CQ
)
{...}

Parâmetros

CQ

Um descritor que identifica uma fila de conclusão de E/S.

Retornar valor

Se nenhum erro ocorrer, a função RIONotify retornará ERROR_SUCCESS. Caso contrário, a função falhou e um código de erro específico será retornado.

Código de retorno Descrição
WSAEINVAL
 Um parâmetro inválido foi passado para a função.
Esse erro será retornado se a fila de conclusão inválida for passada no parâmetro CQ (RIO_INVALID_CQ, por exemplo). Esse erro também pode ser retornado quando ocorre um erro interno.
WSAEALREADY
 Foi tentada uma operação em um soquete sem bloqueio que já tinha uma operação em andamento.
Esse erro será retornado se uma solicitação RIONotify anterior ainda não tiver sido concluída.

Comentários

A função RIONotify registra o método a ser usado para o comportamento de notificação para enviar ou receber dados de rede com as extensões de E/S registradas do Winsock.

A função RIONotify é o mecanismo pelo qual um aplicativo descobre que as solicitações foram concluídas e estão aguardando uma chamada para a função RIODequeueCompletion . A função RIONotify define o método a ser usado para o comportamento de notificação quando uma fila de conclusão de E/S não está vazia e contém a conclusão de um resultado.

O comportamento de notificação de uma fila de conclusão é definido quando o RIO_CQ é criado. A estrutura RIO_NOTIFICATION_COMPLETION é passada para a função RIOCreateCompletionQueue quando um RIO_CQ é criado.

Para uma fila de conclusão que usa um evento, o membro Type da estrutura RIO_NOTIFICATION_COMPLETION é definido como RIO_EVENT_COMPLETION. 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. Se o aplicativo planeja redefinir e reutilizar o evento, o aplicativo pode 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 ocorrer. Isso atenua a necessidade de chamar a função WSAResetEvent para redefinir o evento entre chamadas para a função RIONotify .

Quando a função RIONotify é chamada de conclusão de evento usado e a fila de conclusão especificada já não está vazia, o evento é definido de forma síncrona ou assíncrona. Em ambos os casos, entradas adicionais não precisam entrar na fila de conclusão antes que o evento seja definido. Até que a fila de conclusão contenha a conclusão de uma solicitação que não tinha o sinalizador RIO_MSG_DONT_NOTIFY definido, a fila de conclusão é considerada vazia para fins da função RIONotify e o evento não está definido. Todas as solicitações concluídas ainda podem ser recuperadas usando a função RIODequeueCompletion . Quando o evento é definido, o aplicativo normalmente chama a função RIODequeueCompletion para remover a fila das solicitações de envio e recebimento concluídas.

Para uma fila de conclusão que usa uma porta de conclusão de E/S, o membro Type da estrutura RIO_NOTIFICATION_COMPLETION é definido como RIO_IOCP_COMPLETION. O membro Iocp.IocpHandle deve conter o identificador de uma porta de conclusão de E/S criada pela função CreateIoCompletionPort . Para receber a conclusão do RIONotify , o aplicativo deve chamar a função GetQueuedCompletionStatus ou GetQueuedCompletionStatusEx . O aplicativo deve fornecer um objeto OVERLAPPED dedicado para a fila de conclusão e também pode usar o membro Iocp.CompletionKey para distinguir solicitações RIONotify na fila de conclusão de outras conclusões de E/S, incluindo conclusões RIONotify para outras filas de conclusão.

Um aplicativo que usa pools de threads pode usar objetos de espera do pool de threads para obter conclusões RIONotify por meio de seu pool de threads. Nesse caso, a chamada para a função SetThreadpoolWait deve seguir imediatamente a chamada para RIONotify. Se a função SetThreadpoolWait for chamada antes de RIONotify e o aplicativo depender de RIONotify para limpar o objeto de evento, isso poderá resultar em execuções espúrias do retorno de chamada do objeto de espera.

Observação

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

Acesso thread-safe

Se vários threads tentarem acessar o mesmo RIO_CQ usando a função RIODequeueCompletion , o acesso deverá ser coordenado por uma seção crítica, bloqueio de gravador de leitor fino ou mecanismo de exclusão mútua semelhante. Se as filas de conclusão não forem compartilhadas, a exclusão mútua não será necessária.

Requisitos

Requisito Valor
Cabeçalho mswsock.h