KeSetEvent 函数 (wdm.h)

项目
08/08/2023

KeSetEvent 例程将事件对象设置为信号状态（如果事件尚未发出信号），并返回事件对象的先前状态。

语法

LONG KeSetEvent(
  [in, out] PRKEVENT  Event,
  [in]      KPRIORITY Increment,
  [in]      BOOLEAN   Wait
);

参数

[in, out] Event

指向调用方为其提供存储的已初始化事件对象的指针。

[in] Increment

指定要在设置事件导致满足等待时应用的优先级增量。

[in] Wait

指定调用 KeSetEvent 后是否立即调用 KeWaitXxx 例程之一。如果 为 TRUE， 则 KeSetEvent 调用必须后跟对 KeWaitForMultipleObjects、 KeWaitForMutexObject 或 KeWaitForSingleObject 的调用。有关更多信息，请参见下面的“备注”部分。

返回值

如果事件对象的先前状态已发出信号，则返回非零值。

注解

调用 KeSetEvent 会导致事件达到信号状态。如果事件是通知事件，则系统会尝试满足事件对象上尽可能多的等待。在调用 KeClearEvent 或 KeResetEvent 清除事件之前，事件将一直发出信号。如果事件是同步事件，则系统会自动清除该事件之前满足一次等待。

KeSetEvent 例程可能会暂时引发 IRQL。如果 Wait 参数为 FALSE，则例程在返回之前，会将 IRQL 还原到调用开始时的原始值。

如果等待 = TRUE，则例程返回而不降低 IRQL。在这种情况下， KeSetEvent 调用必须紧跟 KeWaitXxx 调用。通过将 Wait = TRUE 设置为 TRUE，调用方可以防止 KeSetEvent 调用和 KeWaitXxx 调用之间发生不必要的上下文切换。 KeWaitXxx 例程在返回之前，会在 KeSetEvent 调用开始时将 IRQL 还原为其原始值。尽管 IRQL 禁用两个调用之间的上下文切换，但这些调用不能可靠地用作原子操作的开始和结束。例如，在这两个调用之间，在另一个处理器上同时运行的线程可能会更改事件对象或等待目标的状态。

在 IRQL = PASSIVE_LEVEL 运行的可分页线程或可分页驱动程序例程不应调用将 Wait 参数设置为 TRUE 的 KeSetEvent。如果调用方恰好在对 KeSetEvent 和 KeWaitXxx 的调用之间分页，则此类调用会导致严重页面错误。

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

如果 Wait 设置为 FALSE，则调用方可以在 IRQL <= DISPATCH_LEVEL 运行。否则， KeSetEvent 的调用方必须在 IRQL <= APC_LEVEL 且在非比特线程上下文中运行。

要求

要求	值
最低受支持的客户端	从 Windows 2000 开始可用。
目标平台	通用
标头	wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	请参见“备注”部分。
DDI 符合性规则	CompletionEventChecking (wdm) 、 DoubleKeSetEvent (storport) 、 HwStorPortProhibitedDDi (storport) 、 IoAllocateIrpSignalEventInCompletion (wdm) 、 IoBuildDeviceIoControlSetEvent (wdm) 、 IoBuildFsdIrpSignalEventInCompletion (wdm) 、 IrqlKeSetEvent (wdm) 、 SignalEventInCompletion (wdm)