KeSetTimer

The KeSetTimer routine sets the absolute or relative interval at which a timer object is to be set to a signaled state and, optionally, supplies a CustomTimerDpc routine to be executed when that interval expires.

BOOLEAN 
  KeSetTimer(
    IN PKTIMER  Timer,
    IN LARGE_INTEGER  DueTime,
    IN PKDPC  Dpc  OPTIONAL
    );

Parameters

Timer

Pointer to a timer object that was initialized with KeInitializeTimer or KeInitializeTimerEx.

DueTime

Specifies the absolute or relative time at which the timer is to expire. If the value of the DueTime parameter is negative, the expiration time is relative to the current system time. Otherwise, the expiration time is absolute. The expiration time is expressed in system time units (100-nanosecond intervals). Absolute expiration times track any changes in the system time; relative expiration times are not affected by system time changes.

Dpc

Pointer to a DPC object that was initialized by KeInitializeDpc. This parameter is optional.

Return Value

If the timer object was already in the system timer queue, KeSetTimer returns TRUE.

Headers

Declared in wdm.h and ntddk.h. Include wdm.h or ntddk.h.

Comments

KeSetTimer:

• Computes the expiration time.
• Sets the timer to a not signaled state.
• Inserts the timer object in the system timer queue.

If the timer object was already in the timer queue, it is implicitly canceled before being set to the new expiration time. A call to KeSetTimer before the previously specified DueTime has expired cancels both the timer and the call to the Dpc, if any, associated with the previous call.

If the Dpc parameter is specified, a DPC object is associated with the timer object. When the timer expires, the timer object is removed from the system timer queue and its state is set to signaled. If a DPC object was associated with the timer when it was set, the DPC object is inserted in the system DPC queue to be executed as soon as conditions permit after the timer interval expires.

The expiration of the timer ultimately depends on the granularity of the system clock. The value specified for DueTime guarantees that the timer object is set to a signaled state on or after the given DueTime. However, KeSetTimer cannot override the granularity of the system clock, whatever the value specified for DueTime.

Only one instantiation of a given DPC object can be queued at any given moment. To avoid potential race conditions, the DPC passed to KeSetTimer should not be passed to KeInsertQueueDpc.

Drivers must cancel any active timers in their Unload routines. Use KeCancelTimer to cancel any timers.

A caller cannot wait at raised IRQL nor in an arbitrary thread context for a timer to expire by calling KeWaitXxx.

Callers of KeSetTimer can specify one expiration time for a timer. To set a recurring timer use KeSetTimerEx.

Callers of KeSetTimer must be running at IRQL <= DISPATCH_LEVEL.

See Also

KeCancelTimer, KeInitializeDpc, KeInitializeTimer, KeInitializeTimerEx, KeReadStateTimer, KeSetTimerEx, KeWaitForMultipleObjects, KeWaitForSingleObject