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 所指定的初始時間間隔，指定容錯，以毫秒為單位。對於定期定時器，兩個連續定時器到期之間的時間間隔介於 (Period - 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，當定時器到期時，如果 S0 處於低電源 (Sx) 狀態，系統將不會完全回到其 (S0) 狀態來服務定時器。當定時器與非嚴重定期作業相關時，驅動程式可以指定 TolerableDelayUnlimited 來增加電池使用時間。

將 UseHighResolutionTimer 設定為 WdfTrue 可能會導致電池使用時間降低。

如需 自動串行化 和同步驅動程式回呼函式的詳細資訊，請參閱 Framework-Based 驅動程式的同步處理技術。

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