PrjUpdateFileIfNeeded 関数 (projectedfslib.h)

プロバイダーがローカル ファイル システムにキャッシュされている項目を更新できるようにします。

構文

HRESULT PrjUpdateFileIfNeeded(
  [in]            PRJ_NAMESPACE_VIRTUALIZATION_CONTEXT namespaceVirtualizationContext,
  [in]            PCWSTR                               destinationFileName,
  [in]            const PRJ_PLACEHOLDER_INFO           *placeholderInfo,
  [in]            UINT32                               placeholderInfoSize,
  [in, optional]  PRJ_UPDATE_TYPES                     updateFlags,
  [out, optional] PRJ_UPDATE_FAILURE_CAUSES            *failureReason
);

パラメーター

[in] namespaceVirtualizationContext

仮想化インスタンスの不透明なハンドル。

[in] destinationFileName

更新するファイルまたはディレクトリへの仮想化ルートを基準としたパスを指定する、null で終わる Unicode 文字列。

[in] placeholderInfo

ファイルまたはディレクトリの更新されたメタデータを含む PRJ_PLACEHOLDER_INFO バッファーへのポインター。

placeholderInfo->VersionInfo.ContentID に、ファイル/ディレクトリに既に存在するコンテンツ識別子と同じコンテンツ識別子が含まれている場合、呼び出しは成功し、更新は行われません。 それ以外の場合、呼び出しが成功した場合、placeholderInfo->VersionInfo.ContentID はファイルの既存のコンテンツ識別子を置き換えます。

[in] placeholderInfoSize

placeholderInfo が指すバッファーのサイズ (バイト単位)。

[in, optional] updateFlags

更新を制御するためのフラグ。

アイテムがダーティ プレースホルダー、フル ファイル、または tombstone で、プロバイダーが適切なフラグを指定していない場合、このルーチンはプレースホルダーの更新に失敗します

[out, optional] failureReason

更新が失敗した理由を説明するコードを受け取るオプションのポインター。

戻り値

HRESULT_FROM_WIN32(ERROR_FILE_SYSTEM_VIRTUALIZATION_INVALID_OPERATION) エラーが返された場合、アイテムの状態と updateFlags の値が原因で更新に失敗しました。 failureReason を指定すると、エラーの理由が記述されます。

注釈

プロバイダーは、このルーチンを使用して、ローカル ファイル システム内の項目の情報がプロバイダーのバッキング ストアで変更され、更新プログラムがローカル ファイル システムにキャッシュされている項目に反映される必要がある場合に、ローカル ファイル システム内の項目を更新します。

このルーチンは、仮想ファイル/ディレクトリで呼び出すことはできません。 更新するファイル/ディレクトリが "placeholder" 以外の状態の場合、プロバイダーは updateFlags パラメーターにPRJ_UPDATE_TYPES値の適切な組み合わせを指定する必要があります。 これは、このルーチンから正常に戻ると、アイテムが更新されたメタデータを持つプレースホルダーになるため、データの偶発的な損失を防ぐために役立ちます。プレースホルダーの作成後に変更されたメタデータ、またはプレースホルダーに含まれるファイル データは破棄されます。

プロバイダーは、ローカル ファイル システムを管理する項目のキャッシュとして使用します。 項目 (ファイルまたはディレクトリ) は、ローカル ファイル システム上の 6 つの状態のいずれかになります。

仮想 - 項目はディスク上にローカルに存在しません。 これは、親ディレクトリの列挙中に投影されます (つまり、合成されます)。 仮想項目は、親ディレクトリの完全な内容を表示するためにディスク上に存在する可能性のある項目とマージされます。

プレースホルダー - ファイルの場合: ファイルのコンテンツ (プライマリ データ ストリーム) がディスクに存在しません。 ファイルのメタデータ (名前、サイズ、タイムスタンプ、属性など) はディスクにキャッシュされます。 ディレクトリの場合: ディレクトリの直属の子孫 (ディレクトリ内のファイルとディレクトリ) の一部または全部がディスク上に存在しません。つまり、それらはまだ仮想的です。 ディレクトリのメタデータ (名前、タイムスタンプ、属性など) はディスクにキャッシュされます。

ハイドレートされたプレースホルダー - ファイルの場合: ファイルのコンテンツとメタデータがディスクにキャッシュされています。 "部分ファイル" とも呼ばれます。 ディレクトリの場合: ディレクトリはプレースホルダーとしてハイドレートされることはありません。 プレースホルダーとしてディスク上に作成されたディレクトリは、ハイドレートされたプレースホルダー ディレクトリになることはありません。 これにより、プロバイダーはバッキング ストア内のディレクトリに項目を追加または削除し、それらの変更をローカル キャッシュに反映できます。

ダーティ プレースホルダー (ハイドレートされるかどうか) - アイテムのメタデータはローカルで変更されており、プロバイダーのストアでの状態のキャッシュではなくなりました。 プレースホルダー ディレクトリの下にファイルまたはディレクトリを作成または削除すると、プレースホルダー ディレクトリがダーティになることに注意してください。

完全なファイル/ディレクトリ - ファイルの場合: ファイルのコンテンツ (プライマリ データ ストリーム) が変更されました。 ファイルは、プロバイダーのストア内の状態のキャッシュではなくなりました。 ローカル ファイル システム上に作成されたファイル (つまり、プロバイダーのストアにまったく存在しないファイル) も、完全なファイルと見なされます。 ディレクトリの場合: ローカル ファイル システムで作成されたディレクトリ (つまり、プロバイダーのストアにまったく存在しないディレクトリ) は、完全なディレクトリと見なされます。 プレースホルダーとしてディスク上に作成されたディレクトリが完全なディレクトリになることはありません。

Tombstone - ローカル ファイル システムから削除されたアイテムを表す特別な非表示のプレースホルダー。 ディレクトリが列挙されると、ProjFS はローカル項目のセット (プレースホルダー、完全なファイルなど) を仮想投影項目のセットとマージします。 項目がローカル セットと投影セットの両方に表示される場合は、ローカル項目が優先されます。 ファイルが存在しない場合は、ローカル状態がないため、列挙型に表示されます。 ただし、その項目が削除されている場合は、列挙型に表示されることは予期しない結果になります。 削除されたアイテムを廃棄石に置き換えると、次の効果が得られます。

• アイテムを表示しない列挙体
• 項目が存在することを予期するファイルが開き、"file not found" などのエラーが発生します。
• ファイルは、アイテムが存在しない場合にのみ成功することを想定して作成します。ProjFS は、操作の一部として廃棄石を削除します。

上記の状態を示すために、仮想化ルート C:\root にある 1 つのファイル "foo.txt" を持つ ProjFS プロバイダーを考えて、次のシーケンスを検討します。

• アプリは C:\root を列挙します。 仮想ファイル "foo.txt" が表示されます。 ファイルにはまだアクセスされていないため、ファイルはディスク上に存在しません。
• アプリは、C:\root\foo.txtするハンドルを開きます。 ProjFS は、プロバイダーにプレースホルダーを作成するよう指示します。
• アプリはファイルの内容を読み取ります。 プロバイダーは ProjFS にファイルコンテンツを提供し、C:\root\foo.txtにキャッシュされます。 これで、ファイルはハイドレートされたプレースホルダーになりました。
• アプリは、最終更新日時のタイムスタンプを更新します。 これで、ファイルはダーティ ハイドレートされたプレースホルダーになりました。
• アプリは、ファイルへの書き込みアクセス用のハンドルを開きます。 C:\root\foo.txt は完全なファイルになりました。
• アプリは C:\root\foo.txtを削除します。 ProjFS は、ファイルを廃棄石に置き換えます。 アプリが C:\root it does not see foo.txtを列挙したとき。 ファイルを開こうとすると、開くERROR_FILE_NOT_FOUNDで失敗します。

Requirements