How to: Negotiate a Filter
This topic describes how to use a managed language to negotiate the filter that is used for synchronization. Sync Framework is used to mediate the negotiation between the two providers.
This topic assumes a basic familiarity with C# and Microsoft .NET Framework concepts.
The examples in this topic focus on the following Sync Framework interfaces and members:
Understanding Filter Negotiation
The destination provider can specify the filter that is used by the source provider during change enumeration. The source provider can accept or deny the filter that the destination provider requests. The destination provider can continue to request filters until one is found that the source provider accepts. This negotiation is mediated by Sync Framework. The filter can be of whatever type is most appropriate for the providers.
Sync Framework starts filter negotiation after it calls BeginSession(SyncProviderPosition, SyncSessionContext). When the destination provider implements IRequestFilteredSync, Sync Framework calls its SpecifyFilter(FilterRequestCallback) method. In this method, the destination provider passes filters to the FilterRequestCallback delegate until one is accepted. This delegate passes the filter to the source provider by calling its TryAddFilter(Object, FilteringType) method. In this method, the source provider accepts or denies the requested filter. If it accepts a filter, the source provider must use it to produce filtered change batches that include only items or change units that pass the filter.
Build Requirements
.NET Framework 2.0 or later.
Reference to Microsoft.Synchronization.
Reference to Microsoft.Synchronization.MetadataStorage.
Example
The example code in this topic shows how to negotiate a custom filter between two providers that track filters.
Requesting the Filter
The destination provider implements IRequestFilteredSync, so Sync Framework calls its SpecifyFilter(FilterRequestCallback) method. In this method, the destination provider uses the FilterRequestCallback delegate to request that the first filter in its list of tracked filters be used by the source provider to produce a filtered change batch. Because the destination provider tracks the filter, it specifies a filtering type of CurrentItemsAndVersionsForMovedOutItems. If the source provider denies the filter, the destination provider throws SyncInvalidOperationException to indicate that no filter was agreed upon and that it cannot synchronize with the source provider.
Accepting the Filter
The source provider implements ISupportFilteredSync, so Sync Framework calls its TryAddFilter(Object, FilteringType) method one time for each call made by the destination provider to the FilterRequestCallback delegate. In this method, the source provider enumerates its list of tracked filters and, if one is the same as the requested filter, it accepts the filter.
Next Steps
Next, you might want to learn more about using the various filters available in Sync Framework, such as item filters, change unit filters, and custom filters. For more information on filtering, see Filtering Synchronization Data.