CfUpdatePlaceholder function (cfapi.h)

Updates characteristics of the placeholder file or directory.


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

A handle to the file or directory whose metadata is to be updated.

[in, optional] FsMetadata

File system metadata to be updated for the placeholder. Values of 0 for the metadata indicate there are no updates.

[in, optional] FileIdentity

A user mode buffer that contains file or directory information supplied by the caller. Should not exceed 4KB in size.

[in] FileIdentityLength

Length, in bytes, of the FileIdentity.

[in, optional] DehydrateRangeArray

A range of an existing placeholder that will no longer be considered valid after the call to CfUpdatePlaceholder.

[in] DehydrateRangeCount

The count of a series of discrete DehydrateRangeArray partitions of placeholder data.

[in] UpdateFlags

Update flags for placeholders.

[in, out, optional] UpdateUsn

On input, UpdateUsn instructs the platform to only perform the update if the file still has the same USN value as the one passed in. This serves a similar purpose to CF_UPDATE_FLAG_VERIFY_IN_SYNC but also encompasses local metadata changes.

On return, UpdateUsn receives the final USN value after update actions were performed.

[in, out, optional] Overlapped

When specified and combined with an asynchronous FileHandle, Overlapped allows the platform to perform the CfUpdatePlaceholder call asynchronously. See the Remarks for more details.

If not specified, the platform will perform the API call synchronously, regardless of how the handle was created.

Return value

If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.


To update a placeholder:

  • The placeholder to be updated must be contained in a registered sync root tree; it can be the sync root directory itself, or any descendant directory; otherwise, the call with be failed with HRESULT(ERROR_CLOUD_FILE_NOT_UNDER_SYNC_ROOT).
  • If dehydration is requested, the sync root must be registered with a valid hydration policy that is not CF_HYDRATION_POLICY_ALWAYS_FULL; otherwise the call will be failed with HRESULT(ERROR_CLOUD_FILE_NOT_SUPPORTED).
  • If dehydration is requested, the placeholder must not be pinned locally or the call with be failed with HRESULT(ERROR_CLOUD_FILE_PINNED).
  • If dehydration is requested, the placeholder must be in sync or the call with be failed with HRESULT(ERROR_CLOUD_FILE_NOT_IN_SYNC).
  • The caller must have WRITE_DATA or WRITE_DAC access to the placeholder to be updated. Otherwise the operation will be failed with HRESULT(ERROR_CLOUD_FILE_ACCESS_DENIED).

If the API returns HRESULT_FROM_WIN32(ERROR_IO_PENDING) when using Overlapped asynchronously, the caller can then wait using GetOverlappedResult.


Minimum supported client Windows 10, version 1709 [desktop apps only]
Minimum supported server Windows Server 2016 [desktop apps only]
Target Platform Windows
Header cfapi.h
Library CldApi.lib
DLL CldApi.dll