ISyncMgrHandler::Sinkronkan metode (syncmgr.h)
Memulai sinkronisasi pilihan item sinkronisasi handler.
Sintaks
HRESULT Synchronize(
[in] LPCWSTR *ppszItemIDs,
[in] ULONG cItems,
[in] HWND hwndOwner,
[in] ISyncMgrSessionCreator *pSessionCreator,
[in] IUnknown *punk
);
Parameter
[in] ppszItemIDs
Jenis: LPCWSTR*
Penunjuk ke array ID item yang mewakili item yang akan disinkronkan. Setiap ID item memiliki panjang maksimum MAX_SYNCMGR_ID termasuk karakter null yang mengakhiri.
[in] cItems
Jenis: ULONG
Jumlah item dalam ppszItemIDs.
[in] hwndOwner
Jenis: HWND
Handel ke jendela yang digunakan item untuk menampilkan UI yang diperlukan. Nilai ini bisa NULL.
[in] pSessionCreator
Jenis: ISyncMgrSessionCreator*
Penunjuk ke antarmuka ISyncMgrSessionCreator . Antarmuka ini memungkinkan handler itu sendiri untuk melaporkan kemajuan dan peristiwa, atau untuk memberi sinyal proses latar belakang untuk melaporkan kemajuan dan peristiwa.
[in] punk
Jenis: IUnknown*
Pointer ke antarmuka yang akan diteruskan ke ISyncMgrControl. ISyncMgrHandler::Synchronize dipanggil baik ketika pengguna meminta sinkronisasi dari folder Sync Center atau ketika salah satu metode sinkronisasi ISyncMgrControl dipanggil, seperti StartSyncAll.
Mengembalikan nilai
Jenis: HRESULT
Jika metode ini berhasil, metode ini mengembalikan S_OK. Jika tidak, kode kesalahan HRESULT akan dikembalikan.
Keterangan
ISyncMgrHandler::Synchronize dipanggil pada utasnya sendiri. Sync Center membuat instans objek handler dan objek pembuat sesi pada utas tersebut lalu memanggil metode ini.
Handler dapat membuat sesi itu sendiri dengan memanggil metode CreateSession atau dapat memberi sinyal proses eksternal untuk melakukan sinkronisasi. Jika handler membuat sesi, itu tidak boleh kembali dari metode ISyncMgrHandler::Synchronize hingga sinkronisasi selesai. Jika handler mendelegasikan sinkronisasi ke proses eksternal, proses eksternal harus menggunakan CoCreateInstance untuk membuat objek CLSID_SyncMgrClient, menentukan antarmuka ISyncMgrSessionCreator . Proses kemudian membuat sesi sehingga dapat melaporkan kemajuan.
Pengguna dapat memilih untuk menghentikan sinkronisasi pada item atau penangan. Aplikasi juga dapat menghentikan sinkronisasi dengan memanggil salah satu metode berhenti pada antarmuka ISyncMgrControl , seperti StopItemSync. Mekanisme berikut disediakan untuk mendukung skenario ini.
- ReportProgress mengembalikan parameter yang menunjukkan apakah pembatalan telah diminta.
- Handler dapat memanggil CanContinue.
Jika pengguna meminta untuk menyinkronkan item tambahan setelah metode ISyncMgrHandler::Synchronize telah dipanggil, handler dapat menyinkronkan item baru dalam sesi yang sama dengan mengkuerinya melalui metode QueryForAdditionalItems pada panggilan balik. Jika mereka memilih untuk menyinkronkan item yang mereka kueri, mereka kemudian dapat memanggil AddItemToSession.
Beberapa penangan tidak akan menghitung item hingga item disinkronkan. Jika handler menemukan item tersebut selama sinkronisasi, handler dapat menginformasikan Sync Center tentang item tersebut melalui sesi. Misalnya, jika handler menemukan item untuk ditambahkan ke set sinkronisasi, handler memanggil ProposeItem. Setelah item berhasil dibuat, handler memanggil CommitItem. Pada saat itu, Sync Center menambahkannya ke daftar item yang dilacak untuk handler.
Metode ISyncMgrHandler::Synchronize dianalogikan dengan kombinasi metode PrepareForSync dan Synchronize yang lebih lama. Dalam kasus antarmuka yang lebih lama, Sync Center yang disebut PrepareForSync segera diikuti oleh Synchronize. Metode ISyncMgrHandler::Synchronize menyediakan fungsionalitas kedua metode ini ke dalam satu panggilan.
Perbedaan lain antara ISyncMgrHandler::Synchronize dan Synchronize adalah bahwa metode yang lebih lama diharapkan untuk melakukan sinkronisasi secara asinkron. Sinkronkan antrean permintaan dalam satu atau beberapa utas eksternal lalu dikembalikan. Kemudian disebut SynchronizeCompleted setelah selesai menyinkronkan semua item. ISyncMgrHandler::Synchronize mendukung model sinkron untuk sinkronisasi in-proc (latar depan) atau model asinkron untuk sinkronisasi out-of-proc (latar belakang).
Contoh
Contoh berikut menunjukkan implementasi metode ini.
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;
}
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows Vista [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows Server 2008 [hanya aplikasi desktop] |
| Target Platform | Windows |
| Header | syncmgr.h |