ZwWaitForSingleObject 函式 (ntifs.h)

發行項
02/27/2024

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 可以傳回下列其中一個可能的狀態代碼：

傳回碼	Description
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 值為零，則如果無法立即滿足等候，則不會發生等候。 [逾時] 值為零允許測試一組等候條件，如果可以立即滿足等候條件式效能，則為任何副作用的條件式效能，如同取得 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，則系統會提供下列三個條件保存： (1) IRQL 小於APC_LEVEL， (2) 沒有進行中的核心 APC，而且線程未處於關鍵區段中 (3) 。

如果傳遞至 ZwWaitForSingleObject 的句柄是指 mutex，APC 傳遞與等候期間所有其他發送器物件相同。不過，一旦 ZwWaitForSingleObject 傳回STATUS_SUCCESS，且線程實際上會保存 mutex，只會傳遞特殊的核心模式 APC。已停用核心模式和使用者模式的所有其他 APC 傳遞。對 APC 傳遞的限制會持續存在，直到 Mutex 釋放為止。

當 Alertable 參數為 TRUE 時，檢查 ZwWaitForSingleObject 的傳回值特別重要，因為 ZwWaitForSingleObject 可能會提早傳回狀態為 STATUS_USER_APC 或 STATUS_ALERTED。

如果 Alertable 參數設定為 FALSE，則使用者可以中止所有長期等候。

如需詳細資訊，請參閱等候線程是否接收警示和APC？

ZwWaitForSingleObject 的呼叫端必須在 IRQL 小於或等於DISPATCH_LEVEL執行。通常，呼叫端必須在 IRQL PASSIVE_LEVEL和非bitrary 線程內容中執行。在 IRQL 執行時呼叫DISPATCH_LEVEL只有在呼叫端指定零的 Timeout 參數時才有效。也就是說，驅動程式不得等候 IRQL 等於DISPATCH_LEVEL的非零間隔。

逾時間隔是相對於系統時鐘來測量，而逾時測量的精確度會受限於系統時鐘的數據粒度。如需詳細資訊，請參閱定時器精確度。

如果在使用者模式中呼叫 ZwWaitForSingleObject 函式，您應該使用名稱 “NtWaitForSingleObject”，而不是 “ZwWaitForSingleObject”。

對於核心模式驅動程式的呼叫，Windows 原生系統服務例程的 NtXxx 和 ZwXxx 版本在處理和解譯輸入參數的方式可能會有不同的行為。如需例程 NtXxx 和 ZwXxx 版本之間的關聯性詳細資訊，請參閱使用 Nt 和 Zw 版本的原生系統服務例程。

規格需求

需求	值
最低支援的用戶端	Windows XP
目標平台	Universal
標頭	ntifs.h (包括 Ntifs.h、FltKernel.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 合規性規則	HwStorPortProhibitedDIS (storport) 、 SpNoWait (storport)