CreateTimerQueueTimer function (threadpoollegacyapiset.h)
Creates a timer-queue timer. This timer expires at the specified due time, then after every specified period. When the timer expires, the callback function is called.
Syntax
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
);
Parameters
[out] phNewTimer
A pointer to a buffer that receives a handle to the timer-queue timer on return. When this handle has expired and is no longer required, release it by calling DeleteTimerQueueTimer.
[in, optional] TimerQueue
A handle to the timer queue. This handle is returned by the CreateTimerQueue function.
If this parameter is NULL, the timer is associated with the default timer queue.
[in] Callback
A pointer to the application-defined function of type WAITORTIMERCALLBACK to be executed when the timer expires. For more information, see WaitOrTimerCallback.
[in, optional] Parameter
A single parameter value that will be passed to the callback function.
[in] DueTime
The amount of time in milliseconds relative to the current time that must elapse before the timer is signaled for the first time.
[in] Period
The period of the timer, 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] Flags
This parameter can be one or more of the following values from WinNT.h.
| Value | Meaning |
|---|---|
|
By default, the callback function is queued to a non-I/O worker thread. |
|
The callback function is invoked by the timer thread itself. This flag should be used only for short tasks or it could affect other timer operations.
The callback function is queued as an APC. It should not perform alertable wait operations. |
|
This flag is not used.
Windows Server 2003 and Windows XP: The callback function is queued to an I/O worker thread. This flag should be used if the function should be executed in a thread that waits in an alertable state. I/O worker threads were removed starting with Windows Vista and Windows Server 2008. |
|
The callback function is queued to a thread that never terminates. It does not guarantee that the same thread is used each time. This flag should be used only for short tasks or it could affect other timer operations.
This flag must be set if the thread calls functions that use APCs. For more information, see Asynchronous Procedure Calls. Note that currently no worker thread is truly persistent, although no worker thread will terminate if there are any pending I/O requests. |
|
The callback function can perform a long wait. This flag helps the system to decide if it should create a new thread. |
|
The timer will be set to the signaled state only once. If this flag is set, the Period parameter must be zero. |
|
Callback functions will use the current access token, whether it is a process or impersonation token. If this flag is not specified, callback functions execute only with the process token.
Windows XP: This flag is not supported until Windows XP with SP2 and Windows Server 2003. |
Return value
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
If the DueTime and Period parameters are both nonzero, the timer will be signaled first at the due time, then periodically. The callback is called every time the period elapses, whether or not the previous callback has finished executing. Callback functions are queued to the thread pool. These threads are subject to scheduling delays, so the timing can vary depending on what else is happening in the application or the system.
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 matches the timer's due time or period.
Windows Server 2003 and Windows XP: The time that the system spends in sleep or hibernation counts 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 cancel a timer, call the DeleteTimerQueueTimer function. To cancel all timers in a timer queue, call the DeleteTimerQueueEx function.
By default, the thread pool has a maximum of 500 threads. To raise this limit, use the WT_SET_MAX_THREADPOOL_THREAD macro defined in WinNT.h.
#define WT_SET_MAX_THREADPOOL_THREADS(Flags,Limit) \
((Flags)|=(Limit)<<16)
Use this macro when specifying the Flags parameter. The macro parameters are the desired flags and the new limit (up to (2<<16)-1 threads). However, note that your application can improve its performance by keeping the number of worker threads low.
To compile an application that uses this function, define _WIN32_WINNT as 0x0500 or later. For more information, see Using the Windows Headers.
Examples
For an example that uses CreateTimerQueueTimer, see Using Timer Queues.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps only] |
| Minimum supported server | Windows Server 2003 [desktop apps only] |
| Target Platform | Windows |
| Header | threadpoollegacyapiset.h |
| Library | Kernel32.lib |
| DLL | Kernel32.dll |