OpenMutexW, fonction (synchapi.h)

Article
03/04/2024

Ouvre un objet mutex nommé existant.

Syntaxe

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

Paramètres

[in] dwDesiredAccess

Accès à l’objet mutex. Seul le droit d’accès SYNCHRONIZE est requis pour utiliser un mutex ; pour modifier la sécurité du mutex, spécifiez MUTEX_ALL_ACCESS. La fonction échoue si le descripteur de sécurité de l’objet spécifié n’autorise pas l’accès demandé pour le processus appelant. Pour obtenir la liste des droits d’accès, consultez Synchronization Object Security and Access Rights.

[in] bInheritHandle

Si cette valeur est TRUE, les processus créés par ce processus héritent du handle. Sinon, les processus n’héritent pas de ce handle.

[in] lpName

Nom du mutex à ouvrir. Les comparaisons de noms respectent la casse.

Cette fonction peut ouvrir des objets dans un espace de noms privé. Pour plus d’informations, consultez Espaces de noms d’objets.

Terminal Services : Le nom peut avoir un préfixe « Global » ou « Local » pour ouvrir explicitement un 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.

Note La commutation rapide des utilisateurs est implémentée à l’aide de sessions Terminal Services. Le premier utilisateur à se connecter utilise la session 0, l’utilisateur suivant pour se connecter utilise la session 1, et ainsi de suite. 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.

Valeur retournée

Si la fonction réussit, la valeur de retour est un handle pour l’objet mutex.

Si la fonction échoue, la valeur de retour est NULL. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

S’il n’existe pas de mutex nommé, la fonction échoue et GetLastError retourne ERROR_FILE_NOT_FOUND.

Remarques

La fonction OpenMutex permet à plusieurs processus d’ouvrir des handles du même objet mutex. La fonction réussit uniquement si un processus a déjà créé le mutex à l’aide de la fonction CreateMutex . Le processus appelant peut utiliser le handle retourné dans toute fonction qui nécessite un handle pour un objet mutex, comme les fonctions d’attente, sous réserve des limitations de l’accès spécifié dans le paramètre dwDesiredAccess .

Le handle peut être dupliqué à l’aide de la fonction DuplicateHandle . Utilisez la fonction CloseHandle pour fermer le handle. Le système ferme automatiquement le handle à l’arrêt du processus. L’objet mutex est détruit lorsque son dernier handle a été fermé.

Si votre application multithread doit créer, ouvrir et fermer à plusieurs reprises un objet mutex nommé, une condition de concurrence peut se produire. Dans ce cas, il est préférable d’utiliser CreateMutex au lieu d’OpenMutex, car CreateMutex ouvre un mutex s’il existe et le crée si ce n’est pas le cas.

Exemples

Pour obtenir un exemple qui utilise OpenMutex, consultez Utilisation d’objets nommés.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	synchapi.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll