ExSetTimer 関数 (wdm.h)

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

ExSetTimer ルーチンは、タイマー操作を開始し、指定された期限時にタイマーの有効期限を設定します。

構文

BOOLEAN ExSetTimer(
  [in]           PEX_TIMER           Timer,
  [in]           LONGLONG            DueTime,
  [in]           LONGLONG            Period,
  [in, optional] PEXT_SET_PARAMETERS Parameters
);

パラメーター

[in] Timer

EX_TIMER構造体へのポインター。この構造体は、 ExAllocateTimer ルーチンによって以前に割り当てられたタイマーオブジェクトです。

[in] DueTime

タイマーの有効期限が切れる絶対時間または相対時間。 DueTime パラメーターの値が負の場合、有効期限は現在のシステム時刻を基準とします。それ以外の場合、有効期限は絶対です。有効期限は、システム時間単位 (100 ナノ秒間隔) で表されます。絶対有効期限は、システム時刻の変更を追跡します。相対有効期限は、システム時間の変更の影響を受けません。絶対時間は、1601 年の開始以降にシステム時間単位で渡された時間の量として表されます。

高解像度タイマーの DueTime パラメーターは、相対時間 (負の値)、または定期的なバグチェックである必要があります。

[in] Period

システム時間単位でのタイマーの省略可能な期間 (100 ナノ秒間隔)。 MAXLONG 以下である必要があります。定期的ではなく 1 ショットのタイマーの場合は、[ 期間] を 0 に設定します。

[in, optional] Parameters

EXT_SET_PARAMETERS構造体へのポインター。呼び出し元のドライバーは、この構造体を初期化するために ExInitializeSetTimerParameters ルーチンを以前に呼び出しました。

戻り値

このルーチンは、ルーチンが呼び出された時点で保留中のタイマーを取り消した場合に TRUE を 返します。それ以外の場合、ルーチンは FALSE を返します。詳細については、「解説」を参照してください。

注釈

ドライバーは、このルーチンを呼び出して、将来期限切れになるタイマーを設定できます。その後、ドライバーはタイマーの有効期限が切れるのを待つことができます。または、ドライバーは、タイマーの有効期限が切れたときに呼び出されるコールバックルーチンを実装できます。

ドライバーが ExSetTimer を呼び出した後、ドライバーは、タイマーの有効期限が切れるのを待つ KeWaitForSingleObject や KeWaitForMultipleObjects などのルーチンを呼び出すことができます。タイマーの有効期限が切れると、オペレーティングシステムはタイマーオブジェクトに通知します。

オプションとして、ドライバーは ExTimerCallback コールバックルーチンを実装し、 ExAllocateTimer ルーチンへの入力パラメーターとしてこのルーチンへのポインターを指定できます。タイマーの有効期限が切れると、オペレーティングシステムは ExTimerCallback ルーチンを呼び出します。

ExSetTimer 呼び出しは、Timer で指定されたタイマーオブジェクトに対して以前に開始された set-timer 操作を暗黙的に取り消します。ドライバーが以前に ExSetTimer を呼び出して Timer を使用するタイマーを設定していて、 ExSetTimer が 2 回目と呼ばれるときにこのタイマーがまだ期限切れになっていない場合、2 回目の呼び出しでは最初の呼び出しからタイマーが取り消され、新しいタイマーが開始されます。この場合、2 番目の呼び出しは TRUE を返します。ただし、2 番目の呼び出しでこのタイマーを取り消す前に、最初の呼び出しによって開始されたタイマーの有効期限が切れた場合、2 番目の呼び出しは新しいタイマーを開始し 、FALSE を返します。

Period パラメーターが 0 以外の場合、タイマーは定期的です。定期的なタイマーの場合、 DueTime パラメーターは初期タイマーの有効期限の時刻を指定し、 Period は後続の有効期限の間隔を指定します。

システムクロックに使用されるハードウェアタイマーは、一定の間隔で割り込み要求を通知しますが、これらの割り込みの処理は、他のデバイスの割り込み処理によって遅延する可能性があります。したがって、定期的なタイマーの場合、定期的な有効期限からタイマーオブジェクトが通知される時刻、または ExTimerCallback ルーチンの実行までの遅延は、ある期間から次の期間に変わる場合があります。詳細については、「タイマーの精度」を参照してください。

定期的なタイマーの有効期限は、システムクロックティックごとに 1 回までです。タイマーの期間をシステムクロックティック間の間隔よりも小さい値に設定しても、システムクロックティックごとにタイマーの有効期限が複数回切れることはありませんが、システムクロックレートが変化すると、連続する有効期限の間隔が変わる可能性があります。たとえば、オペレーティングシステムは、高解像度タイマーのタイミング要件を満たすためにシステムクロックレートを一時的に増やします。詳細については、「高解像度タイマー」を参照してください。

高解像度タイマーではない定期的なタイマーの場合、ドライバーは、システムクロックティック間の既定の間隔の整数倍数に Period を設定することで、比較的均一な定期的な有効期限を実現できます。

過剰な電力消費を回避するために、ドライバーは、長時間実行される高解像度タイマーの期間を、システムクロックティック間の既定の間隔より小さい値に設定しないでください。それ以外の場合、システムクロックタイマーは、許容される最大システムクロックレートで継続的に割り込みを生成します。

詳細については、「 ExXxxTimer ルーチン」および「EX_TIMER オブジェクト」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows 8.1 以降で使用できます。
対象プラットフォーム	ユニバーサル
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library	Ntoskrnl.lib
IRQL	<= DISPATCH_LEVEL