IoCreateNotificationEvent-Funktion (wdm.h)

Artikel
02/27/2024

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

Syntax

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

Parameter

[in] EventName

Zeiger auf einen Puffer, der eine unicode-Zeichenfolge mit NULL-Beendigung enthält, die das Ereignis benennt.

[out] EventHandle

Zeiger auf einen Speicherort, an dem ein Kernelhandle für das Ereignisobjekt zurückgegeben werden soll.

Rückgabewert

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

Hinweise

Wenn das Ereignisobjekt noch nicht vorhanden ist, erstellt und öffnet IoCreateNotificationEvent es und legt seinen 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 ein Synchronisierungsereignis jedoch selbst zurückgesetzt wird, 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 mit dem von IoCreateNotificationEvent zurückgegebenen PKEVENT aufrufen. Mehrere Ausführungsthreads können auf ein bestimmtes Benachrichtigungsereignis warten. Geben Sie ein Timeout von 0 (null) für KeWaitForSingleObject an, um die Abfrage anstelle von "angehalten" an.
Schließen Sie das Handle für das Benachrichtigungsereignis mit ZwClose , wenn der Zugriff auf das Ereignis nicht mehr benötigt wird.

Es gibt zwei Standard Methoden zum Freigeben von Ereignisobjekten:

Die Benutzermodusanwendung erstellt das Ereignisobjekt und übergibt ein Handle an das -Objekt an den Treiber, indem sie eine IOCTL an den Treiber sendet. Der Treiber muss die IOCTL im Kontext des Prozesses behandeln, der das Ereignisobjekt erstellt hat, und das Handle durch Aufrufen von ObReferenceObjectByHandle überprüfen. 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 zum Startzeitpunkt geladen werden, keine Ereignisobjekte im Verzeichnis in \\BaseNamedObjects ihren DriverEntry-Routinen erstellen können.

Weitere Informationen zu Ereignissen finden Sie unter Ereignisobjekte.

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	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDIs(storport), IrqlIoPassive4(wdm)