IRequestFilteredSync.SpecifyFilter Method

When overridden in a derived class, negotiates which filter is used by the source provider during change enumeration.

Namespace: Microsoft.Synchronization
Assembly: Microsoft.Synchronization (in microsoft.synchronization.dll)

Syntax

'Declaration
Sub SpecifyFilter ( _
    filterRequest As FilterRequestCallback _
)
'Usage
Dim instance As IRequestFilteredSync
Dim filterRequest As FilterRequestCallback

instance.SpecifyFilter(filterRequest)

void SpecifyFilter (
    FilterRequestCallback filterRequest
)

void SpecifyFilter (
    FilterRequestCallback^ filterRequest
)

void SpecifyFilter (
    FilterRequestCallback filterRequest
)

function SpecifyFilter (
    filterRequest : FilterRequestCallback
)

Parameters

• filterRequest
  The delegate that is used by the destination provider to request that a filter be used by the source provider during change enumeration.

Remarks

Filter negotiation is achieved by using the following steps:

1. Before the source provider begins enumerating changes, Sync Framework starts filter negotiation by calling the SpecifyFilter method of the IRequestFilteredSync interface implemented by the destination provider.

2. During processing of SpecifyFilter, the destination provider passes filters to the FilterRequestCallback that is specified by Sync Framework.

3. During processing of FilterRequestCallback, Sync Framework calls the TryAddFilter method of the ISupportFilteredSync interface implemented by the source provider. If the source provider does not support the requested filter, the destination provider may continue to request filters until it finds one that is supported.

When a filter has been successfully negotiated, the source provider uses it to determine which items to include during change enumeration.

Notes to Implementers: An implementation of this method can repeatedly call FilterRequestCallback with different filters until a filter is found that is supported by both the destination provider and the source provider. The source provider indicates that it does not support a filter by returning false in response to the TryAddFilter call.

Example

The following example implements SpecifyFilter. The first tracked filter requested as the filter for synchronization. An exception is thrown if the source provider denies the requested filter.

Public Sub SpecifyFilter(ByVal filterRequest As FilterRequestCallback) Implements IRequestFilteredSync.SpecifyFilter
    ' Use the first tracked filter as the filter for sync.
    If 0 < _ContactStore.TrackedFilters.Count Then
        _filterForSync = _ContactStore.TrackedFilters(0)
    End If

    ' The source provider must agree to send a filtered change batch.
    If Not filterRequest(_filterForSync, FilteringType.CurrentItemsAndVersionsForMovedOutItems) Then
        Throw New SyncInvalidOperationException("Filter specified by SpecifyFilter was rejected.")
    End If
End Sub

public void SpecifyFilter(FilterRequestCallback filterRequest)
{
    // Use the first tracked filter as the filter for sync.
    if (0 < _ContactStore.TrackedFilters.Count)
    {
        _filterForSync = _ContactStore.TrackedFilters[0];
    }

    // The source provider must agree to send a filtered change batch.
    if (!filterRequest(_filterForSync, FilteringType.CurrentItemsAndVersionsForMovedOutItems))
    {
        throw new SyncInvalidOperationException("Filter specified by SpecifyFilter was rejected.");
    }
}

See Also

Reference

IRequestFilteredSync Interface
IRequestFilteredSync Members
Microsoft.Synchronization Namespace