WDF_TIMER_CONFIG 结构 (wdftimer.h)

项目
02/27/2024

[适用于 KMDF 和 UMDF]

WDF_TIMER_CONFIG 结构包含框架计时器对象的配置信息。

语法

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;

成员

Size

此结构的大小（以字节为单位）。

EvtTimerFunc

指向驱动程序提供的 EvtTimerFunc 回调函数的指针，或 NULL。

Period

一个时间段，以毫秒为单位。只要经过指定的毫秒数，框架就重复调用驱动程序的 EvtTimerFunc 回调函数。如果此值为零，则框架不会重复调用驱动程序的 EvtTimerFunc 回调函数。相反，它会在 WdfTimerStart 方法的 DueTime 过后调用回调函数一次。 (如果 WdfTimerCreate 将执行级别设置为 WdfExecutionLevelPassive.) 则时间段必须为零。

AutomaticSerialization

如果 为 TRUE，则表示框架会将计时器对象的 EvtTimerFunc 回调函数的执行与计时器父设备对象下其他对象的回调函数同步。有关更多信息，请参见下面的“备注”部分。如果 为 FALSE，则框架不会同步 EvtTimerFunc 回调函数的执行。

TolerableDelay

指定 Period 指定的计时器周期的容差（以毫秒为单位），以及 WdfTimerStart 方法的 DueTime 指定的初始时间间隔。对于定期计时器，两个连续计时器过期之间的时间间隔范围为从 (周期 - TolerableDelay) 到 (Period + TolerableDelay) 。初始过期时间的范围从 DueTime 到 (DueTime + TolerableDelay) 。 TolerableDelay 值不能为负值。

TolerableDelay 成员在 1.9 版及更高版本的 KMDF 中可用。

从 Windows 8.1 开始，在至少使用 KMDF 1.13 或 UMDF 2.0 的驱动程序中，可以将此成员设置为 TolerableDelayUnlimited，以指定系统不应由于此计时器过期而唤醒。

如果 UseHighResolutionTimer 为 WdfTrue，则必须将 TolerableDelay 设置为零。否则， WdfTimerCreate 将返回失败代码。

有关此成员的详细信息，请参阅以下“备注”部分。

UseHighResolutionTimer

仅限 KMDF

此成员从 Windows 8.1 和 KMDF 版本 1.13 开始可用。

WDF_TRI_STATE类型的值。如果此值为 WdfTrue，则框架使用精度为 1 毫秒的高分辨率计时器。如果值为 WdfFalse 或 WdfDefault，则框架使用标准计时器，该计时器的准确性与系统时钟刻度间隔（默认情况下为 15.6 毫秒）相匹配。

警告如果将 UseHighResolutionTimer 设置为 WdfTrue，则必须调用 WdfTimerStart ，并将 DueTime 参数设置为负值。否则，调用会导致系统崩溃。

如果 UseHighResolutionTimer 为 WdfTrue，则必须将 TolerableDelay 设置为零。否则， WdfTimerCreate 将返回失败代码。

有关此成员的详细信息，请参阅以下“备注”部分。

注解

WDF_TIMER_CONFIG 结构用作 WdfTimerCreate 方法的输入。若要初始化 WDF_TIMER_CONFIG 结构，驱动程序必须调用 WDF_TIMER_CONFIG_INIT 或 WDF_TIMER_CONFIG_INIT_PERIODIC。

如果将父对象的同步范围设置为 WdfSynchronizationScopeNone，则将 WDF_TIMER_CONFIG 的 AutomaticSerialization 成员设置为 TRUE 不起作用。

如果父设备对象的执行级别为 WdfExecutionLevelPassive，则仅当计时器对象表示被动级别计时器时，才能将 AutomaticSerialization 成员设置为 TRUE。

如果驱动程序使用 TolerableDelay 成员，操作系统可以将接近的过期时间组合在一起，并一次性处理所有这些时间。如果操作系统可以同时处理多个计时器的过期时间，它可能会使计算机长时间处于低功耗状态，以延长电池使用时间。

如果 TolerableDelay 成员为 TolerableDelayUnlimited，则当计时器过期时，如果计时器处于低功耗 (Sx) 状态，则系统不会完全返回到其 (S0) 状态来为计时器提供服务。当计时器与非关键定期操作相关时，驱动程序可以指定 TolerableDelayUnlimited 以延长电池使用时间。

将 UseHighResolutionTimer 设置为 WdfTrue 可能会导致电池使用时间缩短。

有关 自动序列化 和同步驱动程序回调函数的详细信息，请参阅用于 Framework-Based 驱动程序的同步技术。

有关框架计时器对象的详细信息，请参阅使用计时器。