CreateEventExW, fonction (synchapi.h)

Article
08/26/2023

Crée ou ouvre un objet d’événement nommé ou sans nom et retourne un handle à l’objet .

Syntaxe

HANDLE CreateEventExW(
  [in, optional] LPSECURITY_ATTRIBUTES lpEventAttributes,
  [in, optional] LPCWSTR               lpName,
  [in]           DWORD                 dwFlags,
  [in]           DWORD                 dwDesiredAccess
);

Paramètres

[in, optional] lpEventAttributes

Pointeur vers une structure SECURITY_ATTRIBUTES . Si lpEventAttributes a la valeur NULL, le handle d’événement ne peut pas être hérité par les processus enfants.

Le membre lpSecurityDescriptor de la structure spécifie un descripteur de sécurité pour le nouvel événement. Si lpEventAttributes a la valeur NULL, l’événement obtient un descripteur de sécurité par défaut. Les listes de contrôle d’accès dans le descripteur de sécurité par défaut d’un événement proviennent du jeton principal ou d’emprunt d’identité du créateur.

[in, optional] lpName

Nom de l'objet d'événement. Le nom est limité à MAX_PATH caractères. La comparaison de noms respecte la casse.

Si lpName a la valeur NULL, l’objet d’événement est créé sans nom.

Si lpName correspond au nom d’un autre type d’objet dans le même espace de noms (tel qu’un sémaphore existant, mutex, minuteur d’attente, travail ou objet de mappage de fichiers), la fonction échoue et la fonction GetLastError retourne ERROR_INVALID_HANDLE. Cela se produit parce que ces objets partagent le même espace de noms.

Le nom peut avoir un préfixe « Global » ou « Local » pour créer explicitement l’objet dans l’espace de noms global ou de session. Le reste du nom peut contenir n’importe quel caractère à l’exception de la barre oblique inverse (\). Pour plus d’informations, consultez Espaces de noms d’objets du noyau. La commutation rapide des utilisateurs est implémentée à l’aide de sessions Terminal Services. Les noms d’objets de noyau doivent suivre les instructions décrites pour Terminal Services afin que les applications puissent prendre en charge plusieurs utilisateurs.

L’objet peut être créé dans un espace de noms privé. Pour plus d’informations, consultez Espaces de noms d’objets.

[in] dwFlags

Ce paramètre peut prendre une ou plusieurs des valeurs suivantes.

Valeur	Signification
CREATE_EVENT_INITIAL_SET 0x00000002	L’état initial de l’objet d’événement est signalé ; sinon, il n’est pas signé.
CREATE_EVENT_MANUAL_RESET 0x00000001	L’événement doit être réinitialisé manuellement à l’aide de la fonction ResetEvent . Tout nombre de threads en attente, ou threads qui commencent par la suite des opérations d’attente pour l’objet d’événement spécifié, peuvent être libérés pendant que l’état de l’objet est signalé. Si cet indicateur n’est pas spécifié, le système réinitialise automatiquement l’événement après avoir libéré un seul thread d’attente.

Valeur

Signification

CREATE_EVENT_INITIAL_SET
0x00000002

L’état initial de l’objet d’événement est signalé ; sinon, il n’est pas signé.

CREATE_EVENT_MANUAL_RESET
0x00000001

L’événement doit être réinitialisé manuellement à l’aide de la fonction ResetEvent . Tout nombre de threads en attente, ou threads qui commencent par la suite des opérations d’attente pour l’objet d’événement spécifié, peuvent être libérés pendant que l’état de l’objet est signalé.

Si cet indicateur n’est pas spécifié, le système réinitialise automatiquement l’événement après avoir libéré un seul thread d’attente.

[in] dwDesiredAccess

Masque d’accès pour l’objet d’événement. Pour obtenir la liste des droits d’accès, consultez Synchronization Object Security and Access Rights.

Valeur retournée

Si la fonction réussit, la valeur de retour est un handle pour l’objet d’événement. Si l’objet d’événement nommé existait avant l’appel de fonction, la fonction retourne un handle à l’objet existant et GetLastError retourne ERROR_ALREADY_EXISTS.

Si la fonction échoue, la valeur de retour est NULL. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

N’importe quel thread du processus appelant peut spécifier le handle event-object dans un appel à l’une des fonctions d’attente. Les fonctions d’attente à objet unique retournent lorsque l’état de l’objet spécifié est signalé. Les fonctions d’attente à plusieurs objets peuvent être indiquées pour retourner l’un ou l’autre lorsque tous les objets spécifiés sont signalés. Lorsqu’une fonction d’attente est retournée, le thread en attente est libéré pour poursuivre son exécution.

L’état initial de l’objet d’événement est spécifié par le paramètre dwFlags . Utilisez la fonction SetEvent pour définir l’état d’un objet événement sur signalé. Utilisez la fonction ResetEvent pour réinitialiser l’état d’un objet d’événement sur non signé.

Lorsque l’état d’un objet d’événement de réinitialisation manuelle est signalé, il reste signalé jusqu’à ce qu’il soit explicitement réinitialisé à non signé par la fonction ResetEvent . Tout nombre de threads en attente, ou threads qui commencent par la suite des opérations d’attente pour l’objet d’événement spécifié, peuvent être libérés pendant que l’état de l’objet est signalé.

Plusieurs processus peuvent avoir des handles du même objet d’événement, ce qui permet d’utiliser l’objet pour la synchronisation interprocessus. Les mécanismes de partage d’objets suivants sont disponibles :

Un processus enfant créé par la fonction CreateProcess peut hériter d’un handle à un objet d’événement si le paramètre lpEventAttributes de CreateEvent a activé l’héritage.
Un processus peut spécifier le handle event-object dans un appel à la fonction DuplicateHandle pour créer un handle en double qui peut être utilisé par un autre processus.
Un processus peut spécifier le nom d’un objet d’événement dans un appel à la fonction OpenEvent ou CreateEvent .

Utilisez la fonction CloseHandle pour fermer le handle. Le système ferme automatiquement le handle à l’arrêt du processus. L’objet d’événement est détruit lorsque son dernier handle a été fermé.

Notes

L’en-tête synchapi.h définit CreateEventEx comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	synchapi.h (inclure Windows.h sur Windows 7, Windows Server 2008 Windows Server 2008 R2)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll

Voir aussi

CloseHandle

Objets d’événement

Noms d’objets

Fonctions de synchronisation

Share via