共用方式為

FsRtlCopyRead 函式 (ntifs.h)

  • 發行項

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

語法

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

參數

[in] FileObject

要從中讀取數據之快取檔案的檔案對象指標。

[in] FileOffset

在快取檔案內啟動位元組位移。

[in] Length

要讀取之數據的位元組長度。

[in] Wait

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

[in] LockKey

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

[out] Buffer

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

[out] IoStatus

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

[in] DeviceObject

保存檔案資料的裝置裝置物件。

傳回值

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

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

備註

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

  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，FsRtlCopyRead 保證會完成複製要求並傳回 TRUE。 如果快取檔案的必要頁面已經存在於記憶體中，則會立即複製數據，而且不會發生封鎖。 如果有任何必要的頁面未存在，則呼叫端將會進入等候狀態，直到所有必要頁面都已進入駐留狀態，而且可以複製數據。

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

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

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

規格需求

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

另請參閱

CcInitializeCacheMap

FsRtlCopyWrite

FsRtlFastCheckLockForRead