---

ISyncSessionDriverDataSource Protocol Reference

Overview

The ISyncSessionDriverDataSource protocol defines a set of methods that the data source of an ISyncSessionDriver object must implement. This document also includes optional informal protocol methods that a data source can implement.

A data source must implement the clientIdentifier and clientDescriptionURL methods in order for a driver to create an ISyncClient object. A data source must implement preferredSyncModeForEntityName: to request a sync mode—for example, a slow sync when an application doesn't have information on changes since the last sync. However, as with any sync session, the sync engine decides on the actual sync mode used, which depends on many other factors.

A data source also needs to implement the recordsForEntityName:moreComing:error: method to support slow syncing, and optionally, implement the changedRecordsForEntityName:moreComing:error: or changesForEntityName:moreComing:error: methods to support fast syncing. All of these pushing methods allow you to batch records and changes.

Similarly, the data source must implement the applyChange:forEntityName:remappedRecordId:formattedRecord:error: and deleteAllRecordsForEntityName:error: methods to apply changes during the pulling phase of a sync session.

Optional methods include entityNamesToSync and entityNamesToPull which can return a subset of the entities used by the client. The default is to push and pull records for all the entities provided in the client description.

You should use sync anchors to improve performance and avoid serious errors. A sync anchor is an object that is unique per client and per entity, that is saved periodically throughout a sync session. The sync engine compares the clients locally stored sync anchors with its copies to determine the next sync mode. For example, if there is a discrepancy in sync anchors, the client must slow sync. Read ISyncSession Class Reference for details.

To use sync anchors, implement the lastAnchorForEntityName: method to return the previous sync anchor for the specified entity, and implement the nextAnchorForEntityName: method to return the new sync anchor for the specified entity. It is your responsibility to save the sync anchors returned by the nextAnchorForEntityName: method locally, and return them in a subsequent call to the lastAnchorForEntityName: method during the next sync session. Although these methods are optional, if you implement one, you must implement the other.

Tasks

Getting Client Information

• – clientIdentifier
• – clientDescriptionURL
• – schemaBundleURLs
• – entityNamesToSync
• – entityNamesToPull
• – sessionBeginTimeout
• – sessionPullChangesTimeout

Negotiating

• – preferredSyncModeForEntityName:

Pulling

• – applyChange:forEntityName:remappedRecordIdentifier:formattedRecord:error:
• – deleteAllRecordsForEntityName:error:

Pushing

• – recordsForEntityName:moreComing:error:
• – changedRecordsForEntityName:moreComing:error:
• – changesForEntityName:moreComing:error:
• – identifiersForRecordsToDeleteForEntityName:moreComing:error:

Using Sync Anchors

• – lastAnchorForEntityName:
• – nextAnchorForEntityName:

Instance Methods

applyChange:forEntityName:remappedRecordIdentifier:formattedRecord:error:

Applies the given changes to a client's record during the pulling phase of a sync session.

- (ISyncSessionDriverChangeResult)applyChange:(ISyncChange *)change forEntityName:(NSString *)entityName remappedRecordIdentifier:(NSString **)outRecordIdentifier formattedRecord:(NSDictionary **)outRecord error:(NSError **)outError

Discussion

This method applies the changes from the truth database to the local copy of the record. The change parameter is an ISyncChange object that describes the changes to a record since the last sync.

If the change is of type ISyncChangeTypeDelete, then the outRecordIdentifier and outRecord parameters are ignored. Otherwise, they may be used to pass back additional information to the driver.

If the change is of type ISyncChangeTypeAdd or ISyncChangeTypeModify and this method accepts the change, then it may set the value referenced by outRecordIdentifier to an alternate local record identifier. The sync engine uses the returned local record identifier when communicating future changes.

If the change is of type ISyncChangeTypeAdd or ISyncChangeTypeModify and this method accepts the change, then it may specify an alternate format by setting the value referenced by outRecord to the new format. See clientAcceptedChangesForRecordWithIdentifier:formattedRecord:newRecordIdentifier: for more details on formatting records.

This method returns ISyncSessionDriverChangeAccepted if the change is accepted (successfully applied), ISyncSessionDriverChangeRefused if it is refused, and ISyncSessionDriverChangeIgnored if it is neither accepted nor refused. If a client refuses a change, the sync engine does not send the same change during any subsequent syncs unless the record is modified.

If an error occurs, this method returns ISyncSessionDriverChangeError and sets outError to an NSError object that describes the error. If this method returns ISyncSessionDriverChangeError, the ISyncSessionDriver object that invoked this method cancels the sync session.

This method is invoked by the driver during the pulling phase of a sync session, after pushing records.

This method is required.

Availability

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

See Also

• – clientAcceptedChangesForRecordWithIdentifier:formattedRecord:newRecordIdentifier: (ISyncSession)
• – clientRefusedChangesForRecordWithIdentifier: (ISyncSession)

Declared In

ISyncSessionDriver.h

changedRecordsForEntityName:moreComing:error:

Returns changed records for the given entity name that should be pushed to the sync engine during a fast sync.

- (NSDictionary *)changedRecordsForEntityName:(NSString *)entityName moreComing:(BOOL *)moreComing error:(NSError **)outError

Discussion

Returns a dictionary where the keys are record identifiers and the values are dictionary records that you want to push during a fast sync. The dictionary records must be suitable for pushing to the sync engine and belong to the entity specified by entityName. A dictionary record contains the properties of a record that you want to sync. All dictionary records must contain a value for the ISyncRecordEntityNameKey key that identifies the record’s entity. This method returns an empty dictionary if there are no records to push for this entity.

The moreComing parameter is used to batch records. If this method sets the value referenced by moreComing to YES, then this method is invoked repeatedly during the pushing phase of a sync session until moreComing is set to NO.

Because this method is invoked during a fast sync, it returns only records that changed since the last sync session. If this method batches the records, all changes should be returned by multiple invocations of this method before moreComing is set to NO. The sync engine compares each dictionary record with the previous version to determine which properties changed. Use the changesForEntityName:moreComing:error: method instead if you know which properties changed.

If an error occurs, this method returns nil and sets outError to an NSError object that describes the error. If this method returns nil, the ISyncSessionDriver object that invoked this method cancels the sync session.

This method is invoked by the driver during the pushing phase of a sync session, before pulling records. A data source of an ISyncSessionDriver object is required to implement this method or the changesForEntityName:moreComing:error: method if it requests a fast sync—that is, if the preferredSyncModeForEntityName: method may return ISyncSessionDriverModeFast.

This method is optional.

Availability

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

See Also

• – changesForEntityName:moreComing:error:
• – preferredSyncModeForEntityName:

changesForEntityName:moreComing:error:

Returns the changes to records that should be pushed to the sync engine during a fast sync.

- (NSArray *)changesForEntityName:(NSString *)entityName moreComing:(BOOL *)moreComing error:(NSError **)outError

Discussion

Returns an array of ISyncChange objects describing the changes made to records since the last sync session. The array should only contain changes to records belonging to the entity specified by entityName. Returns an empty array if there are no changes to push for this entity.

The moreComing parameter is used to batch changes. If this method sets the value referenced by moreComing to YES, then this method is invoked repeatedly during the pushing phase of a sync session until moreComing is set to NO.

Because this method is invoked during a fast sync, it should return all changes since the last sync session. If this method batches the records, all changed records should be returned by multiple invocations of this method before moreComing is set to NO. Use the changedRecordsForEntityName:moreComing:error: method instead if you don't know which properties changed.

If an error occurs, this method returns nil and sets outError to an NSError object that describes the error. If this method returns nil, the ISyncSessionDriver object that invoked this method cancels the sync session.

This method is invoked by the driver during the pushing phase of a sync session, before pulling records. A data source of an ISyncSessionDriver object is required to implement this method or the changedRecordsForEntityName:moreComing:error: method if it requests a fast sync—that is, if the preferredSyncModeForEntityName: method may return ISyncSessionDriverModeFast.

This method is optional.

Availability

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

See Also

• – changedRecordsForEntityName:moreComing:error:
• – preferredSyncModeForEntityName:

clientDescriptionURL

Returns an NSURL object representing the path to the client description property list.

- (NSURL *)clientDescriptionURL

Discussion

The client description property list specifies client information that the sync engine needs to know to sync its records. See Sync Services Programming Guide for a complete description of the client description file.

This method is required.

Availability

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

See Also

• – registerClientWithIdentifier:descriptionFilePath: (ISyncManager)

Declared In

ISyncSessionDriver.h

clientIdentifier

Returns the client’s unique identifier specified when registering the client.

- (NSString *)clientIdentifier

Discussion

There are no restrictions on the content or length of the client identifier, but it must be unique across all clients. Typically, it’s a DNS-style name such as com.apple.iCal.

This method is required.

Availability

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

See Also

• – registerClientWithIdentifier:descriptionFilePath: (ISyncManager)

Declared In

ISyncSessionDriver.h

deleteAllRecordsForEntityName:error:

Deletes all records for the specified entity.

- (BOOL)deleteAllRecordsForEntityName:(NSString *)entityName error:(NSError **)outError

Discussion

Returns YES if the request to delete all records belonging to the entity specified by entityName is accepted, otherwise NO. This method only returns NO and sets outError to an NSError object that describes the error if a serious error occurred deleting all records.

This method is required.

Availability

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

Declared In

ISyncSessionDriver.h

entityNamesToPull

Returns an array of NSString objects representing the names of entities this client wants to pull.

- (NSArray *)entityNamesToPull

Discussion

Optionally implement this method to return the names of the entities to pull that must be a subset of the entity names returned by the entityNamesToSync method. If this method is not implemented, the sync session pulls the entities returned by the entityNamesToSync method. Returns an empty array if this client doesn't want to pull any entities.

This method is optional.

Availability

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

See Also

• – entityNamesToSync

entityNamesToSync

Returns an array of NSString objects representing the names of entities this client wants to sync.

- (NSArray *)entityNamesToSync

Discussion

Returns an empty array if this client doesn't want to sync any entities. The sync session pushes and pulls the entities returned by this method unless an alternate set of entities is specified by the optional entityNamesToPull method. If this method is not implemented, the driver syncs all enabled entities contained in the client description property list.

This method is optional.

Availability

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

See Also

• – entityNamesToPull

identifiersForRecordsToDeleteForEntityName:moreComing:error:

Returns the record identifiers for deleted records that should be pushed to the sync engine during a fast sync.

- (NSArray *)identifiersForRecordsToDeleteForEntityName:(NSString *)entityName moreComing:(BOOL *)moreComing error:(NSError **)outError

Discussion

Returns an array of NSString objects representing the record identifiers of records that the client deleted since the last sync. The array should contain only identifiers of deleted records belonging to the entity specified by entityName. This method is invoked during a fast sync only. Returns an empty array if there are no deleted records to push for this entity.

The moreComing parameter is used to batch changes. If this method sets the value referenced by moreComing to YES, then this method is invoked repeatedly during the pushing phase of a sync session until moreComing is set to NO.

Alternatively, you can implement the changedRecordsForEntityName:moreComing:error: method using theISyncChangeTypeDelete constant to denote a deleted record.

If an error occurs, this method returns nil and sets outError to an NSError object that describes the error. If this method returns nil, the ISyncSessionDriver object that invoked this method cancels the sync session.

This method is invoked by the driver during the pushing phase of a sync session, before pulling records. A data source of an ISyncSessionDriver object can optionally implement this method or the changesForEntityName:moreComing:error: method using theISyncChangeTypeDelete constant to denote a deleted record.

This method is optional.

Availability

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

See Also

• – changesForEntityName:moreComing:error:
• – preferredSyncModeForEntityName:

lastAnchorForEntityName:

Returns the last sync anchor for the specified entity name.

- (NSString *)lastAnchorForEntityName:(NSString *)entityName

Parameters

entityName

An entity name.

Return Value

A sync anchor corresponding to the entity name that was saved locally and returned by the nextAnchorForEntityName: method in the previous sync session.

Discussion

This method is invoked immediately after a sync session is created and before pushing records. This method is optional. However, if you implement this method you must also implement the nextAnchorForEntityName: method.

See Also

• – nextAnchorForEntityName:

nextAnchorForEntityName:

Returns the next sync anchor for the specified entity name.

- (NSString *)nextAnchorForEntityName:(NSString *)entityName

Parameters

entityName

An entity name.

Return Value

A new sync anchor corresponding to the entity name that is saved locally.

Sync anchors must be globally unique NSString objects. Typically, sync anchors contain a UUID or date.

Discussion

This method is invoked once per entity name after pushing records just before mingling, and once per entity name after pulling records just before accepting changes. This method is optional. However, if you implement this method you must also implement the lastAnchorForEntityName: method.

See Also

• – lastAnchorForEntityName:

preferredSyncModeForEntityName:

Returns the client's preferred sync mode for the session.

- (ISyncSessionDriverMode)preferredSyncModeForEntityName:(NSString *)entity

Discussion

Returns one of these constants that specifies the preferred sync mode for this client: ISyncSessionDriverModeFast, ISyncSessionDriverModeSlow, and ISyncSessionDriverModeRefresh. This method is invoked by the driver during the negotiation phase of a sync session, before pushing records.

This method is required.

Availability

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

See Also

• – clientDidResetEntityNames: (ISyncSession)
• – clientWantsToPushAllRecordsForEntityNames: (ISyncSession)
• – shouldPushChangesForEntityName: (ISyncSession)
• – shouldPushAllRecordsForEntityName: (ISyncSession)
• – shouldPullChangesForEntityName: (ISyncSession)
• – shouldReplaceAllRecordsOnClientForEntityName: (ISyncSession)

Declared In

ISyncSessionDriver.h

recordsForEntityName:moreComing:error:

Returns records for the given entity name that should be pushed to the sync engine during a slow sync.

- (NSDictionary *)recordsForEntityName:(NSString *)entityName moreComing:(BOOL *)moreComing error:(NSError **)outError

Discussion

Returns a dictionary where the keys are record identifiers and the values are dictionary records that you want to push. The dictionary records must be suitable for pushing to the sync engine and belong to the entity specified by entityName. A dictionary record contains the properties of a record that you want to sync. All dictionary records must contain a value for the ISyncRecordEntityNameKey key that identifies the record’s entity. This method returns an empty dictionary if there are no records to push for this entity.

The moreComing parameter is used to batch records. If this method sets the value referenced by moreComing to YES, then this method is invoked repeatedly during the pushing phase of a sync session until moreComing is set to NO.

Because this method is invoked during a slow sync, it should return all records for the given entity. If this method batches the records, all records should be returned by multiple invocations of this method before moreComing is set to NO. Otherwise, the sync engine assumes you deleted the records that you did not push and data loss may result.

If an error occurs, this method returns nil and sets outError to an NSError object that describes the error. If this method returns nil, the ISyncSessionDriver object that invoked this method cancels the sync session.

This method is invoked by the driver during the pushing phase of a sync session, before pulling records.

This method is required.

Availability

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

Declared In

ISyncSessionDriver.h

schemaBundleURLs

Returns an array containing NSURL objects representing the path to schemas this client uses.

- (NSArray *)schemaBundleURLs

Discussion

A schema can define new entities and properties, and extend existing entities. A schema bundle may contain other files, such as images and localization files. The returned array should contain URLs for all the schemas—including the public schemas—that this client intends to use. See Sync Services Programming Guide for more details on the schema format and contents of a schema bundle.

This method is required.

Availability

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

See Also

• – registerSchemaWithBundlePath: (ISyncManager)

Declared In

ISyncSessionDriver.h

sessionBeginTimeout

Returns the time, in seconds, that the client is willing to wait for a sync session to begin.

- (NSTimeInterval)sessionBeginTimeout

Discussion

The default value is 60.0 seconds. This method is optional.

Availability

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

See Also

• + beginSessionWithClient:entityNames:beforeDate: (ISyncSession)

sessionPullChangesTimeout

Returns the time, in seconds, that the client is willing to wait for a sync session to mingle—that is, prepare to pull changes.

- (NSTimeInterval)sessionPullChangesTimeout

Discussion

The default value is 600.0 seconds. This method is optional.

Availability

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

See Also

• – prepareToPullChangesForEntityNames:beforeDate: (ISyncSession)

Constants

Use these constants as possible return values for the preferredSyncModeForEntityName: method. Read Managing Your Sync Session in Sync Services Programming Guide for a description of the different sync modes.

Use these constants as possible return values for the applyChange:forEntityName:remappedRecordId:formattedRecord:error: method.

---