ISyncMgrHandler::Synchronize-Methode (syncmgr.h)
Initiiert eine Synchronisierung einer Auswahl der Synchronisierungselemente des Handlers.
Syntax
HRESULT Synchronize(
[in] LPCWSTR *ppszItemIDs,
[in] ULONG cItems,
[in] HWND hwndOwner,
[in] ISyncMgrSessionCreator *pSessionCreator,
[in] IUnknown *punk
);
Parameter
[in] ppszItemIDs
Typ: LPCWSTR*
Ein Zeiger auf ein Array von Element-IDs, die die zu synchronisierenden Elemente darstellen. Jede Element-ID hat eine maximale Länge MAX_SYNCMGR_ID einschließlich des beendenden NULL-Zeichens .
[in] cItems
Typ: ULONG
Die Anzahl der Elemente in ppszItemIDs.
[in] hwndOwner
Typ: HWND
Ein Handle für das Fenster, das das Element verwendet, um eine erforderliche Benutzeroberfläche anzuzeigen. Dieser Wert kann NULL sein.
[in] pSessionCreator
Typ: ISyncMgrSessionCreator*
Ein Zeiger auf eine ISyncMgrSessionCreator-Schnittstelle . Diese Schnittstelle ermöglicht es dem Handler selbst, Fortschritt und Ereignisse zu melden oder einen Hintergrundprozess zu signalisieren, um Fortschritt und Ereignisse zu melden.
[in] punk
Typ: IUnknown*
Ein Zeiger auf eine Schnittstelle, die an ISyncMgrControl übergeben werden soll. ISyncMgrHandler::Synchronize wird entweder aufgerufen, wenn ein Benutzer eine Synchronisierung aus dem Ordner Sync Center anfordert oder wenn eine der ISyncMgrControl-Synchronisierungsmethoden aufgerufen wird, z. B. StartSyncAll.
Rückgabewert
Typ: HRESULT
Wenn diese Methode erfolgreich ist, wird S_OK zurückgegeben. Andernfalls wird ein Fehlercode HRESULT zurückgegeben.
Hinweise
ISyncMgrHandler::Synchronize wird in einem eigenen Thread aufgerufen. Sync Center instanziiert das Handlerobjekt und das Sitzungserstellerobjekt in diesem Thread und ruft dann diese Methode auf.
Der Handler kann die Sitzung selbst erstellen, indem er die CreateSession-Methode aufruft, oder er kann einem externen Prozess signalisieren, die Synchronisierung durchzuführen. Wenn der Handler die Sitzung erstellt, sollte er erst von der ISyncMgrHandler::Synchronize-Methode zurückgegeben werden, bis die Synchronisierung abgeschlossen ist. Wenn der Handler die Synchronisierung an einen externen Prozess delegiert, sollte der externe Prozess CoCreateInstance verwenden, um das CLSID_SyncMgrClient-Objekt zu erstellen, wobei die ISyncMgrSessionCreator-Schnittstelle angegeben wird. Der Prozess erstellt dann die Sitzung, sodass der Fortschritt gemeldet werden kann.
Ein Benutzer kann die Synchronisierung für ein Element oder einen Handler beenden. Eine Anwendung kann die Synchronisierung auch beenden, indem sie eine der Stoppmethoden für die ISyncMgrControl-Schnittstelle aufruft , z. B. StopItemSync. Die folgenden Mechanismen werden bereitgestellt, um diese Szenarien zu unterstützen.
- ReportProgress gibt einen Parameter zurück, der angibt, ob der Abbruch angefordert wurde.
- Der Handler kann CanContinue aufrufen.
Wenn der Benutzer nach dem Aufruf der ISyncMgrHandler::Synchronize-Methode aufgefordert wird, zusätzliche Elemente zu synchronisieren, kann der Handler die neuen Elemente in derselben Sitzung synchronisieren, indem er sie über die QueryForAdditionalItems-Methode für den Rückruf abfragt. Wenn sie sich für die Synchronisierung eines von ihnen abgefragten Elements entscheiden, können sie AddItemToSession aufrufen.
Einige Handler listet ein Element erst auf, wenn es synchronisiert wurde. Wenn der Handler solche Elemente während einer Synchronisierung erkennt, kann er das Sync Center über die Sitzung darüber informieren. Wenn der Handler beispielsweise ein Element erkennt, das dem Synchronisierungssatz hinzugefügt werden soll, ruft er ProposeItem auf. Nachdem das Element erfolgreich erstellt wurde, ruft der Handler CommitItem auf. Zu diesem Zeitpunkt fügt es das Synchronisierungscenter der Liste der Elemente hinzu, die für den Handler nachverfolgt werden.
Die ISyncMgrHandler::Synchronize-Methode entspricht einer Kombination der älteren PrepareForSync- und Synchronize-Methoden. Im Fall der älteren Schnittstelle heißt das Synchronisierungscenter PrepareForSync unmittelbar gefolgt von Synchronisieren. Die ISyncMgrHandler::Synchronize-Methode stellt die Funktionalität dieser beiden Methoden in einem einzelnen Aufruf bereit.
Ein weiterer Unterschied zwischen ISyncMgrHandler::Synchronize und Synchronize besteht darin, dass die ältere Methode die Synchronisierung asynchron ausführen sollte. Synchronisieren Sie die Anforderung in einen oder mehrere externe Threads und wird dann zurückgegeben. Es hat dann SynchronizeCompleted aufgerufen, nachdem die Synchronisierung aller Elemente abgeschlossen war. ISyncMgrHandler::Synchronize unterstützt ein synchrones Modell für die Synchronisierung in proc (Vordergrund) oder ein asynchrones Modell für die Out-of-Proc-Synchronisierung (Hintergrundsynchronisierung).
Beispiele
Das folgende Beispiel zeigt eine Implementierung dieser Methode.
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;
}
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows Vista [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2008 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | syncmgr.h |