ISyncMgrHandler::Synchronize 메서드(syncmgr.h)
처리기의 동기화 항목 선택 동기화를 시작합니다.
구문
HRESULT Synchronize(
[in] LPCWSTR *ppszItemIDs,
[in] ULONG cItems,
[in] HWND hwndOwner,
[in] ISyncMgrSessionCreator *pSessionCreator,
[in] IUnknown *punk
);
매개 변수
[in] ppszItemIDs
형식: LPCWSTR*
동기화할 항목을 나타내는 항목 ID 배열에 대한 포인터입니다. 각 항목 ID는 종료 null 문자를 포함하여 MAX_SYNCMGR_ID 최대 길이입니다.
[in] cItems
형식: ULONG
ppszItemIDs의 항목 수입니다.
[in] hwndOwner
형식: HWND
항목이 필요한 UI를 표시하는 데 사용하는 창에 대한 핸들입니다. 이 값은 NULL일 수 있습니다.
[in] pSessionCreator
ISyncMgrSessionCreator 인터페이스에 대한 포인터입니다. 이 인터페이스를 사용하면 처리기 자체가 진행률 및 이벤트를 보고하거나 백그라운드 프로세스에 진행률 및 이벤트를 보고하도록 신호를 보낼 수 있습니다.
[in] punk
형식: IUnknown*
ISyncMgrControl에 전달할 인터페이스에 대한 포인터입니다. ISyncMgrHandler::Synchronize는 사용자가 동기화 센터 폴더에서 동기화를 요청하거나 StartSyncAll과 같은 ISyncMgrControl 동기화 메서드 중 하나가 호출되는 경우 호출됩니다.
반환 값
형식: HRESULT
메서드가 성공하면 S_OK를 반환하고, 그러지 않으면 HRESULT 오류 코드를 반환합니다.
설명
ISyncMgrHandler::Synchronize 는 자체 스레드에서 호출됩니다. 동기화 센터는 해당 스레드에서 처리기 개체와 세션 작성자 개체를 인스턴스화한 다음 이 메서드를 호출합니다.
처리기는 CreateSession 메서드를 호출하여 세션 자체를 만들거나 외부 프로세스에 동기화를 수행하도록 신호를 보낼 수 있습니다. 처리기가 세션을 만드는 경우 동기화가 완료될 때까지 ISyncMgrHandler::Synchronize 메서드에서 반환해서는 안 됩니다. 처리기가 외부 프로세스에 동기화를 위임하는 경우 외부 프로세스는 CoCreateInstance 를 사용하여 ISyncMgrSessionCreator 인터페이스를 지정하는 CLSID_SyncMgrClient 개체를 만들어야 합니다. 그런 다음 프로세스는 진행률을 보고할 수 있도록 세션을 만듭니다.
사용자가 항목 또는 처리기에서 동기화를 중지하도록 선택할 수 있습니다. 또한 애플리케이션은 StopItemSync와 같은 ISyncMgrControl 인터페이스에서 중지 메서드 중 하나를 호출하여 동기화를 중지할 수 있습니다. 이러한 시나리오를 지원하기 위해 다음 메커니즘이 제공됩니다.
- ReportProgress 는 취소가 요청되었는지 여부를 나타내는 매개 변수를 반환합니다.
- 처리기는 CanContinue를 호출할 수 있습니다.
ISyncMgrHandler::Synchronize 메서드가 호출된 후 사용자가 추가 항목을 동기화하도록 요청하는 경우 처리기는 콜백의 QueryForAdditionalItems 메서드를 통해 해당 항목을 쿼리하여 동일한 세션의 새 항목을 동기화할 수 있습니다. 쿼리한 항목을 동기화하도록 선택한 경우 AddItemToSession을 호출할 수 있습니다.
일부 처리기는 동기화될 때까지 항목을 열거하지 않습니다. 처리기가 동기화 중에 이러한 항목을 검색하는 경우 세션을 통해 동기화 센터에 해당 항목을 알릴 수 있습니다. 예를 들어 처리기가 동기화 집합에 추가할 항목을 검색하는 경우 ProposeItem을 호출합니다. 항목이 성공적으로 만들어지면 처리기는 CommitItem을 호출합니다. 이 시점에서 동기화 센터는 처리기에 대해 추적하는 항목 목록에 추가합니다.
ISyncMgrHandler::Synchronize 메서드는 이전 PrepareForSync 및 Synchronize 메서드의 조합과 유사합니다. 이전 인터페이스의 경우 동기화 센터에서 PrepareForSync 를 호출한 후 즉시 동기화를 호출했습니다. ISyncMgrHandler::Synchronize 메서드는 이러한 두 메서드의 기능을 단일 호출로 제공합니다.
ISyncMgrHandler::Synchronize와 Synchronize의 또 다른 차이점은 이전 메서드가 동기화를 비동기적으로 수행해야 했다는 것입니다. 동기화는 하나 이상의 외부 스레드에서 요청을 큐에 대기한 다음 반환합니다. 그런 다음 모든 항목 동기화 가 완료되면 SynchronizeCompleted 를 호출했습니다. ISyncMgrHandler::Synchronize 는 프로시저 내(포그라운드) 동기화를 위한 동기 모델 또는 out-of-proc(백그라운드) 동기화를 위한 비동기 모델을 지원합니다.
예제
다음 예제에서는 이 메서드의 구현을 보여줍니다.
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;
}
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows Vista [데스크톱 앱만 해당] |
| 지원되는 최소 서버 | Windows Server 2008 [데스크톱 앱만 해당] |
| 대상 플랫폼 | Windows |
| 헤더 | syncmgr.h |