Edit

WDF_TIMER_CONFIG structure (wdftimer.h)

  • Article

[Applies to KMDF and UMDF]

The WDF_TIMER_CONFIG structure contains configuration information for a framework timer object.

Syntax

typedef struct _WDF_TIMER_CONFIG {
  ULONG         Size;
  PFN_WDF_TIMER EvtTimerFunc;
  ULONG         Period;
  BOOLEAN       AutomaticSerialization;
  ULONG         TolerableDelay;
  BOOLEAN       UseHighResolutionTimer;
} WDF_TIMER_CONFIG, *PWDF_TIMER_CONFIG;

Members

Size

The size, in bytes, of this structure.

EvtTimerFunc

A pointer to a driver-supplied EvtTimerFunc callback function, or NULL.

Period

A time period, in milliseconds. The framework calls the driver's EvtTimerFunc callback function repeatedly, whenever the specified number of milliseconds elapses. If this value is zero, the framework does not call the driver's EvtTimerFunc callback function repeatedly. Instead, it calls the callback function once, after the WdfTimerStart method's DueTime has elapsed. (The time period must be zero if WdfTimerCreate sets the execution level to WdfExecutionLevelPassive.) The time period cannot be a negative value.

AutomaticSerialization

A Boolean value that, if TRUE, indicates that the framework will synchronize execution of the timer object's EvtTimerFunc callback function with callback functions from other objects that are underneath the timer's parent device object. For more information, see the following Remarks section. If FALSE, the framework does not synchronize execution of the EvtTimerFunc callback function.

TolerableDelay

Specifies a tolerance, in milliseconds, for the timer period that Period specifies and for the initial time interval that the WdfTimerStart method's DueTime specifies. For a periodic timer, the time interval between two successive timer expirations will be in the range from (Period - TolerableDelay) to (Period + TolerableDelay). The initial expiration time will be in the range from DueTime to (DueTime + TolerableDelay). The TolerableDelay value cannot be negative.

The TolerableDelay member is available in version 1.9 and later versions of KMDF.

Starting in Windows 8.1, in a driver using at minimum KMDF 1.13 or UMDF 2.0, you can set this member to TolerableDelayUnlimited to specify that the system should not be woken up as a result of this timer's expiration.

If UseHighResolutionTimer is WdfTrue, you must set TolerableDelay to zero. Otherwise, WdfTimerCreate returns a failure code.

For more information about this member, see the following Remarks section.

UseHighResolutionTimer

KMDF only

This member is available starting with Windows 8.1 and KMDF version 1.13.

A WDF_TRI_STATE-typed value. If this value is WdfTrue, the framework uses a high resolution timer that has an accuracy of one millisecond. If the value is WdfFalse or WdfDefault, the framework uses a standard timer that has an accuracy matching the system clock tick interval, which is by default 15.6 milliseconds.

Warning  If you set UseHighResolutionTimer to WdfTrue, you must call WdfTimerStart with the DueTime parameter set to a negative value. Otherwise, the call causes the system to crash.
 
If UseHighResolutionTimer is WdfTrue, you must set TolerableDelay to zero. Otherwise, WdfTimerCreate returns a failure code.

For more information about this member, see the following Remarks section.

Remarks

The WDF_TIMER_CONFIG structure is used as input to the WdfTimerCreate method. To initialize a WDF_TIMER_CONFIG structure, your driver must call either WDF_TIMER_CONFIG_INIT or WDF_TIMER_CONFIG_INIT_PERIODIC.

Setting the AutomaticSerialization member of WDF_TIMER_CONFIG to TRUE has no effect if the parent object's synchronization scope is set to WdfSynchronizationScopeNone.

If the parent device object's execution level is WdfExecutionLevelPassive, you can set the AutomaticSerialization member to TRUE only if the timer object represents a passive-level timer.

If a driver uses the TolerableDelay member, the operating system can group together expiration times that are close together and process them all at once. If the operating system can handle the expirations of multiple timers at once, it can potentially keep the computer in a low-power state for longer periods of time to increase battery life.

If the TolerableDelay member is TolerableDelayUnlimited, the system will not return to its fully on (S0) state to service the timer if it is in a low-power (Sx) state when the timer expires. A driver can specify TolerableDelayUnlimited to increase battery life when the timer is related to a non-critical periodic operation.

Setting UseHighResolutionTimer to WdfTrue may result in decreased battery life.

For more information about AutomaticSerialization and synchronizing driver callback functions, see Synchronization Techniques for Framework-Based Drivers.

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

Requirements

Requirement Value
Minimum KMDF version 1.0
Minimum UMDF version 2.0
Header wdftimer.h (include Wdf.h)

See also

EvtTimerFunc

WDF_TIMER_CONFIG_INIT

WDF_TIMER_CONFIG_INIT_PERIODIC

WdfTimerCreate

WdfTimerStart