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*

項目識別子陣列的指標，表示要同步處理的專案。每個項目標識碼的長度上限MAX_SYNCMGR_ID包括終止 的 Null 字元。

[in] cItems

類型： ULONG

ppszItemIDs 中的項目數。

[in] hwndOwner

類型： HWND

項目用來顯示任何必要UI之視窗的句柄。此值可以是 NULL。

[in] pSessionCreator

類型： ISyncMgrSessionCreator*

ISyncMgrSessionCreator 介面的指標。這個介面可讓處理程式本身報告進度和事件，或向背景進程發出訊號來報告進度和事件。

[in] punk

類型： IUnknown*

要傳遞至 ISyncMgrControl 之介面的指標。當使用者向 Sync Center 資料夾要求同步處理，或呼叫其中一個 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 ，後面接著 Synchronize。 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)

語法

參數

傳回值

備註

範例

規格需求

意見反應

其他資源