Edit

CfHydratePlaceholder function (cfapi.h)

  • Article

Hydrates a placeholder file by ensuring that the specified byte range is present on-disk in the placeholder. This is valid for files only.

Syntax

HRESULT CfHydratePlaceholder(
  [in]                HANDLE           FileHandle,
  [in]                LARGE_INTEGER    StartingOffset,
  [in]                LARGE_INTEGER    Length,
  [in]                CF_HYDRATE_FLAGS HydrateFlags,
  [in, out, optional] LPOVERLAPPED     Overlapped
);

Parameters

[in] FileHandle

Handle of the placeholder file to be hydrated. An attribute or no-access handle is sufficient.

[in] StartingOffset

The starting point offset of the placeholder file data.

[in] Length

The length, in bytes, of the placeholder file whose data must be available locally on the disk after the API completes successfully. A length of CF_EOF (defined as -1) signifies end of file. For any subrange that is not present in the placeholder, the platform will fetch the data from the sync provider and store it on disk in the placeholder.

[in] HydrateFlags

The placeholder hydration flags. HydrateFlags must be set to CF_HYDRATE_FLAG_NONE.

[in, out, optional] Overlapped

When specified and combined with an asynchronous FileHandle, Overlapped allows the platform to perform the CfHydratePlaceholder 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

The caller must have READ_DATA or WRITE_DAC access to the placeholder to be hydrated.

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

Requirements

Requirement Value
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

See also

GetOverlappedResult