共用方式為


ISyncMgrHandler::Synchronize 方法 (syncmgr.h)

起始處理程式同步項目的選取專案同步處理。

語法

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。 提供下列機制來支持這些案例。

如果使用者要求在呼叫 ISyncMgrHandler::Synchronize 方法之後同步處理其他專案,處理程式可以透過回呼上的 QueryForAdditionalItems 方法查詢它們,以同步處理相同會話中的新專案。 如果他們選擇同步查詢的專案,就可以呼叫 AddItemToSession

某些處理程式在同步處理之前不會列舉專案。 如果處理程式在同步處理期間發現這類專案,它可以透過會話通知同步處理中心。 例如,如果處理程序發現要新增至同步集的專案,它會呼叫 ProposeItem。 成功建立項目之後,處理程式會呼叫 CommitItem。 此時,同步中心會將它新增至正在追蹤處理程式的專案清單。

ISyncMgrHandler::Synchronize 方法類似於舊版 PrepareForSyncSynchronize 方法的組合。 在較舊的介面案例中,同步處理中心會立即呼叫 PrepareForSync ,後面接著 SynchronizeISyncMgrHandler::Synchronize 方法會將這兩種方法的功能提供給單一呼叫。

ISyncMgrHandler::SynchronizeSynchronize 的另一個差異是,較舊的方法預期會以異步方式執行同步處理。 同步 處理一或多個外部線程中的要求,然後傳回。 然後它會在同步處理所有項目之後呼叫 SynchronizeCompletedISyncMgrHandler::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