ZwCreateEvent, fonction (ntifs.h)

Article
12/21/2024

La routine ZwCreateEvent crée un objet d’événement, définit l’état initial de l’événement sur la valeur spécifiée et ouvre un handle à l’objet avec l’accès souhaité spécifié.

Syntaxe

NTSYSAPI NTSTATUS ZwCreateEvent(
  [out]          PHANDLE            EventHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in]           EVENT_TYPE         EventType,
  [in]           BOOLEAN            InitialState
);

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, optional] ObjectAttributes

Pointeur vers la structure d’attributs d’objet fournie par l’appelant à utiliser pour l’objet spécifié. Ces attributs incluent le ObjectName et le SECURITY_DESCRIPTOR, par exemple. Ce paramètre est initialisé en appelant la macro InitializeObjectAttributes.

[in] EventType

Type de l’événement, qui peut être SynchronizationEvent ou un NotificationEvent. Ces valeurs appartiennent à l’énumération EVENT_TYPE, qui est définie dans le fichier d’en-tête ntdef.h.

[in] InitialState

État initial de l’objet d’événement. Défini sur TRUE pour initialiser l’objet d’événement à l’état Signaled. Défini sur FALSE pour initialiser l’objet événement à l’état non signalé.

Valeur de retour

ZwCreateEvent retourne STATUS_SUCCESS ou un état d’erreur approprié. Les codes d’état d’erreur possibles sont les 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 structure ObjectAttributes fournie contenait une valeur de paramètre non valide.
STATUS_INVALID_PARAMETER_4	Le paramètre EventType spécifié n’était pas 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 paramètre ObjectAttributes ne contenait pas de membre RootDirectory , mais le membre ObjectName dans la structure OBJECT_ATTRIBUTES était une chaîne vide ou ne contenait pas de caractère OBJECT_NAME_PATH_SEPARATOR. Cela indique une syntaxe incorrecte pour le chemin d’accès de l’objet.
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

ZwCreateEvent crée un objet événement, définit son état initial sur la valeur spécifiée et ouvre un handle à l’objet avec l’accès souhaité spécifié.

Les événements sont utilisés pour coordonner l’exécution. Les événements peuvent être utilisés par les pilotes de système de fichiers 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.

ZwCreateEvent peut créer des événements de notification ou de synchronisation :

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.

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

Contrairement à un événement de synchronisation, un événement de notification n’est pas réinitialisé automatiquement. Une fois qu’un événement de notification est dans l’état Signaled, il reste dans cet état jusqu’à ce qu’il soit réinitialisé explicitement.

Pour synchroniser sur un événement de notification :

Créez l’événement de notification avec ZwCreateEvent avec le paramètre EventType défini sur NotificationEvent.
Attendez que l’événement soit signalé en appelant ZwWaitForSingleObject avec le EventHandle retourné par ZwCreateEvent. Plusieurs threads d’exécution peuvent attendre qu’un événement de notification donné soit signalé. Pour interroger au lieu de bloquer, spécifiez une délai d’expiration de zéro à ZwWaitForSingleObject.
Fermez le handle de l’événement de notification avec ZwClose lorsque l’accès à l’événement n’est plus nécessaire.

La fonction ZwCreateEvent est appelée après la macro InitializeObjectAttributes est utilisée pour définir des attributs dans la structure OBJECT_ATTRIBUTES de l’objet.

Il existe deux façons de spécifier le nom de l’objet passé à ZwCreateEvent:

En tant que chemin d’accès complet, fourni dans le ObjectName membre de l’entrée ObjectAttributes.
En tant que chemin d’accès relatif au répertoire représenté par le handle dans le RootDirectory membre de l’entrée ObjectAttributes.

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

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

Note

Si l’appel à la routine ZwCreateEvent se produit en mode utilisateur, vous devez utiliser le nom «NtCreateEvent» au lieu de «ZwCreateEvent».

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
client minimum pris en charge	Windows XP.
plateforme cible	Universel
d’en-tête	ntifs.h (include Ntifs.h)
bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
règles de conformité DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)