zwOpenEvent 函数 (wdm.h)

项目
02/29/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 参数在OBJECT_ATTRIBUTES结构中包含无效的 ObjectName。
STATUS_OBJECT_PATH_SYNTAX_BAD	对象路径包含错误的语法。例如，ObjectAttributes 参数不包含 RootDirectory 成员，但OBJECT_ATTRIBUTES结构中的 ObjectName 成员是空字符串，或者不以OBJECT_NAME_PATH_SEPARATOR字符开头。
STATUS_OBJECT_PATH_NOT_FOUND	找不到对象的路径，指示该路径不存在。
STATUS_OBJECT_NAME_NOT_FOUND	找不到对象名称，指示该对象不存在。
STATUS_PRIVILEGE_NOT_HELD	调用方没有创建具有 DesiredAccess 参数中指定的访问权限的句柄所需的权限。

注解

ZwOpenEvent 打开现有的命名事件对象，并创建具有指定所需访问权限的对象句柄。

ZwOpenEvent 可以打开通知或同步事件。

事件用于协调执行。文件系统驱动程序可以使用事件使调用方能够等待请求的操作完成，直到给定事件设置为“已信号”状态。

通知事件可用于通知一个或多个执行线程已发生事件。同步事件可用于序列化两个不相关的驱动程序之间的硬件访问。

如果在用户模式下调用 ZwOpenEvent 函数，则应使用名称“NtOpenEvent”而不是“ZwOpenEvent”。

对于来自内核模式驱动程序的调用，Windows Native System Services 例程的 NtXxx 和 ZwXxx 版本在处理和解释输入参数的方式上的行为可能有所不同。有关例程的 NtXxx 和 ZwXxx 版本之间的关系的详细信息，请参阅使用本机系统服务例程的 Nt 和 Zw 版本。

要求

要求	值
目标平台	通用
标头	wdm.h (包括 Wdm.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 符合性规则	HwStorPortProhibitedDDI (storport) ， PowerIrpDDis (wdm)