SetThreadpoolTimerEx function (threadpoolapiset.h)

Article
02/22/2024

Sets the timer object, replacing the previous timer, if any. A worker thread calls the timer object's callback after the specified timeout expires.

Syntax

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

Parameters

[in, out] pti

A pointer to a TP_TIMER structure that defines the timer object to set. The CreateThreadpoolTimer function returns this pointer.

[in, optional] pftDueTime

A pointer to a FILETIME structure that specifies the absolute or relative time at which the timer should expire. If this parameter points to a positive value, it indicates the absolute time since January 1, 1601 (UTC), measured in 100 nanosecond units. If this parameter points to a negative value, it indicates the amount of time to wait relative to the current time. If this parameter points to zero, then the timer expires immediately. For more information about time values, see File Times.

If this parameter is NULL, the timer object will cease to queue new callbacks (but callbacks already queued will still occur).

The timer is set if the pftDueTime parameter is non-NULL.

[in] msPeriod

The timer period, in milliseconds. If this parameter is zero, the timer is signaled once. If this parameter is greater than zero, the timer is periodic. A periodic timer automatically reactivates each time the period elapses, until the timer is canceled.

[in, optional] msWindowLength

The maximum amount of time the system can delay before calling the timer callback. If this parameter is set, the system can batch calls to conserve power.

Return value

Returns TRUE if the timer was previously set and was canceled. Otherwise returns FALSE.

If the timer's previous state was "set", and the function returns FALSE, then a callback is in progress or about to commence. See the remarks for further discussion.

Remarks

Setting the timer cancels the previous timer, if any.

In some cases, callback functions might run after an application closes the threadpool timer. To prevent this behavior, an application should follow the steps described in CloseThreadpoolTimer.

If the due time specified by pftDueTime is relative, the time that the system spends in sleep or hibernation does not count toward the expiration of the timer. The timer is signaled when the cumulative amount of elapsed time the system spends in the waking state equals the timer's relative due time or period. If the due time specified by pftDueTime is absolute, the time that the system spends in sleep or hibernation does count toward the expiration of the timer. If the timer expires while the system is sleeping, the timer is signaled immediately when the system wakes.

To compile an application that uses this function, define _WIN32_WINNT as 0x0600 or higher.

Examples

For an example, see Using the Thread Pool Functions.

Requirements

Requirement	Value
Minimum supported client	Windows 8 [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2012 [desktop apps \| UWP apps]
Target Platform	Windows
Header	threadpoolapiset.h
Library	Kernel32.lib
DLL	Kernel32.dll