Fonction CreateTimerQueueTimer (threadpoollegacyapiset.h)
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 |
|---|---|
|
Par défaut, la fonction de rappel est mise en file d’attente vers un thread de travail non-E/S. |
|
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é. |
|
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. |
|
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. |
|
La fonction de rappel peut effectuer une longue attente. Cet indicateur aide le système à décider s’il doit créer un thread. |
|
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. |
|
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)<<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 |