CfConnectSyncRoot 函数 (cfapi.h)

启动同步提供程序与同步筛选器 API 之间的双向通信。

语法

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
);

参数

[in] SyncRootPath

同步根路径。

[in] CallbackTable

要注册的回调表。 此参数是同步提供程序告知库对来自平台的各种类型的请求调用哪些函数的方式。 它是包含回调类型和关联的函数指针的结构数组。 同步提供程序只需注册其实现的回调。 CallbackTable 数组应始终以CF_CALLBACK_REGISTRATION_END结尾。

[in, optional] CallbackContext

提供 CallbackContext 是为了方便同步提供程序。 每当在当前同步根上调用某个回调函数时，平台都会记住此 CallbackContext ，并将其传递回同步提供程序。 CallbackContext 的一个好用是指向同步提供程序自己的结构的指针，该结构维护此连接的状态。

[in] ConnectFlags

同步提供程序可以通过将 ConnectFlags 传递到此 API 来请求在调用其回调时提供其他信息。 支持以下标志：

请求	说明
REQUEST_PROCESS_INFO	指定此标志时，平台将在回调参数中返回冻结进程的完整图像路径。
REQUIRE_FULL_FILE_PATH	指定此标志时，平台将返回回调参数中请求的占位符的完整路径。
BLOCK_SELF_IMPLICIT_HYDRATION	当防病毒软件扫描非水合云文件占位符上的同步提供程序的文件系统活动时，不会通过 CfHydratePlaceholder 执行隐式解除冻结。 这种隐式水合是预料不到的。 如果同步提供程序从未启动隐式解除冻结操作本身，它可以指示平台阻止所有此类隐式解除冻结操作，而不是稍后失败 FETCH_DATA 回调。

[out] ConnectionKey

成功返回后，此 API 会将不透明的 ConnectionKey 返回到同步提供程序。 这表示刚刚建立的信道，同步提供程序可能会记住 ConnectionKey ，并在调用各种同步提供程序 API 时传递它。 如果同步提供程序只希望建立单个连接，则可以将 ConnectionKey 存储在全局中。 但是，平台支持单个提供程序进程同时连接到多个不同的同步根，并且对于每个连接，将返回不同的 ConnectionKey 。 存储每个 ConnectionKey 的好位置是在 由 CallbackContext 标识的同步提供程序的内部结构内。

返回值

如果此函数成功，则返回 S_OK。 否则，将返回 HRESULT 错误代码。

注解

这会在同步提供程序和同步筛选器之间启动双向信道。 同步提供程序通常在启动后不久调用此 API，一旦它已初始化并准备好为请求提供服务。

在连接之前，必须在平台中注册同步根。 对于给定的 SyncRootPath，在任何给定时间最多可以建立一个连接。

同步提供程序应具有 WRITE_DATA 或 WRITE_DAC 要连接的同步根的访问权限，否则 API 将因 HRESULT (ERROR_CLOUD_FILE_ACCESS_DENIED) 而失败。

要求

要求	值
最低受支持的客户端	Windows 10版本 1709 [仅限桌面应用]
最低受支持的服务器	Windows Server 2016 [仅限桌面应用]
目标平台	Windows
标头	cfapi.h
Library	CldApi.lib
DLL	CldApi.dll

另请参阅

CfHydratePlaceholder