CfCreatePlaceholders function (cfapi.h)

Creates one or more new placeholder files or directories under a sync root tree.


HRESULT CfCreatePlaceholders(
  LPCWSTR                    BaseDirectoryPath,
  DWORD                      PlaceholderCount,
  CF_CREATE_FLAGS            CreateFlags,
  PDWORD                     EntriesProcessed



Path to the local directory in which the placeholders are created. This path must be under the sync root of the provider.


On successful creation, the PlaceholderArray contains the final USN value and a STATUS_OK message. On return, this array contains an HRESULT value describing whether the placeholder was created or not.


The count of placeholders in the PlaceholderArray.


Flags for configuring the creation of a placeholder.


The number of entries processed, including failed entries.

Return value

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


Creating a placeholder with this function is preferred compared to creating a new file with CreateFile and then converting it to a placeholder with CfConvertToPlaceholder; both for efficiency and because it eliminates the time window where the file is not a placeholder. The function can also create multiple files or directories in a batch, which can also be more efficient.

This function is useful when performing an initial sync of files or directories from the cloud down to the client, or when syncing down a newly created single file or directory from the cloud.


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