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 的狀態，則會自動滿足等候。 如果指定了明確的 Timeout 值為零，則如果無法立即滿足等候，則不會發生等候。 Timeout 值為零，可測試一組等候條件，並在可以立即滿足等候時的任何副作用的條件效能，如同取得 mutex 一樣。 您也可以將等候指定為可警示。
Alertable 參數會指定線程是否可以發出警示，以及其等候狀態因此中止。 如果此參數的值是 FALSE，則線程無法發出警示。 此規則的唯一例外是終止線程的例外狀況。 在某些情況下，終止線程會在結束時發出警示。 例如，當使用者以 CTRL+C 終止時，線程會自動發出警示。
如果 Alertable的值為 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 進行中，而線程不在關鍵區段中。
如果傳遞至 ZwWaitForSingleObject 的句柄 是指 mutex，則 APC 傳遞與等候期間所有其他發送器物件相同。 不過，一旦 ZwWaitForSingleObject 會傳回 STATUS_SUCCESS，而線程實際上會保存 mutex，只會傳遞特殊的內核模式 APC。 已停用核心模式和使用者模式的所有其他 APC 傳遞。 在釋放 mutex 之前，對 APC 傳遞的限制會持續存在。
當
如果使用者將 Alertable 參數設為 FALSE，則所有長期等候都可以中止。
如需詳細資訊，請參閱 等候線程是否接收警示和 APC？
ZwWaitForSingleObject 的呼叫端必須在 IRQL 中執行，小於或等於DISPATCH_LEVEL。 呼叫端通常必須在 IRQL PASSIVE_LEVEL 和非bitrary 線程內容中執行。 在 IRQL DISPATCH_LEVEL 執行時呼叫只有在呼叫端指定零的 Timeout 參數時才有效。 也就是說，驅動程式不得等候 IRQL 等於DISPATCH_LEVEL的非零間隔。
逾時間隔是相對於系統時鐘來測量，而逾時測量的精確度會受限於系統時鐘的粒度。 如需詳細資訊，請參閱 定時器精確度。
如果在使用者模式中呼叫 ZwWaitForSingleObject 函式，您應該使用名稱 “NtWaitForSingleObject”，而不是 “ZwWaitForSingleObject”。
對於內核模式驅動程式的呼叫，NtXxx 和 ZwXxx 版本的 Windows 原生系統服務例程，在處理和解譯輸入參數的方式上可能會有不同的行為。 如需 nt NtXxx 與 ZwXxx 例程之間關聯性的詳細資訊，請參閱 使用 Nt 和 Zw 版本的原生系統服務例程。
要求
| 要求 | 價值 |
|---|---|
| 最低支援的用戶端 | Windows XP |
| 目標平臺 | 普遍 |
| 標頭 | ntifs.h （include Ntifs.h， FltKernel.h） |
| 連結庫 | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| DDI 合規性規則 | HwStorPortProhibitedDIs（storport），SpNoWait（storport） |