Applying Changes by Using the Change Application Service
The change application service performs the same actions as the change applier component of Sync Framework, but in a more granular way. A destination provider that requires greater flexibility than that provided by the standard change applier can use the change application service to perform only the set of actions that is required by the provider. For example, a provider can do its own conflict detection and use the change application service to calculate updated knowledge. Or, a destination provider can use the change application service to apply changes in a different order than that sent by the source provider.
Be aware that the change application service cannot be used by a provider that reports constraint conflicts or uses custom filters, or unexpected results may occur.
Processing Changes
To process changes, the destination provider performs the following steps:
Creates and initializes the change applier service.
Starts a change application session.
Uses the change application service to perform conflict detection and change application for changes that are not otherwise handled by the provider.
Reports any changes that failed to apply.
Optionally reports changes that were successfully applied. This is necessary only when the provider retrieves updated destination knowledge during the change application session. Otherwise, it is more efficient to report only failed changes and to retrieve the updated destination knowledge one time after the change application session is ended.
Ends the change application session. The change application service returns updated destination knowledge for the batch of changes processed.
Creating the Change Application Service Object
The destination provider creates and initializes the ChangeApplicationServices object (for managed code) or IChangeApplicationServices object (for unmanaged code). This is accomplished by calling #ctor(SyncIdFormatGroup, ConflictResolutionPolicy, SyncSessionContext) (for managed code) or by passing IID_IChangeApplicationServices to IProviderSyncServices::CreateChangeApplier and then calling IChangeApplicationServices::Initialize (for unmanaged code).
Starting a Change Application Session
The destination provider starts a change application session by calling BeginChangeApplication(SyncKnowledge, ForgottenKnowledge, FilterInfo, SyncCallbacks, IChangeDataRetriever, IChangeDataRetriever) (for managed code) or IChangeApplicationServices::BeginChangeApplication (for unmanaged code). The destination knowledge that is passed to this method is used as a basis to calculate updated destination knowledge during and after change application.
Processing a Change
The destination provider uses the change application service to process only changes that are not otherwise handled. For example, a destination provider performs its own conflict detection and applies changes itself. In this case, the change application service is not used to process changes. Or, a destination provider applies changes in a different order than that sent by the source provider. In this case, the change application service is used to process changes in the order specified by the destination provider.
To process a change, the destination provider performs the following steps:
Calls GetChangeApplicationContext(ItemChange, ItemChange) (for managed code) or IChangeApplicationServices::GetChangeApplicationContext (for unmanaged code) to start processing a change. This method returns a ChangeApplicationContext object (for managed code) or IChangeApplicationContext object (for unmanaged code).
Gets the ChangeApplicationAction property (for managed code) or calls IChangeApplicationContext::GetChangeApplicationAction (for unmanaged code). This method returns the next action to take as a ChangeApplicationAction value (for managed code) or IChangeApplicationContext Interface value (for unmanaged code).
Takes the specified action, such as to save the change to the destination replica. For more information on handling the possible actions, see the reference topics for the change application service components.
Repeat these steps until the action returned in step 1 is Finished (for managed code) or CAA_FINISHED (for unmanaged code).
Reporting Successful and Failed Changes
If the destination provider uses the change application service to calculate updated knowledge, the provider must report any changes that failed to apply before ending the change application session. To report a failed change, call ReportRecoverableErrorOnItemChange(ItemChange, RecoverableErrorData) or ReportRecoverableErrorOnChangeUnitChange(ChangeUnitChange, RecoverableErrorData) (for managed code) or IChangeApplicationServices::ReportRecoverableErrorOnItemChange or IChangeApplicationServices::ReportRecoverableErrorOnChangeUnitChange (for unmanaged code).
Also, if the destination provider retrieves updated destination knowledge during the change application session, the provider must report changes that were successfully applied. Updated destination knowledge is retrieved by calling GetUpdatedDestinationKnowledge(SyncKnowledge, ForgottenKnowledge) (for managed code) or IChangeApplicationServices::GetUpdatedDestinationKnowledge (for unmanaged code). Reporting successful changes is not necessary when the provider retrieves updated knowledge only after the change application session ends. To report a successfully applied change, call ReportItemChangeApplied(ItemChange) or ReportChangeUnitChangeApplied(ChangeUnitChange) (for managed code) or IChangeApplicationServices::ReportItemChangeApplied or IChangeApplicationServices::ReportChangeUnitChangeApplied (for unmanaged code).
Ending a Change Application Session
When all changes have been processed, the destination provider ends the change application session by calling EndChangeApplication(SyncKnowledge) (for managed code) or IChangeApplicationServices::EndChangeApplication (for unmanaged code). The learned knowledge contained in the change batch from the source provider is passed to this method. The change application service calculates the updated destination knowledge from the learned knowledge and the changes that were reported as failed. The updated destination knowledge that is returned from this method must replace the current knowledge of the destination replica.