Método ISyncMgrHandler::Synchronize (syncmgr.h)
Inicia una sincronización de una selección de los elementos de sincronización del controlador.
Sintaxis
HRESULT Synchronize(
[in] LPCWSTR *ppszItemIDs,
[in] ULONG cItems,
[in] HWND hwndOwner,
[in] ISyncMgrSessionCreator *pSessionCreator,
[in] IUnknown *punk
);
Parámetros
[in] ppszItemIDs
Tipo: LPCWSTR*
Puntero a una matriz de identificadores de elemento que representan los elementos que se van a sincronizar. Cada identificador de elemento tiene una longitud máxima MAX_SYNCMGR_ID incluido el carácter nulo de terminación.
[in] cItems
Tipo: ULONG
Número de elementos de ppszItemIDs.
[in] hwndOwner
Tipo: HWND
Identificador de la ventana que usa el elemento para mostrar cualquier interfaz de usuario necesaria. Este valor puede ser NULL.
[in] pSessionCreator
Tipo: ISyncMgrSessionCreator*
Puntero a una interfaz ISyncMgrSessionCreator . Esta interfaz permite al propio controlador notificar el progreso y los eventos, o indicar un proceso en segundo plano para notificar el progreso y los eventos.
[in] punk
Tipo: IUnknown*
Puntero a una interfaz que se va a pasar a ISyncMgrControl. Se llama a ISyncMgrHandler::Synchronize cuando un usuario solicita una sincronización desde la carpeta Centro de sincronización o cuando se llama a uno de los métodos de sincronización de ISyncMgrControl, como StartSyncAll.
Valor devuelto
Tipo: HRESULT
Si este método se realiza correctamente, devuelve S_OK. De lo contrario, devuelve un código de error de HRESULT.
Comentarios
Se llama a ISyncMgrHandler::Synchronize en su propio subproceso. Sync Center crea una instancia del objeto de controlador y del objeto de creador de sesión en ese subproceso y, a continuación, llama a este método.
El controlador puede crear la propia sesión llamando al método CreateSession o puede indicar un proceso externo para realizar la sincronización. Si el controlador crea la sesión, no debe volver del método ISyncMgrHandler::Synchronize hasta que se complete la sincronización. Si el controlador delega la sincronización con un proceso externo, el proceso externo debe usar CoCreateInstance para crear el objeto CLSID_SyncMgrClient, especificando la interfaz ISyncMgrSessionCreator . A continuación, el proceso crea la sesión para que pueda notificar el progreso.
Un usuario puede optar por detener la sincronización en un elemento o controlador. Una aplicación también puede detener la sincronización llamando a uno de los métodos stop en la interfaz ISyncMgrControl , como StopItemSync. Se proporcionan los siguientes mecanismos para admitir estos escenarios.
- ReportProgress devuelve un parámetro que indica si se ha solicitado la cancelación.
- El controlador puede llamar a CanContinue.
Si el usuario solicita sincronizar elementos adicionales después de llamar al método ISyncMgrHandler::Synchronize , el controlador puede sincronizar los nuevos elementos en la misma sesión consultando por medio del método QueryForAdditionalItems en la devolución de llamada. Si eligen sincronizar un elemento para el que consultaron, pueden llamar a AddItemToSession.
Algunos controladores no enumerarán un elemento hasta que se haya sincronizado. Si el controlador detecta estos elementos durante una sincronización, puede informar al Centro de sincronización sobre ellos a través de la sesión. Por ejemplo, si el controlador detecta un elemento que se va a agregar al conjunto de sincronización, llama a ProposeItem. Una vez creado correctamente el elemento, el controlador llama a CommitItem. En ese momento, el Centro de sincronización lo agrega a la lista de elementos que realiza el seguimiento del controlador.
El método ISyncMgrHandler::Synchronize es análogo a una combinación de los métodos PrepareForSync y Synchronize antiguos. En el caso de la interfaz anterior, el Centro de sincronización llamado PrepareForSync inmediatamente seguido de Synchronize. El método ISyncMgrHandler::Synchronize proporciona la funcionalidad de estos dos métodos en una sola llamada.
Otra diferencia entre ISyncMgrHandler::Synchronize y Synchronize es que se esperaba que el método anterior realizara la sincronización de forma asincrónica. Sincronice la solicitud en cola en uno o varios subprocesos externos y, a continuación, se devuelva. A continuación, llamó a SynchronizeCompleted una vez que haya terminado de sincronizar todos los elementos. ISyncMgrHandler::Synchronize admite un modelo sincrónico para la sincronización en proceso (en primer plano) o un modelo asincrónico para la sincronización fuera de proceso (en segundo plano).
Ejemplos
En el ejemplo siguiente se muestra una implementación de este 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
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows Vista [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2008 [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | syncmgr.h |