IoCreateNotificationEvent-Funktion (wdm.h)

Artikel
02/07/2025

Die IoCreateNotificationEvent Routine erstellt oder öffnet ein benanntes Benachrichtigungsereignis, das verwendet wird, um einen oder mehrere Threads der Ausführung zu benachrichtigen, dass ein Ereignis aufgetreten ist.

Syntax

PKEVENT IoCreateNotificationEvent(
  [in]  PUNICODE_STRING EventName,
  [out] PHANDLE         EventHandle
);

Parameter

[in] EventName

Zeigen Sie auf einen Puffer, der eine mit Null beendete Unicode-Zeichenfolge enthält, die das Ereignis benennt.

[out] EventHandle

Zeigen Sie auf eine Position, an der ein Kernelhandle für das Ereignisobjekt zurückgegeben werden soll.

Rückgabewert

IoCreateNotificationEvent gibt einen Zeiger auf das erstellte oder geöffnete Ereignisobjekt zurück oder NULL-, wenn das Ereignisobjekt nicht erstellt oder geöffnet werden konnte.

Bemerkungen

Wenn das Ereignisobjekt noch nicht vorhanden ist, erstellt IoCreateNotificationEvent erstellt und öffnet es und legt den Zustand auf "Signaled" fest.

Wenn das Ereignisobjekt bereits vorhanden ist, öffnet IoCreateNotificationEvent einfach das Ereignisobjekt.

Sowohl Benachrichtigungsereignisse als auch Synchronisierungsereignisse werden verwendet, um die Ausführung zu koordinieren. Während jedoch ein Synchronisierungsereignis sich selbst zurücksetzt, verbleibt ein Benachrichtigungsereignis im Signalzustand, bis der Treiber KeClearEvent oder KeResetEvent-aufruft.

So synchronisieren Sie ein Benachrichtigungsereignis:

Öffnen Sie das Benachrichtigungsereignis mit IoCreateNotificationEvent. Identifizieren Sie das Ereignis mit der EventName- Zeichenfolge.
Warten Sie, bis das Ereignis signalisiert wird, indem Sie KeWaitForSingleObject- aufrufen, wobei das PKEVENT von IoCreateNotificationEventzurückgegeben wird. Mehrere Thread der Ausführung können auf ein bestimmtes Benachrichtigungsereignis warten. Geben Sie einen Timeout- null KeWaitForSingleObject-an, um die Abfrage zu beenden.
Schließen Sie das Handle mit ZwClose-, wenn der Zugriff auf das Ereignis nicht mehr erforderlich ist.

Es gibt zwei Hauptmethoden für das Freigeben von Ereignisobjekten:

Die Benutzermodusanwendung erstellt das Ereignisobjekt und übergibt ein Handle an den Treiber, indem ein IOCTL an den Treiber gesendet wird. Der Treiber muss die IOCTL im Kontext des Prozesses behandeln, der das Ereignisobjekt erstellt hat, und muss das Handle überprüfen, indem ObReferenceObjectByHandleaufgerufen wird. Diese Methode ist die empfohlene Methode zum Freigeben von Ereignisobjekten zwischen Benutzer- und Kernelmodi.
Der Treiber erstellt ein benanntes Ereignisobjekt im globalen \BaseNamedObjects-Objektverzeichnis. Verwenden Sie den Namen Global\\Xxx, um über den Benutzermodus auf ein Kernelmodusereignis zuzugreifen. Beachten Sie, dass Sicherheitseinstellungen verhindern können, dass eine Anwendung das Ereignis öffnet. Das \\BaseNamedObjects-Objektverzeichnis wird erst erstellt, wenn das Microsoft Win32-Subsystem initialisiert wird, sodass Treiber, die zur Startzeit geladen werden, keine Ereignisobjekte im \\BaseNamedObjects Verzeichnis in ihren DriverEntry- Routinen erstellen können.

Weitere Informationen zu Ereignissen finden Sie unter Event Objects.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Ab Windows 2000 verfügbar.
Zielplattform-	Universal
Header-	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL-	NtosKrnl.exe
IRQL-	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDIs(storport), IrqlIoPassive4(wdm)