KeSetEvent-Funktion (wdm.h)

Artikel
02/29/2024

Die KeSetEvent-Routine legt ein Ereignisobjekt auf einen Signalzustand fest, wenn das Ereignis noch nicht signalisiert wurde, und gibt den vorherigen Zustand des Ereignisobjekts zurück.

Syntax

LONG KeSetEvent(
  [in, out] PRKEVENT  Event,
  [in]      KPRIORITY Increment,
  [in]      BOOLEAN   Wait
);

Parameter

[in, out] Event

Ein Zeiger auf ein initialisiertes Ereignisobjekt, für das der Aufrufer den Speicher bereitstellt.

[in] Increment

Gibt das Prioritätsinkrement an, das angewendet werden soll, wenn das Festlegen des Ereignisses dazu führt, dass eine Wartezeit erfüllt wird.

[in] Wait

Gibt an, ob dem Aufruf von KeSetEvent sofort ein Aufruf einer der KeWaitXxx-Routinen folgen soll. Bei TRUE muss auf den KeSetEvent-Aufruf ein Aufruf von KeWaitForMultipleObjects, KeWaitForMutexObject oder KeWaitForSingleObject folgen. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

Rückgabewert

Wenn der vorherige Zustand des Ereignisobjekts signalisiert wurde, wird ein Wert ungleich null zurückgegeben.

Hinweise

Der Aufruf von KeSetEvent bewirkt, dass das Ereignis einen Signalzustand erreicht. Wenn das Ereignis ein Benachrichtigungsereignis ist, versucht das System, so viele Wartezeiten wie möglich auf das Ereignisobjekt zu erfüllen. Das Ereignis bleibt so lange signalisiert, bis es durch einen Aufruf von KeClearEvent oder KeResetEvent gelöscht wird. Wenn das Ereignis ein Synchronisierungsereignis ist, wird eine Wartezeit erfüllt, bevor das System das Ereignis automatisch löscht.

Die KeSetEvent-Routine kann den IRQL vorübergehend auslösen. Wenn der Wait-ParameterFALSE ist, stellt die Routine, bevor sie zurückgibt, den IRQL auf den ursprünglichen Wert zurück, den sie zu Beginn des Aufrufs hatte.

Wenn Wait = TRUE, gibt die Routine zurück, ohne die IRQL zu senken. In diesem Fall muss dem KeSetEvent-Aufruf sofort ein KeWaitXxx-Aufruf folgen. Durch Festlegen von Wait = TRUE kann der Aufrufer verhindern, dass zwischen dem KeSetEvent-Aufruf und dem KeWaitXxx-Aufruf ein unnötiger Kontextwechsel stattfindet. Die KeWaitXxx-Routine stellt den IRQL am Anfang des KeSetEvent-Aufrufs wieder auf seinen ursprünglichen Wert zurück. Obwohl die IRQL Kontextwechsel zwischen den beiden Aufrufen deaktiviert, können diese Aufrufe nicht zuverlässig als Start und Ende eines atomischen Vorgangs verwendet werden. Zwischen diesen beiden Aufrufen kann z. B. ein Thread, der gleichzeitig auf einem anderen Prozessor ausgeführt wird, den Zustand des Ereignisobjekts oder des Ziels des Wartevorgangs ändern.

Ein auslagerungsfähiger Thread oder eine ausgelagerte Treiberroutine, die unter IRQL = PASSIVE_LEVEL ausgeführt wird, sollte niemals KeSetEvent aufrufen, wobei der Wait-Parameter auf TRUE festgelegt ist. Ein solcher Aufruf verursacht einen schwerwiegenden Seitenfehler, wenn der Aufrufer zwischen den Aufrufen von KeSetEvent und KeWaitXxx ausgelagert wird.

Weitere Informationen zu Ereignisobjekten finden Sie unter Ereignisobjekte.

Wenn Wait auf FALSE festgelegt ist, kann der Aufrufer unter IRQL <= DISPATCH_LEVEL ausgeführt werden. Andernfalls müssen Aufrufer von KeSetEvent unter IRQL <= APC_LEVEL und in einem nichtarbiträren Threadkontext ausgeführt werden.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar ab Windows 2000.
Zielplattform	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	Weitere Informationen finden Sie im Abschnitt mit den Hinweisen.
DDI-Complianceregeln	CompletionEventChecking(wdm), DoubleKeSetEvent(storport), HwStorPortProhibitedDIs(storport), IoAllocateIrpSignalEventInCompletion(wdm), IoBuildDeviceIoControlSetEvent(wdm), IoBuildFsdIrpSignalEventInCompletion(wdm), IrqlKeSetEvent(wdm), SignalEventInCompletion(wdm)