WdfTimerStart 函式 (wdftimer.h)

發行項
02/29/2024

[適用於 KMDF 和 UMDF]

WdfTimerStart 方法會啟動定時器的時鐘。

語法

BOOLEAN WdfTimerStart(
  [in] WDFTIMER Timer,
  [in] LONGLONG DueTime
);

參數

[in] Timer

呼叫 WdfTimerCreate 取得之架構定時器物件的句柄。

[in] DueTime

時間週期，以系統時間單位為單位， (100 奈秒間隔) 。架構會在指定的時段經過時呼叫驅動程式的 EvtTimerFunc 回呼函式。時間週期值可以是負數或正值，如下所示：

如果值為負數，則時間週期會相對於目前的系統時間。
如果值為正數，則時間週期會指定絕對時間 (，這實際上相對於 1601 年 1 月 1 日) 。

警告

如果您將 WDF_TIMER_CONFIG的UseHighResolutionTimer成員設定為WdfTrue，則必須呼叫WdfTimerStart，並將 DueTime 參數設定為負值。否則，呼叫會導致系統當機。

相對時間不會受到在指定時段內可能發生之系統時間的任何變更所影響。絕對時間確實會反映系統時間變更。

架構提供時間轉換函式，可將時間值轉換成系統時間單位。

傳回值

如果定時器對象位於系統的定時器佇列中，WdfTimerStart 會傳回 TRUE。否則，這個方法會傳回 FALSE。如需詳細資訊，請參閱接下來的＜備註＞一節。

如果驅動程式提供無效的物件句柄，就會發生錯誤檢查。

備註

驅動程式必須一律呼叫 WdfTimerStart ，在建立定時器之後啟動定時器，不論定時器是否為定期定時器。

在驅動程式呼叫 WdfTimerStart 之後，當為 DueTime 參數指定的時間經過時，架構會呼叫驅動程式的 EvtTimerFunc 回呼函式。在第一次呼叫之後，架構會在每次驅動程式WDF_TIMER_CONFIG結構的 Period 成員所指定的時間週期時呼叫回呼函式。

定時器到期最終取決於系統時鐘的數據粒度。為 DueTime 指定的值保證架構會在指定的 DueTime 上或之後呼叫驅動程式的 EvtTimerFunc 回呼函式。不過，無論為 DueTime 指定的值為何，WdfTimerStart 都無法覆寫系統時鐘的數據粒度。

當驅動程式呼叫 WdfTimerStart 時，其定時器物件會新增至系統的定時器物件佇列。如果定時器不是定期定時器，系統會在定時器的「到期時間」經過之後，從佇列中移除定時器物件。如果定時器是定期定時器，定時器物件會保留在佇列中，直到驅動程式呼叫 WdfTimerStop 為止。

驅動程式可能會從其 EvtTimerFunc 回呼函式呼叫 WdfTimerStart，以便在到期後重新啟動非定期定時器。

如果驅動程式先前已呼叫 WdfTimerStart，而且定時器物件仍在系統的佇列中，WdfTimerStart 會傳回 TRUE，因為時間週期尚未經過 (或因為它是定期定時器) 。 在 WdfTimerStart 傳回 TRUE 之前，操作系統會將時間週期重設為新呼叫 WdfTimerStart 中指定的驅動程式值。架構只會在經過新的時間周期之後呼叫 EvtTimerFunc 回呼函式。

若要停止定時器的時鐘，驅動程式可以呼叫 WdfTimerStop。

如需架構定時器對象的詳細資訊，請參閱使用定時器。

範例

下列程式代碼範例會啟動定時器。架構會在 10 毫秒後呼叫定時器的 EvtTimerFunc 回呼函式。

BOOLEAN inTimerQueue;

inTimerQueue = WdfTimerStart(
                             timerHandle,
                             WDF_REL_TIMEOUT_IN_MS(10)
                             );

規格需求

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