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

Статья
03/08/2023

Подпрограмма 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 .

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

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

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

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

Требования

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