SetWaitableTimer, fonction (synchapi.h)
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 disposer du 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é, dans 100 nanosecondes intervalles. Utilisez le format décrit par la structure FILETIME. Les valeurs positives indiquent l’heure absolue. Veillez à utiliser un temps absolu basé sur 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.
Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 et Windows Server 2008 R2 : Si le temps relatif est spécifié, le minuteur inclut du temps passé dans des états à faible alimentation. Par exemple, le minuteur continue de compter pendant que l’ordinateur est endormi.
Windows 8 et versions ultérieures, Windows Server 2012 et versions ultérieures : Si le temps relatif est spécifié, le minuteur n’inclut pas le temps passé dans les états à faible alimentation. Par exemple, le minuteur ne continue pas à compter pendant que l’ordinateur est endormi.
[in] lPeriod
Période du minuteur, en millisecondes. Si lPeriod est égal à zéro, le minuteur est signalé une seule fois. Si lPeriod est supérieur à zéro, le minuteur est périodique. Un minuteur périodique réactive automatiquement chaque fois que la période s’est écoulée, jusqu’à ce que le minuteur soit annulé à l’aide de la fonction CancelWaitableTimer ou de la réinitialisation à 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 est TRUE, restaure un système en mode de conservation de l’alimentation suspendu 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 de retour
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’erreur étendues, 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 façon 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, elle 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 sur le thread qui définit le minuteur s’il n’y a pas encore d’APC en attente en 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 alertable. 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 l’APC, utilisez un objet waitable tel qu’un minuteur créé avec CreateThreadpoolTimer. Pour les E/S, utilisez un objet d’achèvement d’E/S créé avec CreateThreadpoolIo ou un hEvent-based STRUCTURE OVERLAPPED où l’événement peut être passé à la fonction SetThreadpoolWait.
Si le thread qui définit le minuteur se termine et qu’il existe une routine d’achèvement 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 sur 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 le délai d’échéance initial 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 en tant que 0x0400 ou version ultérieure. Pour plus d’informations, consultez Utilisation des en-têtes Windows.
Pour utiliser un minuteur pour 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 considérablement différentes de ce que vous attendez : certains peuvent être mesurés en millisecondes (pour ceux qui utilisent une puce de minuteur basée sur RTC), à ceux mesurés 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 de la résolution dépend de l’horloge matérielle utilisée par l’API particulière. Pour plus d’informations, consultez votre documentation matérielle.
Exemples
Pour obtenir un exemple qui utilise SetWaitableTimer, consultez Utilisation des objets du minuteur d’attente.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows XP [applications de bureau | Applications UWP] |
| serveur minimum pris en charge | Windows Server 2003 [applications de bureau | Applications UWP] |
| plateforme cible | Windows |
| d’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 |