ZwWaitForSingleObject 函数 (ntifs.h)
ZwWaitForSingleObject 例程将等待指定的对象达到信号状态。 还可以指定可选的超时。
语法
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 将等待指定的对象达到信号状态。 还可以指定可选的超时。 ZwWaitForSingleObject 检查指定对象的当前状态，以确定是否可以立即满足等待。 如果是，则执行操作。 否则，当前线程处于等待状态，并选择新线程在当前处理器上执行。
如果未指定 Timeout 参数，则在对象达到“已信号”状态之前，不会满足等待。 如果指定了 Timeout 参数，并且对象在超时到期时未达到 Signaled 状态，则会自动满足等待。 如果指定了显式 Timeout 值零，则如果无法立即满足等待，则不会发生等待。 超时值零允许测试一组等待条件以及任何副作用的条件性能（如果可以立即满足等待），如获取互斥体。 还可以将等待指定为可警报。
Alertable 参数指定线程是否可以发出警报，并因此中止其等待状态。 如果此参数的值为 FALSE，则无法向线程发出警报。 此规则的唯一例外是终止线程的异常。 在某些情况下，终止线程在关闭过程中可能会发出警报。 例如，当用户使用 CTRL+C 终止线程时，线程会自动发出警报。
如果 Alertable的值为 TRUE，并且存在以下条件之一，则会向线程发出警报：
- 如果警报的源是内部的、用于警报线程的未记录内核模式例程。
- 警报的来源是用户模式 APC。
在这两种情况下的第一种情况中，线程的等待状态为STATUS_ALERTED。 第二种情况是，它满足STATUS_USER_APC的完成状态。
线程必须可发出警报，才能传递用户模式 APC。 内核模式 APC 的情况并非如此。 即使线程未收到警报，也可以传递和执行内核模式 APC。 APC 的执行完成后，线程的等待将恢复。 传送内核模式 APC 时，线程永远不会发出警报，也不会中止其等待。
将内核模式 APC 传送到等待线程并不取决于线程是否可以收到警报。 如果内核模式 APC 是特殊的内核模式 APC，则在 IRQL 小于 APC_LEVEL 的情况下传递 APC。 如果内核模式 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 的调用方必须以小于或等于 DISPATCH_LEVEL 的 IRQL 运行。 通常，调用方必须在 IRQL PASSIVE_LEVEL和非比特线程上下文中运行。 在 IRQL DISPATCH_LEVEL 运行时的调用仅在调用方指定 超时 参数为零时有效。 也就是说，驱动程序不得等待 IRQL 等于 DISPATCH_LEVEL 的非零间隔。
超时间隔相对于系统时钟进行测量，超时测量的准确性受系统时钟粒度的限制。 有关详细信息，请参阅 计时器准确性。
如果对 ZwWaitForSingleObject 函数的调用在用户模式下发生，则应使用名称“NtWaitForSingleObject”而不是“ZwWaitForSingleObject”。
对于来自内核模式驱动程序的调用，Windows Native System Services 例程的 NtXxx 和 ZwXxx 版本在处理和解释输入参数的方式上的行为可能有所不同。 有关例程的 NtXxx 和 ZwXxx 版本之间的关系的详细信息，请参阅 使用本机系统服务例程的 Nt 和 Zw 版本。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | Windows XP |
| 目标平台 | 通用 |
| 标头 | ntifs.h (包括 Ntifs.h、FltKernel.h) |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| DDI 符合性规则 | HwStorPortProhibitedDDI (storport) ， SpNoWait (storport) |