Функция 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 . Если lpEventAttributes имеет значение NULL, то дескриптор события не может наследоваться дочерними процессами.
Элемент lpSecurityDescriptor структуры задает дескриптор безопасности для нового события. Если lpEventAttributes имеет значение NULL, событие получает дескриптор безопасности по умолчанию. Списки управления доступом в дескрипторе безопасности по умолчанию для события поступают из основного маркера или токена олицетворения создателя.
[in, optional] lpName
Имя объекта события. Имя ограничено MAX_PATH символами. Сравнение имен учитывает регистр.
Если lpName имеет значение NULL, объект события создается без имени.
Если lpName соответствует имени другого типа объекта в том же пространстве имен (например, существующего семафора, мьютекса, таймера ожидания, задания или объекта сопоставления файлов), функция завершается сбоем и функция GetLastError возвращает ERROR_INVALID_HANDLE. Это происходит потому, что эти объекты используют одно и то же пространство имен.
Имя может иметь префикс "Global" или "Local" для явного создания объекта в глобальном пространстве имен или пространстве имен сеанса. Оставшаяся часть имени может содержать любой символ, кроме символа обратной косой черты (\). Дополнительные сведения см. в разделе Пространства имен объектов ядра. Быстрое переключение пользователей реализуется с помощью сеансов служб терминалов. Имена объектов ядра должны соответствовать рекомендациям, описанным для служб терминалов, чтобы приложения могли поддерживать нескольких пользователей.
Объект можно создать в частном пространстве имен. Дополнительные сведения см. в разделе Пространства имен объектов.
[in] dwFlags
Этот параметр может быть одним или несколькими из следующих значений.
| Значение | Значение |
|---|---|
|
Сигнализируется о начальном состоянии объекта события; в противном случае он не подписан. |
|
Событие должно быть сброшено вручную с помощью функции ResetEvent . Любое количество потоков ожидания или потоков, которые впоследствии начинают операции ожидания для указанного объекта события, могут быть освобождены при сигнале о состоянии объекта.
Если этот флаг не указан, система автоматически сбрасывает событие после выпуска одного ожидающего потока. |
[in] dwDesiredAccess
Маска доступа для объекта события. Список прав доступа см. в разделе Безопасность объектов синхронизации и права доступа.
Возвращаемое значение
Если функция выполняется успешно, возвращаемое значение является дескриптором объекта события. Если именованный объект события существовал до вызова функции, функция возвращает дескриптор существующему объекту, а GetLastError возвращает ERROR_ALREADY_EXISTS.
Если функция завершается сбоем, возвращается значение NULL. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.
Комментарии
Любой поток вызывающего процесса может указать дескриптор объекта события в вызове одной из функций ожидания. Функции ожидания с одним объектом возвращаются при сигнале о состоянии указанного объекта. Функциям ожидания с несколькими объектами можно указать возвращать либо при получении сигнала о каком-либо из них, либо при сигнале всех указанных объектов. При возврате функции ожидания поток ожидания освобождается для продолжения выполнения.
Начальное состояние объекта события определяется параметром dwFlags . Используйте функцию SetEvent , чтобы задать состояние объекта события как сигнальное. Используйте функцию ResetEvent , чтобы сбросить состояние объекта события до незначаемого.
Когда подается сигнал о состоянии объекта события сброса вручную, он остается сигнальным до тех пор, пока функция ResetEvent не будет явно сброшена до неназначения. Любое количество потоков ожидания или потоков, которые впоследствии начинают операции ожидания для указанного объекта события, могут быть освобождены при сигнале о состоянии объекта.
Несколько процессов могут иметь дескриптор одного объекта события, что позволяет использовать объект для синхронизации между процессами. Доступны следующие механизмы совместного использования объектов:
- Дочерний процесс, созданный функцией CreateProcess, может наследовать дескриптор объекта события, если параметр lpEventAttributes наследования с поддержкой CreateEvent .
- Процесс может указать дескриптор объекта события в вызове функции DuplicateHandle , чтобы создать повторяющийся дескриптор, который может использоваться другим процессом.
- Процесс может указать имя объекта события в вызове функции OpenEvent или CreateEvent .
Примечание
Заголовок synchapi.h определяет CreateEventEx в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows Vista [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows Server 2008 [классические приложения | Приложения UWP] |
| Целевая платформа | Windows |
| Header | synchapi.h (включая Windows.h в Windows 7, Windows Server 2008 Windows Server 2008 R2) |
| Библиотека | Kernel32.lib |
| DLL | Kernel32.dll |