---

ISyncFiltering Protocol Reference

Overview

ISyncFiltering is a protocol implemented by objects that filter records for a client. A client can filter the records it pulls from the sync engine using these objects. Before a record is pulled by a client, the sync engine passes it to each filter associated with the client. A filter can then accept or reject the record. If a filter rejects a record, it is not passed to the client.

For example, a user might want to sync only contacts with phone numbers to their mobile phone. The filter for the phone client would examine each contact and reject it if the contact has no phone number.

Use the setFilters: ISyncClient method to set the filters for a client. The sync engine archives the filters so that they persist after the client process terminates. Because the filters persist, they must conform to the NSCoding protocol. In addition, any process that loads the filters using the filters ISyncClient method must have the classes for those filters. When the set of filters changes, all records for a client must be re-filtered to determine if they need to be pulled during the next sync. This is a potentially computationally expensive operation, so only change filters when necessary.

Note

You can use the ISyncFilter class methods to combine multiple filters into a single filter using logical AND or OR binary operators on a set of filters.

Tasks

Testing for Equality

• – isEqual:

Getting Supported Entities

• – supportedEntityNames

Filtering Records

• – shouldApplyRecord:withRecordIdentifier:

Instance Methods

isEqual:

Returns YES if the receiver and anotherFilter are equal, NO otherwise.

- (BOOL)isEqual:(id)anotherFilter

Discussion

When setting a filter using the setFilters: ISyncClient method, the sync engine uses this method to compare the new filter with the previous filter (if there is one). If the filters are not equal, the sync engine recomputes all records that should be pushed to a client.

When setting filters, the sync engine compares the new filters with the old filters using isEqual:. If a filter has changed, the sync engine must refilter all the client’s records—an expensive operation. Therefore, it’s important that this implementation returns NO only if two filters differ in such a way that the records need to be refiltered.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

ISyncFilter.h

shouldApplyRecord:withRecordIdentifier:

Returns YES if the client should pull record uniquely identified by recordIdentifier, NO otherwise.

- (BOOL)shouldApplyRecord:(NSDictionary *)record withRecordIdentifier:(NSString *)recordIdentifier

Discussion

This is the method that implements the actual filtering logic.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

ISyncFilter.h

supportedEntityNames

Returns an array of entity names that this filter supports.

- (NSArray *)supportedEntityNames

Discussion

This filter is used only to filter records of the supported entities. An exception is raised if this method returns an empty array or nil.

Availability

• Available in Mac OS X v10.4 and later.

Related Sample Code

• People

Declared In

ISyncFilter.h

---