FltPerformAsynchronousIo 函式 (fltkernel.h)

發行項
02/29/2024

迷你篩選驅動程式會呼叫 FltPerformAsynchronousIo 來起始異步 I/O 作業。

語法

NTSTATUS FLTAPI FltPerformAsynchronousIo(
  [in, out] PFLT_CALLBACK_DATA               CallbackData,
  [in]      PFLT_COMPLETED_ASYNC_IO_CALLBACK CallbackRoutine,
  [in]      PVOID                            CallbackContext
);

參數

[in, out] CallbackData

回呼數據的指標 (FLT_CALLBACK_DATA先前呼叫 FltAllocateCallbackData 所配置的) 結構。這個參數是必要的，而且不能是 NULL。呼叫端負責呼叫 FltFreeCallbackData 不再需要此結構時釋放此結構。

[in] CallbackRoutine

完成 I/O 作業時所呼叫之PFLT_COMPLETED_ASYNC_IO_CALLBACK型別回呼例程的指標。注意：篩選管理員會在呼叫後置回呼之後呼叫此例程， (PFLT_POST_OPERATION_CALLBACK) 實例的任何迷你篩選器驅動程式例程，其實例會附加在 Instance 參數中指定的 起始實例下方 (至 FltAllocateCallbackData) 。這個參數是必要的，而且不能是 NULL。篩選管理員一律會呼叫此例程，即使 FltPerformAsynchronousIo 失敗也一樣。

[in] CallbackContext

要傳遞至 CallbackRoutine 的內容指標這個參數是選擇性的，而且可以是 NULL。

傳回值

FltPerformAsynchronousIo 會傳回STATUS_SUCCESS，指出文件系統已完成 I/O 作業，而 CallbackRoutine 所指向的回呼例程已經呼叫。否則，它會傳回適當的NTSTATUS值，例如下列其中一個：

傳回碼	Description
STATUS_FLT_INVALID_ASYNCHRONOUS_REQUEST	IRP_MJ_CREATE要求無法以異步方式執行。這是錯誤碼。
STATUS_PENDING	STATUS_PENDING傳回的作業。篩選管理員會在 I/O 作業完成時呼叫 CallbackRoutine 所指向的回呼例程。此程式代碼只會指出已起始作業。
STATUS_FLT_IO_COMPLETE	作業已完成，其實例附加在起始實例下方的迷你篩選器驅動程序的預先操作回呼例程。

備註

迷你篩選驅動程式會呼叫 FltPerformAsynchronousIo ，在呼叫 FltAllocateCallbackData 之後起始異步 I/O 作業，以配置作業的回呼數據結構。

FltPerformAsynchronousIo 只會將 I/O 作業傳送至附加在 Instance 參數中所指定起始實例下方的迷你篩選驅動程序實例， (FltAllocateCallbackData) ，以及文件系統。附加在指定實例上方的迷你篩選驅動程式不會收到I/O 作業。

迷你篩選驅動程式只能起始 IRP 型 I/O 作業。它們無法起始快速 I/O 或文件系統篩選 (FSFilter) 回呼作業。

Minifilter 驅動程序應該只針對無法使用下列例程的異步 I/O 作業使用 FltPerformAsynchronousIo ：

IRP_MJ_CREATE要求無法以異步方式執行。

回呼數據 (FLT_CALLBACK_DATA) 結構可以在回呼例程呼叫回呼例程之後隨時釋放或重複使用。呼叫端可以藉由呼叫 FltFreeCallbackData 來釋放回呼數據結構，或藉由呼叫 FltReuseCallbackData 來準備它以供重複使用。

注意

STATUS_SUCCESS和STATUS_FLT_IO_COMPLETE表示 I/O 作業已完成，但不表示 I/O 作業的最終狀態。若要判斷基礎迷你篩選驅動程式、篩選驅動程式和文件系統所傳回的實際作業狀態，CallbackRoutine 應該檢查 CallbackRoutine 回呼數據結構在 CallbackRoutine 的 CallbackContext 參數中所收到的 IoStatus 成員。

因為 Filter Manager 一律會呼叫 CallbackRoutine 指向的回呼例程，即使 FltPerformAsynchronousIo 失敗，迷你篩選驅動程式也可以在回呼例程中直接執行釋放或重複使用作業。

FltPerformAsynchronousIo 的呼叫端可以在 IRQL <= APC_LEVEL如果作業之 IRP_PAGING_IO FLT_IO_PARAMETER_BLOCK結構的 IrpFlags 成員中設定APC_LEVEL。 (此旗標僅適用於 IRP_MJ_READ、IRP_MJ_WRITE、IRP_MJ_QUERY_INFORMATION 和 IRP_MJ_SET_INFORMATION operations.) 否則，呼叫端必須在 IRQL PASSIVE_LEVEL上執行。