Fonction IoCreateNotificationEvent (wdm.h)

Article
08/08/2023

La routine IoCreateNotificationEvent crée ou ouvre un événement de notification nommé utilisé pour notifier un ou plusieurs threads d’exécution qu’un événement s’est produit.

Syntaxe

PKEVENT IoCreateNotificationEvent(
  [in]  PUNICODE_STRING EventName,
  [out] PHANDLE         EventHandle
);

Paramètres

[in] EventName

Pointeur vers une mémoire tampon contenant une chaîne Unicode terminée par null qui nomme l’événement.

[out] EventHandle

Pointeur vers un emplacement dans lequel retourner un handle de noyau pour l’objet d’événement.

Valeur retournée

IoCreateNotificationEvent renvoie un pointeur vers l’objet d’événement créé ou ouvert ou NULL si l’objet d’événement n’a pas pu être créé ou ouvert.

Remarques

Si l’objet événement n’existe pas encore, IoCreateNotificationEvent le crée et l’ouvre, puis définit son état sur Signaled.

Si l’objet événement existe déjà, IoCreateNotificationEvent ouvre simplement l’objet d’événement.

Les événements de notification et les événements de synchronisation sont utilisés pour coordonner l’exécution. Toutefois, lorsqu’un événement de synchronisation se réinitialise, un événement de notification reste à l’état Signaled jusqu’à ce que le pilote appelle KeClearEvent ou KeResetEvent.

Pour synchroniser sur un événement de notification :

Ouvrez l’événement de notification avec IoCreateNotificationEvent. Identifiez l’événement avec la chaîne EventName .
Attendez que l’événement soit signalé en appelant KeWaitForSingleObject avec le PKEVENT retourné par IoCreateNotificationEvent. Plusieurs threads d’exécution peuvent attendre un événement de notification donné. Pour interroger au lieu de bloquer, spécifiez un délai d’expiration de zéro à KeWaitForSingleObject.
Fermez le handle de l’événement de notification avec ZwClose lorsque l’accès à l’événement n’est plus nécessaire.

Il existe deux méthodes main pour partager des objets d’événement :

L’application en mode utilisateur crée l’objet d’événement et transmet un handle à l’objet au pilote en envoyant un IOCTL au pilote. Le pilote doit gérer le IOCTL dans le contexte du processus qui a créé l’objet d’événement et doit valider le handle en appelant ObReferenceObjectByHandle. Cette méthode est la méthode recommandée pour partager des objets d’événement entre les modes utilisateur et noyau.
Le pilote crée un objet d’événement nommé dans le répertoire d’objets globaux \BaseNamedObjects . Pour accéder à un événement en mode noyau à partir du mode utilisateur, utilisez le nom Global\\Xxx. Notez que les paramètres de sécurité peuvent empêcher une application d’ouvrir l’événement. Le \\BaseNamedObjects répertoire d’objets n’est pas créé tant que le sous-système Microsoft Win32 n’est pas initialisé. Par conséquent, les pilotes chargés au moment du démarrage ne peuvent pas créer d’objets d’événement dans le \\BaseNamedObjects répertoire dans leurs routines DriverEntry .

Pour plus d’informations sur les événements, consultez Event Objects.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible à partir de Windows 2000.
Plateforme cible	Universal
En-tête	wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport),IrqlIoPassive4(wdm)