Funzione CreateMutexExA (synchapi.h)
Crea o apre un oggetto mutex denominato o senza nome e restituisce un handle all'oggetto.
Sintassi
HANDLE CreateMutexExA(
[in, optional] LPSECURITY_ATTRIBUTES lpMutexAttributes,
[in, optional] LPCSTR lpName,
[in] DWORD dwFlags,
[in] DWORD dwDesiredAccess
);
Parametri
[in, optional] lpMutexAttributes
Puntatore a una struttura SECURITY_ATTRIBUTES . Se questo parametro è NULL, l'handle mutex non può essere ereditato dai processi figlio.
Il membro lpSecurityDescriptor della struttura specifica un descrittore di sicurezza per il nuovo mutex. Se lpMutexAttributes è NULL, il mutex ottiene un descrittore di sicurezza predefinito. Gli ACL nel descrittore di sicurezza predefinito per un mutex provengono dal token primario o di rappresentazione del creatore. Per altre informazioni, vedere Sicurezza oggetti di sincronizzazione e diritti di accesso.
[in, optional] lpName
Nome dell'oggetto mutex. Il nome è limitato a MAX_PATH caratteri. Il confronto tra nomi è distinzione tra maiuscole e minuscole.
Se lpName è NULL, l'oggetto mutex viene creato senza un nome.
Se lpName corrisponde al nome di un evento esistente, semaforo, timer in attesa, processo o oggetto mapping file, la funzione non riesce e la funzione GetLastError restituisce ERROR_INVALID_HANDLE. Ciò si verifica perché questi oggetti condividono lo stesso spazio dei nomi.
Il nome può avere un prefisso "Global" o "Local" per creare in modo esplicito l'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. Il passaggio rapido degli utenti viene implementato usando le sessioni di Servizi terminal. I nomi degli oggetti kernel devono seguire le linee guida descritte per Servizi terminal in modo che le applicazioni possano supportare più utenti.
L'oggetto può essere creato in uno spazio dei nomi privato. Per altre informazioni, vedere Spazi dei nomi degli oggetti.
[in] dwFlags
Questo parametro può essere 0 o il valore seguente.
| Valore | Significato |
|---|---|
|
L'autore dell'oggetto è il proprietario iniziale del mutex. |
[in] dwDesiredAccess
Maschera di accesso per l'oggetto mutex. Per un elenco dei diritti di accesso, vedere Sicurezza oggetti di sincronizzazione e diritti di accesso.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è un handle per l'oggetto mutex appena creato.
Se la funzione ha esito negativo, il valore restituito è NULL. Per informazioni dettagliate sull'errore, chiamare GetLastError.
Se il mutex è un mutex denominato e l'oggetto esiste prima di questa chiamata di funzione, il valore restituito è un handle per l'oggetto esistente e la funzione GetLastError restituisce ERROR_ALREADY_EXISTS.
Commenti
Se si usa un mutex denominato per limitare l'applicazione a una singola istanza, un utente malintenzionato può creare questo mutex prima di eseguire e impedire l'avvio dell'applicazione. Per evitare questa situazione, creare un mutex denominato casualmente e archiviare il nome in modo che possa essere ottenuto solo da un utente autorizzato. In alternativa, è possibile usare un file per questo scopo. Per limitare l'applicazione a un'istanza per utente, creare un file bloccato nella directory del profilo dell'utente.
Qualsiasi thread del processo chiamante può specificare l'handle dell'oggetto mutex in una chiamata a una delle funzioni di attesa. Le funzioni di attesa a singolo oggetto restituiscono quando viene segnalato lo stato dell'oggetto specificato. Le funzioni di attesa a più oggetti possono essere indicate per restituire quando uno o quando vengono segnalati tutti gli oggetti specificati. Quando viene restituita una funzione di attesa, il thread in attesa viene rilasciato per continuare l'esecuzione.
Lo stato di un oggetto mutex viene segnalato quando non è di proprietà di alcun thread. Il thread di creazione può usare il parametro dwFlags per richiedere la proprietà immediata del mutex. In caso contrario, un thread deve usare una delle funzioni di attesa per richiedere la proprietà. Quando lo stato del mutex viene segnalato, viene concesso il proprietario di un thread in attesa, lo stato del mutex cambia in modo non firmato e la funzione di attesa restituisce. Un solo thread può essere proprietario di un mutex in qualsiasi momento. Il thread proprietario usa la funzione ReleaseMutex per rilasciarne la proprietà.
Il thread proprietario di un mutex può specificare lo stesso mutex nelle chiamate di funzione di attesa ripetute senza bloccare l'esecuzione. In genere, non si attende ripetutamente per lo stesso mutex, ma questo meccanismo impedisce a un thread di deadlockarsi mentre aspetta un mutex già proprietario. Tuttavia, per rilasciarne la proprietà, il thread deve chiamare ReleaseMutex una volta per ogni volta che il mutex ha soddisfatto un'attesa.
Due o più processi possono chiamare CreateMutex per creare lo stesso mutex denominato. Il primo processo crea effettivamente il mutex e i processi successivi con diritti di accesso sufficienti aprono semplicemente un handle al mutex esistente. Ciò consente a più processi di ottenere gli handle dello stesso mutex, riducendo al contempo l'utente della responsabilità di garantire che il processo di creazione venga avviato per primo. Quando si usa questa tecnica, non è consigliabile usare il flag di CREATE_MUTEX_INITIAL_OWNER ; in caso contrario, può essere difficile essere certi del processo con proprietà iniziale.
Più processi possono avere handle dello stesso oggetto mutex, consentendo l'uso dell'oggetto per la sincronizzazione tra processi. Sono disponibili i meccanismi di condivisione degli oggetti seguenti:
- Un processo figlio creato dalla funzione CreateProcess può ereditare un handle in un oggetto mutex se il parametro lpMutexAttributes dell'ereditarietà abilitata per CreateMutex . Questo meccanismo funziona sia per i mutex denominati che non denominati.
- Un processo può specificare l'handle in un oggetto mutex in una chiamata alla funzione DuplicateHandle per creare un handle duplicato che può essere usato da un altro processo. Questo meccanismo funziona sia per i mutex denominati che non denominati.
- Un processo può specificare un mutex denominato in una chiamata alla funzione [OpenMutex](./nf-synchapi-openmutexw.md) o CreateMutex per recuperare un handle all'oggetto mutex.
Nota
L'intestazione synchapi.h definisce CreateMutexEx come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows Vista [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2008 [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | synchapi.h (includere Windows.h in Windows 7, Windows Server 2008 Windows Server 2008 R2) |
| Libreria | Kernel32.lib |
| DLL | Kernel32.dll |