ISyncMgrSyncCallback::ReportProgress Method
Reports the progress of the synchronization of a single sync item to Sync Center.
Syntax
HRESULT ReportProgress( LPCWSTR pszItemID, LPCWSTR pszProgressText, SYNCMGR_PROGRESS_STATUS nStatus, ULONG uCurrentStep, ULONG uMaxStep, SYNCMGR_CANCEL_REQUEST *pnCancelRequest );
Parameters
- pszItemID
[in] A pointer to a buffer containing the unique ID of the item currently being synchronized. This string is of maximum length MAX_SYNCMGR_ID including the terminating null character.- pszProgressText
[in] A pointer to a buffer containing a Unicode string for any custom progress messaging for this item.- nStatus
[in] A value from the SYNCMGR_PROGRESS_STATUS enumeration stating the current progress status of the synchronization.- uCurrentStep
[in] The current step in the synchronization. If the SYNCMGR_PS_UPDATING_INDETERMINATE flag is set in nStatus, this parameter is ignored.- uMaxStep
[in] The total number of steps required to complete the synchronization of the item. If the SYNCMGR_PS_UPDATING_INDETERMINATE flag is set in nStatus, this parameter is ignored.- pnCancelRequest
[out] When this method returns, points to a value from the SYNCMGR_CANCEL_REQUEST enumeration specifying the nature of a cancel request, if any.
Return Value
Remarks
If you want to report progress on the handler rather than individual sync items, call ISyncMgrSyncCallback::SetHandlerProgressText.
If the synchronization has been canceled, the handler calls ISyncMgrSyncCallback::ReportProgress on the item one final time, acknowledging the cancellation request by specifying SYNCMGR_PS_CANCELED in the nStatus parameter. This updates the user interface (UI) and also allows the user to restart a sync for that item.
Once this method reports a completion status (SYNCMGR_PS_SUCCEEDED, SYNCMGR_PS_FAILED, or SYNCMGR_PS_CANCELED), the only further status report that can be made is SYNCMGR_PS_FAILED. Any other value causes this method to return E_ACCESSDENIED and Sync Center to mark the item as failed.
This method replaces ISyncMgrSynchronizeCallback::Progress.
The maximum length of a progress string is MAX_SYNCMGR_PROGRESSTEXT. This constant is defined in SyncMgr.h.
Example
The following example shows the usage of ISyncMgrSyncCallback::ReportProgress by the ISyncMgrHandler::Synchronize method.
STDMETHODIMP CMyDeviceHandler::Synchronize(...) { ... // Start synchronizing the sync item. ... // Construct a string to display in the Sync Center folder. // Report the progress to Sync Center. SYNCMGR_CANCEL_REQUEST nCancelRequest; hr = pCallback->ReportProgress(pszItemID, pszProgressText, SYNCMGR_PS_UPDATING, uCurrentStep, uMaxStep, &nCancelRequest); if (SUCCEEDED(hr)) { if (nCancelRequest != SYNCMGR_CR_NONE) { // Synchronization was canceled. hr = pCallback->ReportProgress(pszItemID, pszProgressText, SYNCMGR_PS_CANCELED, uCurrentStep, uMaxStep, NULL); } } ... }