ZwCreateEvent 函数 (ntifs.h)

项目
07/11/2023

ZwCreateEvent 例程创建一个事件对象，将该事件的初始状态设置为指定值，并打开具有指定所需访问权限的对象的句柄。

语法

NTSYSAPI NTSTATUS ZwCreateEvent(
  [out]          PHANDLE            EventHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in]           EVENT_TYPE         EventType,
  [in]           BOOLEAN            InitialState
);

参数

[out] EventHandle

指向将接收事件对象句柄的变量的指针。句柄包括记账信息，例如引用计数和安全上下文。

[in] DesiredAccess

ACCESS_MASK值，该值表示事件对象的所需访问类型。下表包含特定于事件的ACCESS_MASK值。

值	所需访问权限
EVENT_QUERY_STATE	查询事件对象的状态。
EVENT_MODIFY_STATE	修改事件对象的状态。
EVENT_ALL_ACCESS	对事件对象的所有可能的访问权限。

[in, optional] ObjectAttributes

指向由调用方提供的对象属性结构的指针，该结构用于指定对象。例如，这些属性将包括 ObjectName 和 SECURITY_DESCRIPTOR。此参数通过调用 InitializeObjectAttributes 宏进行初始化。

[in] EventType

事件的类型，可以是 SynchronizationEvent 或 NotificationEvent。这些值属于 ntdef.h 头文件中定义的 EVENT_TYPE 枚举。

[in] InitialState

事件对象的初始状态。设置为 TRUE 以将事件对象初始化为“已信号”状态。设置为 FALSE 以将事件对象初始化为未发出信号状态。

返回值

ZwCreateEvent 返回STATUS_SUCCESS或适当的错误状态。可能的错误状态代码包括：

返回代码	说明
STATUS_INSUFFICIENT_RESOURCES	无法分配此函数所需的资源。
STATUS_INVALID_PARAMETER	提供的 ObjectAttributes 结构包含无效的参数值。
STATUS_INVALID_PARAMETER_4	指定的 EventType 参数无效。
STATUS_OBJECT_NAME_INVALID	ObjectAttributes 参数在OBJECT_ATTRIBUTES结构中包含无效的 ObjectName。
STATUS_OBJECT_PATH_SYNTAX_BAD	ObjectAttributes 参数不包含 RootDirectory 成员，但 OBJECT_ATTRIBUTES 结构中的 ObjectName 成员是空字符串或不包含OBJECT_NAME_PATH_SEPARATOR字符。这表示对象路径的语法不正确。
STATUS_PRIVILEGE_NOT_HELD	调用方没有创建具有 DesiredAccess 参数中指定的访问权限的句柄所需的权限。

注解

ZwCreateEvent 创建一个事件对象，将其初始状态设置为指定值，并打开具有指定所需访问权限的对象句柄。

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

ZwCreateEvent 可以创建通知或同步事件：

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

同步事件是自动重置。当同步事件设置为“已信号”状态时，将释放等待事件发出信号的单个执行线程，并且该事件会自动重置为 Not-Signaled 状态。

与同步事件不同，通知事件不会自动重置。通知事件处于“已发出信号”状态后，将一直处于该状态，直到显式重置。

若要对通知事件进行同步，请执行以下操作：

使用 ZwCreateEvent 创建通知事件，并将 EventType 参数设置为 NotificationEvent。
使用 ZwCreateEvent 返回的 EventHandle 调用 ZwWaitForSingleObject，等待事件发出信号。多个执行线程可以等待给定通知事件发出信号。若要轮询而不是停止，请将 ZwWaitForSingleObject 的超时值指定为零。
不再需要访问事件时，使用 ZwClose 关闭通知事件的句柄。

在 InitializeObjectAttributes 宏用于在对象的OBJECT_ATTRIBUTES结构中设置属性之后调用 ZwCreateEvent 函数。

有两种替代方法可以指定传递给 ZwCreateEvent 的对象的名称：

作为完全限定的路径名，在输入 ObjectAttributes 的 ObjectName 成员中提供。
作为相对于输入 ObjectAttributes 的 RootDirectory 成员中的句柄表示的目录的路径名。

若要释放事件，驱动程序使用事件句柄调用 ZwClose 。

有关事件的详细信息，请参阅 事件对象。

注意

如果在用户模式下调用 ZwCreateEvent 例程，则应使用名称“NtCreateEvent”而不是“ZwCreateEvent”。

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

要求

要求	值
最低受支持的客户端	Windowsxp。
目标平台	通用
标头	ntifs.h (包括 Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 符合性规则	HwStorPortProhibitedDDI (storport) ， PowerIrpDDis (wdm)