CcPinRead 関数 (ntifs.h)
CcPinRead ルーチンは、キャッシュされたファイルの指定されたバイト範囲をピン留めし、ピン留めされたデータをメモリ内のバッファーに読み取ります。
構文
BOOLEAN CcPinRead(
[in] PFILE_OBJECT FileObject,
[in] PLARGE_INTEGER FileOffset,
[in] ULONG Length,
[in] ULONG Flags,
[out] PVOID *Bcb,
[out] PVOID *Buffer
);
パラメーター
[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 に設定されます。 |
[out] Bcb
最初の呼び出しでは、バッファー制御ブロック (BCB) へのポインターが返されます。 このポインターは、このバッファーの後続のすべての呼び出しで入力として指定する必要があります。
[out] Buffer
ピン留めされたデータを含むバッファーへのポインター。
戻り値
キャッシュされたファイルのデータがピン留めされ、正常に読み取られた場合、CcPinRead は TRUE を返します。それ以外の場合は FALSE を返します。
注釈
PIN_WAIT フラグが設定されている場合、 CcPinRead はピン留め要求を完了し 、TRUE を返す保証があります。 キャッシュされたファイルの必要なページが既にメモリに存在する場合、データはすぐにピン留めされ、ブロックは行われません。 必要なページが常駐していない場合、呼び出し元は、必要なすべてのページが常駐し、データをピン留めできるようになるまで待機状態になります。 PIN_WAIT フラグが設定されていないが、データをすぐにピン留めできない場合、 CcPinRead は FALSE を返し、出力パラメーター値は無意味です。
その後、呼び出し元が CcPinRead によって読み取られたデータを変更する場合は、変更されたデータが最終的にディスクに書き込まれるように 、CcSetDirtyPinnedData も呼び出す必要があります。
CcPinRead の呼び出しが成功するたびに、後続の CcUnpinData の呼び出しと一致する必要があります。
Buffer で返されるポインターは、CcUnpinData が呼び出されるまで有効です。 このポインターがまだ有効な間 に CcPinMappedData が呼び出された場合、 ポインターは CcPinMappedData の呼び出しの後 ( ただし、CcUnpinData が呼び出されるまでのみ) 有効なままです。
CcPinRead では、キャッシュ マネージャーのビュー境界を越えてデータをピン留めすることはできません。 キャッシュ マネージャーは、256 KB にアラインされたビューでシステム内のファイルを管理します。 (キャッシュ マネージャーのビュー サイズは、システム定義の定数VACB_MAPPING_GRANULARITYによって指定されます。ntifs.h では 256 KB に設定されています)。ピン留めされた領域は、複数の 256 KB ビューにまたがることはできません。 したがって、ピン留めできる最大の領域は 256 KB で、ファイル内の 256 KB で整列されたオフセットから始めます。
キャッシュされたファイルにバイト範囲をピン留めしても、ページがメモリ内に残っているわけではありません。 ページがピン留めされている限り、バイト範囲はシステム キャッシュの仮想アドレス空間にマップされたままであることが保証されますが、メモリ マネージャーは、システムのメモリ需要に応じて物理ページをページングできます。
エラーが発生した場合、 CcPinRead は特定のエラーの状態例外を発生させます。 たとえば、プール割り当てエラーが発生した場合、 CcPinRead はSTATUS_INSUFFICIENT_RESOURCES例外を発生させます。I/O エラーが発生した場合、 CcPinRead は I/O エラーの状態例外を発生させます。 そのため、エラーが発生したかどうかを制御するには、ドライバーは、CcPinRead の呼び出しを try-except ステートメントまたは try-finally ステートメントでラップする必要があります。
キャッシュされたファイルのデータをマップするには、 CcMapData ルーチンを使用します。 ファイルをキャッシュするには、 CcInitializeCacheMap を使用します。
要件
| 要件 | 値 |
|---|---|
| 対象プラットフォーム | ユニバーサル |
| Header | ntifs.h (Ntifs.h を含む) |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |
| IRQL | < DISPATCH_LEVEL |