WdfTimerStart method

[Applies to KMDF and UMDF]

The WdfTimerStart method starts a timer's clock.

Syntax


BOOLEAN WdfTimerStart(
  [in]  WDFTIMER Timer,
  [in]  LONGLONG DueTime
);

Parameters

Timer [in]

A handle to a framework timer object that was obtained by calling WdfTimerCreate.

DueTime [in]

A time period, in system time units (100-nanosecond intervals). The framework calls the driver's EvtTimerFunc callback function when the specified time period elapses. The time period value can be negative or positive as follows:

  • If the value is negative, the time period is relative to the current system time.
  • If the value is positive, the time period specifies an absolute time (which is actually relative to January 1, 1601).

Relative times are not affected by any changes to the system time that might occur within the specified time period. Absolute times do reflect system time changes.

The framework provides time conversion functions that convert time values into system time units.

Return value

WdfTimerStart returns TRUE if the timer object was in the system's timer queue. Otherwise, this method returns FALSE. For more information, see the following Remarks section.

A bug check occurs if the driver supplies an invalid object handle.

Remarks

After a driver calls WdfTimerStart, the framework calls the driver's EvtTimerFunc callback function when the time that is specified for the DueTime parameter elapses. After this first call, the framework calls the callback function each time that the time period that is specified by the Period member of the driver's WDF_TIMER_CONFIG structure elapses.

The expiration of the timer ultimately depends on the granularity of the system clock. The value specified for DueTime guarantees that the framework calls the driver's EvtTimerFunc callback function on or after the given DueTime. However, WdfTimerStart cannot override the granularity of the system clock, whatever the value specified for DueTime.

When a driver calls WdfTimerStart, its timer object is added to the system's queue of timer objects. If the timer is not a periodic timer, the system removes the timer object from the queue after the timer's "due time" has elapsed. If the timer is a periodic timer, the timer object remains in the queue until the driver calls WdfTimerStop.

A driver might call WdfTimerStart from its EvtTimerFunc callback function in order to restart a non-periodic timer after it expires.

WdfTimerStart returns TRUE if the driver has previously called WdfTimerStart and the timer object is still in the system's queue because the time period has not elapsed (or because it is a periodic timer). Before WdfTimerStart returns TRUE, the operating system resets the time period to the value that the driver specified in the new call to WdfTimerStart. The framework calls the EvtTimerFunc callback function only after the new time period elapses.

To stop the timer's clock, the driver can call WdfTimerStop.

For more information about framework timer objects, see Using Timers.

Examples

The following code example starts a timer. The framework will call the timer's EvtTimerFunc callback function after 10 milliseconds.


BOOLEAN inTimerQueue;

inTimerQueue = WdfTimerStart(
                             timerHandle,
                             WDF_REL_TIMEOUT_IN_MS(10)
                             );

Requirements

Minimum KMDF version

1.0

Minimum UMDF version

2.0

Header

Wdftimer.h (include Wdf.h)

Library

Wdf01000.sys (KMDF);
WUDFx02000.dll (UMDF)

IRQL

<=DISPATCH_LEVEL

DDI compliance rules

DriverCreate, KmdfIrql, KmdfIrql2

See also

EvtTimerFunc
WDF_TIMER_CONFIG
WdfTimerCreate
WdfTimerStop

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft