Interoperating with a Provider
The metadata storage service provides methods to help simplify implementing a synchronization provider. These methods help perform the following tasks:
The source provider to enumerate changes.
The source provider to filter changes during change enumeration.
The destination provider to obtain destination versions of items for the change applier.
A provider or application to clean up items marked as deleted in the metadata store.
The destination provider to recover an out-of-date destination replica.
Enumerating Changes
The replica metadata object contains a method that enumerates changes when the provider is acting as the source provider. For most cases, the GetChangeBatch method of the provider can be implemented by passing its parameters directly to the replica metadata object implementation.
Managed code To enumerate changes that were made to the source replica, call the GetChangeBatch method of the ReplicaMetadata object.
Unmanaged code To enumerate changes that were made to the source replica, call the IReplicaMetadata::GetChangeBatch method.
Filtering Changes
Filtered synchronization is handled by using a callback. The callback method is called before an item is added to the change batch. This gives the callback handler the opportunity to examine each item and to indicate whether the item should be included in the batch.
Managed code To filter changes that are included in a change batch, implement an ItemFilterCallback delegate and pass it to GetFilteredChangeBatch.
Unmanaged code To filter changes that are included in a change batch, implement IChangeBatchCallback and pass it to IReplicaMetadata::GetFilteredChangeBatch.
Obtaining Destination Versions
The replica metadata object provides a method that helps a destination provider implement its ProcessChangeBatch method by obtaining the versions on the destination replica for the items that are contained in the change batch from the source provider. This batch of destination versions can then be passed to the change applier.
Managed code To get a change batch that contains versions applicable to the destination replica, call the GetLocalVersions method of the ReplicaMetadata object.
Unmanaged code To get a change batch that contains versions applicable to the destination replica, call the IReplicaMetadata::GetItemBatchVersions method.
Cleaning Up Deleted Items
Items that have been deleted from the replica are retained in the metadata store with a value that indicates the item has been deleted. To avoid running out of storage space on the replica, the metadata for these deleted items must be cleaned up periodically. The replica metadata object provides the CleanupDeletedItems (for managed code) or IReplicaMetadata::CleanupDeletedItems (for unmanaged code) method to help a provider clean up deleted items on a regular schedule. The provider specifies a time interval that represents the minimum age of the deleted items that are kept in the metadata store, and regularly calls the cleanup method, such as every time that the provider performs change detection. To protect the provider against expensive full enumerations, the cleanup method cleans up deleted items only when the specified time has elapsed, and always keeps the deleted items that are not as old as the specified time interval. The cleanup method also updates the forgotten knowledge to reflect the deleted items that were removed.
Recovering an Out-of-Date Replica
When Sync Framework detects that the destination replica is out-of-date, Sync Framework triggers a full enumeration to restore the destination replica. A destination replica is out-of-date when the source replica has removed deleted items from its metadata but has not communicated the item deletions to the destination replica. To perform a full enumeration, Sync Framework calls the GetFullEnumerationChangeBatch method of the source provider and the ProcessFullEnumerationChangeBatch method of the destination provider. The metadata storage service provides methods that help the providers implement these methods.
Managed code When the GetFullEnumerationChangeBatch method of the source provider is called, the source provider can call the GetFullEnumerationChangeBatch method of the ReplicaMetadata object. When the ProcessFullEnumerationChangeBatch method of the destination provider is called, the destination provider can get a change batch that contains versions that apply to the destination replica by calling the GetFullEnumerationLocalVersions method of the ReplicaMetadata object.
Unmanaged code When the GetFullEnumerationChangeBatch method of the source provider is called, the source provider can call IReplicaMetadata::GetFullEnumerationChangeBatch. When the ProcessFullEnumerationChangeBatch method of the destination provider is called, the destination provider can get a change batch that contains versions applicable to the destination replica by calling IReplicaMetadata::GetFullEnumerationItemBatchVersions.
See Also
Reference
IReplicaMetadata Interface
IChangeBatchCallback Interface
ReplicaMetadata
ItemFilterCallback