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 das Mutexhandle nicht von untergeordneten Prozessen geerbt werden.
Der lpSecurityDescriptor-Member 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 Token oder dem Identitätswechseltoken des Erstellers. Weitere Informationen finden Sie unter Sicherheit und Zugriffsrechte für Synchronisierungsobjekte.
[in, optional] lpName
Der Name des Mutex-Objekts. Der Name ist auf MAX_PATH Zeichen beschränkt. Beim Namenvergleich wird die Groß-/Kleinschreibung beachtet.
Wenn lpNameNULL ist, wird das Mutex-Objekt ohne Namen erstellt.
Wenn lpName mit dem Namen eines vorhandenen Ereignisses, Semaphors, wartebaren Timers, Auftrags oder Dateizuordnungsobjekts übereinstimmt, 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.
[in] dwFlags
Dieser Parameter kann 0 oder der folgende Wert sein.
| Wert | Bedeutung |
|---|---|
|
Der Objektersteller ist der anfängliche Besitzer des Mutex. |
[in] dwDesiredAccess
Die Zugriffsmaske für das Mutex-Objekt. Eine Liste der Zugriffsrechte finden Sie unter Sicherheit und Zugriffsrechte für Synchronisierungsobjekte.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle für das neu erstellte Mutex-Objekt.
Wenn bei der Funktion ein Fehler auftritt, ist der Rückgabewert NULL. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.
Wenn der Mutex ein benannter Mutex ist und das Objekt vor diesem Funktionsaufruf vorhanden war, ist der Rückgabewert ein Handle für das vorhandene Objekt, und die GetLastError-Funktion gibt ERROR_ALREADY_EXISTS zurück.
Hinweise
Wenn Sie einen benannten Mutex verwenden, um Ihre Anwendung auf eine einzelne instance zu beschränken, kann ein böswilliger Benutzer diesen Mutex erstellen, bevor Sie dies tun, und verhindern, dass Ihre Anwendung gestartet wird. Um dies zu verhindern, erstellen Sie einen zufällig benannten Mutex, und speichern Sie den Namen, sodass er nur von einem autorisierten Benutzer abgerufen werden kann. Alternativ können Sie zu diesem Zweck eine Datei verwenden. Um Ihre Anwendung auf eine instance 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 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 Zustand eines Mutex-Objekts wird signalisiert, wenn es sich nicht im Besitz eines Threads befindet. Der erstellende Thread 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, wird einem wartenden Thread der Besitz gewährt, der Zustand des Mutex ändert sich in nicht signalisiert, und die Wartefunktion wird zurückgegeben. Nur ein Thread kann zu einem bestimmten Zeitpunkt einen Mutex besitzen. Der besitzende Thread verwendet die ReleaseMutex-Funktion , um seinen Besitz freizugeben.
Der Thread, der einen Mutex besitzt, kann den gleichen Mutex in wiederholten Wartefunktionsaufrufen angeben, ohne dessen Ausführung zu blockieren. In der Regel würden Sie nicht wiederholt auf denselben Mutex warten, aber dieser Mechanismus verhindert, dass ein Thread selbst deadlockt, während er auf einen Mutex wartet, den er bereits besitzt. Um jedoch seinen Besitz freizugeben, muss der Thread ReleaseMutex einmal für jedes Mal 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 ein Handle für den vorhandenen Mutex. Dies ermöglicht es mehreren Prozessen, Handles desselben Mutex abzurufen, während der Benutzer von der Verantwortung entkommt, sicherzustellen, dass der Erstellungsprozess zuerst gestartet wird. Wenn Sie diese Technik verwenden, sollten Sie nicht das flag CREATE_MUTEX_INITIAL_OWNER verwenden. Andernfalls kann es schwierig sein, sicher zu sein, welcher Prozess den ursprünglichen Besitz besitzt.
Mehrere Prozesse können über Handles desselben Mutex-Objekts 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 Mutex-Objekt erben, wenn der lpMutexAttributes-Parameter von CreateMutex die Vererbung aktiviert hat. Dieser Mechanismus funktioniert sowohl für benannte als auch für unbenannte Mutexe.
- Ein Prozess kann das Handle für ein Mutex-Objekt in einem Aufruf der DuplicateHandle-Funktion angeben, um ein doppeltes Handle zu erstellen, das von einem anderen Prozess verwendet werden kann. Dieser Mechanismus funktioniert sowohl für benannte als auch für unbenannte Mutexe.
- Ein Prozess kann einen benannten Mutex in einem Aufruf der Funktion [OpenMutex](./nf-synchapi-openmutexw.md) oder CreateMutex angeben , um ein Handle für das Mutex-Objekt abzurufen.
Hinweis
Der synchapi.h-Header 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 |
|---|---|
| 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 |