Método ISyncMgrHandler::Synchronize (syncmgr.h)

Inicia uma sincronização de uma seleção dos itens de sincronização do manipulador.

Sintaxe

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

Parâmetros

[in] ppszItemIDs

Tipo: LPCWSTR*

Um ponteiro para uma matriz de IDs de item que representam os itens a serem sincronizados. Cada ID de item tem comprimento máximo MAX_SYNCMGR_ID incluindo o caractere nulo de terminação.

[in] cItems

Tipo: ULONG

O número de itens em ppszItemIDs.

[in] hwndOwner

Digite: HWND

Um identificador para a janela que o item usa para exibir qualquer interface do usuário necessária. Esse valor pode ser NULL.

[in] pSessionCreator

Tipo: ISyncMgrSessionCreator*

Um ponteiro para uma interface ISyncMgrSessionCreator . Essa interface permite que o próprio manipulador relate o progresso e os eventos ou sinalize um processo em segundo plano para relatar o progresso e os eventos.

[in] punk

Tipo: IUnknown*

Um ponteiro para uma interface a ser passada para ISyncMgrControl. ISyncMgrHandler::Synchronize é chamado quando um usuário solicita uma sincronização da pasta Do Centro de Sincronização ou quando um dos métodos de sincronização ISyncMgrControl é chamado, como StartSyncAll.

Retornar valor

Tipo: HRESULT

Se o método for bem-sucedido, ele retornará S_OK. Caso contrário, ele retornará um código de erro HRESULT.

Comentários

ISyncMgrHandler::Synchronize é chamado em seu próprio thread. O Sync Center instancia o objeto manipulador e o objeto criador da sessão nesse thread e, em seguida, chama esse método.

O manipulador pode criar a sessão em si chamando o método CreateSession ou pode sinalizar um processo externo para executar a sincronização. Se o manipulador criar a sessão, ele não deverá retornar do método ISyncMgrHandler::Synchronize até que a sincronização seja concluída. Se o manipulador delegar a sincronização a um processo externo, o processo externo deverá usar CoCreateInstance para criar o objeto CLSID_SyncMgrClient, especificando a interface ISyncMgrSessionCreator . Em seguida, o processo cria a sessão para que ela possa relatar o progresso.

Um usuário pode optar por interromper a sincronização em um item ou manipulador. Um aplicativo também pode interromper a sincronização chamando um dos métodos stop na interface ISyncMgrControl , como StopItemSync. Os mecanismos a seguir são fornecidos para dar suporte a esses cenários.

• ReportProgress retorna um parâmetro que indica se o cancelamento foi solicitado.
• O manipulador pode chamar CanContinue.

Se o usuário solicitar a sincronização de itens adicionais após o método ISyncMgrHandler::Synchronize ter sido chamado, o manipulador poderá sincronizar os novos itens na mesma sessão consultando-os por meio do método QueryForAdditionalItems no retorno de chamada. Se optarem por sincronizar um item que consultaram, eles poderão chamar AddItemToSession.

Alguns manipuladores não enumerarão um item até que ele tenha sido sincronizado. Se o manipulador descobrir esses itens durante uma sincronização, ele poderá informar o Sync Center sobre eles por meio da sessão. Por exemplo, se o manipulador descobrir um item a ser adicionado ao conjunto de sincronização, ele chamará ProposeItem. Depois que o item tiver sido criado com êxito, o manipulador chamará CommitItem. Nesse ponto, o Sync Center o adiciona à lista de itens que ele está rastreando para o manipulador.

O método ISyncMgrHandler::Synchronize é análogo a uma combinação dos métodos PrepareForSync e Synchronize mais antigos. No caso da interface mais antiga, o Sync Center chamado PrepareForSync imediatamente seguido de Synchronize. O método ISyncMgrHandler::Synchronize fornece a funcionalidade desses dois métodos em uma única chamada.

Outra diferença entre ISyncMgrHandler::Synchronize e Synchronize é que o método mais antigo era esperado para executar a sincronização de forma assíncrona. Sincronize a solicitação enfileirada em um ou mais threads externos e, em seguida, retornada. Em seguida, ele chamou SynchronizeCompleted depois de terminar de sincronizar todos os itens. ISyncMgrHandler::Synchronize dá suporte a um modelo síncrono para sincronização in-proc (primeiro plano) ou um modelo assíncrono para sincronização fora do proc (segundo plano).

Exemplos

O exemplo a seguir mostra uma implementação desse método.

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

Requisitos