WdfTimercreate 函数 (wdftimer.h)

项目
08/08/2023

[适用于 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	Attributes 参数为 NULL，或者 Attributes 指定的 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)
Library	Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI 符合性规则	DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)