NdisSetCoalescableTimerObject-Funktion (ndis.h)
Die NdisSetCoalescableTimerObject--Funktion legt ein Timerobjekt fest, das das Betriebssystem mit anderen Timern koordiniert, normalerweise um den Stromverbrauch zu reduzieren, wenn der genaue Ablauf des Timers für den Treibervorgang 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 Timerobjekt, das von NDIS bereitgestellt wird, wenn ein Treiber die NdisAllocateTimerObject Funktion.
[in] DueTime
Die absolute oder relative Uhrzeit, 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 ausgedrückt (100-Nanosekunden-Intervalle). Absolute Ablaufzeiten verfolgen alle Änderungen der Systemzeit; Relative Ablaufzeiten sind von Systemzeitänderungen nicht betroffen.
[in, optional] MillisecondsPeriod
Das optionale periodische Zeitintervall in Millisekunden, das zwischen jeder Instanz verstrichen ist, wenn der Timer ausgelöst wird, und dem nächsten Aufruf der NetTimerCallback--Funktion, 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 in der NDIS_TIMER_CHARACTERISTICS Struktur.
[in, optional] Tolerance
Die Toleranz in Millisekunden zwischen dem durch MillisecondsPeriod angegebenen Zeitintervall und dem anfänglichen Zeitintervall, das durch DueTime- angegeben wird. Ein periodischer 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 - Toleranz ) und ( MillisekundenPeriod + Toleranz ).
Rückgabewert
NdisSetCoalescableTimerObject gibt TRUE zurück, wenn sich das Timerobjekt bereits in der Systemzeitgeberwarteschlange befand; andernfalls wird FALSE-zurückgegeben.
Bemerkungen
Ein von dieser Funktion festgelegtes Timerobjekt funktioniert mit einem Timer, der von NdisSetTimerObjectfestgelegt wird, mit einem zusätzlichen Toleranzwert, der dem Ablaufparameter DueTime- hinzugefügt wird. Das Betriebssystem verwendet diesen zusätzlichen Toleranzwert, um die Ablaufzeit des Timers so anzupassen, dass er mit dem Ablauf anderer Softwaretimer übereinstimmt. Dadurch kann das Betriebssystem den Stromverbrauch reduzieren und die Energieeffizienz verbessern.
NdisSetTimerObject funktioniert ähnlich wie NdisSetCoalescableTimerObject-, wenn Toleranz- auf Null festgelegt ist.
Nachdem ein Treiber NdisSetCoalescableTimerObjectaufgerufen hat, wird das Timerobjekt bis zum Ablauf eines Intervalls in die Warteschlange gestellt, das sich im Bereich von ( DueTime - Tolerance ) und ( DueTime + Tolerance ) befindet. Nach Ablauf des Intervalls entfernt das Betriebssystem das Timerobjekt aus der Warteschlange, und die vom Aufrufer bereitgestellte NetTimerCallback--Funktion wird bei IRQL = DISPATCH_LEVEL einmal ausgeführt, sobald ein Prozessor verfügbar ist.
Wenn ein Wert ungleich Null im MillisecondsPeriod Parameter angegeben wird, wird das Timerobjekt erneut in die Warteschlange gestellt, 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 bei IRQL = DISPATCH_LEVEL einmal ausgeführt, sobald ein Prozessor verfügbar ist.
Um die Zeitgeberkonszierung effektiv zu verwenden, sollte ein Aufrufer einen Toleranz- Wert von mindestens 32 Millisekunden angeben. Dieser Wert entspricht etwa zwei Standardzeitintervallen von 15,6 Millisekunden. Verwenden Sie einen größeren Toleranz- Wert, wenn Sie dies tun können, z. B. 100 Millisekunden.
Es wird empfohlen, MillisekundenPeriod- und Toleranz auf Vielfache von 50 Millisekunden festzulegen. Typische MillisekundenPeriod- Werte 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 Toleranz--Wert verwenden. Ein Timer mit MillisekundenPeriod = 500 Millisekunden kann z. B. Toleranz = 50 Millisekunden verwenden. Ein Timer mit MillisekundenPeriod = 10 Sekunden kann jedoch Toleranz = 1 Sekunde verwenden.
Weitere Informationen zum Timerverhalten finden Sie unter KeSetTimerEx.
Rufen Sie zum Abbrechen eines Timers die NdisCancelTimerObject--Funktion auf.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Unterstützt in NDIS 6.20 und höher. |
| Zielplattform- | Universal |
| Header- | ndis.h (include Ndis.h) |
| Library | Ndis.lib |
| IRQL- | <= DISPATCH_LEVEL |