CreateEventA, fonction (synchapi.h)

Article
05/20/2023

Crée ou ouvre un objet d’événement nommé ou non nommé.

Pour spécifier un masque d’accès pour l’objet, utilisez la fonction CreateEventEx .

Syntaxe

HANDLE CreateEventA(
  [in, optional] LPSECURITY_ATTRIBUTES lpEventAttributes,
  [in]           BOOL                  bManualReset,
  [in]           BOOL                  bInitialState,
  [in, optional] LPCSTR                lpName
);

Paramètres

[in, optional] lpEventAttributes

Pointeur vers une structure SECURITY_ATTRIBUTES . Si ce paramètre a la valeur NULL, le handle 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] bManualReset

Si ce paramètre a la valeur TRUE, la fonction crée un objet d’événement de réinitialisation manuelle, qui nécessite l’utilisation de la fonction ResetEvent pour définir l’état de l’événement sur non signé. Si ce paramètre a la valeur FALSE, la fonction crée un objet d’événement de réinitialisation automatique et le système réinitialise automatiquement l’état de l’événement à non signé après qu’un seul thread en attente a été libéré.

[in] bInitialState

Si ce paramètre a la valeur TRUE, l’état initial de l’objet d’événement est signalé ; sinon, il n’est pas signé.

[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 correspond au nom d’un objet d’événement nommé existant, cette fonction demande le droit d’accès EVENT_ALL_ACCESS . Dans ce cas, les paramètres bManualReset et bInitialState sont ignorés, car ils ont déjà été définis par le processus de création. Si le paramètre lpEventAttributes n’a pas la valeur NULL, il détermine si le handle peut être hérité, mais si son membre de descripteur de sécurité est ignoré.

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 (par exemple, un sémaphore, un mutex, un minuteur d’attente, un travail ou un objet de mappage de fichiers existant), 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 du caractère barre oblique inverse (\). Pour plus d’informations, consultez Espaces de noms d’objets de noyau. Le changement rapide d’utilisateur est implémenté à l’aide de sessions Terminal Services. Les noms d’objets de noyau doivent suivre les instructions décrites pour les services Terminal Server 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.

Valeur retournée

Si la fonction réussit, la valeur de retour est un handle de l’objet d’événement. Si l’objet é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

Le handle retourné par CreateEvent a le droit d’accès EVENT_ALL_ACCESS ; il peut être utilisé dans n’importe quelle fonction qui nécessite un handle pour un objet d’événement, à condition que l’appelant ait obtenu l’accès. Si un événement est créé à partir d’un service ou d’un thread qui emprunte l’identité d’un autre utilisateur, vous pouvez soit appliquer un descripteur de sécurité à l’événement lorsque vous le créez, soit modifier le descripteur de sécurité par défaut pour le processus de création en modifiant son DACL par défaut. Pour plus d’informations, consultez Synchronisation Des droits d’accès et de sécurité des objets.

N’importe quel thread du processus d’appel 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 des objets spécifiés. Lorsqu’une fonction d’attente retourne, le thread d’attente est libéré pour poursuivre son exécution.

L’état initial de l’objet événement est spécifié par le paramètre bInitialState . Utilisez la fonction SetEvent pour définir l’état d’un objet d’événement sur signal. Utilisez la fonction ResetEvent pour réinitialiser l’état d’un objet d’événement à 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 . N’importe quel nombre de threads en attente, ou de threads qui commencent par la suite les 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é.

Quand l’état d’un objet d’événement de réinitialisation automatique est signalé, il reste signalé jusqu’à ce qu’un seul thread en attente soit libéré ; le système réinitialise automatiquement l’état non signé. Si aucun thread n’attend, l’état de l’objet d’événement reste signalé.

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

Un processus enfant créé par la fonction CreateProcess peut hériter d’un handle d’un objet d’événement si le paramètre lpEventAttributes de l’héritage CreateEvent activé.
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é.

Exemples

Pour obtenir un exemple qui utilise CreateEvent, consultez Utilisation d’objets d’événement.

Notes

L’en-tête synchapi.h définit CreateEvent comme un 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. Le mélange 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 XP [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	synchapi.h (inclure Windows.h sur Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll