Метод ISyncMgrHandler::Synchronize (syncmgr.h)

Статья
08/26/2023

Инициирует синхронизацию выбора элементов синхронизации обработчика.

Синтаксис

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

Дескриптор окна, которое элемент использует для отображения любого необходимого пользовательского интерфейса. Это значение может иметь значение NULL.

[in] pSessionCreator

Тип: ISyncMgrSessionCreator*

Указатель на интерфейс ISyncMgrSessionCreator . Этот интерфейс позволяет самому обработчику сообщать о ходе выполнения и событиях или сообщать о ходе выполнения и событиях в фоновом режиме.

[in] punk

Тип: IUnknown*

Указатель на интерфейс, передаваемый в ISyncMgrControl. ISyncMgrHandler::Synchronize вызывается, когда пользователь запрашивает синхронизацию из папки Центра синхронизации или вызывается один из методов синхронизации ISyncMgrControl , например StartSyncAll.

Возвращаемое значение

Тип: HRESULT

Если этот метод завершается успешно, он возвращает S_OK. В противном случае возвращается код ошибки HRESULT .

Метод ISyncMgrHandler::Synchronize вызывается в отдельном потоке. Центр синхронизации создает экземпляр объекта обработчика и объекта создателя сеанса в этом потоке, а затем вызывает этот метод.

Обработчик может создать сам сеанс, вызвав метод CreateSession , или может сообщить внешнему процессу о выполнении синхронизации. Если обработчик создает сеанс, он не должен возвращать данные из метода ISyncMgrHandler::Synchronize до завершения синхронизации. Если обработчик делегирует синхронизацию внешнему процессу, внешний процесс должен использовать CoCreateInstance для создания объекта CLSID_SyncMgrClient, указав интерфейс ISyncMgrSessionCreator . Затем процесс создает сеанс, чтобы он смог сообщить о ходе выполнения.

Пользователь может остановить синхронизацию элемента или обработчика. Приложение также может остановить синхронизацию, вызвав один из методов stop в интерфейсе 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
Header	syncmgr.h

Поделиться через