CreateMutexExA-Funktion (synchapi.h)
Erstellt oder öffnet ein benanntes oder unbenannte Mutex -Objekt und gibt ein Handle an das Objekt zurück.
Syntax
HANDLE CreateMutexExA(
[in, optional] LPSECURITY_ATTRIBUTES lpMutexAttributes,
[in, optional] LPCSTR lpName,
[in] DWORD dwFlags,
[in] DWORD dwDesiredAccess
);
Parameter
[in, optional] lpMutexAttributes
Ein Zeiger auf eine SECURITY_ATTRIBUTES Struktur. Wenn dieser Parameter NULL-ist, kann der Mutex-Handle nicht von untergeordneten Prozessen geerbt werden.
Der lpSecurityDescriptor Element der Struktur gibt einen Sicherheitsdeskriptor für den neuen Mutex an. Wenn lpMutexAttributesNULL-ist, erhält der Mutex einen Standardsicherheitsdeskriptor. Die ACLs im Standardsicherheitsdeskriptor für einen Mutex stammen aus dem primären oder Identitätswechseltoken des Erstellers. Weitere Informationen finden Sie unter Sync Object Security and Access Rights.
[in, optional] lpName
Der Name des Mutex-Objekts. Der Name ist auf MAX_PATH Zeichen beschränkt. Bei dem Namensvergleich wird die Groß-/Kleinschreibung beachtet.
Wenn lpName-NULL-ist, wird das Mutex-Objekt ohne Namen erstellt.
Wenn lpName- dem Namen eines vorhandenen Ereignisses, Semaphoren, Wartezeitgeber-, Auftrags- oder Dateizuordnungsobjekts entspricht, 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 0 oder der folgende Wert sein.
| Wert | Bedeutung |
|---|---|
|
Der Objektersteller ist der erste Besitzer des Mutex. |
[in] dwDesiredAccess
Die Zugriffsmaske für das Mutex-Objekt. 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 neu erstellte Mutex-Objekt.
Wenn die Funktion fehlschlägt, ist der Rückgabewert NULL-. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.
Wenn es sich bei dem Mutex um einen benannten Mutex handelt und das Objekt vor diesem Funktionsaufruf vorhanden ist, ist der Rückgabewert ein Handle für das vorhandene Objekt, und die GetLastError-Funktion gibt ERROR_ALREADY_EXISTSzurück.
Bemerkungen
Wenn Sie einen benannten Mutex verwenden, um Ihre Anwendung auf eine einzelne Instanz zu beschränken, kann ein böswilliger Benutzer diesen Mutex erstellen, bevor Sie die Anwendung starten und verhindern. Um diese Situation zu verhindern, erstellen Sie einen zufällig benannten Mutex, und speichern Sie den Namen so, dass er nur von einem autorisierten Benutzer abgerufen werden kann. Alternativ können Sie eine Datei für diesen Zweck verwenden. Um Ihre Anwendung auf eine Instanz pro Benutzer zu beschränken, erstellen Sie eine gesperrte Datei im Profilverzeichnis des Benutzers.
Jeder Thread des aufrufenden Prozesses kann das Mutex-Objekthandle 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 Status eines Mutex-Objekts wird signalisiert, wenn es keinem Thread gehört. Der Erstellungsthread kann den dwFlags Parameter verwenden, um den sofortigen Besitz des Mutex anzufordern. Andernfalls muss ein Thread eine der Wartefunktionen verwenden, um den Besitz anzufordern. Wenn der Status des Mutex signalisiert wird, erhält ein Wartethread den Besitz, der Status des Mutex ändert sich in nicht signalisiert, und die Wartefunktion wird zurückgegeben. Nur ein Thread kann jederzeit einen Mutex besitzen. Der besitzereigene Thread verwendet die ReleaseMutex--Funktion, um den Besitz freizugeben.
Der Thread, der ein Mutex besitzt, kann den gleichen Mutex in wiederholten Wartefunktionsaufrufen angeben, ohne die Ausführung zu blockieren. In der Regel würden Sie nicht wiederholt auf denselben Mutex warten, aber dieser Mechanismus verhindert, dass ein Thread sich selbst blockiert, während er auf einen Mutex wartet, den er bereits besitzt. Um den Besitz freizugeben, muss der Thread jedoch ReleaseMutex- einmal aufrufen, wenn der Mutex eine Wartezeit erfüllt hat.
Zwei oder mehr Prozesse können CreateMutex- aufrufen, um denselben benannten Mutex zu erstellen. Der erste Prozess erstellt tatsächlich den Mutex, und nachfolgende Prozesse mit ausreichenden Zugriffsrechten öffnen einfach einen Handle für den vorhandenen Mutex. Auf diese Weise können mehrere Prozesse den gleichen Mutex abrufen und gleichzeitig den Benutzer von der Verantwortung entlasten, sicherzustellen, dass der Erstellungsprozess zuerst gestartet wird. Wenn Sie diese Technik verwenden, sollten Sie das CREATE_MUTEX_INITIAL_OWNER-Kennzeichen nicht verwenden; andernfalls kann es schwierig sein, sicher zu sein, welcher Prozess über den ursprünglichen Besitz verfügt.
Mehrere Prozesse können Überhandles desselben Mutex-Objekts 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 Mutex-Objekt erben, wenn der lpMutexAttributes Parameter von CreateMutex aktivierte Vererbung. Dieser Mechanismus funktioniert sowohl für benannte als auch für unbenannte Mutexes.
- Ein Prozess kann das Handle für ein Mutex-Objekt in einem Aufruf der DuplicateHandle--Funktion angeben, um ein dupliziertes Handle zu erstellen, das von einem anderen Prozess verwendet werden kann. Dieser Mechanismus funktioniert sowohl für benannte als auch für unbenannte Mutexes.
- Ein Prozess kann einen benannten Mutex in einem Aufruf von [OpenMutex](./nf-synchapi-openmutexw.md) oder CreateMutex-Funktion angeben, um ein Handle für das Mutex-Objekt abzurufen.
Anmerkung
Der header synchapi.h definiert CreateMutexEx 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 |