SetThreadpoolTimerEx, fonction (threadpoolapiset.h)

Article
03/02/2024

Définit l’objet minuteur, en remplaçant le minuteur précédent, le cas échéant. Un thread de travail appelle le rappel de l’objet minuteur après l’expiration du délai d’expiration spécifié.

Syntaxe

BOOL SetThreadpoolTimerEx(
  [in, out]      PTP_TIMER pti,
  [in, optional] PFILETIME pftDueTime,
  [in]           DWORD     msPeriod,
  [in, optional] DWORD     msWindowLength
);

Paramètres

[in, out] pti

Pointeur vers une structure de TP_TIMER qui définit l’objet de minuteur à définir. La fonction CreateThreadpoolTimer retourne ce pointeur.

[in, optional] pftDueTime

Pointeur vers une structure FILETIME qui spécifie l’heure absolue ou relative à laquelle le minuteur doit expirer. Si ce paramètre pointe vers une valeur positive, il indique l’heure absolue depuis le 1er janvier 1601 (UTC), mesurée en unités de 100 nanosecondes. Si ce paramètre pointe vers une valeur négative, il indique le temps d’attente par rapport à l’heure actuelle. Si ce paramètre pointe vers zéro, le minuteur expire immédiatement. Pour plus d’informations sur les valeurs de temps, consultez Heures de fichier.

Si ce paramètre a la valeur NULL, l’objet minuteur cesse de mettre en file d’attente les nouveaux rappels (mais les rappels déjà mis en file d’attente se produisent toujours).

Le minuteur est défini si le paramètre pftDueTime n’a pas la valeur NULL.

[in] msPeriod

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

Durée maximale pendant laquelle le système peut retarder avant d’appeler le rappel du minuteur. Si ce paramètre est défini, le système peut traiter par lot les appels pour économiser l’alimentation.

Valeur retournée

Retourne TRUE si le minuteur a été précédemment défini et a été annulé. Sinon, retourne la valeur FALSE.

Si l’état précédent du minuteur était « défini » et que la fonction retourne FALSE, un rappel est en cours ou sur le point de commencer. Consultez les remarques pour en savoir plus.

Remarques

La définition du minuteur annule le minuteur précédent, le cas échéant.

Dans certains cas, les fonctions de rappel peuvent s’exécuter après la fermeture du minuteur du pool de threads par une application. Pour éviter ce comportement, une application doit suivre les étapes décrites dans CloseThreadpoolTimer.

Si le délai d’échéance spécifié par pftDueTime est relatif, le temps que le système passe en veille ou en veille prolongée ne compte pas dans l’expiration du minuteur. Le minuteur est signalé lorsque la durée cumulée passée par le système à l’état de veille est égale à la durée ou à la période d’échéance relative du minuteur. Si l’heure d’échéance spécifiée par pftDueTime est absolue, le temps que le système passe en veille ou en veille prolongée compte dans l’expiration du minuteur. Si le minuteur expire alors que le système est en veille, le minuteur est signalé immédiatement lorsque le système se réveille.

Pour compiler une application qui utilise cette fonction, définissez _WIN32_WINNT comme 0x0600 ou une version ultérieure.

Exemples

Pour obtenir un exemple, consultez Utilisation des fonctions de pool de threads.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 8 [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows Server 2012 [applications de bureau \| Applications UWP]
Plateforme cible	Windows
En-tête	threadpoolapiset.h
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll