CfCreatePlaceholders 函数 (cfapi.h)

  • 项目

在同步根目录树下创建一个或多个新的占位符文件或目录。

语法

HRESULT CfCreatePlaceholders(
  [in]      LPCWSTR                    BaseDirectoryPath,
  [in, out] CF_PLACEHOLDER_CREATE_INFO *PlaceholderArray,
  [in]      DWORD                      PlaceholderCount,
  [in]      CF_CREATE_FLAGS            CreateFlags,
  [out]     PDWORD                     EntriesProcessed
);

参数

[in] BaseDirectoryPath

在其中创建占位符的本地目录的路径。 指定路径时，请记住以下事项：

  • 此路径必须包含在已注册的同步根树中。 它可以是同步根目录本身，也可以是任何后代目录。 否则，调用将失败并 出现STATUS_CLOUD_FILE_NOT_UNDER_SYNC_ROOT。
  • 必须使用未 CF_HYDRATION_POLICY_ALWAYS_FULL的有效解除冻结策略注册同步根，否则调用将失败并 出现STATUS_CLOUD_FILE_NOT_SUPPORTED。
  • 调用方必须具有 WRITE_DATA 或 WRITE_DAC 对要在其中创建占位符的基目录的访问权限。 否则，操作将失败并 出现STATUS_CLOUD_FILE_ACCESS_DENIED。

[in, out] PlaceholderArray

成功创建后， PlaceholderArray 包含最终 USN 值和一 STATUS_OK 条消息。 返回时，此数组包含一个 HRESULT 值，该值描述是否创建了占位符。 PlaceholderArray 指向要创建的占位符数组，相对于 BaseDirectoryPath。 数组中的每个条目都包含以下字段：

  • RelativeFileName 是要创建的子占位符（文件和目录）的名称。
  • FsMetadata 包含有关要创建的占位符的文件系统元数据，包括目录) 的所有时间戳、文件属性和文件大小 (可选 。
  • FileIdentity 和 FileIdentityLength 描述包含同步提供程序提供的不透明文件信息的用户模式缓冲区。 FileIdentity blob 的大小不应超过CF_PLACEHOLDER_MAX_FILE_IDENTITY_LENGTH (定义为 4KB) 。 FileIdentity 在所有回调中传递回同步提供程序。 这是文件的必填字段。

同步提供程序可以按占位符选择以下标志或组合：

  • CF_PLACEHOLDER_CREATE_FLAG_DISABLE_ON_DEMAND_POPULATION - 此标志仅适用于子占位符目录。 当标志存在时，新创建的子占位符目录被视为其所有子占位符目录在本地存在，因此将来访问它不会对其触发任何 FETCH_PLACEHOLDERS 回调。 当标志不存在时，新创建的占位符目录被视为部分，将来的访问将触发 FETCH_PLACEHOLDERS。
  • CF_PLACEHOLDER_CREATE_FLAG_MARK_IN_SYNC - 此标志同时适用于占位符文件和目录。 如果存在此标志，则新创建的占位符将作为 TRANSFER_PLACEHOLDERS 操作的一部分标记为同步。
  • CF_PLACEHOLDER_CREATE_FLAG_ALWAYS_FULL - 此标志仅在占位符文件上强制执行。 可以在占位符目录上设置它，但它不起作用。 当此标志存在时，新创建的占位符将始终标记为已满。 水合后，任何解除此类文件占位符冻结的尝试都将失败，并 出现错误代码ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWED。

[in] PlaceholderCount

占位符 数组中的占位符计数。

[in] CreateFlags

用于配置占位符的创建的标志。 CreateFlags 可以设置为以下值：

  • CF_CREATE_FLAG_NONE 是默认模式，即使遇到错误，API 也会处理数组中的所有条目。
  • 如果 占位符创建失败，CF_CREATE_FLAG_STOP_ON_ERROR会导致 API 立即返回。 在这种情况下，API 将返回失败代码。

[out] EntriesProcessed

处理的条目数，包括失败的条目。 如果未在 CreateFlags 中指定CF_CREATE_FLAG_STOP_ON_ERROR，则 API 将返回遇到的第一个失败代码，但会继续处理尽可能多的条目;然后，调用方必须检查数组，以查看哪个占位符创建 () 失败。

返回值

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

注解

与使用 CreateFile 创建新文件，然后使用 CfConvertToPlaceholder 将其转换为占位符相比，最好使用此函数创建占位符;为了提高效率，因为它消除了文件不是占位符的时间窗口。 函数还可以在批处理中创建多个文件或目录，这也可以更高效。

执行从云到客户端的文件或目录的初始同步，或者从云向下同步新创建的单个文件或目录时，此函数非常有用。

要求

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

另请参阅

CreateFile

CfConvertToPlaceholder