ZwCreateEvent 函数（ntifs.h）

项目
12/21/2024

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，以将事件对象初始化为 Signaled 状态。设置为 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 创建事件对象，将其初始状态设置为指定值，并打开具有指定所需访问权限的对象句柄。

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

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

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

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

与同步事件不同，通知事件不会自动重置。通知事件处于信号状态后，它将保持该状态，直到显式重置。

若要同步通知事件，

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

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

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

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

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

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

注意

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

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

要求

要求	价值
最低支持的客户端	Windows XP。
目标平台	普遍
标头	ntifs.h （include Ntifs.h）
库	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 符合性规则	HwStorPortProhibitedDIS（storport），PowerIrpDDis（wdm）