ホーム › Storage.ProjectedFileSystem › PrjUpdateFileIfNeeded

PrjUpdateFileIfNeeded

関数

必要に応じて仮想化ファイルのプレースホルダーを更新する。

DLLPROJECTEDFSLIB.dll呼出規約winapi対応OSWindows 10 以降

シグネチャ

// PROJECTEDFSLIB.dll
#include <windows.h>

HRESULT PrjUpdateFileIfNeeded(
    PRJ_NAMESPACE_VIRTUALIZATION_CONTEXT namespaceVirtualizationContext,
    LPCWSTR destinationFileName,
    const PRJ_PLACEHOLDER_INFO* placeholderInfo,
    DWORD placeholderInfoSize,
    PRJ_UPDATE_TYPES updateFlags,   // optional
    PRJ_UPDATE_FAILURE_CAUSES* failureReason   // optional
);

パラメーター

名前	型	方向	説明
namespaceVirtualizationContext	PRJ_NAMESPACE_VIRTUALIZATION_CONTEXT	in	仮想化インスタンスの不透明なハンドル。
destinationFileName	LPCWSTR	in	更新するファイルまたはディレクトリへの、仮想化ルートからの相対パスを指定する、null で終わる Unicode 文字列。
placeholderInfo	PRJ_PLACEHOLDER_INFO*	in	ファイルまたはディレクトリの更新後のメタデータを格納した PRJ_PLACEHOLDER_INFO バッファーへのポインター。 placeholderInfo->VersionInfo.ContentID に、そのファイル/ディレクトリに既に設定されているものと同じコンテンツ識別子が格納されている場合、呼び出しは成功しますが更新は行われません。それ以外の場合、呼び出しが成功すると placeholderInfo->VersionInfo.ContentID がファイル上の既存のコンテンツ識別子を置き換えます。
placeholderInfoSize	DWORD	in	placeholderInfo が指すバッファーのサイズ (バイト単位)。
updateFlags	PRJ_UPDATE_TYPES	inoptional	更新を制御するフラグ。項目がダーティなプレースホルダー、完全なファイル、またはトゥームストーンであるにもかかわらず、プロバイダーが適切なフラグを指定していない場合、このルーチンはプレースホルダーの更新に失敗します
failureReason	PRJ_UPDATE_FAILURE_CAUSES*	outoptional	更新が失敗した理由を示すコードを受け取る省略可能なポインター。

戻り値の型: HRESULT

公式ドキュメント

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

戻り値

HRESULT_FROM_WIN32(ERROR_FILE_SYSTEM_VIRTUALIZATION_INVALID_OPERATION) エラーが返された場合、項目の状態と updateFlags の値が原因で更新が失敗しています。failureReason を指定していれば、失敗の理由が示されます。

解説(Remarks)

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

このルーチンは仮想ファイル/ディレクトリに対しては呼び出せません。更新対象のファイル/ディレクトリが "placeholder" 以外の状態にある場合、プロバイダーは updateFlags パラメーターに PRJ_UPDATE_TYPES 値の適切な組み合わせを指定する必要があります。これは、意図しないデータの喪失を防ぐのに役立ちます。というのも、このルーチンが成功して戻ると、その項目は更新後のメタデータを持つプレースホルダーになり、プレースホルダーの作成後に変更されたメタデータや、その項目が保持していたファイルデータはすべて破棄されるためです。

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

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

Placeholder - ファイルの場合: ファイルの内容 (プライマリデータストリーム) はディスク上に存在しません。ファイルのメタデータ (名前、サイズ、タイムスタンプ、属性など) はディスク上にキャッシュされています。ディレクトリの場合: ディレクトリの直下の子 (そのディレクトリ内のファイルおよびディレクトリ) の一部またはすべてがディスク上に存在せず、まだ仮想のままです。ディレクトリのメタデータ (名前、タイムスタンプ、属性など) はディスク上にキャッシュされています。

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

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

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

Tombstone - ローカルファイルシステムから削除された項目を表す、特殊な隠しプレースホルダーです。ディレクトリが列挙されるとき、ProjFS はローカル項目のセット (プレースホルダー、完全なファイルなど) と、射影された仮想項目のセットをマージします。ある項目がローカルと射影の両方のセットに現れる場合は、ローカル項目が優先されます。ファイルが存在しない場合はローカルの状態が無いため、その項目は列挙に現れることになります。しかし、その項目が削除されていた場合、列挙に現れるのは想定外の動作です。削除された項目をトゥームストーンで置き換えると、次の効果が得られます。

列挙でその項目が現れない
その項目が存在することを前提としたファイルのオープンは、たとえば "file not found" のように失敗する。
その項目が存在しない場合にのみ成功することを期待するファイルの作成は成功する。ProjFS はその操作の一環としてトゥームストーンを削除する。

上記の状態を説明するため、仮想化ルート C: oot に "foo.txt" という 1 つのファイルを持つ ProjFS プロバイダーを例に、次の流れを考えます。

アプリが C: oot を列挙します。アプリには仮想ファイル "foo.txt" が見えます。このファイルはまだアクセスされていないため、ディスク上には存在しません。
アプリが C: ootoo.txt へのハンドルを開きます。ProjFS はプロバイダーに対して、そのファイルのプレースホルダーを作成するよう指示します。
アプリがファイルの内容を読み取ります。プロバイダーは ProjFS にファイルの内容を提供し、その内容が C: ootoo.txt にキャッシュされます。これでこのファイルはハイドレート済みプレースホルダーになります。
アプリが最終更新日時のタイムスタンプを更新します。これでこのファイルはダーティなハイドレート済みプレースホルダーになります。
アプリが書き込みアクセスでファイルのハンドルを開きます。これで C: ootoo.txt は完全なファイルになります。
アプリが C: ootoo.txt を削除します。ProjFS はそのファイルをトゥームストーンで置き換えます。これ以降、アプリが C: oot を列挙しても foo.txt は見えません。ファイルを開こうとすると、そのオープンは ERROR_FILE_NOT_FOUND で失敗します。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// PROJECTEDFSLIB.dll
#include <windows.h>

HRESULT PrjUpdateFileIfNeeded(
    PRJ_NAMESPACE_VIRTUALIZATION_CONTEXT namespaceVirtualizationContext,
    LPCWSTR destinationFileName,
    const PRJ_PLACEHOLDER_INFO* placeholderInfo,
    DWORD placeholderInfoSize,
    PRJ_UPDATE_TYPES updateFlags,   // optional
    PRJ_UPDATE_FAILURE_CAUSES* failureReason   // optional
);

[DllImport("PROJECTEDFSLIB.dll", ExactSpelling = true)]
static extern int PrjUpdateFileIfNeeded(
    IntPtr namespaceVirtualizationContext,   // PRJ_NAMESPACE_VIRTUALIZATION_CONTEXT
    [MarshalAs(UnmanagedType.LPWStr)] string destinationFileName,   // LPCWSTR
    IntPtr placeholderInfo,   // PRJ_PLACEHOLDER_INFO*
    uint placeholderInfoSize,   // DWORD
    int updateFlags,   // PRJ_UPDATE_TYPES optional
    IntPtr failureReason   // PRJ_UPDATE_FAILURE_CAUSES* optional, out
);

<DllImport("PROJECTEDFSLIB.dll", ExactSpelling:=True)>
Public Shared Function PrjUpdateFileIfNeeded(
    namespaceVirtualizationContext As IntPtr,   ' PRJ_NAMESPACE_VIRTUALIZATION_CONTEXT
    <MarshalAs(UnmanagedType.LPWStr)> destinationFileName As String,   ' LPCWSTR
    placeholderInfo As IntPtr,   ' PRJ_PLACEHOLDER_INFO*
    placeholderInfoSize As UInteger,   ' DWORD
    updateFlags As Integer,   ' PRJ_UPDATE_TYPES optional
    failureReason As IntPtr   ' PRJ_UPDATE_FAILURE_CAUSES* optional, out
) As Integer
End Function

' namespaceVirtualizationContext : PRJ_NAMESPACE_VIRTUALIZATION_CONTEXT
' destinationFileName : LPCWSTR
' placeholderInfo : PRJ_PLACEHOLDER_INFO*
' placeholderInfoSize : DWORD
' updateFlags : PRJ_UPDATE_TYPES optional
' failureReason : PRJ_UPDATE_FAILURE_CAUSES* optional, out
Declare PtrSafe Function PrjUpdateFileIfNeeded Lib "projectedfslib" ( _
    ByVal namespaceVirtualizationContext As LongPtr, _
    ByVal destinationFileName As LongPtr, _
    ByVal placeholderInfo As LongPtr, _
    ByVal placeholderInfoSize As Long, _
    ByVal updateFlags As Long, _
    ByVal failureReason As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

PrjUpdateFileIfNeeded = ctypes.windll.projectedfslib.PrjUpdateFileIfNeeded
PrjUpdateFileIfNeeded.restype = ctypes.c_int
PrjUpdateFileIfNeeded.argtypes = [
    wintypes.HANDLE,  # namespaceVirtualizationContext : PRJ_NAMESPACE_VIRTUALIZATION_CONTEXT
    wintypes.LPCWSTR,  # destinationFileName : LPCWSTR
    ctypes.c_void_p,  # placeholderInfo : PRJ_PLACEHOLDER_INFO*
    wintypes.DWORD,  # placeholderInfoSize : DWORD
    ctypes.c_int,  # updateFlags : PRJ_UPDATE_TYPES optional
    ctypes.c_void_p,  # failureReason : PRJ_UPDATE_FAILURE_CAUSES* optional, out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('PROJECTEDFSLIB.dll')
PrjUpdateFileIfNeeded = Fiddle::Function.new(
  lib['PrjUpdateFileIfNeeded'],
  [
    Fiddle::TYPE_VOIDP,  # namespaceVirtualizationContext : PRJ_NAMESPACE_VIRTUALIZATION_CONTEXT
    Fiddle::TYPE_VOIDP,  # destinationFileName : LPCWSTR
    Fiddle::TYPE_VOIDP,  # placeholderInfo : PRJ_PLACEHOLDER_INFO*
    -Fiddle::TYPE_INT,  # placeholderInfoSize : DWORD
    Fiddle::TYPE_INT,  # updateFlags : PRJ_UPDATE_TYPES optional
    Fiddle::TYPE_VOIDP,  # failureReason : PRJ_UPDATE_FAILURE_CAUSES* optional, out
  ],
  Fiddle::TYPE_INT)

#[link(name = "projectedfslib")]
extern "system" {
    fn PrjUpdateFileIfNeeded(
        namespaceVirtualizationContext: *mut core::ffi::c_void,  // PRJ_NAMESPACE_VIRTUALIZATION_CONTEXT
        destinationFileName: *const u16,  // LPCWSTR
        placeholderInfo: *const PRJ_PLACEHOLDER_INFO,  // PRJ_PLACEHOLDER_INFO*
        placeholderInfoSize: u32,  // DWORD
        updateFlags: i32,  // PRJ_UPDATE_TYPES optional
        failureReason: *mut i32  // PRJ_UPDATE_FAILURE_CAUSES* optional, out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("PROJECTEDFSLIB.dll")]
public static extern int PrjUpdateFileIfNeeded(IntPtr namespaceVirtualizationContext, [MarshalAs(UnmanagedType.LPWStr)] string destinationFileName, IntPtr placeholderInfo, uint placeholderInfoSize, int updateFlags, IntPtr failureReason);
"@
$api = Add-Type -MemberDefinition $sig -Name 'PROJECTEDFSLIB_PrjUpdateFileIfNeeded' -Namespace Win32 -PassThru
# $api::PrjUpdateFileIfNeeded(namespaceVirtualizationContext, destinationFileName, placeholderInfo, placeholderInfoSize, updateFlags, failureReason)

#uselib "PROJECTEDFSLIB.dll"
#func global PrjUpdateFileIfNeeded "PrjUpdateFileIfNeeded" sptr, sptr, sptr, sptr, sptr, sptr
; PrjUpdateFileIfNeeded namespaceVirtualizationContext, destinationFileName, varptr(placeholderInfo), placeholderInfoSize, updateFlags, varptr(failureReason)   ; 戻り値は stat
; namespaceVirtualizationContext : PRJ_NAMESPACE_VIRTUALIZATION_CONTEXT -> "sptr"
; destinationFileName : LPCWSTR -> "sptr"
; placeholderInfo : PRJ_PLACEHOLDER_INFO* -> "sptr"
; placeholderInfoSize : DWORD -> "sptr"
; updateFlags : PRJ_UPDATE_TYPES optional -> "sptr"
; failureReason : PRJ_UPDATE_FAILURE_CAUSES* optional, out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "PROJECTEDFSLIB.dll"
#cfunc global PrjUpdateFileIfNeeded "PrjUpdateFileIfNeeded" sptr, wstr, var, int, int, var
; res = PrjUpdateFileIfNeeded(namespaceVirtualizationContext, destinationFileName, placeholderInfo, placeholderInfoSize, updateFlags, failureReason)
; namespaceVirtualizationContext : PRJ_NAMESPACE_VIRTUALIZATION_CONTEXT -> "sptr"
; destinationFileName : LPCWSTR -> "wstr"
; placeholderInfo : PRJ_PLACEHOLDER_INFO* -> "var"
; placeholderInfoSize : DWORD -> "int"
; updateFlags : PRJ_UPDATE_TYPES optional -> "int"
; failureReason : PRJ_UPDATE_FAILURE_CAUSES* optional, out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "PROJECTEDFSLIB.dll"
#cfunc global PrjUpdateFileIfNeeded "PrjUpdateFileIfNeeded" sptr, wstr, sptr, int, int, sptr
; res = PrjUpdateFileIfNeeded(namespaceVirtualizationContext, destinationFileName, varptr(placeholderInfo), placeholderInfoSize, updateFlags, varptr(failureReason))
; namespaceVirtualizationContext : PRJ_NAMESPACE_VIRTUALIZATION_CONTEXT -> "sptr"
; destinationFileName : LPCWSTR -> "wstr"
; placeholderInfo : PRJ_PLACEHOLDER_INFO* -> "sptr"
; placeholderInfoSize : DWORD -> "int"
; updateFlags : PRJ_UPDATE_TYPES optional -> "int"
; failureReason : PRJ_UPDATE_FAILURE_CAUSES* optional, out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。