ISyncMgrHandler ::Synchronize, méthode (syncmgr.h)
Lance la synchronisation d’une sélection des éléments de synchronisation du gestionnaire.
Syntaxe
HRESULT Synchronize(
[in] LPCWSTR *ppszItemIDs,
[in] ULONG cItems,
[in] HWND hwndOwner,
[in] ISyncMgrSessionCreator *pSessionCreator,
[in] IUnknown *punk
);
Paramètres
[in] ppszItemIDs
Type : LPCWSTR*
Pointeur vers un tableau d’ID d’élément représentant les éléments à synchroniser. Chaque ID d’élément a une longueur maximale MAX_SYNCMGR_ID y compris le caractère null de fin.
[in] cItems
Type : ULONG
Nombre d’éléments dans ppszItemIDs.
[in] hwndOwner
Type : HWND
Handle de la fenêtre que l’élément utilise pour afficher toute interface utilisateur nécessaire. Cette valeur peut être NULL.
[in] pSessionCreator
Type : ISyncMgrSessionCreator*
Pointeur vers une interface ISyncMgrSessionCreator . Cette interface permet au gestionnaire lui-même de signaler la progression et les événements, ou de signaler un processus en arrière-plan pour signaler la progression et les événements.
[in] punk
Type : IUnknown*
Pointeur vers une interface à passer à ISyncMgrControl. ISyncMgrHandler ::Synchronize est appelé soit lorsqu’un utilisateur demande une synchronisation à partir du dossier Centre de synchronisation, soit lorsqu’une des méthodes de synchronisation ISyncMgrControl est appelée, comme StartSyncAll.
Valeur retournée
Type : HRESULT
Si cette méthode réussit, elle retourne S_OK. Sinon, elle retourne un code d’erreur HRESULT.
Remarques
ISyncMgrHandler ::Synchronize est appelé sur son propre thread. Le Centre de synchronisation instancie l’objet gestionnaire et l’objet créateur de session sur ce thread, puis appelle cette méthode.
Le gestionnaire peut créer la session elle-même en appelant la méthode CreateSession ou il peut signaler à un processus externe d’effectuer la synchronisation. Si le gestionnaire crée la session, il ne doit pas retourner à partir de la méthode ISyncMgrHandler ::Synchronize tant que la synchronisation n’est pas terminée. Si le gestionnaire délègue la synchronisation à un processus externe, le processus externe doit utiliser CoCreateInstance pour créer l’objet CLSID_SyncMgrClient, en spécifiant l’interface ISyncMgrSessionCreator . Le processus crée ensuite la session afin qu’elle puisse signaler la progression.
Un utilisateur peut choisir d’arrêter la synchronisation sur un élément ou un gestionnaire. Une application peut également arrêter la synchronisation en appelant l’une des méthodes d’arrêt de l’interface ISyncMgrControl , comme StopItemSync. Les mécanismes suivants sont fournis pour prendre en charge ces scénarios.
- ReportProgress retourne un paramètre indiquant si l’annulation a été demandée.
- Le gestionnaire peut appeler CanContinue.
Si l’utilisateur demande à synchroniser des éléments supplémentaires après l’appel de la méthode ISyncMgrHandler ::Synchronize , le gestionnaire peut synchroniser les nouveaux éléments dans la même session en interrogeant pour eux via la méthode QueryForAdditionalItems sur le rappel. S’ils choisissent de synchroniser un élément pour lequel ils ont interrogé, ils peuvent alors appeler AddItemToSession.
Certains gestionnaires n’énumèrent pas un élément tant qu’il n’a pas été synchronisé. Si le gestionnaire découvre de tels éléments pendant une synchronisation, il peut en informer le Centre de synchronisation via la session. Par exemple, si le gestionnaire découvre un élément à ajouter au jeu de synchronisation, il appelle ProposeItem. Une fois l’élément créé, le gestionnaire appelle CommitItem. À ce stade, le Centre de synchronisation l’ajoute à la liste des éléments qu’il suit pour le gestionnaire.
La méthode ISyncMgrHandler ::Synchronize est analogue à une combinaison des anciennes méthodes PrepareForSync et Synchronize . Dans le cas de l’ancienne interface, le Centre de synchronisation appelé PrepareForSync est immédiatement suivi de Synchroniser. La méthode ISyncMgrHandler ::Synchronize fournit les fonctionnalités de ces deux méthodes en un seul appel.
Une autre différence entre ISyncMgrHandler ::Synchronize et Synchronize est que l’ancienne méthode était censée effectuer la synchronisation de manière asynchrone. Synchroniser a mis en file d’attente la requête dans un ou plusieurs threads externes, puis retourné. Il a ensuite appelé SyncCompleted une fois qu’il a terminé la synchronisation de tous les éléments. ISyncMgrHandler ::Synchronize prend en charge un modèle synchrone pour la synchronisation in-proc (au premier plan) ou un modèle asynchrone pour la synchronisation hors processus (en arrière-plan).
Exemples
L’exemple suivant montre une implémentation de cette méthode.
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;
}
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows Vista [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2008 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | syncmgr.h |