Sync Framework 核心组件

项目
10/19/2009

可以通过非托管语言使用 Sync Framework 核心组件来执行同步。这些组件可用于管理元数据以及创建同步提供程序和应用程序。

结构、枚举和标志

下表列出了 Sync Framework 定义的结构、枚举和标志组，以及通常与每个组件相关联的功能。

组件	关联的功能
ID_PARAMETER_PAIR 结构	元数据
ID_PARAMETERS 结构	元数据
SYNC_FILTER_CHANGE 结构	筛选
SYNC_GID 结构	元数据
SYNC_ID 结构	元数据
SYNC_RANGE 结构	元数据
SYNC_SESSION_STATISTICS 结构	会话
SYNC_VERSION 结构	元数据
CHANGE_APPLICATION_ACTION 枚举	变更应用服务
COLLISION_CONFLICT_RESOLUTION_POLICY 枚举	约束冲突
CONFLICT_RESOLUTION_POLICY 枚举	并发冲突
CONSTRAINT_CONFLICT_REASON 枚举	约束冲突
FILTER_COMBINATION_TYPE 枚举	筛选
FILTERING_TYPE 枚举	筛选
KNOWLEDGE_COOKIE_COMPARISON_RESULT 枚举	元数据
SYNC_CONSTRAINT_RESOLVE_ACTION 枚举	约束冲突
SYNC_FULL_ENUMERATION_ACTION 枚举	恢复同步
SYNC_PROGRESS_STAGE 枚举	应用程序回调
SYNC_PROVIDER_ROLE 枚举	应用程序回调
SYNC_RESOLVE_ACTION 枚举	并发冲突
SYNC_SAVE_ACTION 枚举	变更应用
SYNC_SERIALIZATION_VERSION 枚举	版本控制
SYNC_STATISTICS 枚举	元数据
SYNC_CHANGE_FLAG 标志	元数据
SYNC_FILTER_INFO_FLAG 标志	筛选
SYNC_SERIALIZE 标志	元数据

由 Sync Framework 实现的接口

以下接口由 Sync Framework 实现。

工厂接口

以下接口主要用于创建其他 Sync Framework 组件。通过将 CLSID_SyncServices 和指定的 IID 传递到 CoCreateInstance，可以创建这些接口。

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

变更批接口

以下接口表示一个变更批。通过将指定的 IID 传递到任何其他接口的 QueryInterface 方法，可以获取每个接口。某些接口仅在满足指定条件时才能实现。

接口	IID	条件
ISyncChangeBatch 接口	IID_ISyncChangeBatch	变更批不能是恢复同步的组成部分。
ISyncChangeBatch2 接口	IID_ISyncChangeBatch2	始终。
ISyncChangeBatchAdvanced 接口	IID_ISyncChangeBatchAdvanced	始终。
ISyncChangeBatchBase 接口	IID_ISyncChangeBatchBase	始终。
ISyncChangeBatchBase2 接口	IID_ISyncChangeBatchBase2	始终。
ISyncChangeBatchWithFilterKeyMap 接口	IID_ISyncChangeBatchWithFilterKeyMap	始终。
ISyncChangeBatchWithPrerequisite 接口	IID_ISyncChangeBatchWithPrerequisite	始终。
ISyncFullEnumerationChangeBatch 接口	IID_ISyncFullEnumerationChangeBatch	变更批必须是恢复同步的组成部分。
ISyncFullEnumerationChangeBatch2 接口	IID_ISyncFullEnumerationChangeBatch2	变更批必须是恢复同步的组成部分。

以下接口表示一个变更。通过将指定的 IID 传递到任何其他接口的 QueryInterface 方法，可以获取每个接口。

接口	IID
ISyncChange 接口	IID_ISyncChange
ISyncChangeWithFilterKeyMap 接口	IID_ISyncChangeWithFilterKeyMap
ISyncChangeWithPrerequisite 接口	IID_ISyncChangeWithPrerequisite
ISyncFullEnumerationChange 接口	IID_ISyncFullEnumerationChange
ISyncMergeTombstoneChange 接口	IID_ISyncMergeTombstoneChange

以下接口用于将其他信息添加到 ISyncChange 对象。通过使用指定的机制，可以获取每个接口。

接口	获取方式
IFilterTrackingSyncChangeBuilder 接口	将 IID_IFilterTrackingSyncChangeBuilder 传递到 ISyncChangeBuilder 对象的 QueryInterface 方法。
ISyncChangeBuilder 接口	由各种方法（如 ISyncChangeBatchBase::AddItemMetadataToGroup）返回。

以下接口用于处理变更单位。通过使用指定的机制，可以获取每个接口。

接口	获取方式
ISyncChangeUnit 接口	调用 IEnumSyncChangeUnits::Next。
IEnumSyncChangeUnits 接口	调用一个方法，如 ISyncChange::GetChangeUnits。

以下接口用于构建或枚举变更列表。通过使用指定的机制，可以获取每个接口。

接口	获取方式
IDestinationChangeVersionsBuilder 接口	调用 IProviderSyncServices::CreateDestinationChangeVersionsBuilder。
IDestinationChangeVersionsBuilder2 接口	将 IID_IDestinationChangeVersionsBuilder2 传递到 IDestinationChangeVersionsBuilder 对象的 QueryInterface 方法。
IEnumSyncChanges 接口	调用 ISyncChangeBatchBase::GetChangeEnumerator 或 IDestinationChangeVersionsBuilder::GetChangeEnumerator。
IFilterTrackingSyncChangeBuilder 接口	将 IID_IFilterTrackingSyncChangeBuilder 传递到 IDestinationChangeVersionsBuilder 对象的 QueryInterface 方法。

变更应用方接口

目标提供程序可使用以下接口来帮助处理冲突和应用变更。

通过将指定的 IID 传递到下表中任何其他接口的 IProviderSyncServices::CreateChangeApplier 方法或 QueryInterface 方法，可以获取下表中的任何接口。

接口	IID
IAsynchronousNotifyingChangeApplier 接口	IID_IAsynchronousNotifyingChangeApplier
ISynchronousNotifyingChangeApplier 接口	IID_ISynchronousNotifyingChangeApplier
ISynchronousNotifyingChangeApplier2 接口	IID_ISynchronousNotifyingChangeApplier2

变更应用方通过调用 IAsynchronousNotifyingChangeApplierTarget::RegisterCallback 将以下接口注册到目标提供程序。

接口	IID
IAsynchronousNotifyingChangeApplierTargetCallback 接口	IID_IAsynchronousNotifyingChangeApplierTargetCallback

在冲突检测和应用变更期间，变更应用方和提供程序之间通过以下接口进行通信。通过使用指定的机制，可以获取每个接口。

接口	获取方式
ILoadChangeContext 接口	传递到相关方法，如 ISynchronousDataRetriever::LoadChangeData。
IFilterTrackingSaveChangeContext 接口	将 IID_IFilterTrackingSaveChangeContext 传递到 ISaveChangeContext 或 ISaveChangeWithChangeUnitsContext 对象的 QueryInterface 方法。
IRecoverableErrorData 接口	调用 IProviderSyncServices::CreateRecoverableErrorData、IRecoverableError::GetRecoverableErrorDataForChange 或 IRecoverableError::GetRecoverableErrorDataForChangeUnit。
ISaveChangeContext 接口	传递到 ISynchronousNotifyingChangeApplierTarget::SaveChange 和 IAsynchronousNotifyingChangeApplierTarget::SaveChange。
ISaveChangeContext2 接口	将 IID_ISaveChangeContext2 传递到 ISaveChangeContext 对象的 QueryInterface 方法。
ISaveChangeWithChangeUnitsContext 接口	传递到 ISynchronousNotifyingChangeApplierTarget::SaveChangeWithChangeUnits 和 IAsynchronousNotifyingChangeApplierTarget::SaveChangeWithChangeUnits。
ISaveChangeWithChangeUnitsContext2 接口	将 IID_ISaveChangeWithChangeUnitsContext2 传递到 ISaveChangeWithChangeUnitsContext 对象的 QueryInterface 方法。
IDataRetrieverCallback 接口	传递到 IAsynchronousDataRetriever::RegisterCallback。

当需要更大的灵活性时，可使用以下接口代替标准变更应用方。通过使用指定的机制获取每个接口。

接口	获取方式
IChangeApplicationContext 接口	调用 IChangeApplicationServices::GetChangeApplicationContext。
IChangeApplicationServices 接口	将 IID_IChangeApplicationServices 传递到 IProviderSyncServices::CreateChangeApplier。

冲突记录

以下接口用于记录冲突。通过使用指定的机制，可以获取每个接口。

接口	获取方式
IConflictLogAccess 接口	可以由提供程序实现，也可以通过将 IID_IConflictLogAccess 传递到 IMemoryConflictLog 对象的 QueryInterface 方法来获取。
IConflictLogWriter 接口	可以由提供程序实现，也可以通过将 IID_IConflictLogWriter 传递到 IMemoryConflictLog 对象的 QueryInterface 方法来获取。
IEnumLoggedConflicts 接口	调用 IEnumLoggedConflictsBuilder::GetChangeEnumerator。
IEnumLoggedConflictsBuilder 接口	调用 IProviderSyncServices2::CreateLoggedConflictsEnumBuilder。
ILoggedConflict 接口	调用 IProviderSyncServices2::CreateLoggedConflict。
IMemoryConflictLog 接口	调用 IProviderSyncServices2::CreateMemoryConflictLog。

筛选

以下接口表示有关用于控制将哪些数据包括在同步范围内的筛选器的信息。通过使用指定的机制，可以获取每个接口。

接口	获取方式
IChangeUnitListFilterInfo 接口	将 SYNC_FILTER_INFO_FLAG_CHANGE_UNIT_LIST 标志传递到 IProviderFilteredSyncServices::CreateFilterInfo，然后将 IID_IChangeUnitListFilterInfo 传递到返回的 ISyncFilterInfo 对象的 QueryInterface 方法。
ICombinedFilterInfo 接口	调用 IProviderCustomFilteredSyncServices::CreateCombinedFilterInfo。
ICustomFilterInfo 接口	调用 IProviderCustomFilteredSyncServices::CreateCustomFilterInfo。
IFilterKeyMap 接口	调用 IProviderCustomFilteredSyncServices::CreateFilterKeyMap 或 ISyncChangeBatchWithFilterKeyMap::GetFilterKeyMap。
IFilterRequestCallback 接口	传递到 IRequestFilteredSync::SpecifyFilter。
IFilterTrackingRequestCallback 接口	传递到 IFilterTrackingProvider::SpecifyTrackedFilters。
ISyncFilterInfo 接口	调用方法，如 IProviderFilteredSyncServices::CreateFilterInfo。
ISyncFilterInfo2 接口	将 IID_ISyncFilterInfo2 传递到 ISyncFilterInfo 对象的 QueryInterface 方法。

知识元数据

以下接口表示一个知识对象。通过将指定的 IID 传递到下表中的任何其他接口的 QueryInterface 方法，可以获取下表中的任何接口。请注意，当知识对象的最低支持版本不是预期值时，某些接口上的一些方法将失败，例如，当最低支持版本不是 SYNC_SERIALIZATION_VERSION_V1 时，ISyncKnowledge::GetSingleItemExceptions 将失败。此外，一些方法将会变更最低支持版本，例如，IKnowledgeWithMarkers::AddAllChangeUnitsRequiredMarker 会将最低支持版本设置为 SYNC_SERIALIZATION_VERSION_V3。有关需要的或设置的最低支持版本的详细信息，请参阅每个方法的参考文档。

接口	IID
ISyncKnowledge 接口	IID_ISyncKnowledge
ISyncKnowledge2 接口	IID_ISyncKnowledge2
IKnowledgeWithMarkers 接口	IID_IKnowledgeWithMarkers
IForgottenKnowledge 接口	IID_IForgottenKnowledge

以下接口表示其最低支持版本为 SYNC_SERIALIZATION_VERSION_V1 的知识对象的组件。通过调用 ISyncKnowledge2::GetMinimumSupportedVersion，可以获取知识对象的最低支持版本。通过调用指定的方法，可以获取每个接口。

接口	获取该接口需要调用的方法
IChangeUnitException 接口	IEnumChangeUnitExceptions::Next
IRangeException 接口	IEnumRangeExceptions::Next
ISingleItemException 接口	IEnumSingleItemExceptions::Next
IEnumChangeUnitExceptions 接口	ISyncKnowledge::GetChangeUnitExceptions
IEnumRangeExceptions 接口	ISyncKnowledge::GetRangeExceptions
IEnumSingleItemExceptions 接口	ISyncKnowledge::GetSingleItemExceptions

以下接口表示知识对象的所有版本的组件。通过调用指定的方法，可以获取每个接口。

接口	获取该接口需要调用的方法
IClockVector 接口	ISyncKnowledge::FindClockVectorForItem 或ISyncKnowledge::FindClockVectorForChangeUnit
IClockVectorElement 接口	IEnumClockVector::Next
IEnumClockVector 接口	IClockVector::GetClockVectorElements
ICoreFragment 接口	ICoreFragmentInspector::NextCoreFragments
IReplicaKeyMap 接口	IProviderSyncServices::CreateReplicaKeyMap 或 ISyncKnowledge::GetReplicaKeyMap。

以下接口用于检查或构建知识对象。通过使用指定的机制，可以获取每个接口。

接口	获取方式
IConstructReplicaKeyMap 接口	将 IID_IConstructReplicaKeyMap 传递到 IReplicaKeyMap 对象的 QueryInterface 方法。
ICoreFragmentInspector 接口	将 IID_ICoreFragmentInspector 传递到 ISyncKnowledge2::GetInspector。
IKnowledgeBuilder 接口	调用 IClockVectorServices::CreateKnowledgeBuilder。
IKnowledgeBuilder2 接口	将 IID_IKnowledgeBuilder2 传递到 IKnowledgeBuilder 对象的 QueryInterface 方法。

会话接口

同步应用程序使用以下接口来启动同步会话和检索有关会话的信息。通过使用指定的机制，可以获取每个接口。

接口	获取方式
ISyncSession 接口	调用 IApplicationSyncServices::CreateSyncSession。
ISyncSessionExtendedErrorInfo 接口	将 IID_ISyncSessionExtendedErrorInfo 传递到 ISyncSession 对象的 QueryInterface 方法。
ISyncSessionState 接口	调用 IProviderSyncServices2::CreateSyncSessionState。也由 Sync Framework 传递到 IKnowledgeSyncProvider::BeginSession 和 IKnowledgeSyncProvider::EndSession。
ISyncSessionState2 接口	将 IID_ISyncSessionState2 传递到 ISyncSessionState 对象的 QueryInterface 方法。
ISyncDataConversionControl 接口	将 IID_ISyncDataConversionControl 传递到 ISyncSessionState 对象的 QueryInterface 方法。

应用程序回调数据接口

Sync Framework 通过使用指定的回调方法，将以下接口传递到同步应用程序。

接口	回调方法
IChangeConflict 接口	ISyncCallback::OnConflict
IConstraintConflict 接口	ISyncConstraintCallback::OnConstraintConflict
IRecoverableError 接口	ISyncCallback::OnRecoverableError

其他接口

以下接口用于注册提供程序转换器。通过调用指定的方法，可以获取该接口。

接口	获取该接口需要调用的方法
IProviderConverterRegistration 接口	IProviderSyncServices2::CreateProviderConverterRegistration

由同步提供程序实现

以下接口由同步提供程序实现。

提供程序接口

下面的每个接口都必须由 ISyncProvider 对象的 QueryInterface 方法在接收指定的 IID 时返回。同步应用程序通过使用 IApplicationSyncServices::CreateSyncSession 将这些接口传递到同步会话。

接口	IID
IKnowledgeSyncProvider 接口	IID_IKnowledgeSyncProvider
ISyncProvider 接口	IID_ISyncProvider
IFilterTrackingProvider 接口	IID_IFilterTrackingProvider
IRequestFilteredSync 接口	IID_IRequestFilteredSync
ISupportFilteredSync 接口	IID_ISupportFilteredSync

变更应用方目标接口

以下接口由使用同步变更应用方的目标提供程序实现。每个实现的接口都必须由 ISynchronousNotifyingChangeApplierTarget 对象的 QueryInterface 方法在接收指定的 IID 时返回。通过使用一个方法（如 ISynchronousNotifyingChangeApplier::ApplyChanges），将这些接口传递到变更应用方组件。

接口	IID
ISynchronousNotifyingChangeApplierTarget 接口	IID_ISynchronousNotifyingChangeApplierTarget
ISynchronousNotifyingChangeApplierTarget2 接口	IID_ISynchronousNotifyingChangeApplierTarget2
IFilteredReplicaNotifyingChangeApplierTarget 接口	IID_IFilteredReplicaNotifyingChangeApplierTarget
IFilterTrackingNotifyingChangeApplierTarget 接口	IID_IFilterTrackingNotifyingChangeApplierTarget

以下接口由使用异步变更应用方的目标提供程序实现。通过使用一个方法（如 IAsynchronousNotifyingChangeApplier::ApplyChanges），将此接口传递到变更应用方组件。

接口	IID
IAsynchronousNotifyingChangeApplierTarget 接口	IID_IAsynchronousNotifyingChangeApplierTarget

数据检索器接口

以下接口由使用变更应用方的目标提供程序实现。通过使用一个方法（如指定的方法），将这些接口传递到变更应用方组件。

接口	方法
IAsynchronousDataRetriever 接口	IAsynchronousNotifyingChangeApplier::ApplyChanges.
ISynchronousDataRetriever 接口	ISynchronousNotifyingChangeApplier::ApplyChanges.

其他提供程序接口

以下接口由提供程序实现，以便能使用各种功能（如筛选或数据转换）。通过使用指定的机制，将此接口传递到 Sync Framework。

接口	机制
IEnumItemIds 接口	由一个方法返回，如 IFilteredReplicaNotifyingChangeApplierTarget::GetNewMoveins。
IProviderConverter 接口	传递到 IProviderConverterRegistration::RegisterProviderConverter。
ISupportLastWriteTime 接口	在 IID_ISupportLastWriteTime 传递到数据检索器对象的 QueryInterface 时返回。通常，这是一个 ISynchronousDataRetriever 对象。
ISyncDataConverter 接口	传递到 ISyncDataConversionControl::SetSourceDataConverter 或 ISyncDataConversionControl::SetDestinationDataConverter。
ISyncFilter 接口	传递到相关方法，如 IProviderCustomFilteredSyncServices::CreateCustomFilterInfo 或 IFilterKeyMap::AddFilter。
ISyncFilterDeserializer 接口	传递到 IProviderCustomFilteredSyncServices::DeserializeFilterKeyMap 或 IProviderCustomFilteredSyncServices::DeserializeChangeBatchWithFilterKeyMap。

由同步应用程序实现

以下接口由同步应用程序实现，以接收同步期间所发生事件的通知。Sync Framework 通过将指定的 IID 传递到 ISyncCallback 接口（已传递给 ISyncSession::RegisterCallback）的 QueryInterface 方法，来获取这些接口。

接口	IID
ISyncCallback 接口	IID_ISyncCallback
ISyncCallback2 接口	IID_ISyncCallback2
ISyncConstraintCallback 接口	IID_ISyncConstraintCallback

错误代码

Sync Framework 使用一组自定义错误来报告问题。有关详细信息，请参阅 Sync Framework 错误代码。

请参阅

概念

Sync Framework 非托管 API
Microsoft Sync Framework
自定义提供程序的基础知识
 管理标准提供程序的元数据
 实现标准自定义提供程序
 实现同步应用程序

通过