Fonction IoCreateSynchronizationEvent (wdm.h)

  • Article

La routine IoCreateSynchronizationEvent crée ou ouvre un événement de synchronisation nommé à utiliser dans la sérialisation de l’accès au matériel entre deux pilotes par ailleurs non liés.

Syntaxe

PKEVENT IoCreateSynchronizationEvent(
  [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 pour l’objet d’événement. Dans Windows Server 2003 et versions ultérieures de Windows, le handle retourné est un handle de noyau.

Valeur retournée

IoCreateSynchronizationEvent retourne 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

L’objet d’événement est créé s’il n’existe pas déjà. IoCreateSynchronizationEvent définit l’état d’un nouvel événement de synchronisation sur Signaled. Si l’objet d’événement existe déjà, il est simplement ouvert. La paire de pilotes qui utilisent un événement de synchronisation appelle KeWaitForSingleObject avec le pointeur PKEVENT retourné par cette routine.

Lorsqu’un événement de synchronisation est défini sur l’état Signaled, un seul thread d’exécution qui attendait l’événement est libéré et l’événement est automatiquement réinitialisé à l’état Not-Signaled.

Pour libérer l’événement, un pilote appelle ZwClose avec le handle d’événement.

Le partage d’objets d’événement entre le mode utilisateur et le mode noyau nécessite des précautions. 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 répertoire d’objets \BaseNamedObjects n’est pas créé tant que le sous-système Microsoft Win32 n’est pas initialisé, de sorte que les pilotes chargés au moment du démarrage ne peuvent pas créer d’objets d’événement dans le répertoire \BaseNamedObjects 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 (include Ntddk.h)
Bibliothèque NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
Règles de conformité DDI HwStorPortProhibitedDDIs(storport),IrqlIoPassive4(wdm), PowerIrpDDis(wdm)

Voir aussi

IoCreateNotificationEvent

KeWaitForSingleObject

RtlInitUnicodeString

ZwClose