CreateMutexExW, fonction (synchapi.h)
Crée ou ouvre un objet mutex nommé ou sans nom et retourne un handle à l’objet .
Syntaxe
HANDLE CreateMutexExW(
[in, optional] LPSECURITY_ATTRIBUTES lpMutexAttributes,
[in, optional] LPCWSTR 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 pour 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 de la barre oblique inverse (\). Pour plus d’informations, consultez Espaces de noms d’objets du noyau. La commutation rapide des utilisateurs est implémentée à l’aide de sessions Terminal Services. Les noms d’objets de noyau doivent suivre les instructions décrites pour Terminal Services 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 pour 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 le démarrage de votre application. Pour éviter cette situation, créez un mutex nommé de façon aléatoire 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 à un 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 d’objet mutex 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 lorsque tous les objets spécifiés sont signalés. Lorsqu’une fonction d’attente est retournée, le thread en 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 reçoit la propriété, l’état du mutex passe à non signé et la fonction wait 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 qui possède 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 se bloquer 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.
Au moins deux processus peuvent appeler CreateMutex pour créer le même mutex nommé. Le premier processus crée en fait 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 des 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 ; dans le cas contraire, il peut être difficile d’être certain que le 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 interprocessus. Les mécanismes de partage d’objets suivants sont disponibles :
- Un processus enfant créé par la fonction CreateProcess peut hériter d’un handle à 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 d’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 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. La combinaison 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 |
Voir aussi
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour