使提供程序能够更新已缓存在本地文件系统上的项。
语法
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> 包含的内容标识符与文件/目录上已有的内容标识符相同，则调用成功且不会进行更新。 否则，如果调用成功，则占位符Info-VersionInfo.ContentID> 将替换文件上的现有内容标识符。
[in] placeholderInfoSize
placeholderInfo 指向的缓冲区的大小（以字节为单位）。
[in, optional] updateFlags
用于控制更新的标志。
如果项是脏占位符、完整文件或逻辑删除，并且提供程序未 () 指定适当的标志，则此例程将无法更新占位符
[out, optional] failureReason
用于接收描述更新失败原因的代码的可选指针。
返回值
如果返回HRESULT_FROM_WIN32 (ERROR_FILE_SYSTEM_VIRTUALIZATION_INVALID_OPERATION) 错误，则由于项的状态和 updateFlags 的值，更新失败。 failureReason（如果指定）将描述失败的原因。
注解
如果项的信息在提供程序的后备存储中发生了更改，并且更新应反映在本地文件系统中缓存的项中，则提供程序使用此例程更新本地文件系统中的项。
无法对虚拟文件/目录调用此例程。 如果要更新的文件/目录处于“占位符”以外的任何状态，则提供程序必须在 updateFlags 参数中指定PRJ_UPDATE_TYPES值的适当组合。 这有助于防止意外丢失数据，因为从此例程成功返回后，项将成为包含更新元数据的占位符;创建占位符后已更改的任何元数据，或其包含的任何文件数据将被丢弃。
提供程序使用本地文件系统作为其管理的项的缓存。 (文件或目录的项) 在本地文件系统上可以处于六种状态之一。
虚拟 - 项不存在于磁盘本地。 它在其父目录的枚举期间进行投影（即合成）。 虚拟项与磁盘上可能存在的任何项合并，以显示父目录的完整内容。
占位符 - 对于文件：磁盘上不存在文件的内容 (主数据流) 。 文件的元数据 (名称、大小、时间戳、属性等 ) 缓存在磁盘上。 对于目录：目录的某些或所有直接后代 (目录) 中的文件和目录不存在于磁盘上，即它们仍然是虚拟的。 目录的元数据 (名称、时间戳、属性等 ) 缓存在磁盘上。
水合占位符 - 对于文件：文件的内容和元数据已缓存到磁盘。 也称为“部分文件”。 对于目录：目录绝不是水合占位符。 在磁盘上作为占位符创建的目录永远不会成为水合占位符目录。 这允许提供程序在其后备存储区中的目录中添加或删除项，并使这些更改反映在本地缓存中。
脏占位符 (水合或不) - 项的元数据已在本地修改，不再是提供程序存储中其状态的缓存。 请注意，在占位符目录下创建或删除文件或目录会导致占位符目录成为脏。
完整文件/目录 - 对于文件：文件的内容 (主数据流) 已修改。 该文件不再是提供程序存储中其状态的缓存。 在本地文件系统上创建的 (即提供程序存储区中不存在) 的文件也被视为完整文件。 对于目录：已在本地文件系统上创建的目录 (即提供程序存储中根本不存在的目录) 被视为完整目录。 在磁盘上作为占位符创建的目录永远不会成为完整目录。
逻辑删除 - 一个特殊的隐藏占位符，表示已从本地文件系统中删除的项。 枚举目录时，ProjFS 将本地项集 (占位符、完整文件等 ) 与虚拟投影项集合并。 如果某个项同时出现在本地集和投影集中，则本地项优先。 如果文件不存在，则没有本地状态，因此它将显示在枚举中。 但是，如果该项目已被删除，则将其显示在枚举中将是意外的。 将已删除的项目替换为逻辑删除会导致以下效果：
- 不显示项的枚举
- 预期项存在的文件打开失败，例如“找不到文件”。
- 仅当项不存在成功时，文件才会创建成功;ProjFS 在操作过程中删除逻辑删除。
为了说明上述状态，请考虑以下顺序，因为 ProjFS 提供程序在虚拟化根 C：\root 中具有单个文件“foo.txt”。
- 应用枚举 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。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | Windows 10 版本 1809 [仅限桌面应用] |
| 最低受支持的服务器 | Windows Server [仅限桌面应用] |
| 目标平台 | Windows |
| 标头 | projectedfslib.h |