ZwOpenEvent-Funktion (wdm.h)

Artikel
12/22/2024

Die ZwOpenEvent Routine öffnet ein Handle für ein vorhandenes benanntes Ereignisobjekt mit dem angegebenen gewünschten Zugriff.

Syntax

NTSYSCALLAPI NTSTATUS ZwOpenEvent(
  [out] PHANDLE            EventHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes
);

Parameter

[out] EventHandle

Ein Zeiger auf eine Variable, die das Ereignisobjekthandle empfängt. Das Handle enthält Buchführungsinformationen, z. B. eine Referenzanzahl und einen Sicherheitskontext.

[in] DesiredAccess

Der ACCESS_MASK Wert, der die gewünschten Zugriffstypen für das Ereignisobjekt darstellt. Die folgende Tabelle enthält die ereignisspezifischen ACCESS_MASK Werte.

Wert	Gewünschter Zugriff
EVENT_QUERY_STATE	Fragen Sie den Status des Ereignisobjekts ab.
EVENT_MODIFY_STATE	Ändern Sie den Status des Ereignisobjekts.
EVENT_ALL_ACCESS	Alle möglichen Zugriffsrechte für das Ereignisobjekt.

[in] ObjectAttributes

Ein Zeiger auf die Objektattributestruktur, die der aufrufer bereitgestellt hat, der für das angegebene Objekt verwendet werden soll. Zu diesen Attributen gehören beispielsweise die ObjectName- und die Handleattribute. Dieser Parameter wird durch Aufrufen des InitializeObjectAttributes Makros initialisiert.

Rückgabewert

ZwOpenEvent- gibt STATUS_SUCCESS oder einen entsprechenden Fehlerstatus zurück. Diese Routine gibt möglicherweise einen der folgenden Fehlerstatuscodes zurück:

Rückgabecode	Beschreibung
STATUS_INSUFFICIENT_RESOURCES	Ressourcen, die diese Funktion benötigt, konnten nicht zugeordnet werden.
STATUS_INVALID_PARAMETER	Die ObjectAttributes- Struktur wurde nicht angegeben oder enthielt einen ungültigen Parameterwert.
STATUS_OBJECT_NAME_INVALID	Der ObjectAttributes- Parameter enthielt eine ObjectName- in der ungültigen OBJECT_ATTRIBUTES Struktur.
STATUS_OBJECT_PATH_SYNTAX_BAD	Der Objektpfad enthielt eine falsche Syntax. Der parameter ObjectAttributes enthält z. B. kein RootDirectory-element, aber das ObjectName-Element in der OBJECT_ATTRIBUTES-Struktur ist eine leere Zeichenfolge oder beginnt nicht mit einem OBJECT_NAME_PATH_SEPARATOR Zeichen.
STATUS_OBJECT_PATH_NOT_FOUND	Der Pfad zum Objekt wurde nicht gefunden, was angibt, dass er nicht vorhanden ist.
STATUS_OBJECT_NAME_NOT_FOUND	Der Objektname wurde nicht gefunden, was angibt, dass das Objekt nicht vorhanden ist.
STATUS_PRIVILEGE_NOT_HELD	Der Aufrufer verfügte nicht über die erforderlichen Berechtigungen zum Erstellen eines Handles mit dem im parameter DesiredAccess angegebenen Zugriff.

Bemerkungen

ZwOpenEvent- öffnet ein vorhandenes benanntes Ereignisobjekt und erstellt ein Handle für das Objekt mit dem angegebenen gewünschten Zugriff.

ZwOpenEvent- können Benachrichtigungs- oder Synchronisierungsereignisse öffnen.

Ereignisse werden verwendet, um die Ausführung zu koordinieren. Dateisystemtreiber können Ereignisse verwenden, um einem Aufrufer das Warten auf den Abschluss des angeforderten Vorgangs zu ermöglichen, bis das angegebene Ereignis auf den Signalstatus festgelegt ist.

Benachrichtigungsereignisse können verwendet werden, um einen oder mehrere Threads der Ausführung zu benachrichtigen, dass ein Ereignis aufgetreten ist. Synchronisierungsereignisse können bei der Serialisierung des Zugriffs auf Hardware zwischen zwei anderen nicht verknüpften Treibern verwendet werden.

Wenn der Aufruf der ZwOpenEvent--Funktion im Benutzermodus auftritt, sollten Sie den Namen "NtOpenEvent" anstelle von "ZwOpenEvent" verwenden.

Bei Aufrufen von Kernelmodustreibern können sich die NtXxx und ZwXxx- Versionen einer Windows Native System Services-Routine anders verhalten, wie sie Eingabeparameter behandeln und interpretieren. Weitere Informationen zur Beziehung zwischen den NtXxx und ZwXxx- Versionen einer Routine finden Sie unter Using Nt and Zw Versions of the Native System Services Routines.

Anforderungen

Anforderung	Wert
Zielplattform-	Universal
Header-	wdm.h (include Wdm.h)
Library	NtosKrnl.lib
DLL-	NtosKrnl.exe
IRQL-	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)