FltWriteFile 函式 (fltkernel.h)

發行項
03/01/2024

FltWriteFile 可用來將數據寫入開啟的檔案、數據流或裝置。

語法

NTSTATUS FLTAPI FltWriteFile(
  [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] InitiatingInstance

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

[in] FileObject

要寫入數據的檔案 FILE_OBJECT 指標。這個檔案物件目前必須開啟。當檔案物件尚未開啟或不再開啟 (時呼叫 FltWriteFile ，例如，在預先建立或清除後回呼例程中，) 會導致系統在核取的組建上判斷提示。這個參數是必要的，而且不能是 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 傳回時還原它。從 FltWriteFile 的呼叫者的觀點來看， (和在較高高度) CurrrentByteOffset 的篩選不會更新。但呼叫端下方的篩選會在其讀取/寫入后回呼中看到更新的 CurrentByteOffset 值。

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

如果 FileObject 指向的檔案物件已針對異步 I/O 開啟，則這個參數是必要的，而且不能是 NULL。

在 Windows 8 之前，此參數不支援特殊常數FILE_WRITE_TO_END_OF_FILE和FILE_USE_FILE_POINTER_POSITION。

[in] Length

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

[in] Buffer

緩衝區的指標，其中包含要寫入檔案的數據。如果開啟非快取 I/O 的檔案，則必須根據基礎儲存裝置的對齊需求來對齊此緩衝區。 Minifilter 驅動程式可以呼叫 FltAllocatePoolAlignedWithTag 來配置這類對齊的緩衝區。

[in] Flags

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

旗標	意義
FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET	Minifilter 驅動程式可以設定此旗標來指定 FltWriteFile 不會更新檔案物件的 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

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

傳回值

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

備註

迷你篩選驅動程式會呼叫 FltWriteFile 將數據寫入開啟的檔案。

FltWriteFile 會導致寫入要求傳送至附加在起始實例和文件系統下方的迷你篩選驅動程序實例。上面附加的指定實例和實例不會收到寫入要求。

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

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

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

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

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

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

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