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);
        }
    }
    ...
}