CfSetPinState function (cfapi.h)

This function sets the pin state of a placeholder, which represents a user’s intent. Any application, not just the sync provider, can call this function.

Syntax

HRESULT CfSetPinState(
  [in]                HANDLE           FileHandle,
  [in]                CF_PIN_STATE     PinState,
  [in]                CF_SET_PIN_FLAGS PinFlags,
  [in, out, optional] LPOVERLAPPED     Overlapped
);

Parameters

[in] FileHandle

The handle of the placeholder file. The platform properly synchronizes the operation with other active requests. An attribute or no-access handle is sufficient. The caller must have READ_DATA or WRITE_DAC access to the placeholder. Otherwise, the operation fails with STATUS_CLOUD_FILE_ACCESS_DENIED.

[in] PinState

The pin state of the placeholder file. For a list of valid PinState values, see CF_PIN_STATE.

[in] PinFlags

The pin state flags. Set PinFlags to one of the following values:

• If you specify CF_SET_PIN_FLAG_RECURSE, the platform applies the pin state to FileHandle and every file recursively beneath it. This flag is relevant only if FileHandle is a handle to a directory.
• If you specify CF_SET_PIN_FLAG_RECURSE_ONLY, the platform applies the pin state to every file recursively beneath FileHandle, but not to FileHandle itself.
• If you specify CF_SET_PIN_FLAG_RECURSE_STOP_ON_ERROR, the platform stops the recursion when it encounters the first error. Otherwise, the platform skips the error and continues the recursion.

Use CF_SET_PIN_FLAG_NONE to specify no flags.

[in, out, optional] Overlapped

Allows the call to be performed asynchronously. See the Remarks section for more details.

Return value

If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

When you specify and combine an asynchronous FileHandle with Overlapped, the platform can perform the call asynchronously.

You must initialize the overlapped structure with an event to wait on. If this function returns HRESULT_FROM_WIN32(ERROR_IO_PENDING), you can wait by using GetOverlappedResult. If you don't specify this parameter, the platform performs the API call synchronously, regardless of how you created the handle.

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

CF_PIN_STATE

CF_SET_PIN_FLAGS