WdfTimerCreate 函式 (wdftimer.h)

發行項
02/27/2024

[適用於 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。否則，這個方法可能會傳回下列其中一個值：

傳回碼	Description
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;
}

規格需求

需求	值
目標平台	Universal
最低 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)