WdfTimerCreate 函数（wdftimer.h）

项目
02/07/2025

[适用于 KMDF 和 UMDF]

WdfTimerCreate 方法创建框架计时器对象。

语法

NTSTATUS WdfTimerCreate(
  [in]  PWDF_TIMER_CONFIG      Config,
  [in]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [out] WDFTIMER               *Timer
);

参数

[in] Config

指向 WDF_TIMER_CONFIG 结构的指针。

[in] Attributes

指向包含新计时器对象的对象属性的 WDF_OBJECT_ATTRIBUTES 结构的指针。

[out] Timer

指向接收新框架计时器对象的句柄的位置的指针。

返回值

如果作成功，则 WdfTimerCreate 返回STATUS_SUCCESS。否则，此方法可能会返回以下值之一：

返回代码	描述
STATUS_WDF_PARENT_NOT_SPECIFIED	属性参数 NULL，或者属性指定的 WDF_OBJECT_ATTRIBUTES 结构的 ParentObject 成员 NULL。
STATUS_INVALID_PARAMETER	指定了无效参数。
STATUS_INVALID_DEVICE_REQUEST	WDF_OBJECT_ATTRIBUTES 结构的 ParentObject 成员没有引用框架设备对象或父级链指向框架设备对象的对象。
STATUS_INSUFFICIENT_RESOURCES	内存不足。
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL	WDF_TIMER_CONFIG 结构的 AutomaticSerialization 成员设置为 TRUE，但父设备对象的执行级别设置为 WdfExecutionLevelPassive。

有关 WdfTimerCreate 方法可能返回的其他返回值的列表，请参阅 Framework 对象创建错误。

此方法也可能返回其他 NTSTATUS 值。

言论

当驱动程序调用 WdfTimerCreate时，它必须提供 WDF_OBJECT_ATTRIBUTES 结构，并且必须在结构的 ParentObject 成员中指定父对象。父对象可以是框架设备对象，也可以是其父级链导致框架设备对象的任何对象。框架将在删除设备对象时删除计时器对象。

创建计时器对象后，驱动程序必须调用 WdfTimerStart 来启动计时器的时钟，而不考虑计时器是否定期。

如果驱动程序为框架计时器对象提供 EvtCleanupCallback 或 EvtDestroyCallback 回调函数，请注意框架在 IRQL = PASSIVE_LEVEL 调用这些回调函数。

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

例子

下面的代码示例初始化 WDF_TIMER_CONFIG 结构和 WDF_OBJECT_ATTRIBUTES 结构，然后调用 WdfTimerCreate。

WDF_TIMER_CONFIG  timerConfig;
WDF_OBJECT_ATTRIBUTES  timerAttributes;
WDFTIMER  timerHandle;
NTSTATUS  status;

WDF_TIMER_CONFIG_INIT(
                      &timerConfig,
                      MyEvtTimerFunc
                      );

timerConfig.AutomaticSerialization = TRUE;

WDF_OBJECT_ATTRIBUTES_INIT(&timerAttributes);
timerAttributes.ParentObject = DeviceHandle;

status = WdfTimerCreate(
                        &timerConfig,
                        &timerAttributes,
                        &timerHandle
                        );

if (!NT_SUCCESS(status)) {
    return status;
}

要求

要求	价值
目标平台	普遍
最低 KMDF 版本	1.0
最低 UMDF 版本	2.0
标头	wdftimer.h （包括 Wdf.h）
库	Wdf01000.sys（KMDF）：WUDFx02000.dll （UMDF）
IRQL	<=DISPATCH_LEVEL
DDI 符合性规则	DriverCreate（kmdf），KmdfIrql（kmdf），KmdfIrql2（kmdf），KmdfIrqlExplicit（kmdf）