OpenMutexW-Funktion (synchapi.h)

Artikel
03/04/2024

Öffnet ein vorhandenes benanntes mutex-Objekt.

Syntax

HANDLE OpenMutexW(
  [in] DWORD   dwDesiredAccess,
  [in] BOOL    bInheritHandle,
  [in] LPCWSTR lpName
);

Parameter

[in] dwDesiredAccess

Der Zugriff auf das Mutex-Objekt. Nur das Synchronize-Zugriffsrecht ist erforderlich, um einen Mutex zu verwenden. Um die Sicherheit des Mutex zu ändern, geben Sie MUTEX_ALL_ACCESS an. Die Funktion schlägt fehl, wenn der Sicherheitsdeskriptor des angegebenen Objekts den angeforderten Zugriff für den aufrufenden Prozess nicht zulässt. Eine Liste der Zugriffsrechte finden Sie unter Synchronisierungsobjektsicherheit und Zugriffsrechte.

[in] bInheritHandle

Wenn dieser Wert TRUE ist, erben von diesem Prozess erstellte Prozesse das Handle. Andernfalls erben die Prozesse dieses Handle nicht.

[in] lpName

Der Name des zu öffnenden Mutex. Bei Namenvergleichen wird die Groß-/Kleinschreibung beachtet.

Diese Funktion kann Objekte in einem privaten Namespace öffnen. Weitere Informationen finden Sie unter Objektnamespaces.

Terminaldienste: Der Name kann ein Präfix "Global" oder "Local" aufweisen, um ein Objekt explizit im globalen Oder Sitzungsnamespace zu öffnen. Der Rest des Namens kann ein beliebiges Zeichen mit Ausnahme des umgekehrten Schrägstrichs (\) enthalten. Weitere Informationen finden Sie unter Kernelobjektnamespaces.

Hinweis Der schnelle Benutzerwechsel wird mithilfe von Terminaldienstesitzungen implementiert. Der erste Benutzer, der sich anmeldet, verwendet Sitzung 0, der nächste Benutzer zum Anmelden verwendet Sitzung 1 usw. Kernelobjektnamen müssen den für Terminaldienste beschriebenen Richtlinien entsprechen, damit Anwendungen mehrere Benutzer unterstützen können.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle für das Mutex-Objekt.

Wenn bei der Funktion ein Fehler auftritt, ist der Rückgabewert NULL. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Wenn kein benannter Mutex vorhanden ist, schlägt die Funktion fehl, und GetLastError gibt ERROR_FILE_NOT_FOUND zurück.

Hinweise

Die OpenMutex-Funktion ermöglicht es mehreren Prozessen, Handles desselben Mutex-Objekts zu öffnen. Die Funktion ist nur erfolgreich, wenn ein Prozess den Mutex bereits mithilfe der CreateMutex-Funktion erstellt hat. Der aufrufende Prozess kann das zurückgegebene Handle in jeder Funktion verwenden, die ein Handle für ein Mutex-Objekt erfordert, z. B . die Wartefunktionen, vorbehaltlich der Einschränkungen des zugriffs, die im dwDesiredAccess-Parameter angegeben sind.

Das Handle kann mit der DuplicateHandle-Funktion dupliziert werden. Verwenden Sie die CloseHandle-Funktion , um das Handle zu schließen. Das System schließt den Handle automatisch, wenn der Prozess beendet wird. Das Mutex-Objekt wird zerstört, wenn sein letztes Handle geschlossen wurde.

Wenn Ihre Multithreadanwendung wiederholt ein benanntes Mutex-Objekt erstellen, öffnen und schließen muss, kann eine Racebedingung auftreten. In dieser Situation ist es besser, CreateMutex anstelle von OpenMutex zu verwenden, da CreateMutex einen Mutex öffnet, wenn er vorhanden ist, und erstellt es, wenn dies nicht der Fall ist.

Beispiele

Ein Beispiel, das OpenMutex verwendet, finden Sie unter Verwenden von benannten Objekten.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	synchapi.h (einschließlich Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll