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 の内容がコピー操作に失敗したことを示している場合、呼び出し元は FsRtlCopyRead を呼び出す代わりに読み取り IRP を割り当てる必要があります。

注釈

ファイル システム固有の高速 I/O 読み取りルーチンを実装するのではなく、ファイル キャッシュをサポートするファイル システムの開発者は、高速 I/O 読み取り要求を処理するためのファイル システムのエントリ ポイントとして FsRtlCopyRead を使用することを検討する必要があります。 そのためには、ファイル システムの DriverEntry ルーチンが、ファイル システム ドライバー オブジェクトのFAST_IO_DISPATCH構造で FastIoRead エントリ ポイントを FsRtlCopyRead に設定する必要があります。 さらに、ファイル システムでは次の操作を行う必要があります。

  1. 高速 I/O を実行するファイルごとに、ファイル システムはFSRTL_COMMON_FCB_HEADER構造体を割り当てて初期化する必要があります。

    ほとんどのファイル システムでは、これは、開いているファイルの状態を維持するために使用されるファイル制御ブロック (FCB) または同等の構造にFSRTL_COMMON_FCB_HEADER構造を含めることによって実現されます。

    通常、FSRTL_COMMON_FCB_HEADER構造体のストレージは、ページ プールから割り当てられます。

  2. 高速 I/O が実行される可能性がある各ファイルについて、ファイル・システムは、ファイルのファイル・オブジェクトをFSRTL_COMMON_FCB_HEADER構造にリンクする必要があります。 これを行うには、各ファイル オブジェクトの FsContext メンバーを、この構造体 (または、FSRTL_COMMON_FCB_HEADER構造体を含む FCB またはその他の構造体) を指すように設定します。

  3. ファイルをキャッシュする場合、ファイル システムは、ファイルのFSRTL_COMMON_FCB_HEADER構造の IsFastIoPossible メンバーを適切な値に設定する必要があります。 この値は、ファイルがキャッシュされたままである限り、必要に応じて更新する必要があります。

    特に、ファイル システムでは、キャッシュされたファイルに対する排他的なバイト範囲ロックが存在するとすぐに、FSRTL_COMMON_FCB_HEADER構造体の IsFastIoPossible メンバーを FastIoIsQuestionable に設定する必要があります。

Wait が TRUE の場合、FsRtlCopyRead はコピー要求を完了し、TRUE を返す保証があります。 キャッシュされたファイルの必要なページが既にメモリに存在する場合、データはすぐにコピーされ、ブロックは行われません。 必要なページが常駐していない場合、呼び出し元は、必要なすべてのページが常駐し、データをコピーできるようになるまで待機状態になります。

Wait が FALSE の場合、FsRtlCopyRead はブロックを拒否し、ファイルのメイン リソースを取得できない場合、またはキャッシュされたファイルの必要なページがまだメモリに存在していない場合は FALSE を返します。

ファイル システムの FastIoCheckIfPossible ルーチンは、 FileOffset および Length で定義されたバイト範囲に、呼び出し元が適切な LockKey 値を渡さない排他的にロックされたバイト範囲が含まれていないことを確認します。 ファイル システムで FsRtlXxxLockYyy サポート ルーチンを使用してバイト範囲ロックを管理する場合は、FsRtlCopyRead を呼び出す前に FastIoCheckIfPossible ルーチンから FsRtlFastCheckLockForRead を呼び出すことでこれを実現できます。

ファイルをキャッシュするには、 CcInitializeCacheMap ルーチンを使用します。

要件

要件 値
対象プラットフォーム ユニバーサル
Header ntifs.h (Ntifs.h を含む)
Library NtosKrnl.lib
[DLL] NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI コンプライアンス規則 PowerIrpDDis(wdm)

こちらもご覧ください

CcInitializeCacheMap

FsRtlCopyWrite

FsRtlFastCheckLockForRead