Fonction SetWaitableTimer (synchapi.h)

Article
03/02/2024

Active le minuteur d’attente spécifié. Lorsque l’heure d’échéance arrive, le minuteur est signalé et le thread qui définit le minuteur appelle la routine d’achèvement facultative.

Syntaxe

BOOL SetWaitableTimer(
  [in]           HANDLE              hTimer,
  [in]           const LARGE_INTEGER *lpDueTime,
  [in]           LONG                lPeriod,
  [in, optional] PTIMERAPCROUTINE    pfnCompletionRoutine,
  [in, optional] LPVOID              lpArgToCompletionRoutine,
  [in]           BOOL                fResume
);

Paramètres

[in] hTimer

Handle de l’objet minuteur. La fonction CreateWaitableTimer ou OpenWaitableTimer retourne ce handle.

Le handle doit avoir le droit d’accès TIMER_MODIFY_STATE . Pour plus d’informations, consultez Synchronisation Des droits d’accès et de sécurité des objets.

[in] lpDueTime

Heure après laquelle l’état du minuteur doit être défini sur signal, par intervalles de 100 nanosecondes. Utilisez le format décrit par la structure FILETIME . Les valeurs positives indiquent l’heure absolue. Veillez à utiliser une heure absolue UTC, car le système utilise l’heure UTC en interne. Les valeurs négatives indiquent le temps relatif. La précision réelle du minuteur dépend de la capacité de votre matériel. Pour plus d’informations sur l’heure UTC, consultez Heure système.

[in] lPeriod

Période du minuteur, en millisecondes. Si lPeriod est égal à zéro, le minuteur est signalé une fois. Si lPeriod est supérieur à zéro, le minuteur est périodique. Un minuteur périodique se réactive automatiquement chaque fois que la période s’écoule, jusqu’à ce que le minuteur soit annulé à l’aide de la fonction CancelWaitableTimer ou réinitialisé à l’aide de SetWaitableTimer. Si lPeriod est inférieur à zéro, la fonction échoue.

[in, optional] pfnCompletionRoutine

Pointeur vers une routine d’achèvement facultative. La routine d’achèvement est une fonction définie par l’application de type PTIMERAPCROUTINE à exécuter lorsque le minuteur est signalé. Pour plus d’informations sur la fonction de rappel du minuteur, consultez TimerAPCProc. Pour plus d’informations sur les API et les threads de pool de threads, consultez Remarques.

[in, optional] lpArgToCompletionRoutine

Pointeur vers une structure passée à la routine d’achèvement.

[in] fResume

Si ce paramètre a la valeur TRUE, restaure un système en mode de conservation de l’alimentation suspendue lorsque l’état du minuteur est défini sur signal. Sinon, le système n’est pas restauré. Si le système ne prend pas en charge une restauration, l’appel réussit, mais GetLastError retourne ERROR_NOT_SUPPORTED.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

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

Remarques

Les minuteurs sont initialement inactifs. Pour activer un minuteur, appelez SetWaitableTimer. Si le minuteur est déjà actif lorsque vous appelez SetWaitableTimer, le minuteur est arrêté, puis il est réactivé. L’arrêt du minuteur de cette manière ne définit pas l’état du minuteur sur signal, de sorte que les threads bloqués dans une opération d’attente sur le minuteur restent bloqués. Toutefois, il annule toutes les routines d’achèvement en attente.

Lorsque l’heure d’échéance spécifiée arrive, le minuteur devient inactif et l’APC facultatif est mis en file d’attente vers le thread qui définit le minuteur s’il n’y a pas d’APC en attente déjà mis en file d’attente. L’état du minuteur est défini sur signalé, le minuteur est réactivé à l’aide de la période spécifiée et le thread qui définit le minuteur appelle la routine d’achèvement lorsqu’il entre dans un état d’attente pouvant être alerté. Pour plus d’informations, consultez QueueUserAPC. Notez que les API ne fonctionnent pas aussi bien que d’autres mécanismes de signalisation pour les threads de pool de threads, car le système contrôle la durée de vie des threads de pool de threads, il est donc possible qu’un thread soit arrêté avant la remise de la notification. Au lieu d’utiliser le paramètre pfnCompletionRoutine ou un autre mécanisme de signalisation basé sur APC, utilisez un objet d’attente tel qu’un minuteur créé avec CreateThreadpoolTimer. Pour les E/S, utilisez un objet d’achèvement d’E/S créé avec CreateThreadpoolIo ou une structure CHEVAUCHEMENT BASÉE sur hEvent où l’événement peut être passé à la fonction SetThreadpoolWait.

Si le thread qui définit le minuteur se termine et qu’une routine d’achèvement est associée, le minuteur est annulé. Toutefois, l’état du minuteur reste inchangé. S’il n’existe aucune routine d’achèvement, la fin du thread n’a aucun effet sur le minuteur.

Lorsqu’un minuteur de réinitialisation manuelle est défini à l’état signalé, il reste dans cet état jusqu’à ce que SetWaitableTimer soit appelé pour réinitialiser le minuteur. Par conséquent, un minuteur de réinitialisation manuelle périodique est défini sur l’état signalé lorsque l’heure d’échéance initiale arrive et reste signalé jusqu’à ce qu’il soit réinitialisé. Lorsqu’un minuteur de synchronisation est défini sur l’état signalé, il reste dans cet état jusqu’à ce qu’un thread termine une opération d’attente sur l’objet minuteur.

Si l’heure système est ajustée, l’heure d’échéance des minuteurs absolus en attente est ajustée.

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 utiliser un minuteur afin de planifier un événement pour une fenêtre, utilisez la fonction SetTimer .

Les API qui traitent des minuteurs utilisent différentes horloges matérielles. Ces horloges peuvent avoir des résolutions sensiblement différentes de ce que vous attendez : certaines peuvent être mesurées en millisecondes (pour ceux qui utilisent une puce de minuteur basée sur RTC) et celles mesurées en nanosecondes (pour ceux qui utilisent des compteurs ACPI ou TSC). Vous pouvez modifier la résolution de votre API avec un appel aux fonctions timeBeginPeriod et timeEndPeriod . La précision à laquelle vous pouvez modifier la résolution dépend de l’horloge matérielle que l’API particulière utilise. Pour plus d’informations, case activée votre documentation matérielle.

Exemples

Pour obtenir un exemple qui utilise SetWaitableTimer, consultez Utilisation d’objets waitable Minuter.

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