Partager via

Fonction ProcessSocketNotifications (winsock2.h)

  • Article

Associe un ensemble de sockets à un port d’achèvement et récupère toutes les notifications qui sont déjà en attente sur ce port. Une fois associé, le port d’achèvement reçoit les notifications d’état du socket qui ont été spécifiées. Seuls les sockets de fournisseur Microsoft Winsock sont pris en charge.

Pour réduire la surcharge des appels système, vous pouvez vous inscrire aux notifications et les récupérer dans un seul appel à ProcessSocketNotifications. Vous pouvez également les récupérer explicitement en appelant les fonctions de port d’achèvement d’E/S habituelles, telles que GetQueuedCompletionStatus. Les notifications récupérées à l’aide de ProcessSocketNotifications sont les mêmes que celles récupérées à l’aide de GetQueuedCompletionStatusEx, qui peuvent inclure des paquets de notification autres que les changements d’état du socket.

Les indicateurs d’événement de notification sont la valeur entière des champs dwNumberOfBytesTransferred des structures OVERLAPPED_ENTRY retournées. Cela est similaire à l’utilisation de JOBOBJECT_ASSOCIATE_COMPLETION_PORT, qui utilise également le champ dwNumberOfBytesTransferred pour envoyer des messages entiers. Appelez la fonction SocketNotificationRetrieveEvents pour les obtenir.

Un handle de socket ne peut être inscrit qu’auprès d’un seul IOCP à la fois. La réinscription d’un handle de socket précédemment inscrit remplace l’inscription existante. Avant de fermer un handle utilisé pour l’inscription, vous devez supprimer explicitement l’inscription et attendre la notification SOCK_NOTIFY_EVENT_REMOVE (voir Remarques dans cette rubrique).

Pour plus d’informations et des exemples de code, consultez Notifications d’état du socket Winsock.

Syntaxe

DWORD WSAAPI ProcessSocketNotifications(
  HANDLE                   completionPort,
  UINT32                   registrationCount,
  SOCK_NOTIFY_REGISTRATION *registrationInfos,
  UINT32                   timeoutMs,
  ULONG                    completionCount,
  OVERLAPPED_ENTRY         *completionPortEntries,
  UINT32                   *receivedEntryCount
);

Paramètres

completionPort

Type : _in_ HANDLE

Handle vers un port d’achèvement d’E/S créé à l’aide de la fonction CreateIoCompletionPort . Le port sera utilisé dans le paramètre CompletionPort de la fonction PostQueuedCompletionStatus lorsque des messages sont envoyés pour le compte du socket.

registrationCount

Type : _In_ UINT32

Nombre d’inscriptions fournies par registrationInfos.

registrationInfos

Type : SOCK_NOTIFY_REGISTRATION _Inout_updates_opt_(registrationCount)*

Pointeur vers un tableau de structures SOCK_NOTIFY_REGISTRATION qui définissent les paramètres d’inscription de notification. Il s’agit notamment du socket d’intérêt, des événements de notification intéressants et des indicateurs d’opération. En cas de réussite, vous devez inspecter les éléments pour déterminer si l’inscription a été traitée avec succès. Cet argument doit avoir la valeur NULL si registrationCount est égal à 0.

timeoutMs

Type : _In_ UINT32

Délai en millisecondes pendant lequel vous êtes prêt à attendre qu’un paquet d’achèvement apparaisse au port d’achèvement. Si un paquet d’achèvement n’apparaît pas dans le délai spécifié, la fonction expire et retourne ERROR_TIMEOUT.

Si le délai d’expiration est INFINITE (0xFFFFFFFF), la fonction n’expirera jamais. Si le délai d’expiration est 0 et qu’aucune opération d’E/S n’est à mettre en file d’attente, la fonction expire immédiatement.

La valeur des délais d’expiration doit être 0 si completionCount est 0.

completionCount

Type : _In_ ULONG

Nombre maximal de structures OVERLAPPED_ENTRY à supprimer. Si 0 est spécifié, seules les opérations d’inscription seront traitées.

completionPortEntries

Type : _Out_writes_to_opt_(completionCount, *receivedEntryCount) OVERLAPPED_ENTRY*

En entrée, pointe vers un tableau pré-alloué des structures OVERLAPPED_ENTRY. Le tableau ne doit pas chevaucher le tableau registrationInfos . La valeur de completionPortEntries doit être NULL si completionCount est 0.

En sortie, reçoit un tableau des structures OVERLAPPED_ENTRY qui contiennent les entrées. Le nombre d’éléments de tableau est fourni par ReceivedEntryCount. Les champs dwNumberOfBytesTransferred des structures sont des masques entiers des événements reçus. Les champs lpOverlapped sont réservés et ne doivent pas être utilisés comme pointeurs.

receivedEntryCount

Type : _Out_opt_ UINT32*

Pointeur vers une variable qui reçoit le nombre d’entrées supprimées. Doit avoir la valeur NULL si completionCount est 0.

Valeur retournée

En cas de réussite, retourne ERROR_SUCCESS. Si la fonction a réussi et que vous avez fourni un paramètre completionCount autre que 0, mais qu’aucun paquet d’achèvement n’est apparu dans le délai spécifié, retourne WAIT_TIMEOUT. Sinon, retourne un code d’erreur WSAE* approprié.

Si ERROR_SUCCESS ou WAIT_TIMEOUT est retourné, vous devez inspecter les résultats d’inscription des informations d’inscription individuelles. Sinon, l’ensemble de l’opération a échoué et aucune modification ne s’est produite.

Remarques

Consultez SocketNotificationRetrieveEvents pour connaître les événements possibles lors de la réception d’une notification.

Configuration requise

   
Client minimal pris en charge Windows 10 Build 20348
Serveur minimal pris en charge Windows 10 Build 20348
En-tête winsock2.h
Bibliothèque Ws2_32.lib
DLL Ws2_32.dll

Voir aussi