CfCreatePlaceholders function (cfapi.h)

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


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

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

[in, out] PlaceholderArray

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.

[in] PlaceholderCount

The count of placeholders in the PlaceholderArray.

[in] CreateFlags

Flags for configuring the creation of a placeholder.

[out] EntriesProcessed

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