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 |
|---|---|
|
Der Anfangszustand des Ereignisobjekts wird signalisiert. andernfalls wird es nicht signalisiert. |
|
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.
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 |