KeWaitForSingleObject 函数 (wdm.h)
KeWaitForSingleObject 例程将当前线程置于等待状态，直到给定调度程序对象设置为信号状态，或 (选择性地) ，直到等待超时。
语法
NTSTATUS
KeWaitForSingleObject (
PVOID Object,
KWAIT_REASON WaitReason,
KPROCESSOR_MODE WaitMode,
BOOLEAN Alertable,
PLARGE_INTEGER Timeout
);
参数
[in] Object
指向调用方为其提供存储 (事件、互斥体、信号灯、线程或计时器) 的已初始化调度程序对象的指针。 调度程序对象必须驻留在非分页系统内存中。 有关详细信息，请参阅“备注”。
[in] WaitReason
指定等待的原因。 驱动程序应将此值设置为 Executive，除非它代表用户执行工作并在用户线程的上下文中运行，在这种情况下，它应将此值设置为 UserRequest。
[in] WaitMode
指定调用方是在 KernelMode 还是 UserMode 中等待。 最低级别和中间驱动程序应指定 KernelMode。 如果给定 的对象 是互斥体，则调用方必须指定 KernelMode。
[in] Alertable
指定一个布尔值，如果等待可发出警报，则为 TRUE ，否则为 FALSE 。
[in, optional] Timeout
指向超时值的指针，该值指定要完成等待的绝对时间或相对时间（以 100 纳秒为单位）。
正值指定相对于 1601 年 1 月 1 日绝对时间。 负值指定相对于当前时间的间隔。 绝对过期时间跟踪系统时间中的任何更改;相对过期时间不受系统时间更改的影响。
如果 Timeout = 0，则例程返回而不等待。 如果调用方提供 NULL 指针，则例程将无限期等待，直到调度程序对象设置为信号状态。 有关更多信息，请参见下面的“备注”部分。
返回值
KeWaitForSingleObject 可以返回下列值之一。
NT_SUCCESS宏将所有这些状态值识别为“成功”值。
| 返回代码 | 说明 |
|---|---|
| STATUS_SUCCESS | Object 参数指定的调度程序对象满足等待。 |
| STATUS_ALERTED | 等待中断，无法向调用线程发送警报。 |
| STATUS_USER_APC | 等待中断，无法将用户异步过程调用 (APC) 传送到调用线程。 |
| STATUS_TIMEOUT | 在对象设置为信号状态之前发生超时。 当无法立即满足指定的等待条件集并且 Timeout 设置为零时，可以返回此值。 |
注解
检查指定 对象的 当前状态，以确定是否可以立即满足等待。 如果是这样，则对 对象执行必要的副作用。 否则，当前线程处于等待状态，并选择新线程在当前处理器上执行。
Alertable 参数确定线程何时可以发出警报，其等待状态因此中止。 有关详细信息，请参阅 等待和 APC。
当传递给 KeWaitForSingleObject 的 Object 参数是互斥体时，需要特别注意。 如果等待的调度程序对象是互斥体，则 APC 传递与等待期间所有其他调度程序对象的传递相同。 但是，在 KeWaitForSingleObject 返回并STATUS_SUCCESS且线程实际持有互斥体之后，仅传递特殊的内核模式 APC。 禁用所有其他 APC（内核模式和用户模式）的传递。 在释放互斥体之前，对 APC 的传递限制一直存在。
Object 参数指向的调度程序对象必须驻留在非分页系统内存中。
如果 WaitMode 参数为 UserMode，则可以在等待期间交换内核堆栈。 因此，在使用 UserMode 参数调用 KeWaitForSingleObject 时，调用方不得尝试在堆栈上传递参数。 如果在堆栈上分配事件，则必须将 WaitMode 参数设置为 KernelMode。
当 WaitMode 参数为 UserMode 或 Alertable 为 TRUE 时，检查 KeWaitForSingleObject 的返回值尤其重要，因为 KeWaitForSingleObject 可能会提前返回状态为 STATUS_USER_APC 或 STATUS_ALERTED。
用户可以中止的所有长期等待都应为 UserMode 等待， 并且 Alertable 应设置为 FALSE。
如果可能，Alertable 应设置为 FALSE，WaitMode 应设置为 KernelMode，以降低驱动程序的复杂性。 当等待是长期等待时，主要例外。
如果为 Timeout 提供了 NULL 指针，则调用线程将保持等待状态，直到对象收到信号。
如果超时值为零，则允许测试一组等待条件以及任何副作用的条件性能（如果可以立即满足等待），就像获取互斥体一样。
超时间隔相对于系统时钟进行测量，操作系统检测超时间隔结束的准确性受系统时钟粒度的限制。 有关详细信息，请参阅 计时器准确性。
互斥体只能以递归方式获取 MINLONG 时间。 如果超出此限制，则例程将引发STATUS_MUTANT_LIMIT_EXCEEDED异常。
KeWaitForSingleObject 的调用方必须在 IRQL <= DISPATCH_LEVEL 运行。 但是，如果 Timeout = NULL 或 Timeout ！= 0，则调用方必须在 IRQL <= APC_LEVEL 并在非比特线程上下文中运行。 如果 Timeout ！= NULL 且 Timeout = 0，则调用方必须在 IRQL <= DISPATCH_LEVEL运行。
KeWaitForMutexObject 是转换为 KeWaitForSingleObject 的宏，可以改用它。
为了获得更好的性能，请使用快速互斥体或受保护的互斥体。 有关详细信息，请参阅 Mutex 对象的替代项。
有关互斥对象的详细信息，请参阅 互斥对象。