CreateTimerQueueTimer

The CreateTimerQueueTimer function 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.

BOOL CreateTimerQueueTimer(
  PHANDLE phNewTimer,           // handle to timer
  HANDLE TimerQueue,            // handle to timer queue
  WAITORTIMERCALLBACK Callback, // timer callback function
  PVOID Parameter,              // callback parameter
  DWORD DueTime,                // timer due time
  DWORD Period,                 // timer period
  ULONG Flags                   // options
);

Parameters

phNewTimer

[out] Pointer to a buffer that receives a handle to the timer-queue timer on return.

TimerQueue

[in] Handle to a timer queue. This handle is returned by the CreateTimerQueue function.

If this parameter is NULL, the timer is associated with the default timer queue.

Callback

[in] Pointer to the application-defined function of type WAITORTIMERCALLBACK to be executed when the timer expires. For more information, see WaitOrTimerCallback.

Parameter

[in] Specifies a single parameter value that will be passed to the callback function.

DueTime

[in] Specifies when the timer is to be set to the signaled state, in milliseconds.

Period

[in] Specifies 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.

Flags

[in] This parameter can be one or more of the following values.

Value	Meaning
WT_EXECUTEINTIMERTHREAD	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.
WT_EXECUTEINIOTHREAD	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. The callback function is queued as an APC. Be sure to address reentrancy issues if the function performs an alertable wait operation.
WT_EXECUTEINPERSISTENTTHREAD	The callback function is queued to a thread that never terminates. This flag should be used only for short tasks or it could affect other timer operations. Note that currently no worker thread is persistent, although no worker thread will terminate if there are any pending I/O requests.
WT_EXECUTELONGFUNCTION	Specifies that the callback function can perform a long wait. This flag helps the system to decide if it should create a new thread.
WT_EXECUTEONLYONCE	The timer will be set to the signaled state only once.

Return Values

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.

To cancel a timer, call the DeleteTimerQueueTimer function. To cancel all timers in a timer queue, call the DeleteTimerQueueEx function.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Kernel32.lib.

See Also

Synchronization Overview, Synchronization Functions, CreateTimerQueue, DeleteTimerQueueEx, DeleteTimerQueueTimer, Thread Pooling