Freigeben über


CreateEventExA-Funktion (synchapi.h)

Erstellt oder öffnet ein benanntes oder unbenannte Ereignisobjekt und gibt ein Handle an das Objekt zurück.

Syntax

HANDLE CreateEventExA(
  [in, optional] LPSECURITY_ATTRIBUTES lpEventAttributes,
  [in, optional] LPCSTR                lpName,
  [in]           DWORD                 dwFlags,
  [in]           DWORD                 dwDesiredAccess
);

Parameter

[in, optional] lpEventAttributes

Ein Zeiger auf eine SECURITY_ATTRIBUTES-Struktur . Wenn lpEventAttributesNULL ist, kann das Ereignishandle nicht von untergeordneten Prozessen geerbt werden.

Das lpSecurityDescriptor-Element der -Struktur gibt einen Sicherheitsdeskriptor für das neue Ereignis an. Wenn lpEventAttributesNULL ist, erhält das Ereignis eine Standardsicherheitsbeschreibung. Die ACLs im Standardsicherheitsdeskriptor für ein Ereignis stammen aus dem primären Token oder identitätswechsel des Erstellers.

[in, optional] lpName

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

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. einem vorhandenen Semaphor, Mutex, wartebaren Timer, Auftrag oder Dateizuordnungsobjekt), schlägt die Funktion fehl, und die GetLastError-Funktion gibt ERROR_INVALID_HANDLE zurück. Dies tritt auf, weil 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 für Terminaldienste beschriebenen Richtlinien entsprechen, damit Anwendungen mehrere Benutzer unterstützen können.

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

[in] dwFlags

Dieser Parameter kann einen oder mehrere der folgenden Werte aufweisen.

Wert Bedeutung
CREATE_EVENT_INITIAL_SET
0x00000002
Der Anfangszustand des Ereignisobjekts wird signalisiert. andernfalls wird es nicht signalisiert.
CREATE_EVENT_MANUAL_RESET
0x00000001
Das Ereignis muss mithilfe der ResetEvent-Funktion manuell zurückgesetzt werden. Eine beliebige Anzahl von wartenden Threads oder Threads, die anschließend Wartevorgänge für das angegebene Ereignisobjekt beginnen, kann freigegeben werden, während der Zustand des Objekts signalisiert wird.

Wenn dieses Flag nicht angegeben wird, setzt das System das Ereignis automatisch zurück, nachdem ein einzelner wartenden Thread freigegeben wurde.

[in] dwDesiredAccess

Die Zugriffsmaske für das Ereignisobjekt. Eine Liste der Zugriffsrechte finden Sie unter Synchronisierungsobjektsicherheit und Zugriffsrechte.

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

Jeder Thread des aufrufenden Prozesses kann das Ereignis-Objekt-Handle 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 dwFlags-Parameter angegeben. Verwenden Sie die SetEvent-Funktion , um den Status eines Ereignisobjekts auf signalisiert festzulegen. Verwenden Sie die ResetEvent-Funktion , um den Zustand 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 beginnen, kann freigegeben werden, während der Zustand des Objekts signalisiert wird.

Mehrere Prozesse können über Handles desselben Ereignisobjekts verfügen, wodurch die Verwendung des Objekts für die Interprozesssynchronisierung ermöglicht wird. 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 Ereignis-Objekt-Handle 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 den Handle automatisch, wenn der Prozess beendet wird. Das Ereignisobjekt wird zerstört, wenn das letzte Handle geschlossen wurde.

Hinweis

Der header synchapi.h definiert CreateEventEx 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 nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

   
Unterstützte Mindestversion (Client) Windows Vista [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile synchapi.h (Einschließen von Windows.h unter Windows 7, Windows Server 2008 Windows Server 2008 R2)
Bibliothek Kernel32.lib
DLL Kernel32.dll

Siehe auch

CloseHandle

Ereignisobjekte

Objektnamen

Synchronisierungsfunktionen