Metodo ISyncMgrHandler::Sync (syncmgr.h)

Avvia una sincronizzazione di una selezione degli elementi di sincronizzazione del gestore.

Sintassi

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

Parametri

[in] ppszItemIDs

Tipo: LPCWSTR*

Puntatore a una matrice di ID elemento che rappresentano gli elementi da sincronizzare. Ogni ID elemento è di lunghezza massima MAX_SYNCMGR_ID incluso il carattere null terminante.

[in] cItems

Tipo: ULONG

Numero di elementi in ppszItemIDs.

[in] hwndOwner

Tipo: HWND

Handle alla finestra utilizzata dall'elemento per visualizzare qualsiasi interfaccia utente necessaria. Questo valore può essere NULL.

[in] pSessionCreator

Tipo: ISyncMgrSessionCreator*

Puntatore a un'interfaccia ISyncMgrSessionCreator . Questa interfaccia consente al gestore stesso di segnalare lo stato di avanzamento e gli eventi oppure di segnalare un processo in background per segnalare lo stato di avanzamento e gli eventi.

[in] punk

Tipo: IUnknown*

Puntatore a un'interfaccia da passare a ISyncMgrControl. ISyncMgrHandler::Sync viene chiamato quando un utente richiede una sincronizzazione dalla cartella Sync Center o quando viene chiamato uno dei metodi di sincronizzazione ISyncMgrControl , ad esempio StartSyncAll.

Valore restituito

Tipo: HRESULT

Se questo metodo ha esito positivo, restituisce S_OK. In caso contrario, restituisce un codice di errore HRESULT .

Commenti

ISyncMgrHandler::Sync viene chiamato nel proprio thread. Sync Center crea un'istanza dell'oggetto gestore e dell'oggetto creatore sessione in tale thread e quindi chiama questo metodo.

Il gestore può creare la sessione stessa chiamando il metodo CreateSession oppure può segnalare un processo esterno per eseguire la sincronizzazione. Se il gestore crea la sessione, non deve restituire dal metodo ISyncMgrHandler::Sync fino al completamento della sincronizzazione. Se il gestore delega la sincronizzazione a un processo esterno, il processo esterno deve usare CoCreateInstance per creare l'oggetto CLSID_SyncMgrClient, specificando l'interfaccia ISyncMgrSessionCreator . Il processo crea quindi la sessione in modo che possa segnalare lo stato di avanzamento.

Un utente può scegliere di arrestare la sincronizzazione in un elemento o in un gestore. Un'applicazione può anche arrestare la sincronizzazione chiamando uno dei metodi di arresto nell'interfaccia ISyncMgrControl , ad esempio StopItemSync. I meccanismi seguenti vengono forniti per supportare questi scenari.

• ReportProgress restituisce un parametro che indica se è stato richiesto l'annullamento.
• Il gestore può chiamare CanContinue.

Se l'utente chiede di sincronizzare elementi aggiuntivi dopo che è stato chiamato il metodo ISyncMgrHandler::Sync , il gestore può sincronizzare i nuovi elementi nella stessa sessione eseguendo query tramite il metodo QueryForAdditionalItems nel callback. Se scelgono di sincronizzare un elemento per cui hanno query, possono chiamare AddItemToSession.

Alcuni gestori non enumereranno un elemento finché non è stato sincronizzato. Se il gestore individua tali elementi durante una sincronizzazione, può informare il Centro sincronizzazione su di essi tramite la sessione. Ad esempio, se il gestore individua un elemento da aggiungere al set di sincronizzazione, chiama ProposeItem. Dopo aver creato correttamente l'elemento, il gestore chiama CommitItem. A questo punto, Sync Center lo aggiunge all'elenco di elementi che esegue il rilevamento per il gestore.

Il metodo ISyncMgrHandler::Sync è analogo a una combinazione dei metodi PrepareForSync e Sync precedenti. Nel caso dell'interfaccia precedente, Sync Center denominato PrepareForSync immediatamente seguito da Sync. Il metodo ISyncMgrHandler::Sync fornisce la funzionalità di questi due metodi in una singola chiamata.

Un'altra differenza tra ISyncMgrHandler::Sync e Sync è che il metodo precedente era previsto per eseguire la sincronizzazione in modo asincrono. Sincronizzare la richiesta in una o più thread esterni e quindi restituita. Viene quindi chiamato SyncCompleted dopo aver completato la sincronizzazione di tutti gli elementi. ISyncMgrHandler::Sync supporta un modello sincrono per la sincronizzazione in primo piano o un modello asincrono per la sincronizzazione out-of-proc (background).

Esempio

Nell'esempio seguente viene illustrata un'implementazione di questo metodo.

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

Requisiti