ISyncMgrSyncCallback::ReportProgress method (syncmgr.h)

Article
10/13/2021

Reports the progress of the synchronization of a single sync item to Sync Center.

Syntax

HRESULT ReportProgress(
  [in]  LPCWSTR                 pszItemID,
  [in]  LPCWSTR                 pszProgressText,
  [in]  SYNCMGR_PROGRESS_STATUS nStatus,
  [in]  ULONG                   uCurrentStep,
  [in]  ULONG                   uMaxStep,
  [out] SYNCMGR_CANCEL_REQUEST  *pnCancelRequest
);

Parameters

[in] pszItemID

Type: LPCWSTR

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.

[in] pszProgressText

Type: LPCWSTR

A pointer to a buffer containing a Unicode string for any custom progress messaging for this item.

[in] nStatus

Type: SYNCMGR_PROGRESS_STATUS

A value from the SYNCMGR_PROGRESS_STATUS enumeration stating the current progress status of the synchronization.

[in] uCurrentStep

Type: ULONG

The current step in the synchronization. If the SYNCMGR_PS_UPDATING_INDETERMINATE flag is set in nStatus, this parameter is ignored.

[in] uMaxStep

Type: ULONG

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.

[out] pnCancelRequest

Type: SYNCMGR_CANCEL_REQUEST*

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

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

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 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 Progress.

The maximum length of a progress string is MAX_SYNCMGR_PROGRESSTEXT. This constant is defined in SyncMgr.h.

Examples

The following example shows the usage of ISyncMgrSyncCallback::ReportProgress by the 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);
        }
    }
    ...
}

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Target Platform	Windows
Header	syncmgr.h

Share via