Windows API Reference

Timer Objects

Timer objects are kernel objects that can be used to notify a thread after a specified interval or at a specific time. They are useful for scheduling tasks, implementing delays, or synchronizing operations.

Overview

A timer object is associated with a timer queue. When a timer expires, a user-defined callback function is invoked. Timer objects can be periodic or one-shot.

Key Concepts

• Timer Queue: A collection of timers. You can create a timer queue or use the system's default timer queue.
• Timer Callback: A user-defined function that is executed when the timer expires.
• Timer Period: The interval at which a periodic timer will repeatedly expire.
• Due Time: The absolute time or relative interval at which a timer will first expire.

Creating and Managing Timer Objects

The following functions are commonly used to create and manage timer objects:

CreateWaitableTimerEx

Creates or opens a timer- பெறுobject. This function allows specifying an extended attributes parameter.

HANDLE CreateWaitableTimerEx(
  LPSECURITY_ATTRIBUTES lpTimerAttributes,
  LPCWSTR lpTimerName,
  DWORD dwFlags,
  DWORD dwDesiredAccess
);
            

• Return Value: A handle to the timer object if successful, or NULL if it fails.
• Remarks: Use CloseHandle to close the timer object when it is no longer needed.

SetWaitableTimer

Starts or replaces the current setting of a waitable timer object. The system sets the timer object's state to signaled when the due time arrives.

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

• lpDueTime: A pointer to a LARGE_INTEGER structure that specifies the system time at which the timer will become signaled.
• lPeriod: If non-zero, this argument specifies the periodic wake-up interval in milliseconds.
• fResume: If this parameter is TRUE, the timer will be a resume-aware timer.

CancelWaitableTimer

Cancels a pending wait operation on the specified waitable timer object. If the timer has already expired, this function does not affect its state.

BOOL CancelWaitableTimer(
  HANDLE hTimer
);
            

Timer Callback Functions

When a timer expires and a callback routine is specified, the system calls the callback function.

VOID CALLBACK TimerCallback(
  LPVOID lpArg,
  DWORD  dwTimerLowValue,
  DWORD  dwTimerHighValue
);
            

• lpArg: The argument passed to SetWaitableTimer.
• dwTimerLowValue, dwTimerHighValue: These parameters represent the timer's expiration time.

Example Usage

The following snippet demonstrates creating a waitable timer that fires once after 5 seconds.

HANDLE hTimer = CreateWaitableTimer(NULL, FALSE, NULL);
if (hTimer == NULL) {
    // Handle error
    return 1;
}

// Set the timer to fire after 5 seconds (5000 milliseconds)
// Negative value means relative time
LARGE_INTEGER liDueTime;
liDueTime.QuadPart = -5000LL * 10000LL; // Convert milliseconds to 100-nanosecond intervals

if (!SetWaitableTimer(hTimer, &liDueTime, 0, NULL, NULL, FALSE)) {
    // Handle error
    CloseHandle(hTimer);
    return 1;
}

// Wait for the timer to become signaled
WaitForSingleObject(hTimer, INFINITE);

// Timer has expired
// ...

CloseHandle(hTimer);
            

Related Topics

• Event Objects
• Mutex Objects
• Semaphore Objects