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

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

アイテムがダーティプレースホルダー、完全なファイル、または廃棄ストーンであり、プロバイダーが適切なフラグを指定していない場合、このルーチンはプレースホルダーを更新できません

[out, optional] failureReason

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

戻り値

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

注釈

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

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

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

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

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

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

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

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

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

• 項目を表示しない列挙
• アイテムが存在することを想定するファイルが開き、"ファイルが見つかりません" などのエラーが発生します。
• ファイルは、アイテムが存在しない場合にのみ成功することを期待する を作成します。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 を列挙すると、foo.txt は表示されません。 ファイルを開こうとすると、開くはERROR_FILE_NOT_FOUNDで失敗します。

要件