Funzione OpenMutexW (synchapi.h)

Articolo
08/26/2023

Apre un oggetto mutex denominato esistente.

Sintassi

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

Parametri

[in] dwDesiredAccess

Accesso all'oggetto mutex. Solo il diritto di accesso SYNCHRONIZE è necessario per usare un mutex; per modificare la sicurezza del mutex, specificare MUTEX_ALL_ACCESS. La funzione ha esito negativo se il descrittore di sicurezza dell'oggetto specificato non consente l'accesso richiesto per il processo chiamante. Per un elenco dei diritti di accesso, vedere Synchronization Object Security and Access Rights.For a list of access rights, see Synchronization Object Security and Access Rights.

[in] bInheritHandle

Se questo valore è TRUE, i processi creati da questo processo erediteranno l'handle. In caso contrario, i processi non ereditano questo handle.

[in] lpName

Nome del mutex da aprire. I confronti dei nomi fanno distinzione tra maiuscole e minuscole.

Questa funzione può aprire oggetti in uno spazio dei nomi privato. Per altre informazioni, vedere Spazi dei nomi degli oggetti.

Servizi terminal: Il nome può avere un prefisso "Global" o "Local" per aprire in modo esplicito un oggetto nello spazio dei nomi globale o sessione. Il resto del nome può contenere qualsiasi carattere ad eccezione del carattere barra rovesciata (\). Per altre informazioni, vedere Spazi dei nomi degli oggetti kernel.

Nota Il passaggio rapido degli utenti viene implementato usando le sessioni di Servizi terminal. Il primo utente a eseguire l'accesso usa la sessione 0, l'utente successivo per accedere usa la sessione 1 e così via. I nomi degli oggetti kernel devono seguire le linee guida descritte per Servizi terminal in modo che le applicazioni possano supportare più utenti.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è un handle per l'oggetto mutex.

Se la funzione ha esito negativo, il valore restituito è NULL. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Se non esiste un mutex denominato, la funzione ha esito negativo e GetLastError restituisce ERROR_FILE_NOT_FOUND.

Commenti

La funzione OpenMutex consente a più processi di aprire handle dello stesso oggetto mutex. La funzione ha esito positivo solo se alcuni processi hanno già creato il mutex usando la funzione CreateMutex . Il processo chiamante può usare l'handle restituito in qualsiasi funzione che richiede un handle per un oggetto mutex, ad esempio le funzioni di attesa, soggetto alle limitazioni dell'accesso specificato nel parametro dwDesiredAccess .

L'handle può essere duplicato usando la funzione DuplicateHandle . Usare la funzione CloseHandle per chiudere l'handle. Il sistema chiude automaticamente l'handle al termine del processo. L'oggetto mutex viene eliminato definitivamente quando l'ultimo handle è stato chiuso.

Se l'applicazione multithreading deve creare, aprire e chiudere ripetutamente un oggetto mutex denominato, può verificarsi una race condition. In questo caso, è preferibile usare CreateMutex invece di OpenMutex, perché CreateMutex apre un mutex se esiste e lo crea in caso contrario.

Esempio

Per un esempio che usa OpenMutex, vedere Uso di oggetti denominati.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	synchapi.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll