Функция ZwOpenEvent (wdm.h)
Подпрограмма 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 могут вести себя по-разному, так как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связи между версиями подпрограмм NtXxx и ZwXxx см. в разделе Использование версий NT и Zw подпрограмм собственных системных служб.
Требования
| Требование | Значение |
|---|---|
| Целевая платформа | Универсальное |
| Верхняя часть | wdm.h (включая Wdm.h) |
| Библиотека | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| Правила соответствия DDI | HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm) |