CreateEventW-Funktion (synchapi.h)

Artikel
11/20/2024

Erstellt oder öffnet ein benanntes oder unbenannte Ereignisobjekt.

Um ein Zugriffsformat für das Objekt anzugeben, verwenden Sie die CreateEventEx--Funktion.

Syntax

HANDLE CreateEventW(
  [in, optional] LPSECURITY_ATTRIBUTES lpEventAttributes,
  [in]           BOOL                  bManualReset,
  [in]           BOOL                  bInitialState,
  [in, optional] LPCWSTR               lpName
);

Parameter

[in, optional] lpEventAttributes

Ein Zeiger auf eine SECURITY_ATTRIBUTES Struktur. Wenn dieser Parameter NULL-ist, kann das Handle nicht von untergeordneten Prozessen geerbt werden.

Der lpSecurityDescriptor Mitglied der Struktur gibt einen Sicherheitsdeskriptor für das neue Ereignis an. Wenn lpEventAttributes-NULL-ist, ruft das Ereignis einen Standardsicherheitsdeskriptor ab. Die ACLs im Standardsicherheitsdeskriptor für ein Ereignis stammen aus dem primären Oder Identitätswechseltoken des Erstellers.

[in] bManualReset

Wenn dieser Parameter TRUEist, erstellt die Funktion ein manuell zurückgesetztes Ereignisobjekt, das die Verwendung der ResetEvent--Funktion erfordert, um den Ereigniszustand auf nichtsignaliert festzulegen. Wenn dieser Parameter FALSE-ist, erstellt die Funktion ein Ereignisobjekt für die automatische Zurücksetzung, und das System setzt den Ereigniszustand automatisch auf "Nichtsignal" zurück, nachdem ein einzelner Wartethread freigegeben wurde.

[in] bInitialState

Wenn dieser Parameter TRUEist, wird der Anfangszustand des Ereignisobjekts signalisiert; andernfalls wird es nicht signaliert.

[in, optional] lpName

Der Name des Ereignisobjekts. Der Name ist auf MAX_PATH Zeichen beschränkt. Bei dem Namensvergleich wird die Groß-/Kleinschreibung beachtet.

Wenn lpName- dem Namen eines vorhandenen benannten Ereignisobjekts entspricht, fordert diese Funktion das EVENT_ALL_ACCESS Zugriffsrecht an. In diesem Fall werden die parameter bManualReset und bInitialState ignoriert, da sie bereits durch den Erstellungsprozess festgelegt wurden. Wenn der parameter lpEventAttributes nicht NULL-ist, bestimmt er, ob das Handle geerbt werden kann, aber sein Sicherheitsdeskriptorelement wird ignoriert.

Wenn lpName-NULL-ist, wird das Ereignisobjekt ohne Namen erstellt.

Wenn lpName- mit dem Namen eines anderen Objekts im selben Namespace übereinstimmt (z. B. ein vorhandenes Semaphor, mutex, wartebarer Timer, Auftrag oder Dateizuordnungsobjekt), schlägt die Funktion fehl, und die GetLastError Funktion gibt ERROR_INVALID_HANDLEzurück. Dies geschieht, da diese Objekte denselben Namespace gemeinsam nutzen.

Der Name kann ein Präfix "Global" oder "Local" aufweisen, um das Objekt explizit im globalen oder Sitzungsnamespace zu erstellen. Der Rest des Namens kann ein beliebiges Zeichen mit Ausnahme des umgekehrten Schrägstrichs (\) enthalten. Weitere Informationen finden Sie unter Kernel Object Namespaces. Schnelle Benutzerumschaltung wird mithilfe von Terminaldienstesitzungen implementiert. Kernelobjektnamen müssen den Richtlinien für Terminaldienste entsprechen, damit Anwendungen mehrere Benutzer unterstützen können.

Das Objekt kann in einem privaten Namespace erstellt werden. Weitere Informationen finden Sie unter Object Namespaces.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle für das Ereignisobjekt. Wenn das benannte Ereignisobjekt vor dem Funktionsaufruf vorhanden ist, gibt die Funktion ein Handle an das vorhandene Objekt zurück und GetLastError gibt ERROR_ALREADY_EXISTSzurück.

Wenn die Funktion fehlschlägt, ist der Rückgabewert NULL-. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

Das von CreateEvent zurückgegebene Handle verfügt über das EVENT_ALL_ACCESS Zugriffsrecht; sie kann in jeder Funktion verwendet werden, für die ein Handle für ein Ereignisobjekt erforderlich ist, vorausgesetzt, der Aufrufer wurde Zugriff gewährt. Wenn ein Ereignis aus einem Dienst oder einem Thread erstellt wird, der die Identität eines anderen Benutzers angibt, können Sie entweder einen Sicherheitsdeskriptor auf das Ereignis anwenden, wenn Sie es erstellen, oder den Standardsicherheitsdeskriptor für den Erstellungsprozess ändern, indem Sie die standardmäßige DACL ändern. Weitere Informationen finden Sie unter Sync Object Security and Access Rights.

Jeder Thread des aufrufenden Prozesses kann das Ereignisobjekthandle in einem Aufruf einer der Wait-Funktionenangeben. Die Einzelobjekt-Wait-Funktionen werden zurückgegeben, wenn der Status des angegebenen Objekts signalisiert wird. Die Wait-Funktionen mit mehreren Objekten können angewiesen werden, entweder zurückzugeben, wenn eines oder alle angegebenen Objekte signalisiert werden. Wenn eine Wartefunktion zurückgegeben wird, wird der Wartethread losgelassen, um die Ausführung fortzusetzen.

Der Anfangszustand des Ereignisobjekts wird durch den parameter bInitialState angegeben. Verwenden Sie die SetEvent--Funktion, um den Status eines Ereignisobjekts festzulegen, das signalisiert wird. Verwenden Sie die ResetEvent--Funktion, um den Status eines Ereignisobjekts auf nichtsignalierte Zurückzusetzen.

Wenn der Zustand eines manuell zurückgesetzten Ereignisobjekts signalisiert wird, bleibt es signalisiert, bis es explizit auf nicht signalisiert von der funktion ResetEvent zurückgesetzt wird. Eine beliebige Anzahl von Wartethreads oder Threads, die anschließend Mit Wartevorgängen für das angegebene Ereignisobjekt beginnen, können freigegeben werden, während der Status des Objekts signalisiert wird.

Wenn der Zustand eines Ereignisobjekts für das automatische Zurücksetzen signalisiert wird, bleibt es signalisiert, bis ein einzelner Wartethread losgelassen wird. das System setzt den Zustand dann automatisch auf nicht signaliert zurück. Wenn keine Threads warten, bleibt der Status des Ereignisobjekts signalisiert.

Mehrere Prozesse können Überhandles desselben Ereignisobjekts verfügen, wodurch die Verwendung des Objekts für die Interprocess-Synchronisierung ermöglicht wird. Die folgenden Objektfreigabemechanismen sind verfügbar:

Ein untergeordneter Prozess, der von der CreateProcess--Funktion erstellt wird, kann ein Handle an ein Ereignisobjekt erben, wenn der parameter lpEventAttributes parameter von CreateEvent aktivierte Vererbung erbt.
Ein Prozess kann das Ereignisobjekthandle in einem Aufruf der DuplicateHandle--Funktion angeben, um ein dupliziertes Handle zu erstellen, das von einem anderen Prozess verwendet werden kann.
Ein Prozess kann den Namen eines Ereignisobjekts in einem Aufruf der OpenEvent- oder CreateEvent--Funktion angeben.

Verwenden Sie die CloseHandle--Funktion, um den Handle zu schließen. Das System schließt das Handle automatisch, wenn der Prozess beendet wird. Das Ereignisobjekt wird zerstört, wenn das letzte Handle geschlossen wurde.

Beispiele

Ein Beispiel, das CreateEvent-verwendet, finden Sie unter Verwenden von Ereignisobjekten.

Anmerkung

Der Header synchapi.h definiert CreateEvent als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows XP [Desktop-Apps \| UWP-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform-	Fenster
Header-	synchapi.h (enthalten Windows.h unter Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Library	Kernel32.lib
DLL-	Kernel32.dll