CreateMutexExA, fonction (synchapi.h)
Crée ou ouvre un objet mutex nommé ou non nommé 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 est NULL, le handle mutex ne peut pas être hérité par les processus enfants.
Le lpSecurityDescriptor membre de la structure spécifie un descripteur de sécurité pour le nouveau mutex. Si lpMutexAttributes est 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 est 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, 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 de barre oblique inverse (\). Pour plus d’informations, consultez espaces de noms d’objets noyau. Le basculement rapide des utilisateurs est implémenté à l’aide de sessions Terminal Services. Les noms d’objets noyau doivent suivre les instructions décrites pour les services 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 égal à 0 ou à la valeur suivante.
| Valeur | Signification |
|---|---|
|
Le créateur d’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 synchronisation des droits d’accès et sécurité des objets.
Valeur de retour
Si la fonction réussit, la valeur de retour est un handle de l’objet mutex nouvellement créé.
Si la fonction échoue, la valeur de retour est NULL . Pour obtenir des informations d’erreur étendues, 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 à une seule instance, un utilisateur malveillant peut créer ce mutex avant de commencer et empêcher votre application de démarrer. Pour éviter cette situation, créez un mutex nommé de façon aléatoire et stockez le nom afin qu’il puisse uniquement être obtenu par un utilisateur autorisé. Vous pouvez également utiliser un fichier à cet effet. Pour limiter votre application à une instance par utilisateur, créez un fichier verrouillé dans le répertoire de profil de l’utilisateur.
Tout 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 quand un ou lorsque tous les objets spécifiés sont signalés. Lorsqu’une fonction d’attente retourne, 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 d’attente retourne. Un seul thread peut posséder un mutex à tout moment. 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 se bloquer tout en attendant qu’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 satisfait d’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 des handles du même mutex, tout en réduisant 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 de CREATE_MUTEX_INITIAL_OWNER ; sinon, il peut être difficile d’être certain que le processus possède 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 entre processus. 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 del’héritage CreateMutex activé. Ce mécanisme fonctionne à la fois pour les mutex nommés et sans nom. - 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 à la fois pour les mutex nommés et sans nom.
- Un processus peut spécifier un mutex nommé dans un appel à [OpenMutex](./nf-synchapi-openmutexw.md) ou fonction CreateMutex pour récupérer un handle sur l’objet mutex.
Note
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. 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.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows Vista [applications de bureau | Applications UWP] |
| serveur minimum pris en charge | Windows Server 2008 [applications de bureau | Applications UWP] |
| plateforme cible | Windows |
| d’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 |