ZwWaitForSingleObject 函数 （ntifs.h）
ZwWaitForSingleObject 例程等待，直到指定对象达到 Signaled 的状态。 还可以指定可选的超时。
语法
NTSYSAPI NTSTATUS ZwWaitForSingleObject(
[in] HANDLE Handle,
[in] BOOLEAN Alertable,
[in, optional] PLARGE_INTEGER Timeout
);
参数
[in] Handle
对象的句柄。
[in] Alertable
一个布尔值，该值指定等待是否可发出警报。
[in, optional] Timeout
指向超时值的可选指针，该值指定等待完成的绝对时间或相对时间。 负值指定相对于当前时间的间隔。 该值应以 100 纳秒为单位表示。 绝对过期时间跟踪系统时间中的任何更改。 相对过期时间不受系统时间更改的影响。
返回值
ZwWaitForSingleObject 可以返回以下可能的状态代码之一：
| 返回代码 | 描述 |
|---|---|
| STATUS_ACCESS_DENIED | 调用方没有 Handle 参数指定的事件所需的权限。 |
| STATUS_ALERTED | 等待已中止，以便将警报传送到当前线程。 |
| STATUS_INVALID_HANDLE | 提供的 Handle 参数无效。 |
| STATUS_SUCCESS | 指定的对象满足等待。 |
| STATUS_TIMEOUT | 在对象设置为信号状态之前发生超时。 当无法立即满足指定的等待条件集并且 Timeout 参数设置为零时，可以返回此值。 |
| STATUS_USER_APC | 等待已中止，将用户 APC 传递到当前线程。 |
请注意，NT_SUCCESS宏将STATUS_ALERTED、STATUS_SUCCESS、STATUS_TIMEOUT和STATUS_USER_APC状态值识别为“成功”值。
言论
ZwWaitForSingleObject 等待指定对象达到 Signaled 状态。 还可以指定可选超时。 ZwWaitForSingleObject 检查指定对象的当前状态，以确定是否可以立即满足等待。 如果是，则执行操作。 否则，当前线程处于等待状态，并且已选择新线程以便在当前处理器上执行。
如果未指定 Timeout 参数，则在对象达到 Signaled 状态之前，不会满足等待。 如果指定了 Timeout 参数，并且该对象在超时到期时未达到 Signaled 状态，则会自动满足等待。 如果指定了显式 超时 值为零，则如果无法立即满足等待，则不会发生等待。 超时 值为零，允许测试一组等待条件，如果可以立即满足等待，则允许测试任何副作用的条件性能，就像在获取互斥体时一样。 还可以将等待指定为可警报。
Alertable 参数指定线程是否可以发出警报及其等待状态，从而中止。 如果此参数的值为 FALSE，则无法发出线程警报。 此规则的唯一例外是终止线程。 在某些情况下，终止线程在结束过程中可能会发出警报。 例如，当用户使用 CTRL+C 终止时，线程会自动发出警报。
如果 可警报的值为 TRUE，并且存在以下条件之一，则线程将发出警报：
- 如果警报的来源是用于警报线程的内部无证内核模式例程。
- 警报的来源是用户模式 APC。
在这两种情况下，线程的等待对STATUS_ALERTED完成状态感到满意。 第二种情况下，它满足于STATUS_USER_APC的完成状态。
对于要传递的用户模式 APC，线程必须可发出警报。 对于内核模式 APC，情况并非如此。 即使线程未发出警报，也可以传递和执行内核模式 APC。 APC 的执行完成后，线程的等待将恢复。 线程从不发出警报，也不会通过传送内核模式 APC 来中止线程。
将内核模式 APC 传送到等待线程并不取决于线程是否可以发出警报。 如果内核模式 APC 是特殊的内核模式 APC，则提供 APC，前提是 IRQL 小于APC_LEVEL。 如果内核模式 APC 是正常的内核模式 APC，则提供 APC，前提是以下三个条件保留：（1） IRQL 小于 APC_LEVEL，（2） 没有正在进行内核 APC，并且 （3） 线程不在关键部分中。
如果传递给 ZwWaitForSingleObject 的句柄 引用互斥体，则 APC 传递与等待期间所有其他调度程序对象的传递相同。 但是，ZwWaitForSingleObject 返回STATUS_SUCCESS并且线程实际保存互斥体后，只传递特殊的内核模式 APC。 禁用了所有其他 APC（内核模式和用户模式）的传递。 在释放互斥体之前，对 APC 传递的这种限制会一直存在。
当 Alertable 参数为 TRUE 时，检查 ZwWaitForSingleObject 的返回值尤其重要，因为 ZwWaitForSingleObject 可能提前返回STATUS_USER_APC或STATUS_ALERTED状态。
如果用户将 Alertable 参数设置为 FALSE，则可以中止所有长期等待。
有关详细信息，请参阅 等待线程是否接收警报和 APC？
ZwWaitForSingleObject 的调用方必须在 IRQL 中运行小于或等于DISPATCH_LEVEL。 通常，调用方必须在 IRQL PASSIVE_LEVEL和非比特线程上下文中运行。 在 IRQL DISPATCH_LEVEL 运行时运行的调用仅在调用方指定 Timeout 参数为零时才有效。 也就是说，驱动程序不得等待 IRQL 等于DISPATCH_LEVEL的非零间隔。
超时间隔相对于系统时钟进行度量，超时度量的准确性受系统时钟粒度的限制。 有关详细信息，请参阅 计时器准确性。
如果在用户模式下调用 ZwWaitForSingleObject 函数，则应使用名称“NtWaitForSingleObject”而不是“ZwWaitForSingleObject”。
对于内核模式驱动程序的调用，NtXxx 和 ZwXxx 版本的 Windows 本机系统服务例程的行为方式可能以不同的方式处理和解释输入参数。 有关 NtXxx 与 ZwXxx 例程之间的关系的详细信息，请参阅 使用 Nt 和 Zw 版本的本机系统服务例程。
要求
| 要求 | 价值 |
|---|---|
| 最低支持的客户端 | Windows XP |
| 目标平台 | 普遍 |
| 标头 | ntifs.h（包括 Ntifs.h、FltKernel.h） |
| 库 | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| DDI 符合性规则 | HwStorPortProhibitedDIS（storport），SpNoWait（storport） |