IoCreateSynchronizationEvent 函数 (wdm.h)

  • 项目

IoCreateSynchronizationEvent 例程创建或打开一个命名的同步事件，用于序列化两个其他不相关的驱动程序之间的硬件访问。

语法

PKEVENT IoCreateSynchronizationEvent(
  [in]  PUNICODE_STRING EventName,
  [out] PHANDLE         EventHandle
);

参数

[in] EventName

指向缓冲区的指针，该缓冲区包含以 null 结尾的 Unicode 字符串，该字符串为事件命名。

[out] EventHandle

指向要在其中返回事件对象的句柄的位置的指针。 在 Windows Server 2003 及更高版本的 Windows 中，返回的句柄是 内核句柄。

返回值

IoCreateSynchronizationEvent 返回指向创建或打开的事件对象的指针;如果无法创建或打开事件对象，则返回 NULL 。

注解

如果事件对象尚不存在，则会创建该事件对象。 IoCreateSynchronizationEvent 将新同步事件的状态设置为 Signaled。 如果事件对象已存在，则只需打开它。 使用同步事件的驱动程序对使用此例程返回的 PKEVENT 指针调用 KeWaitForSingleObject 。

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

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

在用户模式和内核模式之间共享事件对象需要小心。 有两种用于共享事件对象的main方法：

  • 用户模式应用程序创建事件对象，并通过向驱动程序发送 IOCTL 将对象的句柄传递给驱动程序。 驱动程序必须在创建事件对象的进程的上下文中处理 IOCTL，并且必须通过调用 ObReferenceObjectByHandle 来验证句柄。 建议使用此方法在用户模式和内核模式之间共享事件对象。

  • 驱动程序在全局 \BaseNamedObjects 对象目录中创建命名事件对象。 若要从用户模式访问内核模式事件，请使用名称 Global\\Xxx。 请注意，安全设置可能会阻止应用程序打开事件。 在 Microsoft Win32 子系统初始化之前，不会创建 \BaseNamedObjects 对象目录，因此在启动时加载的驱动程序无法在其 DriverEntry 例程的 \BaseNamedObjects 目录中创建事件对象

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

要求

要求 值
最低受支持的客户端 从 Windows 2000 开始可用。
目标平台 通用
标头 wdm.h (包括 Ntddk.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI 符合性规则 HwStorPortProhibitedDDI (storport) 、 IrqlIoPassive4 (wdm) 、 PowerIrpDDis (wdm)

另请参阅

IoCreateNotificationEvent

KeWaitForSingleObject

RtlInitUnicodeString

ZwClose