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 参数在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) |