SetWaitableTimerEx, fonction (synchapi.h)

Active le minuteur d’attente spécifié et fournit des informations de contexte pour le minuteur. 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 SetWaitableTimerEx(
  [in] HANDLE              hTimer,
  [in] const LARGE_INTEGER *lpDueTime,
  [in] LONG                lPeriod,
  [in] PTIMERAPCROUTINE    pfnCompletionRoutine,
  [in] LPVOID              lpArgToCompletionRoutine,
  [in] PREASON_CONTEXT     WakeContext,
  [in] ULONG               TolerableDelay
);

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 utc absolue, 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 seule 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 SetWaitableTimerEx. Si lPeriod est inférieur à zéro, la fonction échoue.

[in] 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] lpArgToCompletionRoutine

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

[in] WakeContext

Pointeur vers une structure REASON_CONTEXT qui contient des informations de contexte pour le minuteur.

[in] TolerableDelay

Délai tolérable pour le délai d’expiration, en millisecondes.

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.

Notes

La fonction SetWaitableTimerEx est similaire à la fonction SetWaitableTimer , sauf que SetWaitableTimerEx peut être utilisé pour spécifier une chaîne de contexte et un délai tolérable pour l’expiration du minuteur.

Pour compiler une application qui utilise cette fonction, définissez _WIN32_WINNT comme 0x0601 ou version ultérieure. Pour plus d’informations, consultez Utilisation des en-têtes Windows.

Les minuteurs sont initialement inactifs. Pour activer un minuteur, appelez SetWaitableTimerEx. Si le minuteur est déjà actif lorsque vous appelez SetWaitableTimerEx, le minuteur est arrêté, puis 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, 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 vers le thread qui définit le minuteur s’il n’y a pas d’APC en attente déjà 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’elle 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 du 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 OVERLAPPED 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, l’arrêt 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 SetWaitableTimerEx 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.

Si le thread qui a appelé SetWaitableTimerEx se ferme, le minuteur est annulé. Cela arrête le minuteur avant qu’il ne puisse être défini sur l’état signalé et annule les API en attente ; elle ne modifie pas l’état signalé du minuteur.

Pour utiliser un minuteur afin de planifier un événement pour une fenêtre, utilisez la fonction SetTimer .

Spécifications

Voir aussi

REASON_CONTEXT

SetWaitableTimer