CreateMutexExA, fonction (synchapi.h)
Crée ou ouvre un objet mutex nommé ou sans nom et retourne un handle à l’objet.
Syntaxe
HANDLE CreateMutexExA(
[in, optional] LPSECURITY_ATTRIBUTES lpMutexAttributes,
[in, optional] LPCSTR lpName,
[in] DWORD dwFlags,
[in] DWORD dwDesiredAccess
);
Paramètres
[in, optional] lpMutexAttributes
Pointeur vers une structure SECURITY_ATTRIBUTES . Si ce paramètre a la valeur NULL, le handle mutex ne peut pas être hérité par les processus enfants.
Le membre lpSecurityDescriptor de la structure spécifie un descripteur de sécurité pour le nouveau mutex. Si lpMutexAttributes a la valeur NULL, le mutex obtient un descripteur de sécurité par défaut. Les listes de contrôle d’accès dans le descripteur de sécurité par défaut d’un mutex proviennent du jeton principal ou d’emprunt d’identité du créateur. Pour plus d’informations, consultez Synchronisation Des droits d’accès et de sécurité des objets.
[in, optional] lpName
Nom de l’objet mutex. Le nom est limité à MAX_PATH caractères. La comparaison de noms respecte la casse.
Si lpName a la valeur NULL, l’objet mutex est créé sans nom.
Si lpName correspond au nom d’un événement, d’un sémaphore, d’un minuteur d’attente, d’un travail ou d’un objet de mappage de fichiers existant, la fonction échoue et la fonction GetLastError retourne ERROR_INVALID_HANDLE. Cela se produit parce que ces objets partagent le même espace de noms.
Le nom peut avoir un préfixe « Global » ou « Local » pour créer explicitement l’objet dans l’espace de noms global ou de session. Le reste du nom peut contenir n’importe quel caractère à l’exception du caractère barre oblique inverse (\). Pour plus d’informations, consultez Espaces de noms d’objets de noyau. Le changement rapide d’utilisateur est implémenté à l’aide de sessions Terminal Services. Les noms d’objets de noyau doivent suivre les instructions décrites pour les services Terminal Server afin que les applications puissent prendre en charge plusieurs utilisateurs.
L’objet peut être créé dans un espace de noms privé. Pour plus d’informations, consultez Espaces de noms d’objets.
[in] dwFlags
Ce paramètre peut être 0 ou la valeur suivante.
| Valeur | Signification |
|---|---|
|
Le créateur de l’objet est le propriétaire initial du mutex. |
[in] dwDesiredAccess
Masque d’accès pour l’objet mutex. Pour obtenir la liste des droits d’accès, consultez Synchronization Object Security and Access Rights.
Valeur retournée
Si la fonction réussit, la valeur de retour est un handle pour l’objet mutex nouvellement créé.
Si la fonction échoue, la valeur de retour est NULL. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.
Si le mutex est un mutex nommé et que l’objet existait avant cet appel de fonction, la valeur de retour est un handle de l’objet existant et la fonction GetLastError retourne ERROR_ALREADY_EXISTS.
Remarques
Si vous utilisez un mutex nommé pour limiter votre application à un seul instance, un utilisateur malveillant peut créer ce mutex avant de le faire et empêcher votre application de démarrer. Pour éviter cette situation, créez un mutex nommé aléatoirement et stockez le nom afin qu’il ne puisse être obtenu que par un utilisateur autorisé. Vous pouvez également utiliser un fichier à cette fin. Pour limiter votre application à une instance par utilisateur, créez un fichier verrouillé dans le répertoire de profil de l’utilisateur.
N’importe quel thread du processus appelant peut spécifier le handle mutex-object dans un appel à l’une des fonctions d’attente. Les fonctions d’attente à objet unique retournent lorsque l’état de l’objet spécifié est signalé. Les fonctions d’attente à plusieurs objets peuvent être indiquées pour retourner l’un ou l’autre des objets spécifiés. Lorsqu’une fonction d’attente retourne, le thread d’attente est libéré pour poursuivre son exécution.
L’état d’un objet mutex est signalé lorsqu’il n’appartient à aucun thread. Le thread de création peut utiliser le paramètre dwFlags pour demander la propriété immédiate du mutex. Sinon, un thread doit utiliser l’une des fonctions d’attente pour demander la propriété. Lorsque l’état du mutex est signalé, un thread en attente obtient la propriété, l’état du mutex devient non signé et la fonction d’attente retourne. Un seul thread peut posséder un mutex à un moment donné. Le thread propriétaire utilise la fonction ReleaseMutex pour libérer sa propriété.
Le thread propriétaire d’un mutex peut spécifier le même mutex dans les appels de fonction d’attente répétés sans bloquer son exécution. En règle générale, vous n’attendez pas à plusieurs reprises le même mutex, mais ce mécanisme empêche un thread de s’interblocage tout en attendant un mutex qu’il possède déjà. Toutefois, pour libérer sa propriété, le thread doit appeler ReleaseMutex une fois pour chaque fois que le mutex a satisfait une attente.
Deux processus ou plus peuvent appeler CreateMutex pour créer le même mutex nommé. Le premier processus crée réellement le mutex, et les processus suivants avec des droits d’accès suffisants ouvrent simplement un handle au mutex existant. Cela permet à plusieurs processus d’obtenir les handles du même mutex, tout en soulageant l’utilisateur de la responsabilité de s’assurer que le processus de création est démarré en premier. Lorsque vous utilisez cette technique, vous ne devez pas utiliser l’indicateur CREATE_MUTEX_INITIAL_OWNER ; sinon, il peut être difficile de déterminer quel processus a la propriété initiale.
Plusieurs processus peuvent avoir des handles du même objet mutex, ce qui permet d’utiliser l’objet pour la synchronisation interprocess. Les mécanismes de partage d’objets suivants sont disponibles :
- Un processus enfant créé par la fonction CreateProcess peut hériter d’un handle vers un objet mutex si le paramètre lpMutexAttributes de l’héritage CreateMutex activé. Ce mécanisme fonctionne pour les mutex nommés et non nommés.
- Un processus peut spécifier le handle à un objet mutex dans un appel à la fonction DuplicateHandle pour créer un handle en double qui peut être utilisé par un autre processus. Ce mécanisme fonctionne pour les mutex nommés et non nommés.
- Un processus peut spécifier un mutex nommé dans un appel à la fonction [OpenMutex](./nf-synchapi-openmutexw.md) ou CreateMutex pour récupérer un handle à l’objet mutex.
Notes
L’en-tête synchapi.h définit CreateMutexEx comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows Vista [applications de bureau | applications UWP] |
| Serveur minimal pris en charge | Windows Server 2008 [applications de bureau | applications UWP] |
| Plateforme cible | Windows |
| En-tête | synchapi.h (inclure Windows.h sur Windows 7, Windows Server 2008 Windows Server 2008 R2) |
| Bibliothèque | Kernel32.lib |
| DLL | Kernel32.dll |