Sync Framework Core Components

Article
10/22/2010

Sync Framework core components can be used from an unmanaged language to perform synchronization. These components can be used to manage metadata and to create synchronization providers and applications.

Structures, Enumerations, and Flags

The following table lists the structures, enumerations, and sets of flags defined by Sync Framework, and which feature each component is typically associated with.

Component	Associated feature
ID_PARAMETER_PAIR Structure	Metadata
ID_PARAMETERS Structure	Metadata
SYNC_FILTER_CHANGE Structure	Filtering
SYNC_GID Structure	Metadata
SYNC_ID Structure	Metadata
SYNC_RANGE Structure	Metadata
SYNC_SESSION_STATISTICS Structure	Session
SYNC_VERSION Structure	Metadata
CHANGE_APPLICATION_ACTION Enumeration	Change application service
COLLISION_CONFLICT_RESOLUTION_POLICY Enumeration	Constraint conflicts
CONFLICT_RESOLUTION_POLICY Enumeration	Concurrency conflicts
CONSTRAINT_CONFLICT_REASON Enumeration	Constraint conflicts
FILTER_COMBINATION_TYPE Enumeration	Filtering
FILTERING_TYPE Enumeration	Filtering
KNOWLEDGE_COOKIE_COMPARISON_RESULT Enumeration	Metadata
SYNC_CONSTRAINT_RESOLVE_ACTION Enumeration	Constraint conflicts
SYNC_FULL_ENUMERATION_ACTION Enumeration	Recovery synchronization
SYNC_PROGRESS_STAGE Enumeration	Application callback
SYNC_PROVIDER_ROLE Enumeration	Application callback
SYNC_RESOLVE_ACTION Enumeration	Concurrency conflicts
SYNC_SAVE_ACTION Enumeration	Change application
SYNC_SERIALIZATION_VERSION Enumeration	Versioning
SYNC_STATISTICS Enumeration	Metadata
SYNC_CHANGE_FLAG Flags	Metadata
SYNC_FILTER_INFO_FLAG Flags	Filtering
SYNC_SERIALIZE Flags	Metadata

Interfaces Implemented by Sync Framework

The following interfaces are implemented by Sync Framework.

Factory Interfaces

The following interfaces are used primarily for creating other Sync Framework components. Each of these interfaces can be created by passing CLSID_SyncServices and the specified IID to CoCreateInstance.

Interface	IID
IApplicationSyncServices Interface	IID_IApplicationSyncServices
IClockVectorServices Interface	IID_IClockVectorServices
IProviderCustomFilteredSyncServices Interface	IID_IProviderCustomFilteredSyncServices
IProviderFilteredSyncServices Interface	IID_IProviderFilteredSyncServices
IProviderFilteredSyncServices2 Interface	IID_IProviderFilteredSyncServices2
IProviderSyncServices Interface	IID_IProviderSyncServices
IProviderSyncServices2 Interface	IID_IProviderSyncServices2

Change Batch Interfaces

The following interfaces represent a batch of changes. Each interface can be obtained by passing the specified IID to the QueryInterface method of any other interface. Some interfaces are only implemented when the specified conditions are met.

Interface	IID	Condition
ISyncChangeBatch Interface	IID_ISyncChangeBatch	The change batch can not be part of a recovery synchronization.
ISyncChangeBatch2 Interface	IID_ISyncChangeBatch2	Always.
ISyncChangeBatchAdvanced Interface	IID_ISyncChangeBatchAdvanced	Always.
ISyncChangeBatchBase Interface	IID_ISyncChangeBatchBase	Always.
ISyncChangeBatchBase2 Interface	IID_ISyncChangeBatchBase2	Always.
ISyncChangeBatchWithFilterKeyMap Interface	IID_ISyncChangeBatchWithFilterKeyMap	Always.
ISyncChangeBatchWithPrerequisite Interface	IID_ISyncChangeBatchWithPrerequisite	Always.
ISyncFullEnumerationChangeBatch Interface	IID_ISyncFullEnumerationChangeBatch	The change batch must be part of a recovery synchronization.
ISyncFullEnumerationChangeBatch2 Interface	IID_ISyncFullEnumerationChangeBatch2	The change batch must be part of a recovery synchronization.

The following interfaces represent a single change. Each interface can be obtained by passing the specified IID to the QueryInterface method of any other interface.

Interface	IID
ISyncChange Interface	IID_ISyncChange
ISyncChangeWithFilterKeyMap Interface	IID_ISyncChangeWithFilterKeyMap
ISyncChangeWithPrerequisite Interface	IID_ISyncChangeWithPrerequisite
ISyncFullEnumerationChange Interface	IID_ISyncFullEnumerationChange
ISyncMergeTombstoneChange Interface	IID_ISyncMergeTombstoneChange

The following interfaces are used to add additional information to an ISyncChange object. Each interface can be obtained by using the specified mechanism.

Interface	Obtained by
IFilterTrackingSyncChangeBuilder Interface	Passing IID_IFilterTrackingSyncChangeBuilder to the QueryInterface method of an ISyncChangeBuilder object.
ISyncChangeBuilder Interface	Returned by various methods, such as ISyncChangeBatchBase::AddItemMetadataToGroup.

The following interfaces are used to handle change units. Each interface can be obtained by using the specified mechanism.

Interface	Obtained by
ISyncChangeUnit Interface	Calling IEnumSyncChangeUnits::Next.
IEnumSyncChangeUnits Interface	Calling a method such as ISyncChange::GetChangeUnits.

The following interfaces are used to build or enumerate a list of changes. Each interface can be obtained by using the specified mechanism.

Interface	Obtained by
IDestinationChangeVersionsBuilder Interface	Calling IProviderSyncServices::CreateDestinationChangeVersionsBuilder.
IDestinationChangeVersionsBuilder2 Interface	Passing IID_IDestinationChangeVersionsBuilder2 to the QueryInterface method of an IDestinationChangeVersionsBuilder object.
IEnumSyncChanges Interface	Calling ISyncChangeBatchBase::GetChangeEnumerator or IDestinationChangeVersionsBuilder::GetChangeEnumerator.
IFilterTrackingSyncChangeBuilder Interface	Passing IID_IFilterTrackingSyncChangeBuilder to the QueryInterface method of an IDestinationChangeVersionsBuilder object.

Change Applier Interfaces

The following interfaces can be used by the destination provider to help handle conflicts and apply changes.

Any of the interfaces in the following table can be obtained by passing the specified IID to the IProviderSyncServices::CreateChangeApplier method or to the QueryInterface method of any of the other interfaces in the table.

Interface	IID
IAsynchronousNotifyingChangeApplier Interface	IID_IAsynchronousNotifyingChangeApplier
ISynchronousNotifyingChangeApplier Interface	IID_ISynchronousNotifyingChangeApplier
ISynchronousNotifyingChangeApplier2 Interface	IID_ISynchronousNotifyingChangeApplier2

The change applier registers the following of interface with the destination provider by calling IAsynchronousNotifyingChangeApplierTarget::RegisterCallback.

Interface	IID
IAsynchronousNotifyingChangeApplierTargetCallback Interface	IID_IAsynchronousNotifyingChangeApplierTargetCallback

The following interfaces are used to communicate between the change applier and a provider during conflict detection and change application. Each interface can be obtained by using the specified mechanism.

Interface	Obtained by
ILoadChangeContext Interface	Passed to methods such as ISynchronousDataRetriever::LoadChangeData.
IFilterTrackingSaveChangeContext Interface	Passing IID_IFilterTrackingSaveChangeContext to the QueryInterface method of an ISaveChangeContext or ISaveChangeWithChangeUnitsContext object.
IRecoverableErrorData Interface	Calling IProviderSyncServices::CreateRecoverableErrorData, IRecoverableError::GetRecoverableErrorDataForChange, or IRecoverableError::GetRecoverableErrorDataForChangeUnit.
ISaveChangeContext Interface	Passed to ISynchronousNotifyingChangeApplierTarget::SaveChange and IAsynchronousNotifyingChangeApplierTarget::SaveChange.
ISaveChangeContext2 Interface	Passing IID_ISaveChangeContext2 to the QueryInterface method of an ISaveChangeContext object.
ISaveChangeWithChangeUnitsContext Interface	Passed to ISynchronousNotifyingChangeApplierTarget::SaveChangeWithChangeUnits and IAsynchronousNotifyingChangeApplierTarget::SaveChangeWithChangeUnits.
ISaveChangeWithChangeUnitsContext2 Interface	Passing IID_ISaveChangeWithChangeUnitsContext2 to the QueryInterface method of an ISaveChangeWithChangeUnitsContext object.
IDataRetrieverCallback Interface	Passed to IAsynchronousDataRetriever::RegisterCallback.

The following interfaces can be used in place of a standard change applier when greater flexibility is required. Each interface is obtained by using the specified mechanism.

Interface	Obtained by
IChangeApplicationContext Interface	Calling IChangeApplicationServices::GetChangeApplicationContext.
IChangeApplicationServices Interface	Passing IID_IChangeApplicationServices to IProviderSyncServices::CreateChangeApplier.

Conflict Logging

The following interfaces are used to log conflicts. Each interface can be obtained by using the specified mechanism.

Interface	Obtained by
IConflictLogAccess Interface	Can be implemented by a provider, or can be obtained by passing IID_IConflictLogAccess to the QueryInterface method of an IMemoryConflictLog object.
IConflictLogWriter Interface	Can be implemented by a provider, or can be obtained by passing IID_IConflictLogWriter to the QueryInterface method of an IMemoryConflictLog object.
IEnumLoggedConflicts Interface	Calling IEnumLoggedConflictsBuilder::GetChangeEnumerator.
IEnumLoggedConflictsBuilder Interface	Calling IProviderSyncServices2::CreateLoggedConflictsEnumBuilder.
ILoggedConflict Interface	Calling IProviderSyncServices2::CreateLoggedConflict.
IMemoryConflictLog Interface	Calling IProviderSyncServices2::CreateMemoryConflictLog.

Filtering

The following interfaces represent information about filters that are used to control the data that is included in the synchronization scope. Each interface can be obtained by using the specified mechanism.

Interface	Obtained by
IChangeUnitListFilterInfo Interface	Passing the SYNC_FILTER_INFO_FLAG_CHANGE_UNIT_LIST flag to the IProviderFilteredSyncServices::CreateFilterInfo and then passing IID_IChangeUnitListFilterInfo to the QueryInterface method of the returned ISyncFilterInfo object.
ICombinedFilterInfo Interface	Calling IProviderCustomFilteredSyncServices::CreateCombinedFilterInfo.
ICustomFilterInfo Interface	Calling IProviderCustomFilteredSyncServices::CreateCustomFilterInfo.
IFilterKeyMap Interface	Calling IProviderCustomFilteredSyncServices::CreateFilterKeyMap or ISyncChangeBatchWithFilterKeyMap::GetFilterKeyMap.
IFilterRequestCallback Interface	Passed to IRequestFilteredSync::SpecifyFilter.
IFilterTrackingRequestCallback Interface	Passed to IFilterTrackingProvider::SpecifyTrackedFilters.
ISyncFilterInfo Interface	Calling methods such as IProviderFilteredSyncServices::CreateFilterInfo.
ISyncFilterInfo2 Interface	Passing IID_ISyncFilterInfo2 to the QueryInterface method of an ISyncFilterInfo object.

Knowledge Metadata

The following interfaces represent a knowledge object. Any of the interfaces in the table can be obtained by passing the specified IID to the QueryInterface method of any of the other interfaces in the table. Be aware that some of the methods on some of the interfaces will fail when the minimum supported version of the knowledge object is not the expected value, such as ISyncKnowledge::GetSingleItemExceptions, which will fail when the minimum supported version is not SYNC_SERIALIZATION_VERSION_V1. Also, some of the methods will change the minimum supported version, such as IKnowledgeWithMarkers::AddAllChangeUnitsRequiredMarker, which will set the minimum supported version to SYNC_SERIALIZATION_VERSION_V3. For details on the minimum supported version that is required or set, see the reference documentation for each method.

Interface	IID
ISyncKnowledge Interface	IID_ISyncKnowledge
ISyncKnowledge2 Interface	IID_ISyncKnowledge2
IKnowledgeWithMarkers Interface	IID_IKnowledgeWithMarkers
IForgottenKnowledge Interface	IID_IForgottenKnowledge

The following interfaces represent the components of a knowledge object that has a minimum supported version of SYNC_SERIALIZATION_VERSION_V1. The minimum supported version of a knowledge object can be obtained by calling ISyncKnowledge2::GetMinimumSupportedVersion. Each interface can be obtained by calling the specified method.

Interface	Obtained by calling
IChangeUnitException Interface	IEnumChangeUnitExceptions::Next
IRangeException Interface	IEnumRangeExceptions::Next
ISingleItemException Interface	IEnumSingleItemExceptions::Next
IEnumChangeUnitExceptions Interface	ISyncKnowledge::GetChangeUnitExceptions
IEnumRangeExceptions Interface	ISyncKnowledge::GetRangeExceptions
IEnumSingleItemExceptions Interface	ISyncKnowledge::GetSingleItemExceptions

The following interfaces represent the components of all versions of a knowledge object. Each interface can be obtained by calling the specified method.

Interface	Obtained by calling
IClockVector Interface	ISyncKnowledge::FindClockVectorForItem or ISyncKnowledge::FindClockVectorForChangeUnit
IClockVectorElement Interface	IEnumClockVector::Next
IEnumClockVector Interface	IClockVector::GetClockVectorElements
ICoreFragment Interface	ICoreFragmentInspector::NextCoreFragments
IReplicaKeyMap Interface	IProviderSyncServices::CreateReplicaKeyMap or ISyncKnowledge::GetReplicaKeyMap.

The following interfaces are used to inspect or build a knowledge object. Each interface can be obtained by the specified mechanism.

Interface	Obtained by
IConstructReplicaKeyMap Interface	Passing IID_IConstructReplicaKeyMap to the QueryInterface method of an IReplicaKeyMap object.
ICoreFragmentInspector Interface	Passing IID_ICoreFragmentInspector to ISyncKnowledge2::GetInspector.
IKnowledgeBuilder Interface	Calling IClockVectorServices::CreateKnowledgeBuilder.
IKnowledgeBuilder2 Interface	Passing IID_IKnowledgeBuilder2 to the QueryInterface method of an IKnowledgeBuilder object.

Session Interfaces

The following interfaces are used by a synchronization application to start a synchronization session and to retrieve information about the session. Each interface can be obtained by using the specified mechanism.

Interface	Obtained by
ISyncSession Interface	Calling IApplicationSyncServices::CreateSyncSession.
ISyncSessionExtendedErrorInfo Interface	Passing IID_ISyncSessionExtendedErrorInfo to the QueryInterface method of an ISyncSession object.
ISyncSessionState Interface	Calling IProviderSyncServices2::CreateSyncSessionState. Also passed by Sync Framework to IKnowledgeSyncProvider::BeginSession and IKnowledgeSyncProvider::EndSession.
ISyncSessionState2 Interface	Passing IID_ISyncSessionState2 to the QueryInterface method of an ISyncSessionState object.
ISyncDataConversionControl Interface	Passing IID_ISyncDataConversionControl to the QueryInterface method of an ISyncSessionState object.

Application Callback Data Interfaces

The following interfaces are passed by Sync Framework to a synchronization application by using the specified callback method.

Interface	Callback method
IChangeConflict Interface	ISyncCallback::OnConflict
IConstraintConflict Interface	ISyncConstraintCallback::OnConstraintConflict
IRecoverableError Interface	ISyncCallback::OnRecoverableError

Other Interfaces

The following interface is used to register a provider converter. It can be obtained by calling the specified method.

Interface	Obtained by calling
IProviderConverterRegistration Interface	IProviderSyncServices2::CreateProviderConverterRegistration

Implemented by Synchronization Providers

The following interfaces are implemented by synchronization providers.

Provider Interfaces

Each of the following interfaces must be returned by the QueryInterface method of the ISyncProvider object when it receives the specified IID. These interfaces are passed by the synchronization application to the synchronization session object by using IApplicationSyncServices::CreateSyncSession.

Interface	IID
IKnowledgeSyncProvider Interface	IID_IKnowledgeSyncProvider
ISyncProvider Interface	IID_ISyncProvider
IFilterTrackingProvider Interface	IID_IFilterTrackingProvider
IRequestFilteredSync Interface	IID_IRequestFilteredSync
ISupportFilteredSync Interface	IID_ISupportFilteredSync

Change Applier Target Interfaces

The following interfaces are implemented by a destination provider that uses a synchronous change applier. Each implemented interface must be returned by the QueryInterface method of the ISynchronousNotifyingChangeApplierTarget object when it receives the specified IID. These interfaces are passed to the change applier component by using a method such as ISynchronousNotifyingChangeApplier::ApplyChanges.

Interface	IID
ISynchronousNotifyingChangeApplierTarget Interface	IID_ISynchronousNotifyingChangeApplierTarget
ISynchronousNotifyingChangeApplierTarget2 Interface	IID_ISynchronousNotifyingChangeApplierTarget2
IFilteredReplicaNotifyingChangeApplierTarget Interface	IID_IFilteredReplicaNotifyingChangeApplierTarget
IFilterTrackingNotifyingChangeApplierTarget Interface	IID_IFilterTrackingNotifyingChangeApplierTarget

The following interface is implemented by a destination provider that uses an asynchronous change applier. This interface is passed to the change applier component by using a method such as IAsynchronousNotifyingChangeApplier::ApplyChanges.

Interface	IID
IAsynchronousNotifyingChangeApplierTarget Interface	IID_IAsynchronousNotifyingChangeApplierTarget

Data Retriever Interfaces

The following interfaces are implemented by a destination provider that uses a change applier. These interfaces are passed to the change applier component by using a method such as the specified method.

Interface	Method
IAsynchronousDataRetriever Interface	IAsynchronousNotifyingChangeApplier::ApplyChanges.
ISynchronousDataRetriever Interface	ISynchronousNotifyingChangeApplier::ApplyChanges.

Other Provider Interfaces

The following interfaces are implemented by a provider to take advantage of various features, such as filtering or data conversion. The interface is passed to Sync Framework by using the specified mechanism.

Interface	Mechanism
IEnumItemIds Interface	Returned by a method such as IFilteredReplicaNotifyingChangeApplierTarget::GetNewMoveins.
IProviderConverter Interface	Passed to IProviderConverterRegistration::RegisterProviderConverter.
ISupportLastWriteTime Interface	Returned when IID_ISupportLastWriteTime is passed to the QueryInterface of the data retriever object. Typically, this is an ISynchronousDataRetriever object.
ISyncDataConverter Interface	Passed to ISyncDataConversionControl::SetSourceDataConverter or ISyncDataConversionControl::SetDestinationDataConverter.
ISyncFilter Interface	Passed to methods such as IProviderCustomFilteredSyncServices::CreateCustomFilterInfo or IFilterKeyMap::AddFilter.
ISyncFilterDeserializer Interface	Passed to IProviderCustomFilteredSyncServices::DeserializeFilterKeyMap or IProviderCustomFilteredSyncServices::DeserializeChangeBatchWithFilterKeyMap.

Implemented by Synchronization Applications

The following interfaces are implemented by a synchronization application to receive notification of events that occur during synchronization. Sync Framework obtains these interfaces by passing the specified IID to the QueryInterface method of the ISyncCallback interface that is passed to ISyncSession::RegisterCallback.

Interface	IID
ISyncCallback Interface	IID_ISyncCallback
ISyncCallback2 Interface	IID_ISyncCallback2
ISyncConstraintCallback Interface	IID_ISyncConstraintCallback

Error Codes

Sync Framework uses a set of custom errors to report problems. For more information, see Sync Framework Error Codes.