WdfTimerStart function (wdftimer.h)
[Applies to KMDF and UMDF]
The WdfTimerStart method starts a timer's clock.
Syntax
BOOLEAN WdfTimerStart(
[in] WDFTIMER Timer,
[in] LONGLONG DueTime
);
Parameters
[in] Timer
A handle to a framework timer object that was obtained by calling WdfTimerCreate.
[in] DueTime
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).
Warning
If you set the UseHighResolutionTimer member of WDF_TIMER_CONFIG to WdfTrue, you must call WdfTimerStart with the DueTime parameter set to a negative value. Otherwise, the call causes the system to crash.
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
Drivers must always call WdfTimerStart to start a timer after creating it, regardless of whether the timer is a periodic timer or not.
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
| Requirement | Value |
|---|---|
| Target Platform | Universal |
| 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(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |