CreateWaitableTimerW, fonction (synchapi.h)

Article
03/02/2024

Crée ou ouvre un objet minuteur pouvant être attendu.

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

Syntaxe

HANDLE CreateWaitableTimerW(
  [in, optional] LPSECURITY_ATTRIBUTES lpTimerAttributes,
  [in]           BOOL                  bManualReset,
  [in, optional] LPCWSTR               lpTimerName
);

Paramètres

[in, optional] lpTimerAttributes

Pointeur vers une structure SECURITY_ATTRIBUTES qui spécifie un descripteur de sécurité pour le nouvel objet de minuteur et détermine si les processus enfants peuvent hériter du handle retourné.

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] bManualReset

Si ce paramètre a la valeur TRUE, le minuteur est un minuteur de notification de réinitialisation manuelle. Sinon, le minuteur est un minuteur de synchronisation.

[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 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.

Valeur retournée

Si la fonction réussit, la valeur de retour est un handle pour l’objet minuteur. Si l’objet minuteur nommé existe avant l’appel de la fonction, la fonction retourne un handle à l’objet existant et GetLastError renvoie 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 CreateWaitableTimer est créé avec le droit d’accès TIMER_ALL_ACCESS ; il peut être utilisé dans n’importe quelle fonction qui nécessite un handle pour un objet minuteur, à condition que l’appelant ait obtenu l’accès. Si un minuteur est créé à partir d’un service ou d’un thread qui emprunte l’identité d’un autre utilisateur, vous pouvez appliquer un descripteur de sécurité au minuteur lorsque vous le créez, ou 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 appelant peut spécifier le handle d’objet minuteur dans un appel à l’une des fonctions d’attente.

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

Un processus créé par la fonction CreateProcess peut hériter d’un handle à un objet de minuteur si le paramètre lpTimerAttributes de CreateWaitableTimer active l’héritage.
Un processus peut spécifier le handle d’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 CreateWaitableTimer .

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 compiler une application qui utilise cette fonction, définissez _WIN32_WINNT comme 0x0400 ou version ultérieure. Pour plus d’informations, consultez Utilisation des en-têtes Windows.

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

Exemples

Pour obtenir un exemple qui utilise CreateWaitableTimer, consultez Utilisation d’objets du minuteur d’attente.

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