CfGetPlaceholderRangeInfo function (cfapi.h)

Gets range information about a placeholder file or folder.

Syntax

HRESULT CfGetPlaceholderRangeInfo(
  [in]            HANDLE                          FileHandle,
  [in]            CF_PLACEHOLDER_RANGE_INFO_CLASS InfoClass,
  [in]            LARGE_INTEGER                   StartingOffset,
  [in]            LARGE_INTEGER                   Length,
  [out]           PVOID                           InfoBuffer,
  [in]            DWORD                           InfoBufferLength,
  [out, optional] PDWORD                          ReturnedLength
);

Parameters

[in] FileHandle

The handle of the placeholder file to be queried.

[in] InfoClass

Types of the range of placeholder data.

[in] StartingOffset

Offset of the starting point of the range of data.

[in] Length

Length of the range of data. A provider can specify CF_EOF for Length to indicate that range for which information is requested is from StartingOffset to end of the file.

[out] InfoBuffer

Pointer to a buffer that will receive the data. The buffer is an array of CF_FILE_RANGE structures, which are offset/length pairs, describing the requested ranges.

[in] InfoBufferLength

The length of InfoBuffer in bytes.

[out, optional] ReturnedLength

The length of the returned range of placeholder data in the InfoBuffer.

Return value

If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. Some common error codes are listed in the following table:

Error code Meaning
HRESULT_FROM_WIN32( ERROR_HANDLE_EOF ) This means that StartingOffset >= the position of the end of the file.
HRESULT_FROM_WIN32( ERROR_MORE_DATA ) This implies that the next CF_FILE_RANGE entry doesn't fit in the provided buffer. The caller should verify if any entry is received or not using the returned InfoBufferWritten value.

Remarks

Unlike most placeholder APIs that take a file handle, this one does not modify the file in any way, therefore the file handle only requires READ_ATTRIBUTES access.

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

CfGetPlaceholderRangeInfoForHydration