NdisSetCoalescableTimerObject-Funktion (ndis.h)

Artikel
08/07/2023

Die NdisSetCoalescableTimerObject-Funktion legt ein Timerobjekt fest, das das Betriebssystem mit anderen Timern koordiniert, in der Regel, um den Stromverbrauch zu reduzieren, wenn der genaue Ablauf des Timers für den Treiberbetrieb nicht wichtig ist.

Syntax

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

Parameter

[in] TimerObject

Ein Handle für ein Zeitgeberobjekt, das NDIS bereitstellt, wenn ein Treiber die NdisAllocateTimerObject-Funktion .

[in] DueTime

Die absolute oder relative Zeit, zu der der Timer abläuft. Wenn der Wert des DueTime-Parameters negativ ist, ist die Ablaufzeit relativ zur aktuellen Systemzeit. Andernfalls ist die Ablaufzeit absolut. Die Ablaufzeit wird in Systemzeiteinheiten (100-Nanosekunden-Intervalle) ausgedrückt. Absolute Ablaufzeiten verfolgen alle Änderungen in der Systemzeit; relative Ablaufzeiten werden von Systemzeitänderungen nicht beeinflusst.

[in, optional] MillisecondsPeriod

Das optionale periodische Zeitintervall in Millisekunden, das zwischen jedem instance, wenn der Timer ausgelöst wird, und dem nächsten Aufruf der NetTimerCallback-Funktion verstreicht, es sei denn, der Timer wird abgebrochen. Der Wert dieses Parameters muss kleiner oder gleich MAXLONG sein. Dieser Parameter kann auf null festgelegt werden, um anzugeben, dass der Timer nicht periodisch ist.

[in, optional] FunctionContext

Ein Zeiger auf einen vom Aufrufer bereitgestellten Kontextbereich, den NDIS an die zugeordnete NetTimerCallback-Funktion übergibt, wenn ein Timer ausgelöst wird. Wenn dieser Parameter NULL ist, verwendet NDIS den Standardwert, der im NDIS_TIMER_CHARACTERISTICS Struktur.

[in, optional] Tolerance

Die Toleranz in Millisekunden zwischen dem durch MillisecondsPeriod angegebenen Timerzeitraum und dem anfänglichen Zeitintervall, das von DueTime angegeben wird. Ein regelmäßiger Timer läuft zuerst im Zeitintervall zwischen ( DueTime-Toleranz - ) und ( DueTime-Toleranz + ) ab. Das Zeitintervall zwischen zwei späteren Ablaufzeiten eines periodischen Timers liegt im Bereich von ( MillisekundenPeriod - Tolerance ) und ( MillisekundenPeriod + Tolerance ).

Rückgabewert

NdisSetCoalescableTimerObject gibt TRUE zurück, wenn sich das Timerobjekt bereits in der Systemzeitgeberwarteschlange befand. Andernfalls wird FALSE zurückgegeben.

Hinweise

Ein von dieser Funktion festgelegtes Timerobjekt funktioniert genauso wie ein von NdisSetTimerObject festgelegter Timer, wobei dem Ablaufparameter DueTime ein zusätzlicher Toleranzwert hinzugefügt wird. Das Betriebssystem verwendet diesen zusätzlichen Toleranzwert, um die Ablaufzeit des Timers entsprechend dem Ablauf anderer Softwaretimer anzupassen. Auf diese Weise kann das Betriebssystem den Stromverbrauch senken und die Energieeffizienz verbessern.

NdisSetTimerObject funktioniert ähnlich wie NdisSetCoalescableTimerObject , wenn Toleranz auf 0 festgelegt ist.

Nachdem ein Treiber NdisSetCoalescableTimerObject aufgerufen hat, wird das Timerobjekt bis zum Ablauf eines Intervalls in die Warteschlange eingereiht, das sich im Bereich von ( DueTime-Toleranz - ) und ( DueTime-Toleranz + ) befindet. Nach Ablauf des Intervalls entfernt das Betriebssystem das Timerobjekt aus der Warteschlange, und die vom Aufrufer bereitgestellte NetTimerCallback-Funktion wird einmal um IRQL = DISPATCH_LEVEL ausgeführt, sobald ein Prozessor verfügbar ist.

Wenn im MillisecondsPeriod-Parameter ein Wert ungleich null angegeben wird, wird das Timerobjekt erneut in die Warteschlange eingereiht, bis ein Intervall im Bereich von ( MillisecondsPeriod - Tolerance ) und ( MillisecondsPeriod + Tolerance ) abläuft. Nach Ablauf dieses Intervalls wird das Timerobjekt erneut an die Warteschlange übermittelt, und die vom Aufrufer bereitgestellte NetTimerCallback-Funktion wird einmal um IRQL = DISPATCH_LEVEL ausgeführt, sobald ein Prozessor verfügbar ist.

Um die Timer-Zusammenführung effektiv zu verwenden, sollte ein Aufrufer einen Toleranzwert von mindestens 32 Millisekunden angeben. Dieser Wert entspricht ungefähr zwei Standardmäßigen Systemuhrintervallen von 15,6 Millisekunden. Verwenden Sie einen größeren Toleranzwert , wenn Sie dies tun können, z. B. 100 Millisekunden.

Es wird empfohlen, millisecondsPeriod und Tolerance auf Vielfache von 50 Millisekunden festzulegen. Typische MillisekundenZeitwerte sind 50, 100, 250, 500 und 1000 Millisekunden. Typische Toleranzwerte sind 50, 100, 150 und 250 Millisekunden.

In der Regel kann ein Timer mit einem großen MillisekundenPeriod-Wert einen proportional großen Toleranzwert verwenden. Beispielsweise kann ein Timer mit MillisecondsPeriod = 500 Millisekunden Toleranz = 50 Millisekunden verwenden. Ein Timer mit MillisecondsPeriod = 10 Sekunden kann jedoch Toleranz = 1 Sekunde verwenden.

Weitere Informationen zum Timerverhalten finden Sie unter KeSetTimerEx.

Um einen Timer abzubrechen, rufen Sie die Funktion NdisCancelTimerObject auf .

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Unterstützt in NDIS 6.20 und höher.
Zielplattform	Universell
Header	ndis.h (include Ndis.h)
Bibliothek	Ndis.lib
IRQL	<= DISPATCH_LEVEL