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

Статья
11/20/2024

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

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

Синтаксис

HANDLE CreateEventA(
  [in, optional] LPSECURITY_ATTRIBUTES lpEventAttributes,
  [in]           BOOL                  bManualReset,
  [in]           BOOL                  bInitialState,
  [in, optional] LPCSTR                lpName
);

Параметры

[in, optional] lpEventAttributes

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

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

[in] bManualReset

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

[in] bInitialState

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

[in, optional] lpName

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

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

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

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

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

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

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

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

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

Замечания

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

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

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

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

Когда состояние объекта события автоматического сброса сигнализирует, оно остается сигналом до выпуска одного потока ожидания; Затем система автоматически сбрасывает состояние на незначаемое. Если потоки не ожидают, состояние объекта события по-прежнему сигнализирует.

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

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

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

Примеры

Пример использования CreateEventсм. в разделе Using Event Objects.

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows Server 2003 [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	synchapi.h (включая Windows.h в Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
библиотеки	Kernel32.lib
DLL	Kernel32.dll