SetWaitableTimer Function

The SetWaitableTimer function creates or opens a timer object and sets its available wait time to the system time. When the timer expires, the timer object is signaled.

Note

This function is used to create periodic timers. For one-shot timers, use CreateTimerQueueTimer.

Syntax


BOOL SetWaitableTimer(
  HANDLE               hTimer,
  const LARGE_INTEGER *lpDueTime,
  LONG                 lPeriod,
  PTIMER_CALLBACK      pfnCompletionRoutine,
  LPVOID               pvArgToCompletionRoutine,
  BOOL                 bResume
);

Parameters

Parameter Description
hTimer A handle to the timer object. The CreateWaitableTimer function returns this handle.
lpDueTime A pointer to a LARGE_INTEGER structure that specifies the wait interval in hundred-nanosecond units.
  • If the value is negative, the due time is the current system time plus the interval specified.
  • If the value is positive, the due time is set to the system time plus the interval specified.
  • If the value is zero, the timer is signaled immediately.
lPeriod The period of the timer, in milliseconds.
  • If this parameter is zero, the timer is signaled once when it expires.
  • If this parameter is positive, the timer is periodic, and its wake-up time is re-set to lpDueTime plus lPeriod milliseconds after each wait operation.
  • If this parameter is negative, the timer is periodic, and its wake-up time is re-set to the previous wake-up time plus lPeriod milliseconds after each wait operation.
pfnCompletionRoutine A pointer to an optional completion routine. If this parameter is NULL, the timer is a manual-reset timer. If it is not NULL, the timer is an auto-reset timer and pfnCompletionRoutine is the address of the function to be called when the timer expires.
pvArgToCompletionRoutine A pointer to a buffer that contains the argument to be passed to the pfnCompletionRoutine.
bResume If this parameter is TRUE, the timer is a system-wide timer that wakes the system from any hibernation or sleep state. The system's current time is used to calculate the due time. If this parameter is FALSE, the timer is not a system-wide timer.

Return Value

Value Description
TRUE The function succeeds.
FALSE The function fails. To get extended error information, call GetLastError.

Remarks

The SetWaitableTimer function is used to set a timer that can be waited on using functions such as WaitForSingleObject. If the timer expires, the timer object is signaled, and any threads waiting on it are released.

If pfnCompletionRoutine is not NULL, it is the address of a callback function that is executed when the timer expires. This callback function is responsible for signaling the timer object if necessary.

When bResume is TRUE, the timer becomes a system-wide timer. This means that if the system enters a hibernation or sleep state, the timer will wake the system when it expires.

Requirements

Minimum supported client Windows 2000 Professional
Minimum supported server Windows 2000 Server
Header winbase.h
Library Kernel32.lib
DLL Kernel32.dll

See Also