CfRegisterSyncRoot 函数 (cfapi.h)

项目
04/06/2023

执行一次性同步根注册，允许同步提供程序声明整个目录树结构（根位于 SyncRootPath）作为自己的管理。

语法

HRESULT CfRegisterSyncRoot(
  [in] LPCWSTR                    SyncRootPath,
  [in] const CF_SYNC_REGISTRATION *Registration,
  [in] const CF_SYNC_POLICIES     *Policies,
  [in] CF_REGISTER_FLAGS          RegisterFlags
);

参数

[in] SyncRootPath

要注册的同步根路径。

[in] Registration

包含有关要注册的同步提供程序和同步根的信息。

ProviderName 和 ProviderVersion 是面向最终用户的字符串，每个字符串的最大长度为 255 个字符。

SyncRootIdentity 和 FileIdentity 都是可选的，如果未提供相应的缓冲区长度，也应将其设置为 0 。它们是同步提供程序将任意数据与同步根永久关联的一种方式。

平台将在同步提供程序的任何回调中向同步提供程序提供 SyncRootIdentity 。仅当回调的主题是同步根本身时，才会提供同步根 FileIdentity blob。

提供此功能只是为了方便同步提供程序，这两个 blob 在同步提供程序之外没有特殊含义。

FileIdentity 允许的最大长度为 4KB，SyncRootIdentity 允许的最大长度为 64KB。超过任一最大长度时，API 失败并 ERROR_INVALID_PARAMETER 。

ProviderId 是用于标识特定同步提供程序的 GUID。它是可选的。如果未提供，平台将使用 ProviderName 字符串的 MD5 哈希生成 GUID。此信息仅用于遥测，以便平台可以更好地关联来自同一同步提供程序的活动，更高效和更准确地，即使同步提供程序注册了不同 ProviderName 字符串的同步根。建议同步提供程序始终为其同步产品的所有版本提供相同的 GUID () 。但是，为了获得最佳用户体验，同步提供程序可以自由选择不同的 ProviderName 字符串。

[in] Policies

要注册的同步根的策略。

[in] RegisterFlags

用于注册以前和新的同步根的标志。

标志	描述
CF_REGISTER_FLAG_UPDATE	同步提供程序可以传递 CF_REGISTER_FLAG_UPDATE 来重新注册以前注册的同步根标识和策略。
CF_REGISTER_FLAG_DISABLE_ON_DEMAND_POPULATION_ON_ROOT	按需目录/文件夹填充行为由填充策略全局控制。此标志允许同步提供程序仅针对同步根本身选择退出按需填充行为，同时使同步根下所有其他目录的按需填充保持打开状态。当同步提供程序想要预填充同步根目录的即时子文件/目录时，这非常有用。
CF_REGISTER_FLAG_MARK_IN_SYNC_ON_ROOT	此标志允许同步提供程序将同步根标记为在注册时同时注册。替代方法是稍后对同步根目录调用 CfSetInSyncState 。

返回值

如果此函数成功，则返回 S_OK。否则，将返回 HRESULT 错误代码。

注解

这可以在同步提供程序安装时、首次为单个用户设置时使用，或者当用户配置另一个同步根 (（如果此方案受支持) ）。

注意

不允许两个同步根树重叠。由于文件系统禁止目录硬链接，因此两个同步根重叠的唯一方法是它们具有直接上级/后代关系。平台负责持续记住在给定卷上注册的所有同步根，并阻止任何尝试创建重叠的同步根。

同步提供程序应具有 WRITE_DATA 或 WRITE_DAC 对要注册的同步根目录的访问权限，否则注册将失败并 显示ERROR_CLOUD_FILE_ACCESS_DENIED。

同步提供程序应提供一个注册记录，其中包含同步提供程序本身和要注册的同步根的各种标识、一组平台用于根据每个同步根来调整其行为的策略，以及一组允许同步提供程序更精细地控制注册操作的注册标志。

除非显式调用为可选字段，否则所有字段都是必需的，如果不提供它们，将导致 API 调用失败并出现无效参数错误。

预期将来扩展的所有结构都以 StructSize 字段开头。调用方负责准确计算结构大小。

该平台目前支持五种类型的策略：

水化策略

混合策略允许同步提供程序控制平台应如何冻结占位符文件。它由一个主策略和一组策略修饰符组成。

主要水化策略有四个不同的值：

策略	描述
ALWAYS_FULL	平台将失败 (，ERROR_CLOUD_FILE_INVALID_REQUEST) 任何可能导致未完全水化占位符的占位符操作，其中包括 CfCreatePlaceholders、 CfDehydratePlaceholder、带解水选项的 CfUpdatePlaceholder 和具有解冻选项的 CfConvertToPlaceholder 。
FULL	平台将允许占位符脱水。当平台检测到对脱水占位符的访问时，它将确保在完成用户 IO 请求之前，占位符的完整内容在本地可用，即使请求仅请求 1 个字节。
进步	平台将允许占位符脱水。当平台检测到对脱水占位符的访问时，它将在确定从同步提供程序收到足够的数据后立即完成用户 IO 请求。但是，平台承诺继续从后台的同步提供程序请求占位符中的剩余内容，直到占位符的完整内容在本地可用或占位符上的最后一个用户句柄关闭为止。注意：选择使用 PROGRESSIVE 的同步提供程序可能不会假定混合回调从偏移 `0`量按顺序到达。换句话说，具有渐进式策略的同步提供程序应处理占位符上的随机查找。
PARTIAL	此策略与 PROGRESSIVE 非常相似，唯一的区别在于后台缺少连续水化。

目前支持三个策略修饰符。通常，只要组合不自冲突，修饰符就可以混合并与任何主策略和其他策略修饰符匹配。

修饰符	说明
VALIDATION_REQUIRED	此策略修饰符为同步提供程序提供两个保证。首先，它保证同步提供程序返回的数据在返回到用户应用程序之前始终保存到磁盘。其次，它允许同步提供程序检索之前返回到平台的相同数据，并验证其完整性。只有在同步提供程序成功确认完整性后，平台才会完成用户 IO 请求。此修饰符有助于支持端到端数据完整性，但代价是额外的磁盘 IO。
STREAMING_ALLOWED	此策略修饰符授予平台不在本地磁盘上存储同步提供程序返回的任何数据的权限。此策略修饰符与 VALIDATION_REQUIRED 互斥。指定两个标志时，API 失败并 ERROR_INVALID_PARAMETER 。
AUTO_DEHYDRATION_ALLOWED	此策略修饰符授予平台无需同步提供商帮助即可解除同步云文件占位符的冻结权限。如果没有此标志，则不允许平台直接调用 CfDehydratePlaceholder 。相反，解除云文件占位符冻结的唯一受支持方法是清除文件的固定属性并设置文件的未固定属性，然后在同步引擎收到这两个属性的目录更改通知后，以异步方式执行实际的解除冻结。指定此标志后，将允许平台直接在任何同步云文件占位符上调用 CfDehydratePlaceholder 。建议同步提供程序支持自动解除冻结。

人口政策

填充策略允许同步提供程序控制占位符命名空间 (目录和文件) 应由平台创建的方式。目前有三个主要策略未定义修饰符：

策略	描述
ALWAYS_FULL	平台假定全名空间始终在本地可用。它永远不会将任何目录枚举请求转发到同步提供程序。
FULL	当平台检测到对未完全填充目录的访问时，它将请求同步提供程序在完成用户请求之前返回目录下的所有条目。
PARTIAL	当平台检测到对未完全填充目录的访问时，它将仅从同步提供程序请求用户应用程序所需的条目。

InSync 跟踪策略

InSync 策略允许同步提供程序控制平台何时应清除占位符上的同步状态。除了始终清除任何数据修改的同步外，平台目前还可以清除三个文件属性的任意组合的更改， (ReadOnly、 System 和 Hidden) ， (CreateTime 和 LastWriteTime) 两个文件时间。这些策略可以分别应用于文件和目录。

硬链接策略

默认情况下，平台不允许在任何占位符上创建硬链接。但是，能够处理硬链接的同步提供程序可以指示平台通过 ALLOWED 策略启用支持。使用此策略，只要链接位于同一同步根或没有同步根下，应用程序就可以创建文件系统支持的任意数量的硬链接。当引入第一个同步根链接时，平台将强制对占位符进行水合，并在删除其最后一个同步根链接时将占位符还原到普通文件。与策略不兼容的硬链接创建将失败， STATUS_CLOUD_FILES_INCOMPATIBLE_HARDLINKS。与策略不兼容的占位符操作也会因 STATUS_CLOUD_FILES_INCOMPATIBLE_HARDLINKS而失败。

占位符管理策略

默认情况下，只有同步提供程序可以在同步根中执行占位符管理操作。仅当同步根处于非活动状态时，即当同步根未连接到任何同步提供程序时，非同步提供程序进程才能执行占位符管理操作。启用这些策略后，允许非同步提供程序进程在活动同步根中执行相应的占位符管理操作。 CF_PLACEHOLDER_MANAGEMENT_POLICY_DEFAULT 是默认策略，仅允许连接的同步提供程序执行任何占位符管理操作。可以任意组合指定以下策略：

策略	描述
CF_PLACEHOLDER_MANAGEMENT_POLICY_CREATE_UNRESTRICTED	在注册期间指定此策略时，任何进程都可以通过调用 CfCreatePlaceholders 在活动同步根目录中创建占位符。
CF_PLACEHOLDER_MANAGEMENT_POLICY_CONVERT_UNRESTRICTED	在注册过程中指定此策略时，任何进程都可以通过调用 CfConvertToPlaceholder 将活动同步根中的文件或目录转换为占位符。
CF_PLACEHOLDER_MANAGEMENT_POLICY_UPDATE_UNRESTRICTED	在注册期间指定此策略时，任何进程都可以通过调用 CfUpdatePlaceholder 更新活动同步根目录中的占位符。

注意

仅当从 CfGetPlatformInfo 获取的 PlatformVersion.IntegrationNumber 为或更高版本时，0x310才支持这些标志。

要求

要求	值
最低受支持的客户端	Windows 10版本 1709 [仅限桌面应用]
最低受支持的服务器	Windows Server 2016 [仅限桌面应用]
目标平台	Windows
标头	cfapi.h
Library	CldApi.lib
DLL	CldApi.dll