Fonction CreateTimerQueueTimer (threadpoollegacyapiset.h)

Article
03/04/2024

Crée un minuteur-file d’attente. Ce minuteur expire à l’heure d’échéance spécifiée, puis après chaque période spécifiée. Lorsque le minuteur expire, la fonction de rappel est appelée.

Syntaxe

BOOL CreateTimerQueueTimer(
  [out]          PHANDLE             phNewTimer,
  [in, optional] HANDLE              TimerQueue,
  [in]           WAITORTIMERCALLBACK Callback,
  [in, optional] PVOID               Parameter,
  [in]           DWORD               DueTime,
  [in]           DWORD               Period,
  [in]           ULONG               Flags
);

Paramètres

[out] phNewTimer

Pointeur vers une mémoire tampon qui reçoit un handle vers le minuteur-file d’attente au retour. Lorsque ce handle a expiré et n’est plus nécessaire, relâchez-le en appelant DeleteTimerQueueTimer.

[in, optional] TimerQueue

Handle de la file d’attente du minuteur. Ce handle est retourné par la fonction CreateTimerQueue .

Si ce paramètre a la valeur NULL, le minuteur est associé à la file d’attente du minuteur par défaut.

[in] Callback

Pointeur vers la fonction définie par l’application de type WAITORTIMERCALLBACK à exécuter à l’expiration du minuteur. Pour plus d’informations, consultez WaitOrTimerCallback.

[in, optional] Parameter

Valeur de paramètre unique qui sera passée à la fonction de rappel.

[in] DueTime

Durée en millisecondes par rapport à l’heure actuelle qui doit s’écouler avant que le minuteur soit signalé pour la première fois.

[in] Period

Période du minuteur, en millisecondes. Si ce paramètre est égal à zéro, le minuteur est signalé une fois. Si ce paramètre 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é.

[in] Flags

Ce paramètre peut être une ou plusieurs des valeurs suivantes de WinNT.h.

Valeur	Signification
WT_EXECUTEDEFAULT 0x00000000	Par défaut, la fonction de rappel est mise en file d’attente vers un thread de travail non-E/S.
WT_EXECUTEINTIMERTHREAD 0x00000020	La fonction de rappel est appelée par le thread du minuteur lui-même. Cet indicateur doit être utilisé uniquement pour les tâches de courte durée, sinon il peut affecter d’autres opérations du minuteur. La fonction de rappel est mise en file d’attente en tant que APC. Il ne doit pas effectuer d’opérations d’attente pouvant être alerté.
WT_EXECUTEINIOTHREAD 0x00000001	Cet indicateur n’est pas utilisé. Windows Server 2003 et Windows XP : La fonction de rappel est mise en file d’attente vers un thread de travail d’E/S. Cet indicateur doit être utilisé si la fonction doit être exécutée dans un thread qui attend dans un état alertable. Les threads de travail d’E/S ont été supprimés à partir de Windows Vista et De Windows Server 2008.
WT_EXECUTEINPERSISTENTTHREAD 0x00000080	La fonction de rappel est mise en file d’attente vers un thread qui ne se termine jamais. Cela ne garantit pas que le même thread soit utilisé à chaque fois. Cet indicateur doit être utilisé uniquement pour les tâches de courte durée, sinon il peut affecter d’autres opérations du minuteur. Cet indicateur doit être défini si le thread appelle des fonctions qui utilisent des API. Pour plus d’informations, consultez Appels de procédure asynchrone. Notez qu’aucun thread de travail n’est réellement persistant, bien qu’aucun thread de travail ne se termine s’il y a des demandes d’E/S en attente.
WT_EXECUTELONGFUNCTION 0x00000010	La fonction de rappel peut effectuer une longue attente. Cet indicateur aide le système à décider s’il doit créer un thread.
WT_EXECUTEONLYONCE 0x00000008	Le minuteur n’est défini à l’état signalé qu’une seule fois. Si cet indicateur est défini, le paramètre Period doit être égal à zéro.
WT_TRANSFER_IMPERSONATION 0x00000100	Les fonctions de rappel utilisent le jeton d’accès actuel, qu’il s’agisse d’un jeton de processus ou d’emprunt d’identité. Si cet indicateur n’est pas spécifié, les fonctions de rappel s’exécutent uniquement avec le jeton de processus. Windows XP : Cet indicateur n’est pas pris en charge tant que Windows XP avec SP2 et Windows Server 2003.

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

Si les paramètres DueTime et Period ne sont pas nuls, le minuteur est d’abord signalé à l’heure d’échéance, puis régulièrement. Le rappel est appelé chaque fois que la période s’écoule, que le rappel précédent soit terminé ou non. Les fonctions de rappel sont mises en file d’attente vers le pool de threads. Ces threads sont soumis à des retards de planification, de sorte que le minutage peut varier en fonction de ce qui se passe dans l’application ou le système.

Le temps passé par le système en veille ou en veille prolongée ne compte pas dans l’expiration du minuteur. Le minuteur est signalé lorsque le temps cumulé passé par le système à l’état de veille correspond à l’heure ou à la période d’échéance du minuteur.

Windows Server 2003 et Windows XP : Le temps que le système passe en veille ou en veille prolongée compte pour l’expiration du minuteur. Si le minuteur expire pendant que le système est en veille, le minuteur est immédiatement signalé lorsque le système se réveille.

Pour annuler un minuteur, appelez la fonction DeleteTimerQueueTimer . Pour annuler tous les minuteurs d’une file d’attente du minuteur, appelez la fonction DeleteTimerQueueEx .

Par défaut, le pool de threads a un maximum de 500 threads. Pour augmenter cette limite, utilisez la macro WT_SET_MAX_THREADPOOL_THREAD définie dans WinNT.h.

#define WT_SET_MAX_THREADPOOL_THREADS(Flags,Limit) \
    ((Flags)|=(Limit)&lt;&lt;16)

Utilisez cette macro lors de la spécification du paramètre Flags . Les paramètres macro sont les indicateurs souhaités et la nouvelle limite (jusqu’à (2<<16)-1 threads). Toutefois, notez que votre application peut améliorer ses performances en gardant le nombre de threads de travail faible.

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

Exemples

Pour obtenir un exemple qui utilise CreateTimerQueueTimer, consultez Utilisation des files d’attente du minuteur.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	threadpoollegacyapiset.h
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll