ISyncMgrHandler::Synchronize 메서드(syncmgr.h)

처리기의 동기화 항목 선택 동기화를 시작합니다.

구문

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

매개 변수

[in] ppszItemIDs

형식: LPCWSTR*

동기화할 항목을 나타내는 항목 ID 배열에 대한 포인터입니다. 각 항목 ID는 종료 null 문자를 포함하여 MAX_SYNCMGR_ID 최대 길이입니다.

[in] cItems

형식: ULONG

ppszItemIDs의 항목 수입니다.

[in] hwndOwner

형식: HWND

항목이 필요한 UI를 표시하는 데 사용하는 창에 대한 핸들입니다. 이 값은 NULL일 수 있습니다.

[in] pSessionCreator

형식: ISyncMgrSessionCreator*

ISyncMgrSessionCreator 인터페이스에 대한 포인터입니다. 이 인터페이스를 사용하면 처리기 자체가 진행률 및 이벤트를 보고하거나 백그라운드 프로세스에 진행률 및 이벤트를 보고하도록 신호를 보낼 수 있습니다.

[in] punk

형식: IUnknown*

ISyncMgrControl에 전달할 인터페이스에 대한 포인터입니다. ISyncMgrHandler::Synchronize는 사용자가 동기화 센터 폴더에서 동기화를 요청하거나 StartSyncAll과 같은 ISyncMgrControl 동기화 메서드 중 하나가 호출되는 경우 호출됩니다.

반환 값

형식: HRESULT

메서드가 성공하면 S_OK를 반환하고, 그러지 않으면 HRESULT 오류 코드를 반환합니다.

설명

ISyncMgrHandler::Synchronize 는 자체 스레드에서 호출됩니다. 동기화 센터는 해당 스레드에서 처리기 개체와 세션 작성자 개체를 인스턴스화한 다음 이 메서드를 호출합니다.

처리기는 CreateSession 메서드를 호출하여 세션 자체를 만들거나 외부 프로세스에 동기화를 수행하도록 신호를 보낼 수 있습니다. 처리기가 세션을 만드는 경우 동기화가 완료될 때까지 ISyncMgrHandler::Synchronize 메서드에서 반환해서는 안 됩니다. 처리기가 외부 프로세스에 동기화를 위임하는 경우 외부 프로세스는 CoCreateInstance 를 사용하여 ISyncMgrSessionCreator 인터페이스를 지정하는 CLSID_SyncMgrClient 개체를 만들어야 합니다. 그런 다음 프로세스는 진행률을 보고할 수 있도록 세션을 만듭니다.

사용자가 항목 또는 처리기에서 동기화를 중지하도록 선택할 수 있습니다. 또한 애플리케이션은 StopItemSync와 같은 ISyncMgrControl 인터페이스에서 중지 메서드 중 하나를 호출하여 동기화를 중지할 수 있습니다. 이러한 시나리오를 지원하기 위해 다음 메커니즘이 제공됩니다.

• ReportProgress 는 취소가 요청되었는지 여부를 나타내는 매개 변수를 반환합니다.
• 처리기는 CanContinue를 호출할 수 있습니다.

ISyncMgrHandler::Synchronize 메서드가 호출된 후 사용자가 추가 항목을 동기화하도록 요청하는 경우 처리기는 콜백의 QueryForAdditionalItems 메서드를 통해 해당 항목을 쿼리하여 동일한 세션의 새 항목을 동기화할 수 있습니다. 쿼리한 항목을 동기화하도록 선택한 경우 AddItemToSession을 호출할 수 있습니다.

일부 처리기는 동기화될 때까지 항목을 열거하지 않습니다. 처리기가 동기화 중에 이러한 항목을 검색하는 경우 세션을 통해 동기화 센터에 해당 항목을 알릴 수 있습니다. 예를 들어 처리기가 동기화 집합에 추가할 항목을 검색하는 경우 ProposeItem을 호출합니다. 항목이 성공적으로 만들어지면 처리기는 CommitItem을 호출합니다. 이 시점에서 동기화 센터는 처리기에 대해 추적하는 항목 목록에 추가합니다.

ISyncMgrHandler::Synchronize 메서드는 이전 PrepareForSync 및 Synchronize 메서드의 조합과 유사합니다. 이전 인터페이스의 경우 동기화 센터에서 PrepareForSync 를 호출한 후 즉시 동기화를 호출했습니다. ISyncMgrHandler::Synchronize 메서드는 이러한 두 메서드의 기능을 단일 호출로 제공합니다.

ISyncMgrHandler::Synchronize와 Synchronize의 또 다른 차이점은 이전 메서드가 동기화를 비동기적으로 수행해야 했다는 것입니다. 동기화는 하나 이상의 외부 스레드에서 요청을 큐에 대기한 다음 반환합니다. 그런 다음 모든 항목 동기화 가 완료되면 SynchronizeCompleted 를 호출했습니다. ISyncMgrHandler::Synchronize 는 프로시저 내(포그라운드) 동기화를 위한 동기 모델 또는 out-of-proc(백그라운드) 동기화를 위한 비동기 모델을 지원합니다.

예제

다음 예제에서는 이 메서드의 구현을 보여줍니다.

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

요구 사항