FltCancellableWaitForMultipleObjects 函式（fltkernel.h）

發行項
12/21/2024

FltCancellableWaitForMultipleObjects 會在一或多個發送器物件上執行可取消的等候作業（可以終止的等候）。

語法

NTSTATUS FLTAPI FltCancellableWaitForMultipleObjects(
  [in]           ULONG              Count,
  [in]           PVOID []           ObjectArray,
  [in]           WAIT_TYPE          WaitType,
  [in, optional] PLARGE_INTEGER     Timeout,
  [in, optional] PKWAIT_BLOCK       WaitBlockArray,
  [in]           PFLT_CALLBACK_DATA CallbackData
);

參數

[in] Count

要等候的物件數目。

[in] ObjectArray

發送器物件的指標陣列指標（事件、Mutex、信號、線程和定時器），呼叫端會提供記憶體。

[in] WaitType

列舉，其值為 WaitAll，表示所有指定的物件都必須在滿足等候之前達到訊號狀態：或 WaitAny，這表示任何一個對象必須在滿足等候之前達到訊號狀態。

[in, optional] Timeout

選擇性逾時值的指標。此參數會指定等候完成的 100 奈秒單位中的絕對或相對時間。

如果 Timeout 指向零值（也就是 *Timeout == 0），則例程會傳回而不等候。如果呼叫端提供 NULL 指標（也就是 Timeout == NULL），則例程會無限期等候，直到任何或所有發送器物件都設定為訊號狀態為止。

正值會指定絕對時間，相對於 1601 年 1 月 1 日。負值會指定相對於目前時間的間隔。絕對到期時間會追蹤系統時間中的任何變更;相對到期時間不會受到系統時間變更的影響。

如果指定逾時，如果指定的間隔到期時，未符合任何指定的等候條件，則會自動滿足等候。

零的逾時值（也就是 *Timeout == 0）可讓您測試一組等候條件，並在可以立即滿足等候時有條件地執行任何其他動作，就像取得 Mutex 一樣。

[in, optional] WaitBlockArray

如果 Count <= THREAD_WAIT_OBJECTS，WaitBlockArray 可以是 NULL。否則，此參數必須指向 sizeof(KWAIT_BLOCK) * Count 位元組的記憶體緩衝區。例程會在執行等候作業時使用此緩衝區進行記錄保留。

[in] CallbackData

FLT_CALLBACK_DATA 結構的指標，代表使用者所發出的 I/O 作業，而且可由使用者取消。這個參數是選擇性的，而且可以是 NULL。呼叫端必須確保 I/O 作業在此例程的持續時間內保持有效，而且 I/O 不得有取消例程集（例如，FltSetCancelCompletion 函式不得在 I/O 作業上呼叫）。請注意，呼叫端必須保留 CallbackData，因為它無法傳遞至較低層級的驅動程式。

傳回值

FltCancellableWaitForMultipleObjects 可以傳回下列其中一個值：

傳回碼	描述
STATUS_SUCCESS	WaitType 參數和 ObjectArray 陣列中的所有發送器物件都已設定為訊號狀態 WaitAll 呼叫端。
STATUS_TIMEOUT	在符合指定的等候條件集之前發生逾時。當指定的等候條件集無法立即符合且 Timeout 設定為零時，也可以傳回這個值。
透過STATUS_WAIT_63 STATUS_WAIT_0	WaitType 指定 WaitAny 呼叫端，且 ObjectArray 陣列中的其中一個發送器物件已設定為訊號狀態。傳回值的下六位會編碼滿足等候之物件之以零起始的索引。
透過STATUS_ABANDONED_WAIT_63 STATUS_ABANDONED_WAIT_0	呼叫端嘗試等候已放棄的 Mutex。傳回值的下六位會編碼 ObjectArray 陣列中 mutex 以零起始的索引。
STATUS_CANCELLED	等候因 I/O 作業上的擱置取消要求而中斷。請注意，只有在對應至 IRP 作業 CallbackData 傳遞至 FltCancellableWaitForMultipleObjects，且 I/O 已由 FltCancelIo等例程取消時，才會傳回此值。
STATUS_THREAD_IS_TERMINATING	等候已中斷，因為應用程式或使用者已終止線程。

傳回值只會指出等候的狀態。

請注意，NT_SUCCESS巨集會針對所有其他狀態值傳回STATUS_CANCELLED和STATUS_THREAD_IS_TERMINATING狀態值 FALSE FALSE （“success”）。

言論

FltCancellableWaitForMultipleObjects 會在發送器物件上執行可取消的等候作業。如果使用者或應用程式終止線程，或與線程相關聯的 I/O 作業已由如 FltCancelIo等例程取消，則會取消等候。

此例程的設計訴求是支援I/O 完成/取消指導方針。這些指導方針的目標是允許使用者快速終止應用程式。這反過來又要求應用程式能夠快速終止執行 I/O 的線程，以及任何目前的 I/O 作業。此例程提供一種方式，讓使用者線程封鎖核心中的 I/O 完成、發送器物件或同步處理變數，以允許立即取消等候。如果線程由使用者或應用程式終止，此例程也允許線程的等候終止。

例如，重新導向器可能需要建立一或多個次要 I/O 作業，才能處理使用者模式 I/O，並同步等候次要要求完成。這樣做的其中一種方法是設定事件，該事件將由次要 I/O 作業的完成例程發出訊號，然後等候事件發出訊號。然後，若要執行可取消的等候作業，FltCancellableWaitForMultipleObjects 會呼叫傳入與次要 I/O 作業相關聯的事件，以及原始使用者模式 I/O 作業。如果發生擱置終止事件，或取消原始使用者模式 I/O 作業，線程等候事件發出訊號會取消。

請注意，終止等候不會自動取消呼叫端所發出的任何 I/O 作業，必須由呼叫端分開處理。

每個線程物件都有一個內建的等候區塊陣列，可用來同時等候數個物件。可能的話，您應該在等候多重作業中使用內建的等候區塊陣列，因為不需要配置額外的等候區塊記憶體，稍後再解除分配。不過，如果您必須同時等候的物件數目大於內建等候區塊的數目，請使用 WaitBlockArray 參數來指定等候作業中要使用的替代等候區塊集。驅動程式只需要為 waitBlockArray 配置足夠大的記憶體緩衝區。您不需要初始化緩衝區，驅動程式可以將它視為不透明結構。一旦例程傳回，您就可以釋放緩衝區。

如果 Count 大於 MAXIMUM_WAIT_OBJECTS，或如果 WaitBlockArray 為 NULL 且 Count 大於 THREAD_WAIT_OBJECTS，則系統會發出錯誤檢查0xC：MAXIMUM_WAIT_OBJECTS_EXCEEDED。

當傳遞至 FltCancellableWaitForMultipleObjects 的 ObjectArray 參數中的一或多個元素參考 mutex 時，就會特別考慮。如果等候的發送器對像是 mutex，則 APC 傳遞與等候期間所有其他發送器物件相同。不過，一旦 FltCancellableWaitForMultipleObjects 會傳回STATUS_SUCCESS，而線程實際上會保存 mutex，只會傳遞特殊的內核模式 APC。已停用核心模式和使用者模式的所有其他 APC 傳遞。在釋放 mutex 之前，對 APC 傳遞的限制會持續存在。

Mutex 只能以遞歸方式取得MINLONG時間。如果超過此限制，例程會引發STATUS_MUTANT_LIMIT_EXCEEDED例外狀況。

FltCancellableWaitForMultipleObjects 例程必須在 IRQL PASSIVE_LEVEL呼叫，如果 CallbackData 參數代表有效的篩選管理員 IRP。否則，可以在 IRQL 中呼叫例程小於或等於APC_LEVEL。呼叫端可以視需要呼叫 KeEnterCriticalRegion 或 FsRtlEnterFileSystem 例程來停用一般核心 APC。不過，不得停用特殊核心 APC。

FltCancellableWaitForMultipleObjects 會在偵錯組建上判斷提示，如果 CallbackData 代表篩選管理員 IRP 作業，但 CallbackData 結構中的 IRP 為 NULL。

要求

要求	價值
最低支援的用戶端	Windows Vista
目標平臺	普遍
標頭	fltkernel.h （include Ntifs.h， Fltkernel.h）
連結庫	Fltmgr.lib
IRQL	請參閱一節。