ExAllocateTimer-Funktion (wdm.h)

Artikel
02/27/2024

Die ExAllocateTimer-Routine weist ein Timerobjekt zu und initialisiert es.

Syntax

PEX_TIMER ExAllocateTimer(
  [in, optional] PEXT_CALLBACK Callback,
  [in, optional] PVOID         CallbackContext,
  [in]           ULONG         Attributes
);

Parameter

[in, optional] Callback

Ein Zeiger auf eine vom Treiber implementierte ExTimerCallback-Rückrufroutine . Das Betriebssystem ruft diese Routine auf, wenn der Timer abläuft. Dieser Parameter ist optional und kann NULL sein, wenn keine Rückrufroutine erforderlich ist.

[in, optional] CallbackContext

Ein Kontextwert für die Rückrufroutine, auf die der Rückrufparameter verweist. Wenn angegeben, übergibt das Betriebssystem diesen Wert als Parameter an die ExTimerCallback-Rückrufroutine . Dieser Parameter ist in der Regel ein Zeiger auf eine vom Aufrufer definierte Struktur, die Kontextinformationen enthält, die von der Rückrufroutine verwendet werden. Dieser Parameter ist optional und kann auf NULL festgelegt werden, wenn keine Kontextinformationen erforderlich sind.

[in] Attributes

Die Timerattribute. Legen Sie diesen Parameter auf Null oder auf den bitweisen OR eines oder mehrerer der folgenden Timerflaggbits fest.

Timer-Flagbit	BESCHREIBUNG
EX_TIMER_HIGH_RESOLUTION	Hochauflösender Timer. Machen Sie den Timer präziser, indem Sie eine Uhr mit höherer Auflösung verwenden, um den Timer zu steuern.
EX_TIMER_NO_WAKE	Timer ohne Aktivierung. Stellen Sie fest, dass die Zeitgeberverzögerung des Prozessors abläuft, bis die Ablaufzeit des Timers und die Verzögerungstoleranz überschritten werden.
EX_TIMER_NOTIFICATION	Benachrichtigungszeitgeber. Stellen Sie den Timer als Benachrichtigungszeitgeber anstelle eines Synchronisierungszeitgebers fest. Wenn dieses Flag nicht festgelegt ist, ist der Timer ein Synchronisierungszeitgeber.

Das EX_TIMER_NOTIFICATION Flagbits kann unabhängig davon festgelegt werden, welche anderen Flagbits festgelegt sind.

Die EX_TIMER_HIGH_RESOLUTION- und EX_TIMER_NO_WAKE-Flagbits schließen sich gegenseitig aus. Wenn der Aufrufer beide Flagbits festlegt, wird der routinemäßige Fehler überprüft.

Weitere Informationen zu Timerattributen finden Sie unter Hinweise.

Rückgabewert

Diese Routine gibt einen Zeiger auf eine EX_TIMER-Struktur zurück, wenn der Aufruf erfolgreich ist. Diese Struktur ist das Timerobjekt, das die Routine zugeordnet und initialisiert hat. Wenn der Aufruf fehlschlägt, gibt die Routine NULL zurück.

Hinweise

Diese Routine gibt einen Zeiger auf das neue Timerobjekt zurück. Um den Timer zu verwenden, stellt der aufrufende Treiber diesen Zeiger in nachfolgenden Aufrufen der Routinen ExSetTimer, ExCancelTimer und ExDeleteTimer bereit. Wenn der Treiber einen Zeiger auf eine ExTimerCallback-Rückrufroutine als Eingabeparameter für die ExAllocateTimer-Routine bereitstellt, übergibt das Betriebssystem dieses Timerobjekt als Eingabeparameter an die ExTimerCallback-Routine .

Ein Timer kann ein Benachrichtigungstimer oder ein Synchronisierungszeitgeber sein. Wenn ein Benachrichtigungszeitgeber signalisiert wird, wird für alle wartenden Threads die Wartezeit erfüllt. Der Zustand dieses Timers bleibt so lange signalisiert, bis er explizit zurückgesetzt wird. Wenn ein Synchronisierungszeitgeber abläuft, wird sein Status auf signalisiert festgelegt, bis ein einzelner wartenden Thread freigegeben wird. Anschließend wird der Timer auf den nicht signalierten Zustand zurückgesetzt.

Wenn das EX_TIMER_HIGH_RESOLUTION Flagbits in Attributen festgelegt ist, erhöht das Betriebssystem die Auflösung der Systemuhr nach Bedarf, sodass die Zeiten, zu denen der Timer abläuft, genauer den nominalen Ablaufzeiten entsprechen, die in den Parametern DueTime und Period für die ExSetTimer-Routine angegeben sind. Weitere Informationen finden Sie unter Hochauflösende Timer.

Wenn das EX_TIMER_NO_WAKE-Flagbits in Attribute festgelegt ist, vermeidet der Timer, dass der Prozessor unnötig aus einem Zustand mit geringer Leistung versetzt wird. Weitere Informationen finden Sie unter No-Wake-Timer.

ExAllocateTimer weist den Speicher für das Timerobjekt zu. Wenn dieses Objekt nicht mehr benötigt wird, ist der Aufrufer dafür verantwortlich, dieses Objekt durch Aufrufen der ExDeleteTimer-Routine frei zu geben.

Der Rückrufparameter ist optional. Ein Treiber, der keine ExTimerCallback-Routine bereitstellt, kann stattdessen einen Wartevorgang für das Timerobjekt initiieren. Ein Treiberthread kann eine Routine wie KeWaitForSingleObject oder KeWaitForMultipleObjects aufrufen, um auf das Ablaufen des Timers zu warten. Wenn der Timer abläuft, wird das Timerobjekt signalisiert.

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

Weitere Informationen