CfConnectSyncRoot function (cfapi.h)

Initiates bi-directional communication between a sync provider and the sync filter API.

Syntax

HRESULT CfConnectSyncRoot(
  [in]           LPCWSTR                        SyncRootPath,
  [in]           const CF_CALLBACK_REGISTRATION *CallbackTable,
  [in, optional] LPCVOID                        CallbackContext,
  [in]           CF_CONNECT_FLAGS               ConnectFlags,
  [out]          CF_CONNECTION_KEY              *ConnectionKey
);

Parameters

[in] SyncRootPath

The path to the sync root.

[in] CallbackTable

The callback table to be registered. This parameter is how the sync provider tells the library which functions to call for various types of requests from the platform. It is an array of structures containing a callback type and associated function pointer. The sync provider only needs to register the callbacks it implements. The CallbackTable array should always end with CF_CALLBACK_REGISTRATION_END.

[in, optional] CallbackContext

CallbackContext is provided for the convenience of the sync provider. The platform will remember this CallbackContext and pass it back to the sync provider any time one of its callback functions is invoked on the current sync root. A good use for the CallbackContext would be a pointer into the sync provider’s own structure that maintains state for this connection.

[in] ConnectFlags

The sync provider can request additional information be provided when its callbacks are invoked by passing ConnectFlags to this API. The following flags are supported:

[out] ConnectionKey

On successful return, this API will return an opaque ConnectionKey back to the sync provider. This represents the communication channel that was just established, and the sync provider may remember the ConnectionKey and pass it when calling various sync provider APIs. If a sync provider only expects to establish a single connection, then the ConnectionKey could be stored in a global. However, the platform supports a single provider process connecting to multiple different sync roots at the same time, and for each connection there will be a different ConnectionKey returned. A good place to store each ConnectionKey would be inside the sync provider’s internal structure identified by the CallbackContext.

Return value

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

Remarks

This initiates a bi-directional communication channel between the sync provider and the sync filter. A sync provider typically calls this API soon after startup, once it has been initialized and is ready to service requests.

The sync root must be registered with the platform prior to being connected. For a given SyncRootPath, there can be at most one connection established at any given time.

The sync provider should have WRITE_DATA or WRITE_DAC access to the sync root to be connected or the API will be failed with HRESULT(ERROR_CLOUD_FILE_ACCESS_DENIED).

Requirements

See also

CfHydratePlaceholder