FltCancellableWaitForSingleObject 函式 (fltkernel.h)

發行項
03/01/2024

FltCancellableWaitForSingleObject 例程會執行可取消的等候作業， (可以在發送器對象上終止的等候) 。

語法

NTSTATUS FLTAPI FltCancellableWaitForSingleObject(
  [in]           PVOID              Object,
  [in, optional] PLARGE_INTEGER     Timeout,
  [in, optional] PFLT_CALLBACK_DATA CallbackData
);

參數

[in] Object

初始化發送器物件的指標， (事件、mutex、旗號、線程或定時器) ，呼叫端會為其提供記憶體。

[in, optional] Timeout

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

如果 Timeout 指向零值 (也就是 *Timeout == 0) ，則例程會傳回而不等候。如果呼叫端 (提供 NULL 指標，也就是 Timeout == NULL) ，則例程會無限期等候，直到物件設定為訊號狀態為止。

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

如果指定 Timeout ，則當指定的間隔到期時，如果物件未設定為訊號狀態，就會自動滿足等候。

零 (逾時值，也就是 *Timeout == 0) 可讓您測試一組等候條件，並在等候可立即滿足時有條件地執行任何其他動作，如同取得 mutex 一樣。

[in, optional] CallbackData

FLT_CALLBACK_DATA 結構的指標，表示使用者所發出的 I/O 作業，而且可由使用者取消。呼叫端必須確定 I/O 作業在這段期間會維持有效狀態，而且 I/O 必須沒有取消例程集 (例如 ，FltSetCancelCompletion 函式不得在 I/O 作業上呼叫) 。請注意，呼叫端必須保存 CallbackData;它無法傳遞至較低層級的驅動程式。

傳回值

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

傳回碼	Description
STATUS_SUCCESS	Object 參數指定的發送器對象已設定為已發出訊號的狀態。
STATUS_TIMEOUT	物件設定為訊號狀態之前發生逾時。當無法立即符合指定的等候條件且 Timeout 設定為零時，也可以傳回此值。
STATUS_ABANDONED_WAIT_0	呼叫端嘗試等候已放棄的 Mutex。
STATUS_CANCELLED	等候因 I/O 作業上的擱置取消要求而中斷。請注意，只有在 CallbackData 對應至 IRP 型作業時，才會傳回此值給 FltCancellableWaitForSingleObject ，而 I/O 是由 FltCancelIo 等例程取消。
STATUS_THREAD_IS_TERMINATING	因為應用程式或使用者已終止線程，所以等候已中斷。

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

請注意，NT_SUCCESS宏會針對STATUS_CANCELLED和STATUS_THREAD_IS_TERMINATING狀態值傳回 FALSE (「失敗」) ，並針對所有其他狀態值傳回 TRUE (「成功」) 。

備註

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

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

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

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

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

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

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

如果 CallbackData 代表 Filter Manager IRP 作業，FltCancellableWaitForSingleObject 例程將會判斷提示偵錯組建，但 CallbackData 結構中的 IRP 為 NULL。

規格需求

需求	值
最低支援的用戶端	Windows Vista
目標平台	Universal
標頭	fltkernel.h (包括 Fltkernel.h、Ntifs.h)
程式庫	Fltmgr.lib
Dll	Fltmgr.sys
IRQL	請參閱一節。