CfUpdatePlaceholder 函数 (cfapi.h)
此 API 更改现有占位符的特征。 此 API 最有可能用于在云中修改文件，并且同步提供程序希望将修改的效果合并到占位符中。 为了支持此方案，调用方可能会传入新的文件系统元数据 (时间戳、文件大小等 ) 应用，以及/或新的 FileIdentity blob。
语法
HRESULT CfUpdatePlaceholder(
[in] HANDLE FileHandle,
[in, optional] const CF_FS_METADATA *FsMetadata,
[in, optional] LPCVOID FileIdentity,
[in] DWORD FileIdentityLength,
[in, optional] const CF_FILE_RANGE *DehydrateRangeArray,
[in] DWORD DehydrateRangeCount,
[in] CF_UPDATE_FLAGS UpdateFlags,
[in, out, optional] USN *UpdateUsn,
[in, out, optional] LPOVERLAPPED Overlapped
);
参数
[in] FileHandle
FileHandle 是要更新其元数据的文件或目录的句柄。 对于文件，如果调用方还打算同时解除文件冻结，则调用方必须获取文件的独占句柄，否则可能会发生数据损坏。 为了尽量减少对用户应用程序的影响，强烈建议调用方通过 CfOpenFileWithOplock) （而不是使用无共享句柄）使用适当的 oplock (获取独占性。
[in, optional] FsMetadata
FsMetadata 包含有关要更新的占位符的文件系统元数据，包括目录) 可选的所有时间戳、文件属性和文件大小 (。 这是一个可选字段。 如果未提供，所有这些字段在调用后保持不变。
0时间戳字段中 (CreationTime、LastAccessTime、LastWriteTime 和 ChangeTime) 的值表示对文件的当前时间戳没有更改。0FileAttributes 中的值意味着对文件的当前文件属性没有更改。- FileSize 中没有特殊值;
0FileSize 中的值将文件大小截断为0。
[in, optional] FileIdentity
FileIdentity 是包含调用方提供的不透明文件或目录信息的用户模式缓冲区。 FileIdentity blob 的大小不应超过 4KB。 FileIdentity 在所有回调中传递回同步提供程序。 如果不需要更新，或者调用方想要从要更新的占位符中删除 FileIdentity blob，则这是可选的。
[in] FileIdentityLength
FileIdentity 的长度（以字节为单位）。
[in, optional] DehydrateRangeArray
此数组指定在更新后将不再被视为有效的现有占位符的范围。
此参数的最简单用法是传递单个范围，告知平台整个字节范围的数据现在无效。 此参数的更复杂用途是提供一系列被视为无效的离散范围。 这意味着同步提供程序可以区分子文件级别的更改。 所有偏移量和长度都应 PAGE_SIZE 对齐。 平台将确保指定的所有范围在更新过程中都解除冻结。 如果任何范围的解除冻结失败，API 将失败，而不是导致文件内容撕毁。
注意
传递偏移量 为 0 和长度 CF_EOF 的单个范围将使整个文件失效 - 这与改为 CF_UPDATE_FLAG_DEHYDRATE 传递标志的效果相同。 此外，传递 CF_UPDATE_FLAG_DEHYDRATE 会导致 DehydrateRangeArray 被静默删除
[in] DehydrateRangeCount
占位符数据的一系列离散 DehydrateRangeArray 分区的计数。
[in] UpdateFlags
更新占位符的标志。 UpdateFlags 可以设置为以下值：
| 标志 | 描述 |
|---|---|
| CF_UPDATE_FLAG_VERIFY_IN_SYNC | 如果当前未在占位符上设置 IN_SYNC 属性，更新将失败。 这是为了防止从云向下同步到本地占位符的更改与本地修改占位符的数据流之间的争用。 |
| CF_UPDATE_FLAG_MARK_IN_SYNC | 成功更新占位符操作后，平台会将占位符标记为同步。 |
| CF_UPDATE_FLAG_DEHYDRATE | 仅适用于文件。 指定后，平台在成功更新占位符后解除文件冻结。 调用方在指定此标志时必须获取独占句柄，否则可能会发生数据损坏。 请注意，平台不验证句柄的独占性。 |
| CF_UPDATE_FLAG_ENABLE_ON_DEMAND_POPULATION | 仅适用于目录。 指定后，它会将更新的占位符目录标记为部分填充，以便将来对其进行的任何访问都将导致向同步提供程序发送 FETCH_PLACEHOLDERS 回调。 |
| CF_UPDATE_FLAG_DISABLE_ON_DEMAND_POPULATION | 仅适用于目录。 指定后，它会将更新的占位符目录标记为已完全填充，以便平台将来对其进行的任何访问都将由平台处理，而无需对同步提供程序进行任何回调。 |
| CF_UPDATE_FLAG_REMOVE_FILE_IDENTITY | FileIdentity 和 FileIdentityLength 将被忽略，平台将在成功调用更新后删除占位符上的现有文件标识 blob。 |
| CF_UPDATE_FLAG_CLEAR_IN_SYNC | 成功更新占位符操作时，平台会将占位符标记为未同步。 |
| CF_UPDATE_FLAG_REMOVE_PROPERTY | 平台删除占位符上的所有现有外部属性。 |
| CF_UPDATE_FLAG_PASSTHROUGH_FS_METADATA | 平台无需任何筛选即可将 CF_FS_METADATA 传递到文件系统;否则，平台将跳过设置值为 0的任何字段。 |
| CF_UPDATE_FLAG_ALWAYS_FULL | 仅适用于占位符文件。 指定后，要更新的占位符将始终标记为已满。 水合后，任何解除此类占位符文件冻结的尝试都将失败，并 出现错误代码ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWED。 |
| CF_UPDATE_FLAG_ALLOW_PARTIAL | 仅适用于占位符文件。 指定后，将清除占位符文件上的始终完整状态（如果存在），从而允许其再次脱水。 指定此标志和 CF_UPDATE_FLAG_ALWAYS_FULL 无效，因此将返回错误代码 ERROR_CLOUD_FILE_INVALID_REQUEST 。 |
[in, out, optional] UpdateUsn
在输入时， UpdateUsn 指示平台仅当文件仍具有与传入的文件相同的 USN 值时执行更新。 这与CF_UPDATE_FLAG_VERIFY_IN_SYNC用途类似 ， 但也包含本地元数据更改。 将指针传递到输入上的 USN 值 0 与传递 NULL 指针相同。
返回时， UpdateUsn 在执行更新操作后收到最终的 USN 值。
[in, out, optional] Overlapped
指定并结合异步 FileHandle 时， Overlapped 允许平台异步执行 CfUpdatePlaceholder 调用。 有关更多详细信息，请参阅 备注 。
如果未指定，平台将同步执行 API 调用，而不考虑句柄的创建方式。
返回值
如果此函数成功，则返回 S_OK。 否则，将返回 HRESULT 错误代码。
注解
更新占位符：
- 要更新的占位符必须包含在已注册的同步根树中;它可以是同步根目录本身，也可以是任何后代目录;否则，调用将失败，并出现 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 |