CfConvertToPlaceholder 函数 (cfapi.h)
将同步根目录树下的现有非占位符文件或目录转换为占位符。 例如，在客户端上出现新的本地文件或目录并且同步提供程序完成将其同步到云之后，这非常有用。 请注意，没有用于传入文件系统元数据的参数 (时间戳、文件大小等 ) ;它们从本地文件逐字获取。
语法
HRESULT CfConvertToPlaceholder(
[in] HANDLE FileHandle,
[in, optional] LPCVOID FileIdentity,
[in] DWORD FileIdentityLength,
[in] CF_CONVERT_FLAGS ConvertFlags,
[out, optional] USN *ConvertUsn,
[in, out, optional] LPOVERLAPPED Overlapped
);
参数
[in] FileHandle
要转换的文件或目录的句柄。
[in, optional] FileIdentity
包含调用方提供的不透明文件或目录信息的用户模式缓冲区。 如果调用方未同时解除冻结文件，或者调用方正在转换目录，则为可选。 FileIdentity 在所有回调中传递回同步提供程序。 大小不能超过 4KB。
[in] FileIdentityLength
FileIdentity 的长度（以字节为单位）。
[in] ConvertFlags
占位符转换标志。 ConvertFlags 可以设置为以下值：
| 标志 | 描述 |
|---|---|
| CF_CONVERT_FLAG_MARK_IN_SYNC | 如果指定了这一点，则成功转换文件后，平台会将转换的占位符标记为与云同步。 |
| CF_CONVERT_FLAG_DEHYDRATE | 这仅适用于文件。 指定后，平台在成功将文件转换为占位符后将其冻结。 调用方在指定此标志时必须获取独占句柄，否则可能会发生数据损坏。 请注意，平台不验证句柄的独占性。 |
| CF_CONVERT_FLAG_ENABLE_ON_DEMAND_POPULATION | 这仅适用于目录。 指定后，它会将转换的占位符目录标记为部分填充，以便将来对其进行的任何访问都将导致 FETCH_PLACEHOLDERS 回调发送到同步提供程序。 |
| CF_CONVERT_FLAG_ALWAYS_FULL | 这仅适用于占位符文件。 将文件转换为具有此标志的占位符后，占位符将始终标记为已满。 任何解除此类占位符冻结的尝试都将失败，并 出现错误代码ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWED。 |
| CF_CONVERT_FLAG_FORCE_CONVERT_TO_CLOUD_FILE | 指定后，平台允许同步引擎以原子方式将非云文件占位符转换为 (将另一个重新分析标记/数据) 转换为云文件占位符。 请注意，API 通常无法将任何非占位符文件转换为占位符。 组合 (CF_CONVERT_FLAG_FORCE_CONVERT_TO_CLOUD_FILE |当某些提供商从另一个平台迁移到云文件平台，并且他们打算以原子方式将旧平台上的合水占位符转换为云文件平台上的脱水占位符时，CF_CONVERT_FLAG_DEHYDRATE) 在迁移方案中特别有用。 应仅传递此标志，以便将完整占位符转换为云文件占位符。 如果旧平台将完整文件实现为常规的非占位符文件，则不需要此标志。 在目录上传递此标志也会将目录转换为云文件，但 DEHYDRATE 标志不适用于目录。 即使策略 CF_PLACEHOLDER_MANAGEMENT_POLICY_CONVERT_TO_UNRESTRICTED 是使用 CfRegisterSyncRoot 指定的，也仅允许已注册/连接到云文件同步根的进程指定此标志。 注意： 仅当 PlatformVersion.IntegrationNumber 从 CfGetPlatformInfo 获取的 为 0x500 或更高时，才支持标志。 |
[out, optional] ConvertUsn
指定后，这是执行转换操作后的最终 USN 值。
[in, out, optional] Overlapped
指定并结合异步 FileHandle 时， Overlapped 允许平台异步执行 CfConvertToPlaceholder 调用。 有关更多详细信息，请参阅 备注 。
如果未指定，平台将同步执行 API 调用，而不考虑句柄的创建方式。
返回值
如果此函数成功，则返回 S_OK。 否则，将返回 HRESULT 错误代码。
注解
在文件案例中，如果调用方还打算同时解除文件冻结，否则可能会发生数据损坏，则调用方必须获取文件的独占句柄。 为了尽量减少对用户应用程序的影响，强烈建议调用方通过 CfOpenFileWithOplock) （而不是使用无共享句柄）使用适当的 oplock (获取独占性。
转换占位符：
- 要转换的文件或目录必须包含在已注册的同步根树中;它可以是同步根目录本身，也可以是任何后代目录;否则，具有 的调用将失败， HRESULT (ERROR_CLOUD_FILE_NOT_UNDER_SYNC_ROOT) 。
- 如果请求解除冻结，则必须使用未 CF_HYDRATION_POLICY_ALWAYS_FULL的有效解除冻结策略注册同步根;否则调用将失败， HRESULT (ERROR_CLOUD_FILE_NOT_SUPPORTED) 。
- 如果请求解除冻结，则不能在本地固定占位符，或者使用 的调用因 HRESULT (ERROR_CLOUD_FILE_PINNED) 失败。
- 如果请求解除冻结，则占位符必须处于同步状态，或者调用 失败， HRESULT (ERROR_CLOUD_FILE_NOT_IN_SYNC) 。
- 调用方必须对要转换的文件或目录具有 WRITE_DATA 或 WRITE_DAC 访问权限。 否则，操作将失败， HRESULT (ERROR_CLOUD_FILE_ACCESS_DENIED) 。
如果 API 在异步使用 Overlapped 时返回HRESULT_FROM_WIN32 (ERROR_IO_PENDING) ，则调用方可以使用 GetOverlappedResult 等待。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | Windows 10版本 1709 [仅限桌面应用] |
| 最低受支持的服务器 | Windows Server 2016 [仅限桌面应用] |
| 目标平台 | Windows |
| 标头 | cfapi.h |
| Library | CldApi.lib |
| DLL | CldApi.dll |