ISyncMgrHandler：：Synchronize 方法 (syncmgr.h)

项目
03/02/2024

启动处理程序的同步项选择的同步。

语法

HRESULT Synchronize(
  [in] LPCWSTR                *ppszItemIDs,
  [in] ULONG                  cItems,
  [in] HWND                   hwndOwner,
  [in] ISyncMgrSessionCreator *pSessionCreator,
  [in] IUnknown               *punk
);

参数

[in] ppszItemIDs

类型： LPCWSTR*

指向表示要同步的项的项 ID 数组的指针。每个项 ID 的最大长度MAX_SYNCMGR_ID包括终止 null 字符。

[in] cItems

类型： ULONG

ppszItemIDs 中的项数。

[in] hwndOwner

类型：HWND

项用于显示任何必要 UI 的窗口句柄。此值可以为 NULL。

[in] pSessionCreator

类型： ISyncMgrSessionCreator*

指向 ISyncMgrSessionCreator 接口的指针。此接口使处理程序本身能够报告进度和事件，或向后台进程发出信号以报告进度和事件。

[in] punk

类型： IUnknown*

指向要传递给 ISyncMgrControl 的接口的指针。当用户从同步中心文件夹请求同步或调用其中一个 ISyncMgrControl 同步方法（如 StartSyncAll）时，将调用 ISyncMgrHandler：：Synchronize。

返回值

类型： HRESULT

如果该方法成功，则返回 S_OK。否则，将返回 HRESULT 错误代码。

注解

在其自己的线程上调用 ISyncMgrHandler：：Synchronize。同步中心在该线程上实例化处理程序对象和会话创建者对象，然后调用此方法。

处理程序可以通过调用 CreateSession 方法创建会话本身，也可以向外部进程发出信号以执行同步。如果处理程序创建会话，则在同步完成之前，它不应从 ISyncMgrHandler：：Synchronize 方法返回。如果处理程序将同步委托给外部进程，则外部进程应使用 CoCreateInstance 创建 CLSID_SyncMgrClient 对象，并指定 ISyncMgrSessionCreator 接口。然后，该进程会创建会话，以便它可以报告进度。

用户可以选择停止对项或处理程序的同步。应用程序还可以通过在 ISyncMgrControl 接口上调用停止方法之一（如 StopItemSync）来停止同步。提供了以下机制来支持这些方案。

ReportProgress 返回一个参数，指示是否已请求取消。
处理程序可以调用 CanContinue。

如果用户在调用 ISyncMgrHandler：：Synchronize 方法后要求同步其他项，处理程序可以通过回调上的 QueryForAdditionalItems 方法查询新项来同步同一会话中的新项。如果他们选择同步查询的项，则可以调用 AddItemToSession。

在项目同步之前，某些处理程序不会枚举项。如果处理程序在同步期间发现此类项，它可以通过会话通知同步中心。例如，如果处理程序发现要添加到同步集的项，它将调用 ProposeItem。成功创建项后，处理程序将调用 CommitItem。此时，同步中心会将其添加到它正在跟踪处理程序的项列表中。

ISyncMgrHandler：：Synchronize 方法类似于旧式 PrepareForSync 和 Synchronize 方法的组合。对于较旧的接口，同步中心立即调用 PrepareForSync ，然后 是同步。 ISyncMgrHandler：：Synchronize 方法在单个调用中提供这两种方法的功能。

ISyncMgrHandler：：Synchronize 和 Synchronize 之间的另一个区别是，旧方法应异步执行同步。同步在一个或多个外部线程中将请求排队，然后返回。然后，它在完成同步所有项后调用 SynchronizeCompleted 。 ISyncMgrHandler：：Synchronize 支持将同步模型用于过程内 (前台) 同步，或支持用于过程外 (后台) 同步的异步模型。

示例

以下示例演示此方法的实现。

STDMETHODIMP CMyDeviceHandler::Synchronize(__in_ecount(cItems) LPCWSTR *ppszItemIDs,
                              __in ULONG                   cItems,
                              __in HWND                    hwndOwner,
                              __in ISyncMgrSessionCreator *pCreator,
                              __in_opt IUnknown           *punk)
{
    HRESULT hr = S_OK;

    // Create the session since we are going to perform synchronization in
    // this method.
    ISyncMgrSyncCallback *pCallback = NULL;
    
    hr = pCreator->CreateSession(_szHandlerID, ppszItemIDs, cItems,&pCallback);
    if (SUCCEEDED(hr))
    {
        for (ULONG iItem = 0; iItem < cItems; iItem++)
        {
            SYNCMGR_CANCEL_REQUEST nCancelRequest = SYNCMGR_CR_NONE;
            ULONG   uCurrentStep = 1;
            ULONG   cMaxSteps    = 50;
            LPCWSTR pszItemID    = ppszItemIDs[iItem];
            WCHAR   szProgressText[256];

            // Find the item.
            CMyDeviceSyncItem *pItem = NULL;
            
            // _FindItem is a private class function that abstracts the
            // specifics of how the handler has implemented its storage of 
            // its items. Its internal details can remain transparent as 
            // they have no bearing on this example.
            hr = _FindItem(pszItemID, &pItem);
            if (FAILED(hr))
            {
                // _ReportProgress is another private class function that loads
                // string resources so that reports can be localized rather 
                // than use hard-coded strings. Its internal details have no 
                // bearing on this example.
                _ReportProgress(pCallback, 
                                pszItemID, 
                                IDS_ITEM_NOTFOUND,
                                SYNCMGR_PS_FAILED, 
                                0, 
                                0, 
                                &nCancelRequest);

                if (nCancelRequest != SYNCMGR_CR_NONE)
                {
                    break;
                }
                continue;
            }

            // Send the initial progress report to set min and max values.
            _ReportProgress(pCallback, 
                            pszItemID, 
                            IDS_START_ITEM_SYNC,
                            SYNCMGR_PS_UPDATING, 
                            uCurrentStep, 
                            cMaxSteps,
                            &nCancelRequest);

            for (; uCurrentStep < cMaxSteps; uCurrentStep++)
            {
                if (nCancelRequest != SYNCMGR_CR_NONE)
                {
                    break;
                }

                // Report progress.
                StringCchPrintfW(szProgressText, 
                                 ARRAYSIZE(szProgressText),
                                 L"Entry %d of %d", 
                                 uCurrentStep + 1, 
                                 cMaxSteps);

                pCallback->ReportProgress(pszItemID, 
                                          szProgressText,
                                          SYNCMGR_PS_UPDATING,
                                          uCurrentStep, 
                                          cMaxSteps,
                                          &nCancelRequest);

                // The code that accomplishes the synchronization goes here.
                // This code depends entirely on the nature of the items
                // involved in the sync. 
            }

            // Send the final progress report for this item.
            if (nCancelRequest != SYNCMGR_CR_NONE);
            {
                SYNCMGR_PROGRESS_STATUS nStatus = SYNCMGR_PS_SUCCEEDED;
                if (FAILED(hr))
                {
                    nStatus = SYNCMGR_PS_FAILED;
                }
                _ReportProgress(pCallback, 
                                ppszItemIDs[iItem], 
                                IDS_ITEM_SYNC_DONE,
                                nStatus, 
                                uCurrentStep - 1, 
                                cMaxSteps, 
                                &nCancelRequest);
            }

            hr = S_OK;

            if (nCancelRequest == SYNCMGR_CR_CANCEL_ALL)
            {
                 break;
            }
        }

        pCallback->Release();
    }

    return hr;
}

要求

要求	值
最低受支持的客户端	Windows Vista [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 [仅限桌面应用]
目标平台	Windows
标头	syncmgr.h

通过

ISyncMgrHandler：：Synchronize 方法 (syncmgr.h)

语法

参数

返回值

注解

示例

要求

反馈

其他资源