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

Статья
12/21/2024

Подпрограмма 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, чтобы инициализировать объект события в состояние not-Signaled.

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

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 с параметр ом EventTypeNotificationEvent.
Подождите, пока событие будет сигнализировать, вызвав ZwWaitForSingleObject с EventHandle, возвращенной ZwCreateEvent. Несколько потоков выполнения могут ожидать передачи сигнала заданного события уведомления. Для опроса вместо остановки укажите время ожидания нуля до ZwWaitForSingleObject.
Закройте дескриптор события уведомления с ZwClose, когда доступ к событию больше не нужен.

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

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

В качестве полного имени пути, предоставленного в элементе objectName входных ObjectAttributes.
Как имя пути относительно каталога, представленного дескриптором в элементе RootDirectory элемента входных ObjectAttributes.

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

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

Заметка

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

Для вызовов драйверов в режиме ядра NtXxx и ZwXxx версии подпрограммы Windows Native System Services могут вести себя по-разному в том, как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связи между NtXxx и ZwXxx версиями подпрограммы см. в разделе Using Nt and Zw Versions of the Native System Services Routines.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP.
целевая платформа	Всеобщий
заголовка	ntifs.h (include Ntifs.h)
библиотеки	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
правил соответствия DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)