ExSetTimer-Funktion (wdm.h)

Artikel
08/08/2023

Die ExSetTimer-Routine startet einen Timervorgang und legt fest, dass der Timer zum angegebenen Zeitpunkt abläuft.

Syntax

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

Parameter

[in] Timer

Ein Zeiger auf eine EX_TIMER-Struktur . Diese Struktur ist ein Timerobjekt, das zuvor von der ExAllocateTimer-Routine zugeordnet wurde.

[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. Eine absolute Zeit wird als die Seit Beginn des Jahres 1601 verstrichene Zeit in Systemzeiteinheiten ausgedrückt.

Der DueTime-Parameter für einen Timer mit hoher Auflösung muss eine relative Zeit (negativer Wert) oder die routinemäßigen Fehlerüberprüfungen sein.

[in] Period

Ein optionaler Zeitraum für den Timer in Systemzeiteinheiten (Intervalle von 100 Nanosekunden). Muss kleiner oder gleich MAXLONG sein. Legen Sie für einen Timer, der einen Schuss anstelle von periodisch aufweist, Den Zeitraum auf 0 (Null) fest.

[in, optional] Parameters

Ein Zeiger auf eine EXT_SET_PARAMETERS-Struktur . Der aufrufende Treiber hat zuvor die ExInitializeSetTimerParameters-Routine aufgerufen, um diese Struktur zu initialisieren.

Rückgabewert

Diese Routine gibt TRUE zurück, wenn sie einen Timer abbricht, der zum Zeitpunkt des Aufrufs der Routine ausstand. Andernfalls gibt die Routine FALSE zurück. Weitere Informationen finden Sie in den Hinweisen.

Hinweise

Ihr Treiber kann diese Routine aufrufen, um festzulegen, dass ein Timer zu einem späteren Zeitpunkt abläuft. Der Treiber kann dann warten, bis der Timer abläuft. Oder der Treiber kann eine Rückrufroutine implementieren, die aufgerufen wird, wenn der Timer abläuft.

Nachdem ein Treiber ExSetTimer aufgerufen hat, kann der Treiber eine Routine wie KeWaitForSingleObject oder KeWaitForMultipleObjects aufrufen, um auf das Ablaufen des Timers zu warten. Wenn der Timer abläuft, signalisiert das Betriebssystem das Timerobjekt.

Optional kann der Treiber eine ExTimerCallback-Rückrufroutine implementieren und einen Zeiger auf diese Routine als Eingabeparameter für die ExAllocateTimer-Routine bereitstellen. Wenn der Timer abläuft, ruft das Betriebssystem die ExTimerCallback-Routine auf .

Ein ExSetTimer-Aufruf bricht implizit alle zuvor gestarteten Set-Timer-Vorgänge für das vom Timer angegebene Timerobjekt ab. Wenn Ihr Treiber zuvor ExSetTimer aufgerufen hat, um einen Timer festzulegen, der Timer verwendet, und dieser Timer noch nicht abgelaufen ist, wenn ExSetTimer ein zweites Mal aufgerufen wird, wird der zeitgeber des ersten Aufrufs abgebrochen und dann der neue Timer gestartet. In diesem Fall gibt der zweite Aufruf TRUE zurück. Wenn der vom ersten Aufruf gestartete Timer jedoch abläuft, bevor der zweite Aufruf diesen Timer abbrechen kann, startet der zweite Aufruf den neuen Timer und gibt FALSE zurück.

Wenn der Period-Parameter ungleich null ist, ist der Timer periodisch. Für einen regelmäßigen Timer gibt der DueTime-Parameter den Zeitpunkt des anfänglichen Timersablaufs an, und Period gibt das Intervall zwischen nachfolgenden Ablaufzeiten an.

Der hardwarebasierte Timer, der für die Systemuhrsignale verwendet wird, unterbricht Anforderungen in einheitlichen Intervallen, aber die Behandlung dieser Interrupts kann durch die Interruptverarbeitung für andere Geräte verzögert werden. Daher kann bei einem periodischen Timer die Verzögerung von einer periodischen Ablaufzeit bis zu dem Zeitpunkt, zu dem das Timerobjekt signalisiert wird oder die ExTimerCallback-Routine ausgeführt wird, von einem Zeitraum zum nächsten variieren. Weitere Informationen finden Sie unter Timergenauigkeit.

Ein periodischer Timer kann nicht mehr als einmal pro Systemuhrtakt ablaufen. Wenn Sie den Zeitraum eines Timers auf einen Wert festlegen, der kleiner als das Intervall zwischen Systemuhrtakttakten ist, läuft der Timer nicht mehr als einmal pro Systemuhrtakt ab, kann jedoch dazu führen, dass die Intervalle zwischen aufeinander folgenden Ablaufzeiten variieren, wenn sich die Systemuhrrate ändert. Beispielsweise kann das Betriebssystem vorübergehend die Systemuhrrate erhöhen, um die Zeitsteuerungsanforderungen eines Timers mit hoher Auflösung zu erfüllen. Weitere Informationen finden Sie unter Timer mit hoher Auflösung.

Für einen periodischen Timer, der kein Timer mit hoher Auflösung ist, kann ein Treiber relativ einheitliche periodische Ablaufzeiten erzielen, indem er Period auf ein ganzzahliges Vielfaches des Standardintervalls zwischen Systemuhrtakten festlegt.

Um übermäßigen Stromverbrauch zu vermeiden, sollte ein Treiber den Zeitraum eines zeitintensiven Timers mit hoher Auflösung nicht auf einen Wert festlegen, der kleiner als das Standardintervall zwischen Systemuhrtakten ist. Andernfalls generiert der Systemuhrtimer kontinuierlich Unterbrechungen mit der maximal zulässigen Systemuhrrate.

Weitere Informationen finden Sie unter ExXxxTimer-Routinen und EX_TIMER-Objekte.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar ab Windows 8.1.
Zielplattform	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	Ntoskrnl.lib
IRQL	<= DISPATCH_LEVEL