ZwCreateEvent, fonction (ntifs.h)

Article
07/11/2023

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

Pointeur vers la structure d’attributs d’objet fournie par l’appelant à utiliser pour l’objet spécifié. Ces attributs incluent 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 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éfinissez sur TRUE pour initialiser l’objet d’événement à l’état Signaled. Définissez sur FALSE pour initialiser l’objet d’événement à l’état non signalé.

Valeur retournée

ZwCreateEvent retourne STATUS_SUCCESS ou une erreur appropriée status. Les codes status d’erreur possibles sont les suivants :

Code de retour	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’avait 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 d’é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 Signalé.

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 à l’état Signaled, il reste dans cet état jusqu’à ce qu’il soit explicitement réinitialisé.

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 l’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 décrochage, spécifiez un délai d’expiration de zéro pour 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 l’utilisation de la macro InitializeObjectAttributes pour définir des attributs dans la structure OBJECT_ATTRIBUTES de l’objet.

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

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

Notes

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

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
Client minimal pris en charge	Windows XP.
Plateforme cible	Universal
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)