ZwCreateEvent-Funktion (ntifs.h)

Artikel
03/01/2024

Die ZwCreateEvent-Routine erstellt ein Ereignisobjekt, legt den Anfangszustand des Ereignisses auf den angegebenen Wert fest und öffnet ein Handle für das Objekt mit dem angegebenen gewünschten Zugriff.

Syntax

NTSYSAPI NTSTATUS ZwCreateEvent(
  [out]          PHANDLE            EventHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in]           EVENT_TYPE         EventType,
  [in]           BOOLEAN            InitialState
);

Parameter

[out] EventHandle

Ein Zeiger auf eine Variable, die das Ereignisobjekthandle empfängt. Das Handle enthält Buchhaltungsinformationen, z. B. eine Verweisanzahl 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 Zustand des Ereignisobjekts ab.
EVENT_MODIFY_STATE	Ändern Sie den Zustand des Ereignisobjekts.
EVENT_ALL_ACCESS	Alle möglichen Zugriffsrechte für das Ereignisobjekt.

[in, optional] ObjectAttributes

Ein Zeiger auf die Objektattributestruktur, die vom Aufrufer bereitgestellt wird, der für das angegebene Objekt verwendet werden soll. Zu diesen Attributen gehören beispielsweise objectName und die SECURITY_DESCRIPTOR. Dieser Parameter wird initialisiert, indem das Makro InitializeObjectAttributes aufgerufen wird.

[in] EventType

Der Typ des Ereignisses, der SynchronizationEvent oder ein NotificationEvent sein kann. Diese Werte gehören zur EVENT_TYPE-Enumeration , die in der Headerdatei ntdef.h definiert ist.

[in] InitialState

Der Anfangszustand des Ereignisobjekts. Legen Sie auf TRUE fest, um das Ereignisobjekt im Signalzustand zu initialisieren. Legen Sie auf FALSE fest, um das Ereignisobjekt in den Nicht-Signalzustand zu initialisieren.

Rückgabewert

ZwCreateEvent gibt STATUS_SUCCESS oder einen entsprechenden Fehler status zurück. Mögliche Fehler status Codes sind:

Rückgabecode	Beschreibung
STATUS_INSUFFICIENT_RESOURCES	Ressourcen, die für diese Funktion erforderlich sind, konnten nicht zugeordnet werden.
STATUS_INVALID_PARAMETER	Die angegebene ObjectAttributes-Struktur enthielt einen ungültigen Parameterwert.
STATUS_INVALID_PARAMETER_4	Der angegebene EventType-Parameter war ungültig.
STATUS_OBJECT_NAME_INVALID	Der ObjectAttributes-Parameter enthielt einen ObjectName in der OBJECT_ATTRIBUTES-Struktur , die ungültig war.
STATUS_OBJECT_PATH_SYNTAX_BAD	Der ObjectAttributes-Parameter enthielt kein RootDirectory-Element , aber das ObjectName-Element in der OBJECT_ATTRIBUTES-Struktur war eine leere Zeichenfolge oder enthielt kein OBJECT_NAME_PATH_SEPARATOR Zeichen. Dies gibt eine falsche Syntax für den Objektpfad an.
STATUS_PRIVILEGE_NOT_HELD	Der Aufrufer verfügte nicht über die erforderliche Berechtigung zum Erstellen eines Handles mit dem im DesiredAccess-Parameter angegebenen Zugriff.

Hinweise

ZwCreateEvent erstellt ein Ereignisobjekt, legt seinen Anfangszustand auf den angegebenen Wert fest und öffnet ein Handle für das Objekt mit dem angegebenen gewünschten Zugriff.

Ereignisse werden verwendet, um die Ausführung zu koordinieren. Ereignisse können von Dateisystemtreibern verwendet werden, damit ein Aufrufer auf den Abschluss des angeforderten Vorgangs warten kann, bis das angegebene Ereignis auf den Signalzustand festgelegt ist.

ZwCreateEvent kann entweder Benachrichtigungs- oder Synchronisierungsereignisse erstellen:

Benachrichtigungsereignisse können verwendet werden, um einen oder mehrere Threads über die Ausführung zu benachrichtigen, dass ein Ereignis aufgetreten ist.
Synchronisierungsereignisse können bei der Serialisierung des Hardwarezugriffs zwischen zwei ansonsten unabhängigen Treibern verwendet werden.

Ein Synchronisierungsereignis wird automatisch zurückgesetzt. Wenn ein Synchronisierungsereignis auf den Zustand Signal festgelegt ist, wird ein einzelner Ausführungsthread, der auf das Signal des Ereignisses wartete, freigegeben, und das Ereignis wird automatisch auf den Not-Signaled Zustand zurückgesetzt.

Im Gegensatz zu einem Synchronisierungsereignis wird ein Benachrichtigungsereignis nicht automatisch zurückgesetzt. Sobald sich ein Benachrichtigungsereignis im Signalzustand befindet, bleibt es in diesem Zustand, bis es explizit zurückgesetzt wird.

So synchronisieren Sie ein Benachrichtigungsereignis:

Erstellen Sie das Benachrichtigungsereignis mit ZwCreateEvent , wobei der EventType-Parameter auf NotificationEvent festgelegt ist.
Warten Sie, bis das Ereignis signalisiert wird, indem Sie ZwWaitForSingleObject mit dem von ZwCreateEvent zurückgegebenen EventHandle aufrufen. Mehrere Ausführungsthreads können warten, bis ein bestimmtes Benachrichtigungsereignis signalisiert wird. Geben Sie ein Timeout von 0 auf ZwWaitForSingleObject an, um die Abfrage statt zu stagnieren.
Schließen Sie das Handle für das Benachrichtigungsereignis mit ZwClose , wenn der Zugriff auf das Ereignis nicht mehr erforderlich ist.

Die ZwCreateEvent-Funktion wird aufgerufen, nachdem das Makro InitializeObjectAttributes verwendet wird, um Attribute in der OBJECT_ATTRIBUTES-Struktur für das -Objekt festzulegen.

Es gibt zwei alternative Möglichkeiten, den Namen des an ZwCreateEvent übergebenen Objekts anzugeben:

Als vollqualifizierter Pfadname, der im ObjectName-Member der Eingabe ObjectAttributes angegeben wird.
Als Pfadname relativ zum Verzeichnis, das durch das Handle im RootDirectory-Member der Eingabe ObjectAttributes dargestellt wird.

Zum Freigeben des Ereignisses ruft ein Treiber ZwClose mit dem Ereignishandle auf.

Weitere Informationen zu Ereignissen finden Sie unter Ereignisobjekte.

Hinweis

Wenn der Aufruf der ZwCreateEvent-Routine im Benutzermodus erfolgt, sollten Sie den Namen "NtCreateEvent" anstelle von "ZwCreateEvent" verwenden.

Bei Aufrufen von Kernelmodustreibern können sich die NtXxx - und ZwXxx-Versionen einer Windows Native System Services-Routine anders verhalten, da sie Eingabeparameter verarbeiten und interpretieren. Weitere Informationen zur Beziehung zwischen den Nt Xxx- und ZwXxx-Versionen einer Routine finden Sie unter Verwenden von Nt- und Zw-Versionen der Systemdienstroutinen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP.
Zielplattform	Universell
Header	ntifs.h (include Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)