ZwOpenEvent, fonction (wdm.h)

Article
02/29/2024

La routine ZwOpenEvent ouvre un handle à un objet d’événement nommé existant avec l’accès souhaité spécifié.

Syntaxe

NTSYSCALLAPI NTSTATUS ZwOpenEvent(
  [out] PHANDLE            EventHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes
);

Paramètres

[out] EventHandle

Pointeur vers une variable qui recevra le handle de l’objet d’événement. Le handle inclut des informations de comptabilité, telles qu’un nombre de références et un contexte de sécurité.

[in] DesiredAccess

Valeur ACCESS_MASK qui représente les types d’accès souhaités pour l’objet d’événement. Le tableau suivant contient les valeurs de ACCESS_MASK spécifiques à l’événement.

Valeur	Accès souhaité
EVENT_QUERY_STATE	Interrogez l’état de l’objet d’événement.
EVENT_MODIFY_STATE	Modifiez l’état de l’objet d’événement.
EVENT_ALL_ACCESS	Tous les droits d’accès possibles à l’objet d’événement.

[in] ObjectAttributes

Pointeur vers la structure d’attributs d’objet que l’appelant a fournie pour être utilisée pour l’objet spécifié. Ces attributs incluent les attributs ObjectName et handle, par exemple. Ce paramètre est initialisé en appelant la macro InitializeObjectAttributes .

Valeur retournée

ZwOpenEvent retourne STATUS_SUCCESS ou une erreur appropriée status. Cette routine peut retourner l’un des codes d’erreur status suivants :

Code de retour	Description
STATUS_INSUFFICIENT_RESOURCES	Les ressources dont cette fonction a besoin n’ont pas pu être allouées.
STATUS_INVALID_PARAMETER	La structure ObjectAttributes n’a pas été fournie ou contenait une valeur de paramètre non valide.
STATUS_OBJECT_NAME_INVALID	Le paramètre ObjectAttributes contenait un ObjectName dans la structure OBJECT_ATTRIBUTES qui n’était pas valide.
STATUS_OBJECT_PATH_SYNTAX_BAD	Le chemin d’accès de l’objet contenait une syntaxe incorrecte. Par exemple, le paramètre ObjectAttributes ne contient pas de membre RootDirectory , mais le membre ObjectName dans la structure OBJECT_ATTRIBUTES est une chaîne vide ou ne commence pas par un caractère OBJECT_NAME_PATH_SEPARATOR.
STATUS_OBJECT_PATH_NOT_FOUND	Le chemin d’accès à l’objet est introuvable, ce qui indique qu’il n’existe pas.
STATUS_OBJECT_NAME_NOT_FOUND	Le nom de l’objet est introuvable, ce qui indique que l’objet n’existe pas.
STATUS_PRIVILEGE_NOT_HELD	L’appelant n’avait pas le privilège requis pour créer un handle avec l’accès spécifié dans le paramètre DesiredAccess .

Remarques

ZwOpenEvent ouvre un objet d’événement nommé existant et crée un handle pour l’objet avec l’accès souhaité spécifié.

ZwOpenEvent peut ouvrir des événements de notification ou de synchronisation.

Les événements sont utilisés pour coordonner l’exécution. Les pilotes de système de fichiers peuvent utiliser des événements pour permettre à un appelant d’attendre la fin de l’opération demandée jusqu’à ce que l’événement donné soit défini sur l’état Signaled.

Les événements de notification peuvent être utilisés pour notifier un ou plusieurs threads d’exécution qu’un événement s’est produit. Les événements de synchronisation peuvent être utilisés dans la sérialisation de l’accès au matériel entre deux pilotes non liés.

Si l’appel à la fonction ZwOpenEvent se produit en mode utilisateur, vous devez utiliser le nom « NtOpenEvent » au lieu de « ZwOpenEvent ».

Pour les appels provenant de pilotes en mode noyau, les versions NtXxx et ZwXxx d’une routine Windows Native System Services peuvent se comporter différemment dans la façon dont elles gèrent et interprètent les paramètres d’entrée. Pour plus d’informations sur la relation entre les versions NtXxx et ZwXxx d’une routine, consultez Using Nt and Zw Versions of the Native System Services Routines.

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
En-tête	wdm.h (include Wdm.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)