Функция ZwCreateEvent (ntifs.h)

Статья
07/11/2023

Подпрограмма ZwCreateEvent создает объект события, устанавливает исходное состояние события в указанное значение и открывает дескриптор для объекта с указанным требуемым доступом.

Синтаксис

NTSYSAPI NTSTATUS ZwCreateEvent(
  [out]          PHANDLE            EventHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in]           EVENT_TYPE         EventType,
  [in]           BOOLEAN            InitialState
);

Параметры

[out] EventHandle

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

[in] DesiredAccess

Значение ACCESS_MASK , представляющее требуемые типы доступа для объекта события. В следующей таблице содержатся значения ACCESS_MASK для конкретных событий.

Значение	Требуемый доступ
EVENT_QUERY_STATE	Запрос состояния объекта события.
EVENT_MODIFY_STATE	Измените состояние объекта события.
EVENT_ALL_ACCESS	Все возможные права доступа к объекту события.

[in, optional] ObjectAttributes

Указатель на структуру атрибутов объекта, предоставляемую вызывающим объектом для использования для указанного объекта. К этим атрибутам относятся , например, ObjectName и SECURITY_DESCRIPTOR. Этот параметр инициализируется путем вызова макроса InitializeObjectAttributes .

[in] EventType

Тип события, который может быть SynchronizationEvent или NotificationEvent. Эти значения принадлежат перечислению EVENT_TYPE , которое определено в файле заголовка ntdef.h .

[in] InitialState

Начальное состояние объекта события. Задайте значение TRUE , чтобы инициализировать объект события в состояние Signaled . Задайте значение FALSE , чтобы инициализировать объект события в состояние без сигнала.

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

ZwCreateEvent возвращает STATUS_SUCCESS или соответствующее состояние ошибки. Возможные коды состояния ошибок:

Код возврата	Описание
STATUS_INSUFFICIENT_RESOURCES	Ресурсы, необходимые для этой функции, не могут быть выделены.
STATUS_INVALID_PARAMETER	Предоставленная структура ObjectAttributes содержала недопустимое значение параметра.
STATUS_INVALID_PARAMETER_4	Указанный параметр EventType был недопустимым.
STATUS_OBJECT_NAME_INVALID	Параметр ObjectAttributes содержал objectName в структуре OBJECT_ATTRIBUTES , которая была недопустимой.
STATUS_OBJECT_PATH_SYNTAX_BAD	Параметр ObjectAttributes не содержал элемента RootDirectory , но элемент ObjectName в структуре OBJECT_ATTRIBUTES был пустой строкой или не содержал символ OBJECT_NAME_PATH_SEPARATOR. Это указывает на неправильный синтаксис пути к объекту.
STATUS_PRIVILEGE_NOT_HELD	У вызывающего объекта не было необходимых привилегий для создания дескриптора с доступом, указанным в параметре DesiredAccess .

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

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

ZwCreateEvent может создавать события уведомления или синхронизации:

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

Событие синхронизации сбрасывается автоматически. Если для события синхронизации задано состояние Signaled, освобождается один поток выполнения, ожидающий передачи сигнала о событии, и событие автоматически сбрасывается в состояние Not-Signaled.

В отличие от события синхронизации, событие уведомления не сбрасывается автоматически. После того как событие уведомления перейдет в состояние Signaled , оно остается в этом состоянии до тех пор, пока оно не будет сброшено явным образом.

Чтобы синхронизировать событие уведомления, выполните приведенные далее действия.

Создайте событие уведомления с помощью ZwCreateEvent с параметром EventType , равным NotificationEvent.
Дождитесь передачи сигнала о событии путем вызова ZwWaitForSingleObject с EventHandle, возвращенным ZwCreateEvent. Несколько потоков выполнения могут ожидать передачи сигнала о событии уведомления. Для опроса вместо остановки укажите нулевое время ожидания для ZwWaitForSingleObject.
Закройте дескриптор события уведомления с помощью ZwClose , если доступ к событию больше не нужен.

Функция ZwCreateEvent вызывается после того, как макрос InitializeObjectAttributes используется для задания атрибутов в структуре OBJECT_ATTRIBUTES для объекта .

Существует два альтернативных способа указать имя объекта, передаваемого в ZwCreateEvent:

В качестве полного имени пути, указанного в элементе ObjectName входного объекта ObjectAttributes.
Значение pathname относительно каталога, представленного дескриптором в элементе RootDirectory входного объекта ObjectAttributes.

Чтобы освободить событие, драйвер вызывает ZwClose с дескриптором события.

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

Примечание

Если вызов подпрограммы ZwCreateEvent происходит в пользовательском режиме, следует использовать имя NtCreateEvent вместо ZwCreateEvent.

Для вызовов из драйверов режима ядра версии NtXxx и ZwXxx подпрограммы собственных системных служб Windows могут вести себя по-разному, так как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связи между версиями процедуры NtXxx и ZwXxx см. в разделе Использование версий Nt и Zw для процедур собственных системных служб.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP.
Целевая платформа	Универсальное
Верхняя часть	ntifs.h (включая Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Правила соответствия DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)