CfUpdatePlaceholder function (cfapi.h)

This API changes characteristics of an existing placeholder. The most likely use of this API is when a file has been modified in the cloud, and the sync provider wishes to incorporate the effects of that modification into a placeholder. To support this scenario, the caller may pass in new file system metadata (timestamps, file size, etc.) to apply, and/or a new FileIdentity blob.

Syntax

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
);

Parameters

[in] FileHandle

FileHandle is a handle to the file or directory whose metadata is to be updated. In the case of a file, the caller must acquire an exclusive handle to the file if it also intends to dehydrate the file at the same time or data corruption can occur. To minimize the impact on user applications, it is highly recommended that the caller obtain the exclusiveness using proper oplocks (via CfOpenFileWithOplock) as opposed to using a share-nothing handle.

[in, optional] FsMetadata

FsMetadata contains file system metadata about the placeholder to be updated, including all timestamps, file attributes, and file size (optional for directories). This is an optional field. If not provided, all these fields remain intact after the call.

• A 0 value in a timestamp field (CreationTime, LastAccessTime, LastWriteTime, and ChangeTime) means no change to the current timestamp on the file.
• A 0 value in FileAttributes means no change to the current file attributes on the file.
• There is no special value in FileSize; a 0 value in FileSize truncates the file size to 0.

[in, optional] FileIdentity

FileIdentity is a user mode buffer that contains the opaque file or directory information supplied by the caller. The FileIdentity blob should not exceed 4KB in size. FileIdentity gets passed back to the sync provider in all callbacks. This is optional if an update is not needed or if the caller wants to remove the FileIdentity blob from the placeholder to be updated.

[in] FileIdentityLength

Length, in bytes, of the FileIdentity.

[in, optional] DehydrateRangeArray

This array specifies ranges of the existing placeholder that will no longer be considered valid after the update.

The simplest use of this parameter is to pass a single range, telling the platform that the entire byte range of data is now invalid. A more complex use of this parameter is to provide a series of discrete ranges to be considered invalid. This implies that the sync provider can distinguish changes on a sub-file level. All the offsets and lengths should be PAGE_SIZE Aligned. The platform will ensure that all the ranges specified get dehydrated as part of the update. If dehydration of any ranges fails the API will fail rather than result in torn file contents.

[in] DehydrateRangeCount

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

[in] UpdateFlags

Update flags for placeholders. UpdateFlags can be set to the following values:

[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. Passing a pointer to a USN value of 0 on input is the same as passing a NULL pointer.

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.

Remarks

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 will 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 will be failed with HRESULT(ERROR_CLOUD_FILE_PINNED).
• If dehydration is requested, the placeholder must be in sync or the call will 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.

Requirements

See also

CfOpenFileWithOplock

CF_UPDATE_FLAGS