NdisSetCoalescableTimerObject 函式 (ndis.h)

發行項
02/26/2024

當定時器作業的確切到期時間不重要時， 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。此參數可以設定為零，表示定時器為非定期。

[in, optional] FunctionContext

當定時器引發時，NDIS 傳遞至相關聯 NetTimerCallback 函式的呼叫端提供內容區域的指標。如果此參數為 NULL，NDIS 會使用中指定的預設值 NDIS_TIMER_CHARACTERISTICS 結構。

[in, optional] Tolerance

在 MillisecondsPeriod 所指定的定時器期間與 DueTime 所指定的初始時間間隔之間，容錯以毫秒為單位。定期定時器會先在 DueTimeTolerance ( ) 和 ( DueTime + - Tolerance ) 之間的時間間隔到期。定期定時器兩個稍後到期之間的時間間隔會介於 ( 毫秒的容錯 ) 和 ( 毫秒Period + - 容錯 ) 的範圍內。

傳回值

如果定時器對象已經在系統定時器佇列中，NdisSetCoalescableTimerObject 會傳回 TRUE;否則會傳回 FALSE。

備註

此函式所設定的定時器物件的運作方式與 NdisSetTimerObject 所設定的定時器物件相同，並將額外的容錯值新增至到期參數 DueTime 。操作系統會使用此額外的容錯值來調整定時器的到期時間，以符合其他軟體定時器的到期時間。如此一來，操作系統可以降低耗電量並提升能源效率。

當 Tolerance 設定為零時，NdisSetTimerObject 的運作方式與 NdisSetCoalescableTimerObject 類似。

驅動程式呼叫 NdisSetCoalescableTimerObject 之後，定時器物件會排入佇列，直到 ( DueTimeTolerance ) 範圍內的間隔到期，並 ( DueTime + - Tolerance ) 。間隔到期之後，操作系統會從佇列中移除定時器物件，而呼叫端提供的 NetTimerCallback 函式會在 IRQL = DISPATCH_LEVEL一次執行，只要處理器可供使用。

如果在MillisecondsPeriod 參數中指定非零值，定時器物件會再次排入佇列，直到 ( 毫秒容錯 ) 範圍中的間隔，以及 ( 毫秒Period - + 容錯 ) 到期為止。此間隔到期之後，定時器物件會重新提交至佇列，而呼叫端提供的 NetTimerCallback 函式會在 IRQL = DISPATCH_LEVEL一次執行，只要處理器可供使用。

若要有效地使用定時器聯合，呼叫端應該指定至少 32 毫秒的容錯值。這個值相當於大約兩個預設系統時鐘間隔 15.6 毫秒。如果可以這麼做，請使用較大的容錯值，例如 100 毫秒。

我們建議 將毫秒Period 和 Tolerance 設定為 50 毫秒的倍數。一般 毫秒Period 值為 50、100、250、500 和 1000 毫秒。典型的容錯值為 50、100、150 和 250 毫秒。

一般而言，具有大型 MillisecondsPeriod 值的定時器可以使用比例較大的容錯值。例如， 具有MillisecondsPeriod = 500 毫秒的定時器可能會使用 Tolerance = 50 毫秒。但 具有MillisecondsPeriod = 10 秒的定時器可能會使用 Tolerance = 1 秒。

如需定時器行為的詳細資訊，請參閱 KeSetTimerEx。

若要取消定時器，請呼叫 NdisCancelTimerObject 函式。

規格需求

需求	值
最低支援的用戶端	NDIS 6.20 和更新版本支援。
目標平台	Universal
標頭	ndis.h (包括 Ndis.h)
程式庫	Ndis.lib
IRQL	<= DISPATCH_LEVEL