CcPreparePinWrite 関数 (ntifs.h)

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

CcPreparePinWrite ルーチンは、キャッシュされたファイルの指定されたバイト範囲を書き込みアクセス用にピン留めします。

構文

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

パラメーター

[in] FileObject

データの書き込み先となるキャッシュされたファイルのファイルオブジェクトへのポインター。

[in] FileOffset

データを書き込むファイル内の開始バイトオフセットを指定する変数へのポインター。

[in] Length

必要なデータの長さ (バイト単位)。

[in] Zero

戻り時にバッファーをゼロにする場合は TRUE に設定します。 PIN_CALLER_TRACKS_DIRTY_DATA フラグが Flags パラメーターに設定されている場合、このパラメーターは無視されます。

[in] Flags

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

値	意味
PIN_WAIT	呼び出し元は、データがピン留めされるまで待機状態にすることができます。
PIN_EXCLUSIVE	バッファー制御ブロック (BCB) は排他的に獲得されます。
PIN_NO_READ	既にメモリに常駐しているページのみがピン留めされます。このフラグが設定されている場合は、PIN_WAITも設定する必要があります。
PIN_IF_BCB	データは、BCB が既に存在する場合にのみピン留めされます。それ以外の場合、ピンは失敗し、BCB は返されません。
PIN_CALLER_TRACKS_DIRTY_DATA	呼び出し元は、ダーティページを追跡する責任があります。このフラグが設定されている場合、他のすべてのフラグは無視されます。このフラグは、Microsoft Windows Server 2003 SP1 以降で使用できます。

[out] Bcb

固定されたバッファー制御ブロック (BCB) への不透明なポインター。このポインターは、このバッファーの CcPreparePinWrite または CcUnpinData への後続の呼び出しで入力として指定する必要があります。

[out] Buffer

バッファーが固定解除または解放されるまで有効な、目的のデータへのポインターを返します。

戻り値

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

注釈

CcPreparePinWrite は 、指定されたファイルページをシステムキャッシュにピン留めします。完全に上書きされるページは、0 のページで満たされる場合があります。

PIN_WAIT フラグが設定されている場合、 CcPreparePinWrite は準備要求を完了し 、TRUE を返すことが保証されます。すべてのページをすぐに準備できる場合、ブロックは発生しません。必要なページが常駐していない場合、呼び出し元は、必要なすべてのページが常駐し、ページを準備できるようになるまで待機状態になります。 PIN_WAIT フラグが設定されていないが、すべてのページをすぐに準備できない場合、 CcPreparePinWrite は FALSE を返し、出力パラメーター値は無意味です。

Microsoft Windows Server 2003 SP1 以降: PIN_CALLER_TRACKS_DIRTY_DATA フラグは、ファイルシステムが書き込まれたが読み取り元ではないログファイルを管理する場合に一般的に使用されます。既存のファイルデータは上書きされ、読み取られないため、キャッシュマネージャーは、ディスクからのファイルデータの実際のページでエラーが発生する代わりに、ゼロのページを返す場合があります。このフラグが設定されている場合、キャッシュ・マネージャーはダーティページを追跡しません。呼び出し元は、ダーティページを追跡する責任があります。 CcPreparePinWrite は、バッファーが最終的にディスクにフラッシュされる場合にのみ、この方法でデータをピン留めするために使用する必要があることに注意してください。 CcFlushCache を呼び出してバッファーをディスクにフラッシュする前に、呼び出し元はまず MmSetAddressRangeModified を呼び出して、システムキャッシュバッファー内の指定されたページがダーティされ、書き込まれる必要があることをメモリマネージャーに通知する必要があります。

CcPreparePinWrite の呼び出しが成功するたびに、後続の CcUnpinData の呼び出しと一致する必要があります。同じデータ に対して CcPreparePinWrite が複数回呼び出される場合は、 CcUnpinData を同じ回数呼び出す必要があります。

Buffer で返されるポインターは、CcUnpinData が呼び出されるまで有効です。このポインターがまだ有効な間に CcPinMappedData が呼び出された場合、 ポインターは CcPinMappedData の呼び出しの後 ( ただし、CcUnpinData が呼び出されるまでのみ) 有効なままです。

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

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

CcPreparePinWrite を呼び出した後に CcSetDirtyPinnedData を呼び出す必要はありません。 CcPreparePinWrite が TRUE を返す場合、BCB は既にダーティとしてマークされています。

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

要件

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