WDF_TIMER_CONFIG 構造体 (wdftimer.h)

[アーティクル]
08/08/2023

[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 コールバック関数を繰り返し呼び出します。この値が 0 の場合、フレームワークはドライバーの EvtTimerFunc コールバック関数を繰り返し呼び出しません。代わりに、 WdfTimerStart メソッドの DueTime が経過した後、コールバック関数を 1 回呼び出します。 ( WdfTimerCreate が実行レベルを WdfExecutionLevelPassive に設定する場合、期間は 0 にする必要があります)。期間を負の値にすることはできません。

AutomaticSerialization

TRUE の場合、フレームワークがタイマーオブジェクトの EvtTimerFunc コールバック関数の実行を、タイマーの親デバイスオブジェクトの下にある他のオブジェクトからのコールバック関数と同期することを示すブール値。詳細については、「解説」を参照してください。 FALSE の場合、フレームワークは EvtTimerFunc コールバック関数の実行を同期しません。

TolerableDelay

Period が指定するタイマー期間と、WdfTimerStart メソッドの DueTime で指定される初期時間間隔の許容範囲をミリ秒単位で指定します。定期的なタイマーの場合、2 つの連続するタイマーの有効期限の時間間隔は、(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 を 0 に設定する必要があります。それ以外の場合、 WdfTimerCreate はエラーコードを返します。

このメンバーの詳細については、次の「解説」セクションを参照してください。

UseHighResolutionTimer

KMDF のみ

このメンバーは、Windows 8.1 および KMDF バージョン 1.13 以降で使用できます。

WDF_TRI_STATE型指定された値。この値が WdfTrue の場合、フレームワークでは、精度が 1 ミリ秒の高解像度タイマーが使用されます。値が WdfFalse または WdfDefault の場合、フレームワークでは、システムクロックティック間隔 (既定では 15.6 ミリ秒) に一致する精度を持つ標準タイマーが使用されます。

警告UseHighResolutionTimer を WdfTrue に設定した場合は、DueTime パラメーターを負の値に設定して WdfTimerStart を呼び出す必要があります。それ以外の場合、呼び出しによってシステムがクラッシュします。

このメンバーの詳細については、次の「解説」セクションを参照してください。

注釈

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 の場合、タイマーの有効期限が切れたときに低電力 (Sx) 状態の場合、システムはタイマーを完全にオン (S0) 状態に戻してサービスを提供しません。ドライバーは、タイマーが重要でない定期的な操作に関連している場合にバッテリの寿命を長くするために 、TolerableDelayUnlimited を指定できます。

UseHighResolutionTimer を WdfTrue に設定すると、バッテリ寿命が低下する可能性があります。

ドライバーコールバック関数 の AutomaticSerialization と同期の詳細については、「 Framework-Based ドライバーの同期手法」を参照してください。

フレームワークタイマーオブジェクトの詳細については、「タイマーの使用」を参照してください。