ZwOpenEvent, fonction (wdm.h)

Article
12/21/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 d’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 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 des attributs d’objet que l’appelant a fourni à utiliser pour l’objet spécifié. Ces attributs incluent les ObjectName et les attributs de handle, par exemple. Ce paramètre est initialisé en appelant la macro InitializeObjectAttributes.

Valeur de retour

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

Retourner le code	Description
STATUS_INSUFFICIENT_RESOURCES	Les ressources requises par cette fonction n’ont pas pu être allouées.
STATUS_INVALID_PARAMETER	La ObjectAttributes structure 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 n’a pas été trouvé, indiquant qu’il n’existe pas.
STATUS_OBJECT_NAME_NOT_FOUND	Le nom de l’objet n’a pas été trouvé, indiquant que l’objet n’existe pas.
STATUS_PRIVILEGE_NOT_HELD	L’appelant n’a 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 à partir de pilotes en mode noyau, les versions NtXxx et ZwXxx d’une routine Windows Native System Services peuvent se comporter différemment de 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.

Exigences

Exigence	Valeur
plateforme cible	Universel
d’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)