Reporting Synchronization Progress
Microsoft Sync Framework reports synchronization progress to an application by using the ProgressChanged event (for managed code) or ISyncCallback::OnProgress event (for unmanaged code). When this event is raised and the information that it communicates depends on the implementation of the source provider.
Reporting Each Change
By default, Sync Framework sends the ProgressChanged event (for managed code) or ISyncCallback::OnProgress event (for unmanaged code) one time for each change that is applied by the destination provider. Sync Framework also sends this event one time after each change batch has been completely applied.
This default progress notification is used only when the source provider does not specify work estimates for changes and change batches.
Reporting Estimated Work
Sync Framework can also report work estimates for applied changes and change batches. The source provider must estimate both the work that is required to apply each change and the work that is required to completely apply each change batch. The source provider must also estimate the remaining work in the synchronization session. If the source provider has specified these values, while a batch of changes is being applied, Sync Framework adds up the work completed as each change, conflict, or change batch is applied by the destination provider. Sync Framework then periodically sends the ProgressChanged event (for managed code) or ISyncCallback::OnProgress event (for unmanaged code) to report the current total of work completed and the total work in the session. Sync Framework also sends this event after each change batch has been completely applied.
To report estimated work progress, the source provider must specify estimated work for each change and each change batch, and the remaining work for the session as described in the following table.
Estimated work type |
Specify by using managed code |
Specify by using unmanaged code |
|---|---|---|
Change |
dwWorkForChange parameter of ISyncChangeBatchBase::AddItemMetadataToGroup or ISyncChangeBatch::AddLoggedConflict. Sync Framework also provides this value through ISyncChange::SetWorkEstimate. |
|
Change batch |
||
Session |
Reporting Custom Progress
Providers can also send a progress notification at any time by calling OnProgressChanged(SyncStagedProgressEventArgs) (for managed code) or ISyncSessionState::OnProgress (for unmanaged code). When the synchronization stage is specified as ChangeApplication (for managed code) or SPS_CHANGE_APPLICATION (for unmanaged code), Sync Framework accumulates the total completed work every time that the progress notification is sent. Sync Framework also interprets the specified total work as the remaining work for the session and calculates the total work for the session by adding the specified total work to the accumulated value for completed work. Sync Framework then passes these calculated values to the progress notification event. When the synchronization stage is any other valid value, the work estimate values are passed directly to the progress notification event.
Care must be taken to avoid reporting the same work two times when the source provider specifies work estimates, and the destination provider sends progress notifications and specifies ChangeApplication (for managed code) or SPS_CHANGE_APPLICATION (for unmanaged code) for the synchronization state. This is because Sync Framework adds up the completed work value every time that progress notifications are sent during change application. If a provider sends its own progress notification, Sync Framework adds the estimated work values specified by the provider to the total completed work for the session. This can cause the same work to be counted two times: one time when it is reported by Sync Framework and one time when it is reported by the provider.