CcPinMappedData 関数 (ntifs.h)
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 |