FltReadFileEx 函式 (fltkernel.h)

發行項
03/08/2024

FltReadFileEx 會從開啟的檔案、數據流或裝置讀取數據。此函式會擴充 FltReadFile ，以允許選擇性地使用 MDL 來讀取數據，而不是對應的緩衝區位址。

語法

NTSTATUS FLTAPI FltReadFileEx(
  [in]            PFLT_INSTANCE                    InitiatingInstance,
  [in]            PFILE_OBJECT                     FileObject,
  [in, optional]  PLARGE_INTEGER                   ByteOffset,
  [in]            ULONG                            Length,
  [out]           PVOID                            Buffer,
  [in]            FLT_IO_OPERATION_FLAGS           Flags,
  [out, optional] PULONG                           BytesRead,
  [in, optional]  PFLT_COMPLETED_ASYNC_IO_CALLBACK CallbackRoutine,
  [in, optional]  PVOID                            CallbackContext,
  [in, optional]  PULONG                           Key,
  [in, optional]  PMDL                             Mdl
);

參數

[in] InitiatingInstance

要傳送作業之迷你篩選驅動程序實例的不透明實例指標。實例必須附加至檔案所在的磁碟區。這個參數是必要的，而且不能是 NULL。

[in] FileObject

要讀取數據的檔案 FILE_OBJECT 指標。這個檔案物件目前必須開啟。當檔案物件尚未開啟或不再開啟 (時呼叫 FltReadFileEx ，例如，在預先建立或清除後回呼例程中，) 會導致系統在核取的組建上判斷提示。這個參數是必要的，而且不能是 NULL。

[in, optional] ByteOffset

呼叫端配置的變數指標，指定讀取作業開始之檔案內的起始位元組位移。

如果指定 ByteOffset ，則不論檔案物件的 CurrentByteOffset 欄位目前值為何，都會在該位移執行 I/O。

如果檔案已針對同步 I/O 開啟， (FO_SYNCHRONOUS_IO 是在檔案物件的 Flags 字段中設定) ，則呼叫端可以將 ByteOffset-LowPart 設定為 FILE_USE_FILE_POINTER_POSITION，並將 ByteOffset-HighPart>> 設定為 -1，讓 I/O 在檔案物件的 CurrentByteOffset 字段中執行。
如果檔案未針對同步 I/O 開啟，則使用 FILE_USE_FILE_POINTER_POSITION 是錯誤。

如果未指定 ByteOffset ：

如果檔案未針對同步 I/O 開啟，即為錯誤。
否則，I/O 會在檔案物件的 CurrentByteOffset 上執行。

如果檔案對象已針對同步 I/O 開啟，除非呼叫端通過FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET旗標，否則 CurrentByteOffset 字段會更新。

注意：文件系統在此案例中仍會更新 CurrentByteOffset 。篩選管理員會先儲存 CurrentByteOffset 值，再將 I/O 向下傳送至堆棧，並在 I/O 傳回時還原它。從 FltReadFileEx 呼叫端的觀點來看，) CurrrentByteOffset 不會更新 (和篩選。但呼叫端下方的篩選會在其讀取/寫入后回呼中看到更新的 CurrentByteOffset 值。

如果未針對同步 I/O 開啟檔案物件，則不論 ByteOffset 參數的狀態為何，CurrentByteOffset 字段都不會更新。

[in] Length

Buffer 參數指向之緩衝區的大小，以位元組為單位。

[out] Buffer

呼叫端配置的緩衝區指標，可接收從檔案讀取的數據。如果在 Mdl 中提供 MDL， 緩衝區 必須是 NULL。

[in] Flags

旗標的位掩碼，指定要執行的讀取作業類型。

旗標	意義
FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET	Minifilter 驅動程式可以設定此旗標，以指定 FltReadFile 不應該更新檔案物件的 CurrentByteOffset 字段。
FLTFL_IO_OPERATION_NON_CACHED	Minifilter 驅動程式可以設定此旗標來指定非快取讀取，即使檔案物件未以FILE_NO_INTERMEDIATE_BUFFERING開啟也一樣。
FLTFL_IO_OPERATION_PAGING	迷你篩選驅動程式可以設定此旗標來指定分頁讀取。
FLTFL_IO_OPERATION_SYNCHRONOUS_PAGING	迷你篩選驅動程式可以設定此旗標來指定同步分頁 I/O 讀取。設定此旗標的迷你篩選驅動程式也必須設定FLTFL_IO_OPERATION_PAGING旗標。從 Windows Vista 開始提供。

[out, optional] BytesRead

呼叫端配置的變數指標，可接收從檔案讀取的位元元組數目。如果 CallbackRoutine 不是 NULL，則會忽略此參數。否則，此參數是選擇性的，而且可以是 NULL。

[in, optional] CallbackRoutine

讀取作業完成時要呼叫 之PFLT_COMPLETED_ASYNC_IO_CALLBACK型別回呼例程的指標。此參數是選擇性的，可以是 NULL。

[in, optional] CallbackContext

如果有，要傳遞至 CallbackRoutine 的內容指標。此參數是選擇性的，可以是 NULL。如果 CallbackRoutine 為 NULL，則會忽略此參數。

[in, optional] Key

與位元組範圍鎖定相關聯的選擇性索引鍵。

[in, optional] Mdl

選擇性 MDL，描述讀取資料的記憶體。如果在 Buffer 中提供緩衝區， 則 Mdl 必須是 NULL。

傳回值

FltReadFileEx 會傳回文件系統所傳回的NTSTATUS值。

備註

迷你篩選驅動程式會呼叫 FltReadFileEx ，從開啟的檔案讀取數據。

FltReadFileEx 會建立讀取要求，並將其傳送至附加在起始實例下方的迷你篩選驅動程序實例，以及文件系統。指定的實例及其上方附加的實例不會收到讀取要求。

如果下列任一項為 true，FltReadFileEx 會執行非快取 I/O：

呼叫端會在 Flags 參數中設定FLTFL_IO_OPERATION_NON_CACHED旗標。
檔案物件已針對非快取的 I/O 開啟。這通常是藉由在上述對 FltCreateFile、FltCreateFileEx 或 ZwCreateFile 的呼叫中指定 FILE_NO_INTERMEDIATE_BUFFERING CreateOptions 旗標來完成。

非快取 I/O 會對傳遞至 FltReadFileEx 的參數值施加下列限制：

Buffer 參數所指向的緩衝區，必須根據基礎儲存裝置的對齊需求進行對齊。若要配置這類對齊的緩衝區，請呼叫 FltAllocatePoolAlignedWithTag。
ByteOffset 參數指向的位元移必須是磁碟區扇區大小的非負數倍數。
Length 參數中指定的長度必須是磁碟區扇區大小的非負數倍數。

如果嘗試在檔案結尾之外讀取， FltReadFileEx 會傳回錯誤。

如果 CallbackRoutine 參數的值不是 NULL，則會以異步方式執行讀取作業。

如果 CallbackRoutine 參數的值是 NULL，則會同步執行讀取作業。也就是說， FltReadFileEx 會等到讀取作業完成再傳回為止。即使 FileObject 指向的檔案對象已針對異步 I/O 開啟，也是如此。

如果多個線程針對相同的檔案物件呼叫 FltReadFileEx ，而且檔案對象已針對同步 I/O 開啟，篩選管理員不會嘗試在檔案上串行化 I/O。在此方面， FltReadFileEx 與 ZwReadFile 不同。

當迷你篩選器已有 MDL 可用時， Mdl 參數會提供為方便。直接使用 MDL，而且可以避免對應 Buffer 位址的其他步驟。

規格需求

需求	值
最低支援的用戶端	Windows 8
目標平台	Universal
標頭	fltkernel.h (包含 Fltkernel.h)
程式庫	FltMgr.lib
Dll	Fltmgr.sys
IRQL	PASSIVE_LEVEL