Função ProcessSocketNotifications (winsock2.h)
Associa um conjunto de soquetes a uma porta de conclusão e recupera todas as notificações que já estão pendentes nessa porta. Uma vez associada, a porta de conclusão recebe as notificações de estado do soquete que foram especificadas. Há suporte apenas para soquetes de provedor do Microsoft Winsock .
Para reduzir a sobrecarga de chamada do sistema, você pode se registrar para notificações e recuperá-las em uma única chamada para ProcessSocketNotifications. Como alternativa, você pode recuperá-las explicitamente chamando as funções de porta de conclusão de E/S usuais, como GetQueuedCompletionStatus. As notificações recuperadas usando ProcessSocketNotifications são as mesmas que as recuperadas usando GetQueuedCompletionStatusEx, que podem incluir pacotes de notificação diferentes das alterações de estado do soquete.
Os sinalizadores de evento de notificação são o valor inteiro dos campos dwNumberOfBytesTransferred das estruturasde OVERLAPPED_ENTRY retornadas. Isso é semelhante ao uso de JOBOBJECT_ASSOCIATE_COMPLETION_PORT, que também usa o campo dwNumberOfBytesTransferred para enviar mensagens inteiras. Chame a função SocketNotificationRetrieveEvents para obtê-los.
Um identificador de soquete pode ser registrado em apenas um IOCP por vez. Registrar novamente um identificador de soquete registrado anteriormente substitui o registro existente. Antes de fechar um identificador usado para registro, você deve remover explicitamente o registro e aguardar a notificação de SOCK_NOTIFY_EVENT_REMOVE (consulte Comentários neste tópico).
Para obter mais informações e exemplos de código, consulte Notificações de estado do soquete Winsock.
Sintaxe
DWORD WSAAPI ProcessSocketNotifications(
HANDLE completionPort,
UINT32 registrationCount,
SOCK_NOTIFY_REGISTRATION *registrationInfos,
UINT32 timeoutMs,
ULONG completionCount,
OVERLAPPED_ENTRY *completionPortEntries,
UINT32 *receivedEntryCount
);
Parâmetros
completionPort
Tipo: _In_ HANDLE
Um identificador para uma porta de conclusão de E/S criada usando a função CreateIoCompletionPort . A porta será usada no parâmetro CompletionPort da função PostQueuedCompletionStatus quando as mensagens forem enviadas em nome do soquete.
registrationCount
Tipo: _In_ UINT32
O número de registros fornecidos por registrationInfos.
registrationInfos
Tipo: _Inout_updates_opt_(registrationCount) SOCK_NOTIFY_REGISTRATION*
Um ponteiro para uma matriz de estruturas SOCK_NOTIFY_REGISTRATION que definem os parâmetros de registro de notificação. Isso inclui o soquete de interesse, os eventos de notificação de interesse e os sinalizadores de operação. Em caso de êxito, você deve inspecionar os elementos para saber se o registro foi processado com êxito. Esse argumento deverá ser NULL se registrationCount for 0.
timeoutMs
Tipo: _In_ UINT32
O tempo em milissegundos que você está disposto a aguardar até que um pacote de conclusão apareça na porta de conclusão. Se um pacote de conclusão não aparecer dentro do tempo especificado, a função atingirá o tempo limite e retornará ERROR_TIMEOUT.
Se timeoutMs for INFINITE (0xFFFFFFFF), a função nunca terá tempo limite. Se timeoutMs for 0 e não houver nenhuma operação de E/S para remover a fila, a função terá o tempo limite atingido imediatamente.
O valor de timeoutMs deverá ser 0 se completionCount for 0.
completionCount
Tipo: _In_ ULONG
O número máximo de estruturas de OVERLAPPED_ENTRY a serem removidas. Se 0 for especificado, somente as operações de registro serão processadas.
completionPortEntries
Tipo: _Out_writes_to_opt_(completionCount, *receivedEntryCount) OVERLAPPED_ENTRY*
Na entrada, aponta para uma matriz pré-alocada de estruturas OVERLAPPED_ENTRY. A matriz não deve se sobrepor à matriz registrationInfos . O valor de completionPortEntries deverá ser NULL se completionCount for 0.
Na saída, recebe uma matriz de estruturas OVERLAPPED_ENTRY que mantêm as entradas. O número de elementos de matriz é fornecido por ReceivedEntryCount. Os campos dwNumberOfBytesTransferred das estruturas são máscaras inteiras de eventos recebidos. Os campos lpOverlapped são reservados e não devem ser usados como ponteiros.
receivedEntryCount
Tipo: _Out_opt_ UINT32*
Um ponteiro para uma variável que recebe o número de entradas removidas. Deve ser NULL se completionCount for 0.
Valor retornado
Se tiver êxito, retornará ERROR_SUCCESS. Se a função foi bem-sucedida e você forneceu um completionCount não 0, mas nenhum pacote de conclusão apareceu dentro do tempo especificado, retorna WAIT_TIMEOUT. Caso contrário, retornará um código de erro WSAE* apropriado.
Se ERROR_SUCCESS ou WAIT_TIMEOUT for retornado, você deverá inspecionar os resultados de registro das informações de registro individuais. Caso contrário, toda a operação falhou e nenhuma alteração ocorreu.
Comentários
Consulte SocketNotificationRetrieveEvents para obter os eventos possíveis quando uma notificação é recebida.
Requisitos
| Cliente mínimo com suporte | Windows 10 Build 20348 |
| Servidor mínimo com suporte | Windows 10 Build 20348 |
| Cabeçalho | winsock2.h |
| Biblioteca | Ws2_32.lib |
| DLL | Ws2_32.dll |