CF_SYNC_POLICIES 结构 (cfapi.h)

  • 项目

定义同步根使用的同步策略。

语法

typedef struct CF_SYNC_POLICIES {
  ULONG                            StructSize;
  CF_HYDRATION_POLICY              Hydration;
  CF_POPULATION_POLICY             Population;
  CF_INSYNC_POLICY                 InSync;
  CF_HARDLINK_POLICY               HardLink;
  CF_PLACEHOLDER_MANAGEMENT_POLICY PlaceholderManagement;
} CF_SYNC_POLICIES;

成员

StructSize

CF_SYNC_POLICIES 结构的大小。

Hydration

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

主策略有四个可能的值：

策略 描述
ALWAYS_FULL 选择 后ALWAYS_FULL，平台将失败，使用 HRESULT ERROR_CLOUD_FILE_INVALID_REQUEST，任何可能导致不完全水合占位符的占位符操作，其中包括 CfCreatePlaceholders、CfDehydratePlaceholder、具有脱水选项的 CfUpdatePlaceholder 和具有失水选项的 CfConvertPlaceholder。
FULL 选择 时 FULL ，平台将允许占位符脱水。 当平台检测到对脱水占位符的访问时，它将确保在完成用户 IO 请求之前，占位符的完整内容在本地可用，即使请求仅请求 1 字节。
进步 选择 时 PROGRESSIVE ，平台将允许占位符脱水。 当平台检测到对脱水占位符的访问时，一旦确定从同步提供程序接收足够的数据，它将立即完成用户 IO 请求。 但是，平台承诺继续从后台同步提供程序请求占位符中的剩余内容，直到占位符的完整内容在本地可用或关闭占位符上的最后一个用户句柄为止。

请注意，选择加入的 PROGRESSIVE 同步提供程序可能不会假定解除冻结回调从偏移量 0 按顺序到达。 换句话说，具有策略的 PROGRESSIVE 同步提供程序应处理占位符上的随机查找。
PARTIAL 该 PARTIAL 策略与 非常相似 PROGRESSIVE。 两者的唯一区别是，在政策背景下 PARTIAL 缺乏持续水合作。

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

策略修饰符 说明
VALIDATION_REQUIRED 此策略修饰符为同步提供程序提供两个保证。 首先，它保证同步提供程序返回的数据在返回到用户应用程序之前始终保存到磁盘。 其次，它允许同步提供程序检索之前返回到平台的相同数据，并验证其完整性。 只有在同步提供程序成功确认完整性后，平台才会完成用户 IO 请求。 此修饰符有助于支持端到端数据完整性，但代价是额外的磁盘 IO。
STREAMING_ALLOWED 此策略修饰符授予平台不在本地磁盘上存储同步提供程序返回的任何数据的权限。 此策略修饰符与 VALIDATION_REQUIRED互斥。 指定了两个标志时，API 将失败，并 ERROR_INVALID_PARAMETER 返回 。
AUTO_DEHYDRATION_ALLOWED 此策略修饰符授予平台无需同步提供程序帮助即可解除同步中云文件占位符的冻结权限。 如果没有此标志，则不允许平台直接调用 CfDehydratePlaceholder 。 相反，解除云文件占位符冻结的唯一受支持方法是清除文件的固定属性并设置文件的未固定属性。 然后，在同步引擎收到有关这两个属性的目录更改通知后，实际解除冻结将由同步引擎异步执行。 指定此标志后，将允许平台直接在任何同步云文件占位符上调用 CfDehydratePlaceholder 。 建议同步提供程序支持自动解除冻结。
ALLOW_FULL_RESTART_HYDRATION 当平台截获 AV 筛选器扫描文件的尝试时，此策略修饰符授予平台同步完全冻结文件的权限。 希望使用 RestartHydration 从 FetchData 回调更改 的fileSize同步提供程序必须选择加入ALLOW_FULL_RESTART_HYDRATION策略，以避免尝试扫描文件的防病毒软件和反恶意软件以及尝试使用 RestartHydration 进行更改fileSize的提供程序可能出现的死锁。

注意： 仅当 PlatformVersion.IntegrationNumber 从 CfGetPlatformInfo 获取的 为 0x500 或更高时，才支持此修饰符。

Population

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

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

InSync

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

HardLink

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

PlaceholderManagement

默认情况下，只有同步提供程序可以在同步根中执行占位符管理操作。 仅当同步根处于非活动状态 (即，当没有同步提供程序连接到同步根时，非同步提供程序进程才能执行占位符管理操作。) 启用这些策略后，允许非同步提供程序进程在活动同步根中执行相应的占位符管理操作。 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 在注册期间指定此策略时，任何进程都可以通过 API CfUpdatePlaceholder 更新活动同步根目录中的占位符。

注意

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

要求

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

另请参阅

CfCreatePlaceholders

CfConvertToPlaceholder

CfGetPlatformInfo