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

Статья
08/26/2023

Создает или открывает именованный или неименованный объект события.

Чтобы указать маску доступа для объекта, используйте функцию CreateEventEx .

Синтаксис

HANDLE CreateEventW(
  [in, optional] LPSECURITY_ATTRIBUTES lpEventAttributes,
  [in]           BOOL                  bManualReset,
  [in]           BOOL                  bInitialState,
  [in, optional] LPCWSTR               lpName
);

Параметры

[in, optional] lpEventAttributes

Указатель на структуру SECURITY_ATTRIBUTES . Если этот параметр имеет значение NULL, дескриптор не может наследоваться дочерними процессами.

Элемент lpSecurityDescriptor структуры задает дескриптор безопасности для нового события. Если lpEventAttributes имеет значение NULL, событие получает дескриптор безопасности по умолчанию. Списки управления доступом в дескрипторе безопасности по умолчанию для события поступают из основного маркера или маркера олицетворения создателя.

[in] bManualReset

Если этот параметр имеет значение TRUE, функция создает объект события сброса вручную, для которого требуется использовать функцию ResetEvent , чтобы задать для события состояние без знака. Если этот параметр имеет значение FALSE, функция создает объект события с автоматическим сбросом, а система автоматически сбрасывает состояние события до nonsignaled после освобождения одного ожидающего потока.

[in] bInitialState

Если этот параметр имеет значение TRUE, сигнализирует о начальном состоянии объекта события; в противном случае он не будет подписан.

[in, optional] lpName

Имя объекта события. Имя ограничено MAX_PATH символами. При сравнении имен учитывается регистр.

Если lpName соответствует имени существующего именованного объекта события, эта функция запрашивает EVENT_ALL_ACCESS право доступа. В этом случае параметры bManualReset и bInitialState игнорируются, так как они уже заданы процессом создания. Если параметр lpEventAttributes не равен NULL, он определяет, можно ли наследовать дескриптор, но его член дескриптора безопасности игнорируется.

Если lpName имеет значение NULL, объект события создается без имени.

Если lpName соответствует имени другого типа объекта в том же пространстве имен (например, существующего семафора, мьютекса, таймера ожидания, задания или объекта сопоставления файлов), функция завершается сбоем и функция GetLastError возвращает ERROR_INVALID_HANDLE. Это происходит потому, что эти объекты используют одно и то же пространство имен.

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

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

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

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

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

Дескриптор, возвращаемый CreateEvent , имеет право доступа EVENT_ALL_ACCESS ; Его можно использовать в любой функции, требующей дескриптора объекта события, при условии, что вызывающему объекту предоставлен доступ. Если событие создается из службы или потока, олицетворения другого пользователя, можно либо применить дескриптор безопасности к событию при его создании, либо изменить дескриптор безопасности по умолчанию для процесса создания, изменив его daCL по умолчанию. Дополнительные сведения см. в разделе Синхронизация безопасности объектов и прав доступа.

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

Начальное состояние объекта события определяется параметром bInitialState . Используйте функцию SetEvent , чтобы задать состояние объекта события как сигнальное. Используйте функцию ResetEvent , чтобы сбросить состояние объекта события до nonsignaled.

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

При сигнале о состоянии объекта события автоматического сброса он остается сигнальным до тех пор, пока не будет освобожден один поток ожидания. затем система автоматически сбрасывает состояние до nonsignaled. Если ожидающих потоков нет, состояние объекта события остается сигнальным.

Несколько процессов могут иметь дескриптор одного объекта события, что позволяет использовать объект для синхронизации между процессами. Доступны следующие механизмы совместного использования объектов:

Дочерний процесс, созданный функцией CreateProcess, может наследовать дескриптор объекта события, если параметр lpEventAttributes наследования с поддержкой CreateEvent .
Процесс может указать дескриптор объекта события в вызове функции DuplicateHandle , чтобы создать повторяющийся дескриптор, который может использоваться другим процессом.
Процесс может указать имя объекта события в вызове функции OpenEvent или CreateEvent .

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

Примеры

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

Примечание

Заголовок synchapi.h определяет CreateEvent как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования


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