RIO_NOTIFICATION_COMPLETION structure (mswsock.h)

Article
08/25/2023

La structure RIO_NOTIFICATION_COMPLETION spécifie la méthode d’achèvement des E/S à utiliser avec une fonction RIONotify pour envoyer ou recevoir des données réseau avec les extensions d’E/S inscrites dans Winsock.

Syntaxe

typedef struct _RIO_NOTIFICATION_COMPLETION {
  RIO_NOTIFICATION_COMPLETION_TYPE Type;
  union {
    struct {
      HANDLE EventHandle;
      BOOL   NotifyReset;
    } Event;
    struct {
      HANDLE IocpHandle;
      PVOID  CompletionKey;
      PVOID  Overlapped;
    } Iocp;
  };
} RIO_NOTIFICATION_COMPLETION, *PRIO_NOTIFICATION_COMPLETION;

Membres

Type

Type d’achèvement à utiliser avec la fonction RIONotify lors de l’envoi ou de la réception de données.

Event

Event.EventHandle

Handle pour l’événement à définir après une demande RIONotify terminée.

Cette valeur est valide lorsque le membre Type est défini sur RIO_EVENT_COMPLETION.

Event.NotifyReset

Valeur booléenne qui entraîne la réinitialisation de l’événement associé lorsque la fonction RIONotify est appelée. Une valeur autre que zéro entraîne la réinitialisation de l’événement associé.

Cette valeur est valide lorsque le membre Type est défini sur RIO_EVENT_COMPLETION.

Iocp

Iocp.IocpHandle

Handle pour le port d’achèvement d’E/S à utiliser pour la mise en file d’attente d’une requête RIONotify .

Cette valeur est valide lorsque le membre Type est défini sur RIO_IOCP_COMPLETION.

Iocp.CompletionKey

Valeur à utiliser pour le paramètre lpCompletionKey retourné par la fonction GetQueuedCompletionStatus ou GetQueuedCompletionStatusEx lors de la mise en file d’attente d’une requête RIONotify .

Cette valeur est valide lorsque le membre Type est défini sur RIO_IOCP_COMPLETION.

Iocp.Overlapped

Pointeur vers la structure CHEVAUCHEMENT À utiliser lors de la mise en file d’attente d’une requête RIONotify . Ce membre doit pointer vers une structure OVERLAPPED valide.

Cette valeur est valide lorsque le membre Type est défini sur RIO_IOCP_COMPLETION.

Remarques

La structure RIO_NOTIFICATION_COMPLETION est utilisée pour spécifier le comportement de la fonction RIONotify utilisée avec les extensions d’E/S inscrites winsock.

La structure RIO_NOTIFICATION_COMPLETION est passée à la fonction RIOCreateCompletionQueue lors de la création d’un RIO_CQ . Si une application n’appelle pas la fonction RIONotify pour une file d’attente d’achèvement, la file d’attente d’achèvement peut être créée sans objet RIO_NOTIFICATION_COMPLETION .

Pour les files d’attente d’achèvement utilisant un événement, le membre Type de la structure RIO_NOTIFICATION_COMPLETION est défini sur RIO_EVENT_COMPLETION. Le membre Event.EventHandle de la structure RIO_NOTIFICATION_COMPLETION doit contenir le handle d’un événement créé par la fonction WSACreateEvent ou CreateEvent . Pour recevoir l’achèvement RIONotify , l’application doit attendre le handle d’événement spécifié à l’aide de WSAWaitForMultipleEvents ou d’une routine d’attente similaire. Si l’application prévoit de réinitialiser et de réutiliser l’événement, l’application peut réduire la surcharge en définissant le membre Event.NotifyReset de la structure RIO_NOTIFICATION_COMPLETION sur une valeur différente de zéro. Cela entraîne la réinitialisation de l’événement par la fonction RIONotify lorsque la notification se produit. Cela atténue la nécessité d’appeler la fonction WSAResetEvent pour réinitialiser l’événement entre les appels à la fonction RIONotify .

Pour les files d’attente d’achèvement utilisant un port d’achèvement d’E/S, le membre Type de la structure RIO_NOTIFICATION_COMPLETION est défini sur RIO_IOCP_COMPLETION. Le membre Iocp.IocpHandle de la structure RIO_NOTIFICATION_COMPLETION doit contenir le handle d’un port d’achèvement d’E/S créé par la fonction CreateIoCompletionPort . Pour recevoir l’achèvement RIONotify , l’application doit appeler la fonction GetQueuedCompletionStatus ou GetQueuedCompletionStatusEx . L’application doit fournir un objet OVERLAPPED dédié pour la file d’attente d’achèvement, et elle peut également utiliser le membre Iocp.CompletionKey pour distinguer les demandes RIONotify sur la file d’attente d’achèvement des autres complétions d’E/S, y compris les saisies semi-automatique RIONotify pour d’autres files d’attente d’achèvement.

Une application utilisant des pools de threads peut utiliser des objets d’attente de pool de threads pour obtenir des achèvements RIONotify via son pool de threads. Dans ce cas, l’appel à la fonction SetThreadpoolWait doit suivre immédiatement l’appel à RIONotify. Si la fonction SetThreadpoolWait est appelée avant RIONotify et que l’application s’appuie sur RIONotify pour effacer l’objet d’événement, cela peut entraîner des exécutions erronées du rappel de l’objet wait.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 8 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2012 [applications de bureau uniquement]
En-tête	mswsock.h