Функция ZwOpenEvent (wdm.h)

Статья
12/21/2024

Подпрограмма ZwOpenEvent открывает дескриптор существующего именованного объекта события с указанным требуемым доступом.

Синтаксис

NTSYSCALLAPI NTSTATUS ZwOpenEvent(
  [out] PHANDLE            EventHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes
);

Параметры

[out] EventHandle

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

[in] DesiredAccess

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

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

[in] ObjectAttributes

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

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

ZwOpenEvent возвращает STATUS_SUCCESS или соответствующее состояние ошибки. Эта подпрограмма может вернуть один из следующих кодов состояния ошибки:

Возвращаемый код	Описание
STATUS_INSUFFICIENT_RESOURCES	Ресурсы, необходимые этой функции, не могут быть выделены.
STATUS_INVALID_PARAMETER	Структура objectAttributes не была предоставлена или содержит недопустимое значение параметра.
STATUS_OBJECT_NAME_INVALID	Параметр ObjectAttributes содержал ObjectName в недопустимой структуре OBJECT_ATTRIBUTES.
STATUS_OBJECT_PATH_SYNTAX_BAD	Путь к объекту содержал неправильный синтаксис. Например, параметр objectAttributes не содержит элемент RootDirectory, но элемент ObjectName в структуре OBJECT_ATTRIBUTES является пустой строкой или не начинается с символа OBJECT_NAME_PATH_SEPARATOR.
STATUS_OBJECT_PATH_NOT_FOUND	Путь к объекту не найден, указывающий, что он не существует.
STATUS_OBJECT_NAME_NOT_FOUND	Имя объекта не найдено, указывающее, что объект не существует.
STATUS_PRIVILEGE_NOT_HELD	Вызывающий объект не имеет необходимых привилегий для создания дескриптора с доступом, указанным в параметре DesiredAccess.

Замечания

ZwOpenEvent открывает существующий именованный объект события и создает дескриптор объекта с указанным требуемым доступом.

ZwOpenEvent могут открывать события уведомлений или синхронизации.

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

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

Если вызов функции ZwOpenEvent происходит в пользовательском режиме, следует использовать имя "NtOpenEvent" вместо "ZwOpenEvent".

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

Требования

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