FltWriteFileEx 函式 (fltkernel.h)
FltWriteFileEx 可用來將數據寫入開啟的檔案、數據流或裝置。 此函式會擴充 FltWriteFile ，以允許選擇性地使用 MDL 來寫入數據，而不是對應的緩衝區位址。
語法
NTSTATUS FLTAPI FltWriteFileEx(
[in] PFLT_INSTANCE InitiatingInstance,
[in] PFILE_OBJECT FileObject,
[in, optional] PLARGE_INTEGER ByteOffset,
[in] ULONG Length,
[in] PVOID Buffer,
[in] FLT_IO_OPERATION_FLAGS Flags,
[out, optional] PULONG BytesWritten,
[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 指標。 這個檔案物件目前必須開啟。 當檔案物件尚未開啟或不再開啟 (時呼叫 FltWriteFileEx ，例如，在預先建立或清除後回呼例程中，) 會導致系統在核取的組建上判斷提示。 這個參數是必要的，而且不能是 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-LowPart> 設定為 FILE_WRITE_TO_END_OF_FILE，並將 ByteOffset-HighPart> 設定為 -1，以在檔案結尾開始寫入 (，也就是執行附加寫入) 。
如果未指定 ByteOffset ：
- 如果檔案未針對同步 I/O 開啟，就會發生錯誤。
- 否則，I/O 會在檔案物件的 CurrentByteOffset 上執行。
如果檔案對象已針對同步 I/O 開啟，除非呼叫端通過FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET旗標，否則 CurrentByteOffset 字段會更新。
- 注意：文件系統在此案例中仍會更新 CurrentByteOffset 。 篩選管理員會先儲存 CurrentByteOffset 值，再將 I/O 向下傳送至堆棧，並在 I/O 傳回時還原它。 從 FltWriteFileEx 的呼叫者的觀點來看， (和在 CurrrentByteOffset) 較高高度的篩選條件不會更新。 但呼叫端下方的篩選會在其讀取/寫入后回呼中看到更新的 CurrentByteOffset 值。
如果未針對同步 I/O 開啟檔案物件，則不論 ByteOffset 參數的狀態為何，CurrentByteOffset 字段都不會更新。
如果 FileObject 指向的檔案物件已針對異步 I/O 開啟，則這個參數是必要的，而且不能是 NULL。
FltWriteFileEx 不支援 FILE_WRITE_TO_END_OF_FILE 旗標。
[in] Length
Buffer 參數指向之緩衝區的大小，以位元組為單位。 如果在 Mdl 中提供 MDL，則 Length 是 MDL 所描述的數據大小。
[in] Buffer
緩衝區的指標，其中包含要寫入檔案的數據。 如果開啟非快取 I/O 的檔案，則必須根據基礎儲存裝置的對齊需求來對齊此緩衝區。 Minifilter 驅動程式可以呼叫 FltAllocatePoolAlignedWithTag 來配置這類對齊的緩衝區。
如果在 Mdl 中提供 MDL， 緩衝區 必須是 NULL。
[in] Flags
旗標的位掩碼，指定要執行的寫入作業類型。
| 旗標 | 意義 |
|---|---|
| FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET | Minifilter 驅動程式可以設定此旗標，以指定 FltWriteFileEx 不會更新檔案物件的 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] BytesWritten
呼叫端配置的變數指標，可接收寫入檔案的位元元組數目。 如果 CallbackRoutine 不是 NULL，則會忽略此參數。 否則，此參數是選擇性的，而且可以是 NULL。
[in, optional] CallbackRoutine
寫入作業完成時要呼叫 之PFLT_COMPLETED_ASYNC_IO_CALLBACK型別回呼例程的指標。 此參數是選擇性的，可以是 NULL。
[in, optional] CallbackContext
如果存在 回呼Routine 中，要傳遞至例程的內容指標。 此參數是選擇性的，可以是 NULL。 如果 CallbackRoutine 為 NULL，則會忽略此參數。
[in, optional] Key
與檔案物件鎖定相關聯的選擇性索引鍵。
[in, optional] Mdl
選擇性 MDL，描述要寫入的數據。 如果在 Buffer 中提供緩衝區， 則 Mdl 必須是 NULL。
傳回值
FltWriteFileEx 會傳回文件系統所傳回的 NTSTATUS 值。
備註
迷你篩選驅動程式會呼叫 FltWriteFileEx ，將數據寫入開啟的檔案。
FltWriteFileEx 會導致寫入要求傳送至附加在起始實例和文件系統下方的迷你篩選驅動程序實例。 上面附加的指定實例和實例不會收到寫入要求。
如果下列任一項為 true，FltWriteFileEx 會執行非快取 I/O：
呼叫端會在 Flags 參數中設定FLTFL_IO_OPERATION_NON_CACHED旗標。
檔案物件已針對非快取的 I/O 開啟。 這通常是藉由在上述對 FltCreateFile、FltCreateFileEx 或 ZwCreateFile 的呼叫中指定 FILE_NO_INTERMEDIATE_BUFFERING*/CreateOptions 旗標來完成。
非快取 I/O 會對傳遞至 FltWriteFileEx 的參數值施加下列限制：
Buffer 參數所指向的緩衝區，必須根據基礎儲存裝置的對齊需求進行對齊。 若要配置這類對齊的緩衝區，請呼叫 FltAllocatePoolAlignedWithTag。
ByteOffset 參數指向的位元移必須是磁碟區扇區大小的非負數倍數。
Length 參數中指定的長度必須是磁碟區扇區大小的非負數倍數。
如果 CallbackRoutine 參數的值不是 NULL，則會以異步方式執行寫入作業。
如果 CallbackRoutine 參數的值是 NULL，則會同步執行寫入作業。 也就是說， FltWriteFileEx 會等到寫入作業完成再傳回。 即使 FileObject 指向的檔案對象已針對異步 I/O 開啟，也是如此。
如果多個線程針對相同的檔案物件呼叫 FltWriteFileEx ，而且檔案對象已針對同步 I/O 開啟，篩選管理員不會嘗試在檔案上串行化 I/O。 在此方面， FltWriteFileEx 與 ZwWriteFile 不同。
當迷你篩選器已有 MDL 可用時， Mdl 參數會提供為方便。 直接使用 MDL，而且可以避免對應 Buffer 位址的其他步驟。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows 8 |
| 目標平台 | Universal |
| 標頭 | fltkernel.h (包含 Fltkernel.h) |
| 程式庫 | FltMgr.lib |
| Dll | Fltmgr.sys |
| IRQL | PASSIVE_LEVEL |