NdisSetCoalescableTimerObject 関数 (ndis.h)

[アーティクル]
02/07/2025

NdisSetCoalescableTimerObject 関数は、オペレーティングシステムが他のタイマーと調整するタイマーオブジェクトを設定します。通常は、タイマーの正確な有効期限がドライバー操作にとって重要でない場合に、消費電力を削減します。

構文

BOOLEAN NdisSetCoalescableTimerObject(
  [in]           NDIS_HANDLE   TimerObject,
  [in]           LARGE_INTEGER DueTime,
  [in, optional] LONG          MillisecondsPeriod,
  [in, optional] PVOID         FunctionContext,
  [in, optional] ULONG         Tolerance
);

パラメーター

[in] TimerObject

ドライバーが呼び出されたときに NDIS が提供するタイマーオブジェクトへのハンドルNdisAllocateTimerObject 関数をします。

[in] DueTime

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

[in, optional] MillisecondsPeriod

タイマーが起動してから、タイマーが取り消されない限り、NetTimerCallback 関数の次の呼び出しまでの各インスタンスの間隔 (ミリ秒単位) (省略可能)。このパラメーターの値は MAXLONG 以下である必要があります。このパラメーターを 0 に設定すると、タイマーが非定期的であることを示すことができます。

[in, optional] FunctionContext

タイマーが発生したときに、関連付けられた NetTimerCallback 関数に NDIS が渡す呼び出し元が指定したコンテキスト領域へのポインター。このパラメーターが NULL 場合、NDIS では、〟で指定された既定値が使用されます。 NDIS_TIMER_CHARACTERISTICS 構造体。

[in, optional] Tolerance

MillisecondsPeriod で指定されたタイマー期間と、DueTime で指定された初期時間間隔 ミリ秒単位の許容値。定期的なタイマーは、(DueTime - Tolerance) と (DueTime + Tolerance) の間の時間間隔で最初に期限切れになります。定期的なタイマーの後の 2 つの有効期限の間の時間間隔は、(ミリ秒/秒 - 許容) と (ミリ秒間隔 + 許容) の範囲になります。

戻り値

NdisSetCoalescableTimerObject は、タイマーオブジェクトが既にシステムタイマーキューに存在していた場合 TRUE を返します。それ以外の場合は、FALSE 返します。

備考

この関数によって設定されたタイマーオブジェクトは、NdisSetTimerObjectによって設定されたタイマーと同じように動作し、DueTime 有効期限パラメーターに追加の許容値が追加されます。オペレーティングシステムでは、この追加の許容値を使用して、他のソフトウェアタイマーの有効期限と一致するようにタイマーの有効期限を調整します。これにより、オペレーティングシステムは電力消費量を削減し、エネルギー効率を向上させることができます。

NdisSetTimerObject は、許容値 が 0 に設定されている場合に NdisSetCoalescableTimerObject と同様に動作します。

ドライバーが NdisSetCoalescableTimerObject 呼び出した後、タイマーオブジェクトは、(DueTime - 許容値) と (DueTime + Tolerance) の範囲内の間隔の有効期限が切れるまでキューに入れられます。間隔が切れると、オペレーティングシステムはタイマーオブジェクトをキューから削除し、プロセッサが使用可能になるとすぐに、呼び出し元から提供された NetTimerCallback 関数が IRQL = DISPATCH_LEVEL で 1 回実行されます。

MillisecondsPeriod パラメーターに 0 以外の値を指定した場合、タイマーオブジェクトは、(ミリ秒間隔 - 許容) と (ミリ秒間隔 + 許容) の範囲内の間隔が経過するまで、再度キューに入れられます。この間隔が経過すると、タイマーオブジェクトがキューに再送信され、呼び出し元が指定した NetTimerCallback 関数は、プロセッサが使用可能になるとすぐに IRQL = DISPATCH_LEVEL で 1 回実行されます。

タイマー合体を効果的に使用するには、呼び出し元は 32 ミリ秒以上の 許容値 値を指定する必要があります。この値は、約 2 つの既定のシステムクロック間隔 (15.6 ミリ秒) に相当します。 100 ミリ秒など、より大きな 許容値 値を使用します。

ミリ秒間隔と 許容値 50 ミリ秒の倍数に設定することをお勧めします。一般的な ミリ秒 値は、50、100、250、500、1000 ミリ秒です。一般的な 許容値 値は、50、100、150、250 ミリ秒です。

通常、MillisecondsPeriod 値が大きいタイマーでは、比例的に大きな 許容値 使用できます。たとえば、MillisecondsPeriod = 500 ミリ秒のタイマーでは、トレランス = 50 ミリ秒 使用できます。ただし、MillisecondsPeriod = 10 秒のタイマーでは、許容 = 1 秒 使用できます。

タイマー動作の詳細については、「KeSetTimerEx を参照してください。

タイマーを取り消すには、NdisCancelTimerObject 関数を呼び出します。

必要条件

要件	価値
サポートされる最小クライアント	NDIS 6.20 以降でサポートされています。
ターゲットプラットフォームの	万国
ヘッダー	ndis.h (Ndis.h を含む)
ライブラリ	Ndis.lib
IRQL	<= DISPATCH_LEVEL

次の方法で共有

NdisSetCoalescableTimerObject 関数 (ndis.h)

構文

パラメーター

戻り値

備考

必要条件

関連項目

フィードバック

その他のリソース