CcPreparePinWrite 関数 (ntifs.h)

2024-12-20

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 、システムキャッシュ内の指定されたファイルページをピン留めします。完全に上書きされるページは、ゼロのページで満たされる場合があります。

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 ステートメントラップする必要があります。

必要条件

要件	価値
ターゲットプラットフォームの	万国
ヘッダー	ntifs.h (Ntifs.h を含む)
ライブラリ	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL

次の方法で共有

CcPreparePinWrite 関数 (ntifs.h)

構文

パラメーター

戻り値

備考

必要条件

関連項目

フィードバック

その他のリソース