FltReadFileEx 函式 (fltkernel.h)
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 |