Функция OpenMutexW (synchapi.h)

Статья
08/26/2023

Открывает существующий именованный объект мьютекса.

Синтаксис

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

Параметры

[in] dwDesiredAccess

Доступ к объекту мьютекса. Для использования мьютекса требуется только право доступа SYNCHRONIZE ; Чтобы изменить безопасность мьютекса, укажите MUTEX_ALL_ACCESS. Функция завершается ошибкой, если дескриптор безопасности указанного объекта не разрешает запрошенный доступ для вызывающего процесса. Список прав доступа см. в разделе Synchronization Object Security and Access Rights.

[in] bInheritHandle

Если это значение равно TRUE, процессы, созданные этим процессом, наследуют дескриптор. В противном случае процессы не наследуют этот дескриптор.

[in] lpName

Имя открываемого мьютекса. При сравнении имен учитывается регистр.

Эта функция может открывать объекты в частном пространстве имен. Дополнительные сведения см. в разделе Пространства имен объектов.

Службы терминалов: Имя может иметь префикс "Global" или "Local" для явного открытия объекта в глобальном пространстве имен или пространстве имен сеанса. Оставшаяся часть имени может содержать любой символ, кроме символа обратной косой черты (\). Дополнительные сведения см. в разделе Пространства имен объектов ядра.

Примечание Быстрое переключение пользователей реализуется с помощью сеансов служб терминалов. Первый пользователь, в который выполняется вход, использует сеанс 0, следующий пользователь для входа использует сеанс 1 и т. д. Имена объектов ядра должны соответствовать рекомендациям, описанным для служб терминалов, чтобы приложения могли поддерживать нескольких пользователей.

Возвращаемое значение

Если функция выполняется успешно, возвращаемое значение является дескриптором для объекта мьютекса.

Если функция завершается сбоем, возвращается значение NULL. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Если именованный мьютекс не существует, функция завершается ошибкой и GetLastError возвращает ERROR_FILE_NOT_FOUND.

Функция OpenMutex позволяет нескольким процессам открывать дескрипторы одного объекта мьютекса. Функция выполняется успешно, только если какой-либо процесс уже создал мьютекс с помощью функции CreateMutex . Вызывающий процесс может использовать возвращенный дескриптор в любой функции, требующей дескриптора объекта мьютекса, например функций ожидания, с учетом ограничений доступа, указанных в параметре dwDesiredAccess .

Дескриптор можно дублировать с помощью функции DuplicateHandle . Используйте функцию CloseHandle , чтобы закрыть дескриптор. Система автоматически закрывает дескриптор при завершении процесса. Объект мьютекса уничтожается при закрытии последнего дескриптора.

Если многопоточное приложение должно многократно создавать, открывать и закрывать именованный объект мьютекса, может возникнуть состояние гонки. В этом случае лучше использовать CreateMutex вместо OpenMutex, так как CreateMutex открывает мьютекс, если он существует, и создает его, если это не так.

Примеры

Пример использования OpenMutex см. в разделе Использование именованных объектов.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	synchapi.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll