KeWaitForSingleObject 函式 （wdm.h）
KeWaitForSingleObject 例程會將目前的線程置於等候狀態，直到指定的發送器物件設定為訊號狀態，或（選擇性地）直到等候逾時為止。
語法
NTSTATUS
KeWaitForSingleObject (
PVOID Object,
KWAIT_REASON WaitReason,
KPROCESSOR_MODE WaitMode,
BOOLEAN Alertable,
PLARGE_INTEGER Timeout
);
參數
[in] Object
初始化發送器物件的指標（事件、mutex、號誌、線程或定時器），呼叫端會提供記憶體。 發送器對象必須位於非分頁的系統記憶體中。 如需詳細資訊，請參閱。
[in] WaitReason
指定等候的原因。 驅動程式應該將此值設定為 Executive，除非它代表使用者執行工作，而且是在使用者線程的內容中執行，在此情況下，它應該將此值設定為 UserRequest。
[in] WaitMode
指定呼叫端在 KernelMode 或 UserMode中等候。 最低層級和中繼驅動程式應該指定 KernelMode。 如果指定的 物件 為 mutex，呼叫端必須指定 KernelMode。
[in] Alertable
指定布爾值 ，如果等候可發出警示，則為 TRUE，否則為 FALSE 。
[in, optional] Timeout
指定以 100 奈秒為單位的絕對或相對時間逾時值的指標，等候完成。
正值會指定絕對時間，相對於 1601 年 1 月 1 日。 負值會指定相對於目前時間的間隔。 絕對到期時間會追蹤系統時間中的任何變更;相對到期時間不會受到系統時間變更的影響。
如果 逾時 = 0，則例程會傳回而不等候。 如果呼叫端提供 NULL 指標，則例程會無限期地等候，直到發送器物件設定為訊號狀態為止。 如需詳細資訊，請參閱下列一節。
傳回值
KeWaitForSingleObject 可以傳回下列其中一項。
NT_SUCCESS巨集會將所有這些狀態值辨識為「成功」值。
| 傳回碼 | 描述 |
|---|---|
| STATUS_SUCCESS | Object 參數指定的發送器物件符合等候。 |
| STATUS_ALERTED | 等候中斷，以將警示傳遞至呼叫端線程。 |
| STATUS_USER_APC | 等候中斷，以將使用者異步過程調用 （APC） 傳遞給呼叫線程。 |
| STATUS_TIMEOUT | 物件設定為訊號狀態之前發生逾時。 當無法立即符合指定的等候條件集，且 逾時 設為零時，就可以傳回此值。 |
言論
檢查指定之 物件 的目前狀態，以判斷是否可以立即滿足等候。 如果是，則會對對對象執行必要的副作用。 否則，目前的線程會處於等候狀態，並選取新的線程以在目前的處理器上執行。
Alertable 參數會決定線程何時可以發出警示，並因此中止其等候狀態。 如需詳細資訊，請參閱 等候和 APC。
當傳遞 至 keWaitForSingleObject 的 Object 參數為 mutex 時，會特別考慮。 如果等候的發送器對像是 mutex，則 APC 傳遞與等候期間所有其他發送器物件相同。 不過，KeWaitForSingleObject 會傳回 STATUS_SUCCESS，而線程實際上會保留 mutex，只會傳遞特殊的內核模式 APC。 已停用核心模式和使用者模式的所有其他 APC 傳遞。 在釋放 mutex 之前，對 APC 傳遞的限制會持續存在。
Object 參數所指向的發送器對象必須位於非分頁的系統記憶體中。
如果 WaitMode 參數 UserMode，則可以在等候期間交換核心堆棧。 因此，呼叫者絕對不能在使用 userMode 自變數呼叫 KeWaitForSingleObject 時，嘗試在堆棧上傳遞參數。 如果您在堆疊上設定事件，則必須將 waitMode 參數設定為 KernelMode。
當 WaitMode 參數 UserMode或時，檢查 keWaitForSingleObject 的傳回 值特別重要 警示為 TRUE，因為 KeWaitForSingleObject 可能會在STATUS_USER_APC或STATUS_ALERTED狀態早期傳回。
用戶可中止的所有長期等候，都應該 UserMode 等候，可警示 應設定為 FALSE 。
可能的話，Alertable 應設定為 FALSE，且 WaitMode 應設定為 KernelMode，以減少驅動程式的複雜度。 此作業的主要例外狀況是等候是長期等候的時間。
如果 NULL 指標提供給 逾時，則呼叫線程會維持等候狀態，直到發出 物件 訊號為止。
零的逾時值允許測試一組等候條件，並在可以立即滿足等候時的任何副作用的條件效能，如同取得 Mutex 一樣。
逾時間隔是相對於系統時鐘來測量，而作系統可以偵測逾時間隔結束的正確性會受限於系統時鐘的粒度。 如需詳細資訊，請參閱 定時器精確度。
Mutex 只能以遞歸方式取得MINLONG時間。 如果超過此限制，例程會引發STATUS_MUTANT_LIMIT_EXCEEDED例外狀況。
KeWaitForSingleObject 的呼叫端必須在 IRQL <= DISPATCH_LEVEL 執行。 不過，如果 Timeout = NULL 或 Timeout ！= 0，則呼叫端必須在 IRQL <= APC_LEVEL 和非bitrary 線程內容中執行。 如果 逾時 ！= NULL，且 逾時 = 0，呼叫端必須在 IRQL <= DISPATCH_LEVEL執行。
KeWaitForMutexObject 是轉換成 KeWaitForSingleObject的巨集，可以改用。
為了提升效能，請使用快速 Mutex 或受防護的 Mutex。 如需詳細資訊，請參閱 Mutex 物件的替代項目。
如需 mutex 物件的詳細資訊，請參閱 Mutex Objects。