[in] Object

指向已初始化的调度程序对象的指针， (调用方为其提供存储的事件、互斥体、信号灯、线程或计时器) 。 调度程序对象必须驻留在非分页系统内存中。 有关详细信息，请参阅“备注”。

[in] WaitReason

指定等待的原因。 驱动程序应将此值设置为 Executive ，除非它代表用户执行工作并在用户线程的上下文中运行，在这种情况下，它应将此值设置为 UserRequest 。

[in] WaitMode

指定调用方是在 KernelMode 还是 UserMode 中等待。 最低级别和中间驱动程序应指定 KernelMode 。 如果给定 的 Object 是互斥体，则调用方必须指定 KernelMode 。

[in] Alertable

指定一个布尔值，如果等待可发出警报，则为 TRUE ，否则为 FALSE 。

[in, optional] Timeout

指向超时值的指针，该值指定要完成等待的绝对时间或相对时间（以 100 纳秒为单位）。

正值指定相对于 1601 年 1 月 1 日绝对时间。 负值指定相对于当前时间的间隔。 绝对过期时间跟踪系统时间中的任何更改;相对过期时间不受系统时间更改的影响。

如果 Timeout = 0，则例程返回而不等待。 如果调用方提供 NULL 指针，则例程将无限期等待，直到调度程序对象设置为信号状态。 有关更多信息，请参见下面的“备注”部分。

KeWaitForSingleObject 可以返回下列值之一。

NT_SUCCESS宏会将所有这些状态值识别为“成功”值。

检查指定 对象的 当前状态以确定能否立即满足等待。 如果是这样，则会对 对象执行必要的副作用。 否则，当前线程处于等待状态，并选择一个新线程在当前处理器上执行。

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 且在非bitrary线程上下文中运行。 如果 Timeout ！= NULL 且 Timeout = 0，则调用方必须在 IRQL <= DISPATCH_LEVEL 运行。

KeWaitForMutexObject 是转换为 KeWaitForSingleObject 的宏，可以改用它。

为了提高性能，请使用快速互斥体或受保护的互斥体。 有关详细信息，请参阅 互斥对象的替代项 。

有关互斥对象的详细信息，请参阅 互斥对象 。

DDI 符合性规则 CompleteRequestStatusCheck (wdm) ， HwStorPortProhibitedDDI (storport) ， IoAllocateIrpSignalEventInCompletionTimeout (wdm) ， IoBuildDeviceControlWait (wdm) ， IoBuildDeviceControlWaitTimeout (wdm) ， IoBuildFsdIrpSignalEventInCompletionTimeout (wdm) ， IoBuildSynchronousFsdRequestWait (wdm) ， IoBuildSynchronousFsdRequestWaitTimeout (wdm) ， IrpProcessingComplete (wdm) 、 IrqlKeWaitForMutexObject (wdm) 、 LowerDriverReturn (wdm) 、 MarkIrpPending2 (wdm) 、 PendedCompletedRequest (wdm) ( PendedCompletedRequest2 (wdm) 、 PendedCompletedRequest3 (wdm) 、 PendedCompletedRequestEx (wdm) 、 RemoveLockForwardDeviceControl (wdm) ， RemoveLockForwardDeviceControlInternal (wdm) ， RemoveLockForwardRead (wdm) ， RemoveLockForwardWrite (wdm) ， SpNoWait (storport) ， StartDeviceWait (wdm) 、 StartDeviceWait2 (wdm) 、 StartDeviceWait3 (wdm) 、 StartDeviceWait4 (wdm)

ExInitializeFastMutex

KeBugCheckEx

KeInitializeEvent

KeInitializeMutex

KeInitializeSemaphore

KeInitializeTimer

KeWaitForMultipleObjects