CreateEventA-Funktion (synchapi.h)

Artikel
03/02/2024

Erstellt oder öffnet ein benanntes oder unbenannte Ereignisobjekt.

Verwenden Sie die CreateEventEx-Funktion , um eine Zugriffsmaske für das Objekt anzugeben.

Syntax

HANDLE CreateEventA(
  [in, optional] LPSECURITY_ATTRIBUTES lpEventAttributes,
  [in]           BOOL                  bManualReset,
  [in]           BOOL                  bInitialState,
  [in, optional] LPCSTR                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-Member der -Struktur gibt einen Sicherheitsdeskriptor für das neue Ereignis an. Wenn lpEventAttributesNULL ist, ruft das Ereignis einen Standardsicherheitsdeskriptor ab. Die ACLs im Standardsicherheitsdeskriptor für ein Ereignis stammen aus dem primären Token oder dem Identitätswechseltoken des Erstellers.

[in] bManualReset

Wenn dieser Parameter TRUE ist, erstellt die Funktion ein Ereignisobjekt mit manueller Zurücksetzung, das die Verwendung der ResetEvent-Funktion erfordert, um den Ereigniszustand auf nicht signalisiert festzulegen. Wenn dieser Parameter FALSE ist, erstellt die Funktion ein Ereignisobjekt für das automatische Zurücksetzen, und das System setzt den Ereigniszustand automatisch auf nicht signalisiert zurück, nachdem ein einzelner wartenden Thread freigegeben wurde.

[in] bInitialState

Wenn dieser Parameter TRUE ist, wird der Anfangszustand des Ereignisobjekts signalisiert. Andernfalls wird es nicht signalisiert.

[in, optional] lpName

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

Wenn lpName mit dem Namen eines vorhandenen benannten Ereignisobjekts übereinstimmt, fordert diese Funktion das zugriffsrecht EVENT_ALL_ACCESS an. In diesem Fall werden die Parameter bManualReset und bInitialState ignoriert, da sie bereits vom Erstellungsprozess festgelegt wurden. Wenn der lpEventAttributes-Parameter nicht NULL ist, bestimmt er, ob das Handle geerbt werden kann, sein Sicherheitsdeskriptor-Member wird jedoch ignoriert.

Wenn lpNameNULL ist, wird das Ereignisobjekt ohne Namen erstellt.

Wenn lpName mit dem Namen einer anderen Art von Objekt im selben Namespace übereinstimmt (z. B. ein vorhandenes Semaphor-, Mutex-, wartebares Timer-, Auftrags- oder Dateizuordnungsobjekt), schlägt die Funktion fehl, und die GetLastError-Funktion gibt ERROR_INVALID_HANDLE zurück. Dies liegt daran, dass diese Objekte denselben Namespace verwenden.

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 Kernelobjektnamespaces. Der schnelle Benutzerwechsel 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 Objektnamespaces.

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 war, gibt die Funktion ein Handle an das vorhandene Objekt zurück, und GetLastError gibt ERROR_ALREADY_EXISTS zurück.

Wenn bei der Funktion ein Fehler auftritt, ist der Rückgabewert NULL. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Das von CreateEvent zurückgegebene Handle verfügt über das zugriffsrecht EVENT_ALL_ACCESS ; Sie kann in jeder Funktion verwendet werden, die ein Handle für ein Ereignisobjekt erfordert, sofern dem Aufrufer Zugriff gewährt wurde. Wenn ein Ereignis aus einem Dienst oder einem Thread erstellt wird, der die Identität eines anderen Benutzers angibt, können Sie entweder beim Erstellen einen Sicherheitsdeskriptor auf das Ereignis anwenden oder den Standardsicherheitsdeskriptor für den Erstellungsprozess ändern, indem Sie die Standard-DACL ändern. Weitere Informationen finden Sie unter Sicherheit und Zugriffsrechte für Synchronisierungsobjekte.

Jeder Thread des aufrufenden Prozesses kann das Ereignisobjekthandle in einem Aufruf einer der Wartefunktionen angeben. Die Wartefunktionen für einzelne Objekte geben zurück, wenn der Zustand des angegebenen Objekts signalisiert wird. Die Wartefunktionen für mehrere Objekte können angewiesen werden, entweder zurückzugeben, wenn eine oder alle angegebenen Objekte signalisiert werden. Wenn eine Wartefunktion zurückgegeben wird, wird der wartende Thread freigegeben, um seine Ausführung fortzusetzen.

Der Anfangszustand des Ereignisobjekts wird durch den bInitialState-Parameter angegeben. Verwenden Sie die SetEvent-Funktion , um den Status eines Ereignisobjekts auf signalisiert festzulegen. Verwenden Sie die ResetEvent-Funktion , um den Status eines Ereignisobjekts auf nicht signalisiert zurückzusetzen.

Wenn der Zustand eines Ereignisobjekts mit manueller Zurücksetzung signalisiert wird, bleibt es so lange signalisiert, bis es von der ResetEvent-Funktion explizit auf nicht signalisiert zurückgesetzt wird. Eine beliebige Anzahl von wartenden Threads oder Threads, die anschließend Wartevorgänge für das angegebene Ereignisobjekt starten, kann freigegeben werden, während der Zustand des Objekts signalisiert wird.

Wenn der Zustand eines Ereignisobjekts für das automatische Zurücksetzen signalisiert wird, bleibt es signalisiert, bis ein einzelner wartenden Thread losgelassen wird. das System setzt den Zustand dann automatisch auf nicht signalisiert zurück. Wenn sich keine Threads in Warteposition befinden, verbleibt das Ereignisobjekt im signalisierten Zustand.

Mehrere Prozesse können über Handles desselben Ereignisobjekts verfügen, sodass das -Objekt für die Prozessübergreifende Synchronisierung verwendet werden kann. Die folgenden Mechanismen für die Objektfreigabe sind verfügbar:

Ein von der CreateProcess-Funktion erstellter untergeordneter Prozess kann ein Handle an ein Ereignisobjekt erben, wenn der lpEventAttributes-Parameter von CreateEvent die Vererbung aktiviert hat.
Ein Prozess kann das Ereignisobjekthandle in einem Aufruf der DuplicateHandle-Funktion angeben, um ein doppeltes 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 das Handle zu schließen. Das System schließt das Handle automatisch, wenn der Prozess beendet wird. Das Ereignisobjekt wird zerstört, wenn sein letztes Handle geschlossen wurde.

Beispiele

Ein Beispiel für die Verwendung von CreateEvent finden Sie unter Verwenden von Ereignisobjekten.

Hinweis

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
Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	synchapi.h (enthalten Windows.h unter Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll