CreateWaitableTimerExW, fonction (synchapi.h)

Article
08/26/2023

Crée ou ouvre un objet minuteur d’attente et retourne un handle à l’objet.

Syntaxe

HANDLE CreateWaitableTimerExW(
  [in, optional] LPSECURITY_ATTRIBUTES lpTimerAttributes,
  [in, optional] LPCWSTR               lpTimerName,
  [in]           DWORD                 dwFlags,
  [in]           DWORD                 dwDesiredAccess
);

Paramètres

[in, optional] lpTimerAttributes

Pointeur vers une structure SECURITY_ATTRIBUTES . Si ce paramètre a la valeur NULL, le handle du minuteur ne peut pas être hérité par les processus enfants.

Si lpTimerAttributes a la valeur NULL, l’objet minuteur obtient un descripteur de sécurité par défaut et le handle ne peut pas être hérité. Les listes de contrôle d’accès dans le descripteur de sécurité par défaut d’un minuteur proviennent du jeton principal ou d’emprunt d’identité du créateur.

[in, optional] lpTimerName

Nom de l’objet minuteur. Le nom est limité à MAX_PATH caractères. La comparaison de noms respecte la casse.

Si lpTimerName a la valeur NULL, l’objet minuteur est créé sans nom.

Si lpTimerName correspond au nom d’un événement, d’un sémaphore, d’un mutex, d’un travail ou d’un objet de mappage de fichiers existant, la fonction échoue et 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.

[in] dwFlags

Ce paramètre peut être 0 ou les valeurs suivantes.

Valeur	Signification
CREATE_WAITABLE_TIMER_MANUAL_RESET 0x00000001	Le minuteur doit être réinitialisé manuellement. Sinon, le système réinitialise automatiquement le minuteur après avoir libéré un seul thread d’attente.
CREATE_WAITABLE_TIMER_HIGH_RESOLUTION 0x00000002	Crée un minuteur haute résolution. Utilisez cette valeur pour les situations critiques dans le temps où des délais d’expiration courts de l’ordre de quelques millisecondes sont inacceptables. Cette valeur est prise en charge dans Windows 10, version 1803 et ultérieure.

[in] dwDesiredAccess

Masque d’accès pour l’objet minuteur. 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 de l’objet minuteur. Si l’objet minuteur nommé existe 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 d’appel peut spécifier le handle de l’objet minuteur dans un appel à l’une des fonctions d’attente.

Plusieurs processus peuvent avoir des handles pour le même objet de minuteur, ce qui permet d’utiliser l’objet pour la synchronisation interprocess.

Un processus créé par la fonction CreateProcess peut hériter d’un handle vers un objet de minuteur si le paramètre lpTimerAttributes de CreateWaitableTimerEx active l’héritage.
Un processus peut spécifier le handle de l’objet minuteur dans un appel à la fonction DuplicateHandle . Le handle résultant peut être utilisé par un autre processus.
Un processus peut spécifier le nom d’un objet minuteur dans un appel à la fonction OpenWaitableTimer ou CreateWaitableTimerEx .

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

Pour associer un minuteur à une fenêtre, utilisez la fonction SetTimer .

Configuration requise


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)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll

Voir aussi

CloseHandle

Fonctions de synchronisation

Objets du minuteur à attente

Partager via