共用方式為


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 時(例如,在預先建立或清除後回呼例程中),會導致系統在核取的組建上 ASSERT。 這個參數是必要的,而且不能是 NULL。

[in, optional] ByteOffset

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

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

  • 如果檔案已針對同步 I/O 開啟(FO_SYNCHRONOUS_IO是在檔案物件的 Flags 字段中設定),呼叫端可以設定 ByteOffset->LowPart to FILE_USE_FILE_POINTER_POSITION and ByteOffset->HighPart to -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,Buffer 必須是 NULL。

[in] Flags

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

意義
FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET Minifilter 驅動程式可以設定此旗標來指定 FltWriteFileEx 不會更新檔案物件的 CurrentByteOffset 字段。
FLTFL_IO_OPERATION_NON_CACHED 迷你篩選驅動程式可以設定此旗標來指定非快取寫入,即使檔案物件未以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,則為要傳遞至例程的內容指標,CallbackRoutine。 這個參數是選擇性的,而且可以是 NULL。 如果 CallbackRoutine 為 NULL,則會忽略此參數。

[in, optional] Key

與檔案物件鎖定相關聯的選擇性索引鍵。

[in, optional] Mdl

描述要寫入之數據的選擇性 MDL。 如果在 Buffer中提供緩衝區,則 Mdl 必須是 NULL。

傳回值

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

言論

小型篩選驅動程式會呼叫 FltWriteFileEx,將數據寫入開啟的檔案。

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

FltWriteFileEx 如果下列任一項成立,則會執行非快取 I/O:

  • 呼叫端會在 Flags 參數中設定FLTFL_IO_OPERATION_NON_CACHED旗標。

  • 檔案物件已針對未快取的 I/O 開啟。 這通常是藉由在上述呼叫中指定 FILE_NO_INTERMEDIATE_BUFFERING****CreateOptions 旗標來 FltCreateFileFltCreateFileExZwCreateFile來完成。

非快取 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
目標平臺 普遍
標頭 fltkernel.h (包括 Fltkernel.h)
連結庫 FltMgr.lib
DLL Fltmgr.sys
IRQL PASSIVE_LEVEL

另請參閱

FILE_OBJECT

FltAllocatePoolAlignedWithTag

FltCreateFile

FltCreateFileEx

FltReadFileEx

ObReferenceObjectByHandle

PFLT_COMPLETED_ASYNC_IO_CALLBACK

ZwCreateFile

ZwReadFile

ZwWriteFile