Функция CreateEventExW (synchapi.h)
Создает или открывает именованный или неименованный объект события и возвращает дескриптор объекту.
Синтаксис
HANDLE CreateEventExW(
[in, optional] LPSECURITY_ATTRIBUTES lpEventAttributes,
[in, optional] LPCWSTR lpName,
[in] DWORD dwFlags,
[in] DWORD dwDesiredAccess
);
Параметры
[in, optional] lpEventAttributes
Указатель на структуру SECURITY_ATTRIBUTES. Если lpEventAttributesNULL, то дескриптор событий не может наследоваться дочерними процессами.
Элемент lpSecurityDescriptor
[in, optional] lpName
Имя объекта события. Имя ограничено MAX_PATH символами. Сравнение имен учитывает регистр.
Если lpNameNULL, объект события создается без имени.
Если lpName совпадает с именем другого типа объекта в том же пространстве имен (например, существующего семафора, мьютекса, таймера ожидания, задания или объекта сопоставления файлов), функция завершается ошибкой, а функция GetLastError возвращает ERROR_INVALID_HANDLE. Это происходит, так как эти объекты используют одно и то же пространство имен.
Имя может иметь префикс "Глобальный" или "Локальный", чтобы явно создать объект в глобальном или пространстве имен сеанса. Оставшаяся часть имени может содержать любой символ, кроме символа обратной косой черты (\). Дополнительные сведения см. в разделе пространства имен объектов ядра. Быстрое переключение пользователей реализуется с помощью сеансов служб терминалов. Имена объектов ядра должны соответствовать рекомендациям, описанным для служб терминалов, чтобы приложения могли поддерживать несколько пользователей.
Объект можно создать в частном пространстве имен. Дополнительные сведения см. в пространствах имен объектов.
[in] dwFlags
Этот параметр может быть одним или несколькими из следующих значений.
| Ценность | Значение |
|---|---|
|
Начальное состояние объекта события сигнализируется; в противном случае оно не назначено. |
|
Событие необходимо сбросить вручную с помощью функции сброса ResetEvent. Любое количество ожидающих потоков или потоков, которые впоследствии начинают операции ожидания для указанного объекта события, можно освободить, пока состояние объекта сигнализирует.
Если этот флаг не указан, система автоматически сбрасывает событие после выпуска одного потока ожидания. |
[in] dwDesiredAccess
Маска доступа для объекта события. Список прав доступа см. в службы "Безопасность объектов синхронизации" и "Права доступа".
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение является дескриптором объекта события. Если именованный объект события существовал перед вызовом функции, функция возвращает дескриптор существующему объекту и GetLastError возвращает ERROR_ALREADY_EXISTS.
Если функция завершается ошибкой, возвращаемое значение равно NULL. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError.
Замечания
Любой поток вызывающего процесса может указать дескриптор объекта события в вызове одной из функций ожидания ожидания. Функции ожидания одного объекта возвращаются при сигнале состояния указанного объекта. Функции ожидания с несколькими объектами можно указать возвращать, когда любой из них или когда сигналируют все указанные объекты. Когда функция ожидания возвращается, поток ожидания освобождается для продолжения его выполнения.
Начальное состояние объекта события определяется параметром dwFlags. Используйте функцию SetEvent, чтобы задать состояние объекта события для сигнала. Используйте функцию ResetEvent, чтобы сбросить состояние объекта события на незначаемый.
Когда состояние объекта события сброса вручную сигнализируется, он остается сигналом, пока он не будет явно сбрасываться на незначаемый функцией ResetEvent. Любое количество ожидающих потоков или потоков, которые впоследствии начинают операции ожидания для указанного объекта события, можно освободить, пока состояние объекта сигнализирует.
Несколько процессов могут иметь дескриптор одного объекта события, что позволяет использовать объект для межпроцессной синхронизации. Доступны следующие механизмы совместного использования объектов:
- Дочерний процесс, созданный функцией CreateProcess createProcess, может наследовать дескриптор объекта события, если параметр
lpEventAttributes Наследование CreateEvent. - Процесс может указать дескриптор объекта события в вызове функции DuplicateHandle, чтобы создать повторяющийся дескриптор, который можно использовать другим процессом.
- Процесс может указать имя объекта события в вызове функции OpenEvent или CreateEvent.
Заметка
Заголовок synchapi.h определяет CreateEventEx как псевдоним, который автоматически выбирает версию 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 |