ZwCreateEvent-Funktion (ntifs.h)

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 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 Abfragen des Status des Ereignisobjekts.
EVENT_MODIFY_STATE Ändern sie den Status des Ereignisobjekts.
EVENT_ALL_ACCESS Alle möglichen Zugriffsberechtigungen 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. Diese Attribute enthalten z. B. den ObjectName und die SECURITY_DESCRIPTOR. Dieser Parameter wird durch Aufrufen des InitializeObjectAttributes-Makros initialisiert .

[in] EventType

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

[in] InitialState

Der Anfangszustand des Ereignisobjekts. Legen Sie auf TRUE fest, um das Ereignisobjekt auf den Signalstatus zu initialisieren. Legen Sie auf FALSE fest, um das Ereignisobjekt auf den nicht signalierten Zustand zu initialisieren.

Rückgabewert

ZwCreateEvent gibt STATUS_SUCCESS oder einen entsprechenden Fehlerstatus zurück. Mögliche Fehlerstatuscodes umfassen Folgendes:

Rückgabecode Beschreibung
STATUS_INSUFFICIENT_RESOURCES Ressourcen, die von dieser Funktion benötigt werden, konnten nicht zugewiesen 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 Parameter ObjectAttributes enthielt einen ObjectName in der OBJECT_ATTRIBUTES Struktur, die ungültig war.
STATUS_OBJECT_PATH_SYNTAX_BAD Der Parameter ObjectAttributes 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 hat nicht über die erforderlichen Berechtigungen zum Erstellen eines Handles mit dem im Parameter DesiredAccess angegebenen Zugriff verfügt.

Bemerkungen

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 signalierten Zustand festgelegt ist.

ZwCreateEvent kann Benachrichtigungs- oder Synchronisierungsereignisse erstellen:

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

Ein Synchronisierungsereignis wird automatisch zurückgesetzt. Wenn ein Synchronisierungsereignis auf den Signalstatus festgelegt ist, wird ein einzelner Ausführungsthread ausgeführt, der darauf wartet, dass das Ereignis freigegeben wird, 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 Zustand "Signaled" befindet, verbleibt es in diesem Zustand, bis es explizit zurückgesetzt wird.

So synchronisieren Sie ein Benachrichtigungsereignis:

  1. Erstellen Sie das Benachrichtigungsereignis mit ZwCreateEvent mit dem EventType-Parameter , der auf NotificationEvent festgelegt ist.

  2. Warten Sie, bis das Ereignis signalisiert wird, indem Sie ZwWaitForSingleObject mit dem von ZwCreateEvent zurückgegebenen EventHandle aufrufen. Mehrere Thread der Ausführung können warten, bis ein bestimmtes Benachrichtigungsereignis signalisiert wird. Geben Sie zum Abfragen anstelle eines Stalls ein Timeout von null auf ZwWaitForSingleObject an.

  3. Schließen Sie das Handle zum Benachrichtigungsereignis mit ZwClose , wenn der Zugriff auf das Ereignis nicht mehr benötigt wird.

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

Es gibt zwei alternative Methoden zum Angeben des Namens des objekts, das an ZwCreateEvent übergeben wird:

  • Als vollqualifizierter Pfadname wird im ObjectName-Element der Eingabe ObjectAttributes angegeben.

  • Als Pfadname relativ zum Verzeichnis, das durch das Handle im RootDirectory-Element der Eingabe ObjectAttributes dargestellt wird.

Um das Ereignis freizugeben, 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 auftritt, sollten Sie den Namen "NtCreateEvent" anstelle von "ZwCreateEvent" verwenden.

Für Aufrufe 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- undZwXxx-Versionen einer Routine finden Sie unter Using Nt and Zw Versions of the Native System Services Routines.

Requirements (Anforderungen)

   
Unterstützte Mindestversion (Client) Ab Windows XP verfügbar.
Zielplattform Universell
Header ntifs.h (einschließlich Ntifs.h)
Bibliothek NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI-Complianceregeln HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)

Weitere Informationen

ACCESS_MASK

InitializeObjectAttributes

IoCreateNotificationEvent

IoCreateSynchronizationEvent

KeClearEvent

KeResetEvent

KeSetEvent

KeWaitForSingleObject

Verwenden von Nt- und Zw-Versionen der systemeigenen Systemdienste-Routinen

ZwClose

ZwSetEvent

ZwWaitForSingleObject