CfCreatePlaceholders function (cfapi.h)

• 12/05/2018
• 2 minutes to read

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

Syntax

HRESULT CfCreatePlaceholders(
  LPCWSTR                    BaseDirectoryPath,
  CF_PLACEHOLDER_CREATE_INFO *PlaceholderArray,
  DWORD                      PlaceholderCount,
  CF_CREATE_FLAGS            CreateFlags,
  PDWORD                     EntriesProcessed
);

Parameters

BaseDirectoryPath

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

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.

PlaceholderCount

The count of placeholders in the PlaceholderArray.

CreateFlags

Flags for configuring the creation of a placeholder.

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.

Remarks

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.

Requirements