Функция CreateMutexExW (synchapi.h)
Создает или открывает именованный или неименованный объект мьютекса и возвращает дескриптор объекту.
Синтаксис
HANDLE CreateMutexExW(
[in, optional] LPSECURITY_ATTRIBUTES lpMutexAttributes,
[in, optional] LPCWSTR lpName,
[in] DWORD dwFlags,
[in] DWORD dwDesiredAccess
);
Параметры
[in, optional] lpMutexAttributes
Указатель на структуру SECURITY_ATTRIBUTES. Если этот параметр null, дескриптор мьютекса не может наследоваться дочерними процессами.
Элемент
[in, optional] lpName
Имя объекта мьютекса. Имя ограничено MAX_PATH символами. Сравнение имен учитывает регистр.
Если lpNameNULL, объект мьютекса создается без имени.
Если lpName соответствует имени существующего события, семафора, ожидающего таймера, задания или объекта сопоставления файлов, функция завершается ошибкой, а функция GetLastError возвращает ERROR_INVALID_HANDLE. Это происходит, так как эти объекты используют одно и то же пространство имен.
Имя может иметь префикс "Глобальный" или "Локальный", чтобы явно создать объект в глобальном или пространстве имен сеанса. Оставшаяся часть имени может содержать любой символ, кроме символа обратной косой черты (\). Дополнительные сведения см. в разделе пространства имен объектов ядра. Быстрое переключение пользователей реализуется с помощью сеансов служб терминалов. Имена объектов ядра должны соответствовать рекомендациям, описанным для служб терминалов, чтобы приложения могли поддерживать несколько пользователей.
Объект можно создать в частном пространстве имен. Дополнительные сведения см. в пространствах имен объектов.
[in] dwFlags
Этот параметр может иметь значение 0 или следующее значение.
Ценность | Значение |
---|---|
|
Создатель объекта является первоначальным владельцем мьютекса. |
[in] dwDesiredAccess
Маска доступа для объекта мьютекса. Список прав доступа см. в службы "Безопасность объектов синхронизации" и "Права доступа".
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение является дескриптором созданного объекта мьютекса.
Если функция завершается ошибкой, возвращаемое значение равно NULL. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError.
Если мьютекс является именованным мьютексом, а объект существовал до этого вызова функции, возвращаемое значение является дескриптором существующего объекта, а функция GetLastError возвращает ERROR_ALREADY_EXISTS.
Замечания
Если вы используете именованный мьютекс для ограничения приложения на один экземпляр, злоумышленник может создать этот мьютекс перед выполнением и запретить запуску приложения. Чтобы предотвратить эту ситуацию, создайте случайным образом именованный мьютекс и сохраните имя, чтобы его можно было получить только авторизованным пользователем. Кроме того, для этой цели можно использовать файл. Чтобы ограничить приложение одним экземпляром на пользователя, создайте заблокированный файл в каталоге профилей пользователя.
Любой поток вызывающего процесса может указать дескриптор мьютекс-объекта в вызове одной из функций ожидания . Функции ожидания одного объекта возвращаются при сигнале состояния указанного объекта. Функции ожидания с несколькими объектами можно указать возвращать, когда любой из них или когда сигналируют все указанные объекты. Когда функция ожидания возвращается, поток ожидания освобождается для продолжения его выполнения.
Состояние объекта мьютекса сигнализируется, когда он не принадлежит ни одному потоку. Создание потока может использовать параметр dwFlags для запроса немедленного владения мьютексом. В противном случае поток должен использовать одну из функций ожидания для запроса владения. Когда состояние мьютекса сигнализирует, один ожидающий поток получает владение, состояние мьютекса изменяется на незначаемое, а функция ожидания возвращается. Только один поток может принадлежать мьютексу в любое время. В потоке владения используется функция ReleaseMutex для освобождения его владения.
Поток, принадлежащий мьютексу, может указать один и тот же мьютекс в повторяющихся вызовах функции ожидания, не блокируя его выполнение. Как правило, вы не будете ждать несколько раз для одного мьютекса, но этот механизм предотвращает взаимоблокировку потока во время ожидания мьютекса, который он уже владеет. Тем не менее, чтобы освободить его владение, поток должен вызывать ReleaseMutex один раз за каждый раз, когда мьютекс удовлетворил ожидание.
Два или более процессов могут вызывать CreateMutex для создания того же именованного мьютекса. Первый процесс фактически создает мьютекс, а последующие процессы с достаточными правами доступа просто открывают дескриптор существующего мьютекса. Это позволяет нескольким процессам получать дескриптора одного и того же мьютекса, при этом пользователю необходимо обеспечить запуск процесса создания. При использовании этого метода не следует использовать флаг CREATE_MUTEX_INITIAL_OWNER; в противном случае может быть трудно определить, какой процесс имеет начальное владение.
Несколько процессов могут иметь дескриптор одного и того же объекта мьютекса, что позволяет использовать объект для межпроцессной синхронизации. Доступны следующие механизмы совместного использования объектов:
- Дочерний процесс, созданный функцией CreateProcess, может наследовать дескриптор объекта мьютекса, если параметр
lpMutexAttributes CreateMutex включено наследование. Этот механизм работает как для именованных, так и неименованных мьютексов. - Процесс может указать дескриптор объекта мьютекса в вызове функции DuplicateHandle, чтобы создать повторяющийся дескриптор, который можно использовать другим процессом. Этот механизм работает как для именованных, так и неименованных мьютексов.
- Процесс может указать именованный мьютекс в вызове [OpenMutex](./nf-synchapi-openmutexw.md) или функцию CreateMutex, чтобы получить дескриптор объекта мьютекса.
Заметка
Заголовок synchapi.h определяет CreateMutexEx как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.
Требования
Требование | Ценность |
---|---|
минимальные поддерживаемые клиентские | Windows Vista [классические приложения | Приложения UWP] |
минимальный поддерживаемый сервер | Windows Server 2008 [классические приложения | Приложения UWP] |
целевая платформа | Виндоус |
заголовка | synchapi.h (включая Windows.h в Windows 7, Windows Server 2008 Windows Server 2008 R2) |
библиотеки |
Kernel32.lib |
DLL | Kernel32.dll |