---

NSPersistentStoreCoordinatorSyncing Protocol Reference

Overview

The NSPersistentStoreCoordinatorSyncing protocol defines callback messages that are sent to a sync handler while a Core Data application syncs. You set a sync handler when you start a sync session using the syncWithClient:inBackground:handler:error: NSPersistentStoreCoordinator method. The callback messages defined in this protocol are sent before and after most phases of a sync session. A sync handler may implement these optional methods to customize the behavior of sync sessions. For example, a sync handler might change records before their pushed to the sync engine or verify changes pulled from the sync engine before they are applied to managed objects.

Read Syncing Core Data Applications in Sync Services Programming Guide for more details on using Core Data sync.

Tasks

Getting Managed Contexts

• – managedObjectContextsToMonitorWhenSyncingPersistentStoreCoordinator:
• – managedObjectContextsToReloadAfterSyncingPersistentStoreCoordinator:

Controlling Sync Behavior

• – persistentStoreCoordinatorShouldStartSyncing:
• – persistentStoreCoordinator:willPushChangesInSyncSession:
• – persistentStoreCoordinator:didPushChangesInSyncSession:
• – persistentStoreCoordinator:willPullChangesInSyncSession:
• – persistentStoreCoordinator:didPullChangesInSyncSession:
• – persistentStoreCoordinator:didFinishSyncSession:
• – persistentStoreCoordinator:didCancelSyncSession:error:
• – persistentStoreCoordinator:willPushRecord:forManagedObject:inSyncSession:
• – persistentStoreCoordinator:willDeleteRecordWithIdentifier:inSyncSession:
• – persistentStoreCoordinator:willApplyChange:toManagedObject:inSyncSession:
• – persistentStoreCoordinator:didApplyChange:toManagedObject:inSyncSession:
• – persistentStoreCoordinator:didCommitChanges:inSyncSession:

Instance Methods

managedObjectContextsToMonitorWhenSyncingPersistentStoreCoordinator:

Returns the managed object contexts that the receiver wants to monitor during the next sync session.

- (NSArray *)managedObjectContextsToMonitorWhenSyncingPersistentStoreCoordinator:(NSPersistentStoreCoordinator *)coordinator

Parameters

coordinator

The persistent store coordinator being synced.

Return Value

An array containing the managed object contexts to monitor.

Discussion

The sync session uses this method to determine if pulled changes should be applied. Pulled changes are ignored—not applied to a record—if any of the managed contexts, returned by this method, changed the same record. In this case, the local changes are pushed in the next sync session and the sync engine is responsible for resolving any conflicts.

Conflicts can result if clients are allowed to change managed objects during a sync session or editing is not disabled during syncing. For example, conflicts can result if the user changes a managed object while the sync session is pulling changes to the same managed object. However, implementing this method does not handle all types of conflicts. The user may still modify a managed object after a sync session applies changes and before a sync session finishes. To avoid this, you should either not allow editing during a sync session, or be prepared to merge local changes with pulled changes after a sync session.

Therefore, although this method is optional, not implementing this method increases the risk of conflicts unless you sync synchronously or disable editing when syncing.

Availability

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

See Also

• – managedObjectContextsToReloadAfterSyncingPersistentStoreCoordinator:

Declared In

ISyncCoreData.h

managedObjectContextsToReloadAfterSyncingPersistentStoreCoordinator:

Returns the managed object contexts that should be reloaded after the persistent store coordinator syncs.

- (NSArray *)managedObjectContextsToReloadAfterSyncingPersistentStoreCoordinator:(NSPersistentStoreCoordinator *)coordinator

Parameters

coordinator

The persistent store coordinator being synced.

Return Value

An array containing the managed object contexts to reload.

Discussion

If you do not implement this method, it is your responsibility to reload managed object contexts after a sync.

Availability

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

See Also

• – managedObjectContextsToMonitorWhenSyncingPersistentStoreCoordinator:

Declared In

ISyncCoreData.h

persistentStoreCoordinator:didApplyChange:toManagedObject:inSyncSession:

Informs the receiver that pulled changes were applied to a specific record during a sync session.

- (void)persistentStoreCoordinator:(NSPersistentStoreCoordinator *)coordinator didApplyChange:(ISyncChange *)change toManagedObject:(NSManagedObject *)managedObject inSyncSession:(ISyncSession *)session

Parameters

coordinator

The persistent store coordinator being synced.

change

The changes that was applied.

managedObject

The managed object that corresponds to the changes.

session

The sync session that applied the changes.

Availability

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

See Also

• – persistentStoreCoordinator:willApplyChange:toManagedObject:inSyncSession:

Declared In

ISyncCoreData.h

persistentStoreCoordinator:didCancelSyncSession:error:

Informs the receiver that a session was cancelled.

- (void)persistentStoreCoordinator:(NSPersistentStoreCoordinator *)coordinator didCancelSyncSession:(ISyncSession *)session error:(NSError *)error

Parameters

coordinator

The persistent store coordinator being synced.

session

The sync session that was cancelled.

error

Describes the error that caused the cancellation.

Availability

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

See Also

• – persistentStoreCoordinator:didFinishSyncSession:

Declared In

ISyncCoreData.h

persistentStoreCoordinator:didCommitChanges:inSyncSession:

Informs the receiver that all applied changes were committed during a sync session.

- (void)persistentStoreCoordinator:(NSPersistentStoreCoordinator *)coordinator didCommitChanges:(NSDictionary *)changes inSyncSession:(ISyncSession *)session

Parameters

coordinator

The persistent store coordinator being synced.

changes

A dictionary containing the changes to possibly multiple objects that were applied and committed. The dictionary contains the following keys: NSInsertedObjectsKey, NSUpdatedObjectsKey, and NSDeletedObjectsKey.

session

The sync session that committed the changes.

Discussion

Typically, this method is invoked after the persistent store changes are saved and the sync session receives the clientCommittedAcceptedChanges message. This method can be invoked multiple times during a sync session.

Availability

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

Declared In

ISyncCoreData.h

persistentStoreCoordinator:didFinishSyncSession:

Informs the receiver that a session was finished.

- (void)persistentStoreCoordinator:(NSPersistentStoreCoordinator *)coordinator didFinishSyncSession:(ISyncSession *)session

Parameters

coordinator

The persistent store coordinator being synced.

session

The sync session that finished.

Availability

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

See Also

• – persistentStoreCoordinator:didCancelSyncSession:error:

Declared In

ISyncCoreData.h

persistentStoreCoordinator:didPullChangesInSyncSession:

Informs the receiver that changes were pulled from the sync engine.

- (void)persistentStoreCoordinator:(NSPersistentStoreCoordinator *)coordinator didPullChangesInSyncSession:(ISyncSession *)session

Parameters

coordinator

The persistent store coordinator being synced.

session

The sync session that pulled the changes.

Availability

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

See Also

• – persistentStoreCoordinator:willPullChangesInSyncSession:

Declared In

ISyncCoreData.h

persistentStoreCoordinator:didPushChangesInSyncSession:

Informs the receiver that client changes were pushed to the sync engine.

- (void)persistentStoreCoordinator:(NSPersistentStoreCoordinator *)coordinator didPushChangesInSyncSession:(ISyncSession *)session

Parameters

coordinator

The persistent store coordinator being synced.

session

The sync session that pushed the changes.

Availability

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

See Also

• – persistentStoreCoordinator:willPushChangesInSyncSession:

Declared In

ISyncCoreData.h

persistentStoreCoordinator:willApplyChange:toManagedObject:inSyncSession:

Informs the receiver that pulled changes will be applied to a specific record during a sync session.

- (ISyncChange *)persistentStoreCoordinator:(NSPersistentStoreCoordinator *)coordinator willApplyChange:(ISyncChange *)change toManagedObject:(NSManagedObject *)managedObject inSyncSession:(ISyncSession *)session

Parameters

coordinator

The persistent store coordinator being synced.

change

The changes that will be applied. An ISyncChange object can represent a delete record change, as well as an insert and update record change.

managedObject

The managed object that corresponds to the changes.

session

The sync session that is applying the changes.

Return Value

The change to apply. nil if you do not want to apply this change.

Discussion

Implement this method if you want to modify a change before it is applied.

Availability

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

See Also

• – persistentStoreCoordinator:didApplyChange:toManagedObject:inSyncSession:

Declared In

ISyncCoreData.h

persistentStoreCoordinator:willDeleteRecordWithIdentifier:inSyncSession:

Informs the receiver that a specific record will be deleted during the pushing phase of a sync session.

- (BOOL)persistentStoreCoordinator:(NSPersistentStoreCoordinator *)coordinator willDeleteRecordWithIdentifier:(NSString *)identifier inSyncSession:(ISyncSession *)session

Parameters

coordinator

The persistent store coordinator being synced.

identifier

The identifier for the record that will be deleted.

session

The sync session that is pushing records.

Return Value

YES to delete the record; otherwise, NO.

Discussion

Implement this method if you want to verify if a record should be deleted before it is deleted.

Availability

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

Declared In

ISyncCoreData.h

persistentStoreCoordinator:willPullChangesInSyncSession:

Informs the receiver that changes will be pulled from the sync engine.

- (void)persistentStoreCoordinator:(NSPersistentStoreCoordinator *)coordinator willPullChangesInSyncSession:(ISyncSession *)session

Parameters

coordinator

The persistent store coordinator being synced.

session

The sync session that is pulling the changes.

Availability

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

See Also

• – persistentStoreCoordinator:didPullChangesInSyncSession:

Declared In

ISyncCoreData.h

persistentStoreCoordinator:willPushChangesInSyncSession:

Informs the receiver that client changes will be pushed to the sync engine.

- (void)persistentStoreCoordinator:(NSPersistentStoreCoordinator *)coordinator willPushChangesInSyncSession:(ISyncSession *)session

Parameters

coordinator

The persistent store coordinator being synced.

session

The sync session that is pushing the changes.

Availability

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

See Also

• – persistentStoreCoordinator:didPushChangesInSyncSession:

Declared In

ISyncCoreData.h

persistentStoreCoordinator:willPushRecord:forManagedObject:inSyncSession:

Informs the receiver that client changes to a specific record will be pushed to the sync engine.

- (NSDictionary *)persistentStoreCoordinator:(NSPersistentStoreCoordinator *)coordinator willPushRecord:(NSDictionary *)record forManagedObject:(NSManagedObject *)managedObject inSyncSession:(ISyncSession *)session

Parameters

coordinator

The persistent store coordinator being synced.

record

The record that will be pushed.

managedObject

The managed object that corresponds to the record.

session

The sync session that is pushing records.

Return Value

The record to push. nil if you do not want to push the record.

Discussion

Implement this method if you want to modify a record before pushing it.

Availability

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

Declared In

ISyncCoreData.h

persistentStoreCoordinatorShouldStartSyncing:

Returns whether or not the persistent store coordinator should start syncing.

- (BOOL)persistentStoreCoordinatorShouldStartSyncing:(NSPersistentStoreCoordinator *)coordinator

Parameters

coordinator

The persistent store coordinator being synced.

Return Value

YES if the persistent store coordinator can start syncing; otherwise, NO.

Availability

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

Declared In

ISyncCoreData.h

---