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 lpEventAttributes-NULL-ist, kann das Ereignishandle 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, 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-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.
[in] dwFlags
Dieser Parameter kann einen oder mehrere der folgenden Werte sein.
| Wert | Bedeutung |
|---|---|
|
Der Anfangszustand des Ereignisobjekts wird signalisiert; andernfalls wird es nicht signaliert. |
|
Das Ereignis muss mithilfe der funktion ResetEvent manuell zurückgesetzt werden. 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 dieses Flag nicht angegeben ist, setzt das System das Ereignis automatisch zurück, nachdem ein einzelner Wartethread freigegeben wurde. |
[in] dwDesiredAccess
Das Zugriffsformat für das Ereignisobjekt. Eine Liste der Zugriffsrechte finden Sie unter Sync Object Security and Access Rights.
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
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 dwFlags Parameter 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.
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.
Anmerkung
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 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 Vista [Desktop-Apps | UWP-Apps] |
| mindestens unterstützte Server- | Windows Server 2008 [Desktop-Apps | UWP-Apps] |
| Zielplattform- | Fenster |
| Header- | synchapi.h (enthalten Windows.h unter Windows 7, Windows Server 2008 Windows Server 2008 R2) |
| Library | Kernel32.lib |
| DLL- | Kernel32.dll |