CfDehydratePlaceholder function

  • Article

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

Syntax

void STDAPI CfDehydratePlaceholder(
  _In_        HANDLE           FileHandle,
  _In_        LARGE_INTEGER    StartingOffset,
  _In_        LARGE_INTEGER    Length,
  _In_        CF_HYDRATE_FLAGS DehydrateFlags,
  _Inout_opt_ LPOVERLAPPED     Overlapped
);

Parameters

  • FileHandle [in]
    A handle to the placeholder file.

  • StartingOffset [in]
    The starting point offset of the placeholder file data.

  • Length [in]
    The length, in bytes, of the placeholder file whose data must be invalidated locally on the disk after the API completes successfully. A length of -1 signifies end of file.

  • DehydrateFlags [in]
    Placeholder dehydration flags.

  • Overlapped [in, out, optional]
    When specified and combined with an asynchronous FileHandle, Overlapped allows the platform to perform the CfDehydratePlaceholder 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

This function does not return a value.

Remarks

The caller must acquire an exclusive handle to the file 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.

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

Requirements

Minimum supported client

Windows 10, version 1709 [desktop apps only]

Minimum supported server

Windows Server 2016 [desktop apps only]

Header

 CfApi.h

Library

 CldApi.lib

DLL

 CldApi.dll