SetWaitableTimer

The SetWaitableTimer function activates the specified "waitable" timer. When the due time arrives, the timer is signaled and the thread that set the timer calls the optional completion routine.

BOOL SetWaitableTimer(
  HANDLE hTimer,                          // handle to a timer object
  const LARGE_INTEGER *pDueTime,          // when timer will become signaled
  LONG lPeriod,                           // periodic timer interval
  PTIMERAPCROUTINE pfnCompletionRoutine,  // completion routine
  LPVOID lpArgToCompletionRoutine,        // data for completion routine
  BOOL fResume                            // flag for resume state
);
 

Parameters

hTimer

Handle to the timer object. The CreateWaitableTimer or OpenWaitableTimer function returns this handle.

pDueTime

Specifies when the state of the timer is to be set to signaled, in 100 nanosecond intervals. Use the format described by the FILETIME structure. Positive values indicate absolute time. Be sure to use a UTC-based absolute time, as the system uses UTC-based time internally. Negative values indicate relative time. The actual timer accuracy depends on the capability of your hardware. For more information about UTC-based time, see System Time.

lPeriod

Specifies the period of the timer, in milliseconds. If lPeriod is zero, the timer is signaled once. If lPeriod is greater than zero, the timer is periodic. A periodic timer automatically reactivates each time the period elapses, until the timer is canceled using the CancelWaitableTimer function or reset using SetWaitableTimer. If lPeriod is less than zero, the function fails.

pfnCompletionRoutine

Pointer to an optional completion routine. The completion routine is application-defined function of type PTIMERAPCROUTINE to be executed when the timer is signaled. For more information on the timer callback function, see TimerAPCProc.

lpArgToCompletionRoutine

Pointer to the structure that is passed to the optional completion routine.

fResume

Specifies whether to restore a system in suspended power conservation mode when the timer state is set to signaled. If fResume is TRUE on a platform that does not support a restore, the call will succeed, but GetLastError returns ERROR_NOT_SUPPORTED.

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

Timers are initially inactive. To activate a timer, call SetWaitableTimer. If the timer is already active when you call SetWaitableTimer, the timer is stopped, then it is reactivated. Stopping the timer in this manner does not set the timer state to signaled, so threads blocked in a wait operation on the timer remain blocked.

When the specified due time arrives, the timer becomes inactive and the APC is queued to the thread that set the timer. The state of the timer is set to signaled, the timer is reactivated using the specified period, and the thread that set the timer calls the completion routine when it enters an alertable wait state. For more information, see QueueUserAPC.

If the thread that set the timer exits before the timer elapses, the timer is cancelled. If you call SetWaitableTimer on a timer that has been set by another thread and that thread is not in an alertable state, the completion routine is cancelled.

When a manual-reset timer is set to the signaled state, it remains in this state until SetWaitableTimer is called to reset the timer. As a result, a periodic manual-reset timer is set to the signaled state when the initial due time arrives and remains signaled until it is reset. When a synchronization timer is set to the signaled state, it remains in this state until a thread completes a wait operation on the timer object.

QuickInfo

  Windows NT: Requires version 4.0 or later.
  Windows: Requires Windows 98 or later.
  Windows CE: Unsupported.
  Header: Declared in winbase.h.
  Import Library: Use kernel32.lib.

See Also

Synchronization Overview, Synchronization Functions, CancelWaitableTimer, CreateWaitableTimer, FILETIME, OpenWaitableTimer, TimerAPCProc