共用方式為

FsRtlCopyWrite 函式 (ntifs.h)

  • 發行項

FsRtlCopyWrite 例程會將數據從用戶緩衝區複製到快取的檔案。

語法

BOOLEAN FsRtlCopyWrite(
  [in]  PFILE_OBJECT     FileObject,
  [in]  PLARGE_INTEGER   FileOffset,
  [in]  ULONG            Length,
  [in]  BOOLEAN          Wait,
  [in]  ULONG            LockKey,
  [in]  PVOID            Buffer,
  [out] PIO_STATUS_BLOCK IoStatus,
  [in]  PDEVICE_OBJECT   DeviceObject
);

參數

[in] FileObject

要寫入數據的快取檔案物件的指標。

[in] FileOffset

指定快取檔案內起始位元組位移之變數的指標。

[in] Length

要寫入之數據的位元組長度。

[in] Wait

如果呼叫端可以進入等候狀態，直到複製所有數據，則設定為TRUE，否則為 FALSE。

[in] LockKey

與要鎖定之位元組範圍相關聯的值。 如果要鎖定的範圍重疊另一個已經鎖定為非例外鎖定的範圍，或者要讀取的範圍是另一個範圍子範圍，且該範圍已經非明確鎖定，則此參數中的值必須是該非排除鎖定的索引鍵。呼叫線程的父進程必須保留鎖定。 否則，此參數不會有任何作用。

[in] Buffer

要從中複製數據之緩衝區的指標。

[out] IoStatus

呼叫端配置結構的指標，可接收最終完成狀態和作業的相關信息。 如果成功複製數據， IoStatus.Status 會包含STATUS_SUCCESS。 如果並非所有數據都成功複製， IoStatus.Information 會包含複製的實際位元元組數目。

[in] DeviceObject

裝載磁碟區之裝置物件的指標，該磁碟區會保存盤案數據。

傳回值

如果複製要求已完成，FsRtlCopyWrite 會傳回 TRUE，否則傳回 FALSE。 請注意，TRUE 的傳回值不一定表示複製作業成功。

如果 FsRtlCopyWrite 傳回 FALSE，或 IoStatus 的內容指出複製作業失敗，呼叫端必須配置寫入 IRP，而不是呼叫 FsRtlCopyWrite。

備註

支援檔案快取的文件系統開發人員應該考慮使用 FsRtlCopyWrite 作為文件系統的進入點來處理快速 I/O 寫入要求，而不是實作文件系統特定的快速 I/O 寫入例程。 這需要文件系統的 DriverEntry 例程在文件系統驅動程式物件的FAST_IO_DISPATCH結構中，將 FastIoWrite 進入點設定為 FsRtlCopyWrite 。 此外，檔案系統必須執行下列動作：

  1. 針對執行快速 I/O 的每個檔案，檔案系統必須配置和初始化FSRTL_COMMON_FCB_HEADER結構。

    在大部分的文件系統中，這可藉由在檔案控制區塊中包含FSRTL_COMMON_FCB_HEADER結構， (FCB) 或可比較的結構，用來維護開啟檔案的狀態。

    FSRTL_COMMON_FCB_HEADER 結構的記憶體通常會從分頁集區配置。

  2. 針對執行快速 I/O 的每個檔案，檔案系統必須將檔案的任何檔案對象連結到FSRTL_COMMON_FCB_HEADER結構。 做法是將每個檔案物件的 FsContext 成員設定為指向這個結構 (或 FCB 或其他包含FSRTL_COMMON_FCB_HEADER結構) 結構的結構。

  3. 快取檔案時，文件系統必須將檔案FSRTL_COMMON_FCB_HEADER結構的 IsFastIoPossible 成員設定為適當的值。 只要檔案保持快取狀態，就應該視需要更新此值。

    特別是，文件系統應該在快取檔案上有任何獨佔位元組範圍鎖定時，將FSRTL_COMMON_FCB_HEADER結構的 IsFastIoPossible 成員設定為 FastIoIsQuestionable 。

如果 Wait 為 TRUE， 則保證 FsRtlCopyWrite 會複製數據並傳回 TRUE。 如果快取檔案的必要頁面已經存在於記憶體中，則會立即複製數據，而且不會發生封鎖。 如果有任何必要的頁面未存在，則呼叫端會進入等候狀態，直到所有必要頁面都已存在且可複製數據為止。

如果 Wait 為 FALSE，FsRtlCopyWrite 會拒絕封鎖，如果它無法取得檔案的主要資源，或快取檔案的必要頁面尚未駐留在記憶體中，則會傳回 FALSE。

文件系統的 FastIoCheckIfPossible 例程負責確保 FileOffset 和 Length 所定義的位元組範圍不包含呼叫端未傳遞適當 LockKey 值的任何獨佔鎖定位元組範圍。 如果文件系統使用 FsRtlXxxLockYyy 支援例程來管理位元組範圍鎖定，則可以先從 FastIoCheckIfPossible 例程呼叫 FsRtlFastCheckLockForWrite，再呼叫 FsRtlCopyRead 來完成。

若要快取檔案，請使用 CcInitializeCacheMap 例程。

規格需求

需求 值
目標平台 Universal
標頭 ntifs.h (包含 Ntifs.h)
程式庫 NtosKrnl.lib
Dll NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI 合規性規則 HwStorPortProhibitedDIS (storport) 、 PowerIrpDDis (wdm)

另請參閱

CcInitializeCacheMap

FsRtlCopyRead

FsRtlFastCheckLockForWrite