CcPinMappedData 関数 (ntifs.h)

[アーティクル]
08/07/2023

CcPinMappedData ルーチンは、キャッシュされたファイルの指定されたバイト範囲をピン留めします。

構文

BOOLEAN CcPinMappedData(
  [in]      PFILE_OBJECT   FileObject,
  [in]      PLARGE_INTEGER FileOffset,
  [in]      ULONG          Length,
  [in]      ULONG          Flags,
  [in, out] PVOID          *Bcb
);

パラメーター

[in] FileObject

データの範囲をピン留めするキャッシュされたファイルのファイルオブジェクトへのポインター。

[in] FileOffset

目的のデータが存在するキャッシュされたファイル内の開始バイトオフセットを指定する変数へのポインター。

[in] Length

固定するデータの長さ (バイト単位)。

[in] Flags

ピン留め操作の実行方法を指定するフラグのビットマスク。次の値の 1 つ以上の ORed の組み合わせ:

フラグ	説明
PIN_WAIT	呼び出し元は、データがピン留めされるまで待機状態にすることができます。
PIN_EXCLUSIVE	バッファー制御ブロック (BCB) は排他的に獲得されます。このフラグが設定されている場合は、PIN_WAITも設定する必要があります。
PIN_NO_READ	既にメモリに常駐しているページのみがピン留めされます。このフラグが設定されている場合は、PIN_WAITも設定する必要があります。
PIN_IF_BCB	データは、BCB が既に存在する場合にのみ固定されます。それ以外の場合、ピンは失敗し、 Bcb は NULL に設定されます。

[in, out] Bcb

最初の呼び出しでは、バッファー制御ブロック (BCB) へのポインターが返されます。このポインターは、このバッファーの後続のすべての呼び出しで入力として指定する必要があります。

戻り値

CcPinMappedData は、キャッシュされたファイルのデータが正常にピン留めされた場合は TRUE を返し、それ以外の場合は FALSE を 返します。

注釈

CcPinMappedData から正常に戻った場合、CcMapData への呼び出しで以前にマップされたデータがキャッシュに固定され、指定された範囲のデータを安全に変更できます。呼び出し元が後で CcPinMappedData によって固定されたデータを変更する場合は、変更されたデータが最終的にディスクに書き込まれるように、CcSetDirtyPinnedData も呼び出す必要があります。

CcPinMappedData では、キャッシュマネージャーのビュー境界を越えてデータをピン留めすることはできません。キャッシュマネージャーは、256 KB アラインビューでシステム内のファイルを管理します。 (キャッシュマネージャーのビューサイズは、システム定義の定数 VACB_MAPPING_GRANULARITYによって指定されます。 ntifs.h では 256 KB に設定されています)。ピン留めされた領域は、複数の 256 KB ビューにまたがることはできません。したがって、固定できる最大の領域は 256 KB で、ファイル内の 256 KB アラインオフセットから始めます。

キャッシュされたファイルにバイト範囲をピン留めしても、ページがメモリ内に存在し続けるわけではありません。ページがピン留めされている限り、バイト範囲はシステムキャッシュの仮想アドレス空間にマップされたままであることが保証されますが、メモリマネージャーは、システムのメモリ要求に応じて物理ページをページングできます。

エラーが発生した場合、 CcPinMappedData は特定のエラーの状態例外を発生させます。たとえば、プール割り当てエラーが発生した場合、 CcPinMappedData は STATUS_INSUFFICIENT_RESOURCES 例外を発生させます。I/O エラーが発生した場合、 CcPinMappedData は I/O エラーの状態例外を発生させます。そのため、エラーが発生した場合に制御を取得するには、ドライバーは、try-except またはtry-finally ステートメントで CcPinMappedData への呼び出しをラップする必要があります。

キャッシュされたファイルのデータをマップするには、 CcMapData ルーチンを使用します。ファイルをキャッシュするには、 CcInitializeCacheMap を使用します。

CcPinMappedData を呼び出した後に CcUnpinData を呼び出す必要はありません。これは、ピン参照が CcMapData と一致するためです。

要件

要件	値
対象プラットフォーム	ユニバーサル
Header	ntifs.h (Ntifs.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	PASSIVE_LEVEL