Sync Services is a framework containing all the components you need to sync your applications and devices. If your application uses Sync Services, user data can be synced with other applications and devices on the same computer, or other computers over the network via MobileMe. Ideally, all Mac OS X applications should sync user data quickly and quietly in the background. Consequently, user data is available when and where the user wants it.
Important: If your application uses the Sync Services and Address Book frameworks together, then you should not use Sync Services to sync data shared with the Address Book Framework. The Address Book Framework already syncs its records with Sync Services, so applications sharing the Address Book data do not have to (and should not) sync those records. The results are unpredictable and may result in data loss, if you attempt to sync the same data as the Address Book Framework.
Concurrency Note: The shared ISyncManager
object in the Sync Services framework is thread safe. No additional locking or other synchronization is required when using ISyncManager
methods. However, other objects vended by Sync Services should be used in the thread in which they were created. Typically an ISyncSession
object is used by the thread in which it is created.
You should read this document if you want to sync your application’s data. Types of applications include end-user applications, tools, or servers. For example, a tool may be an interface to a device (such as a phone) or a framework that maintains persistent data. You can use existing schemas for contacts, calendars, and bookmarks. You can also extend a schema or create your own schema to sync custom objects. You can use the Sync Services API from both Objective-C and C programs.
Before using Sync Services you should understand what it is used for, what the system architecture is, and what the core classes are. Because sync sessions are implemented as finite state machines, you also need an in-depth understanding of the states and transactions within a sync session regardless of which approach you choose. The consequences of syncing incorrectly are severe—users may lose their data—so read the following conceptual articles before using this framework. In particular, you need to read “Managing Your Sync Session” if you are writing your own sync methods.
“Why Use Sync Services?” explains why syncing is an important feature to end users and may become commonplace on Mac OS X.
“Sync Services Overview” describes the components of the sync architecture and defines syncing terms such as those used for the different sync modes.
“Managing Your Sync Session” describes the anatomy of an ISyncSession
object. It contains details about each state in the finite state machine and the methods that can be used in each state.
A simple approach to syncing is to use a delegation model where a driver sends messages to a data source and delegate while syncing. You can also use Core Data as the persistent store for local records and to create your schema. Read the following articles to learn more about these approaches:
“Using a Session Driver” describes how to use an ISyncSessionDriver
object to control a sync session.
“Syncing Core Data Applications” describes how to create a Core Data application that syncs managed objects.
If you need more control, read the following articles that cover the low-level classes and methods you use to manage sync sessions:
“Creating a Sync Schema” describes how to create your own custom schemas and contains a description of the sync schema property list.
“Registering Schemas” describes how to register and unregister schemas.
“Registering Clients” describes how to register and unregister clients, as well as provides a description of the client description property list.
“Syncing Relationships” describes how to add relationships to your object model and schema. It also contains tips on pushing and pulling relationships.
“Syncing with Other Clients” describes how to configure your client to sync with other clients.
“Using Sync Anchors” describes how to use sync anchors to improve performance and reliability.
“Filtering Records” describes how to filter the types of records your application syncs.
“Formatting Records” describes how to change the format of a record without the sync engine interpreting the change as a change to the property values.
Read this article if you want to exclude your application preferences from syncing:
“Syncing Preferences” describes how to exclude selected preferences or all preferences of an application from syncing when the user turns this feature on.
For an in-depth description of the Sync Services API, read:
If you are using or extending an Apple Applications schema, such as contacts, bookmarks or calendars, read:
If you are accessing Sync Services from a C application, refer to the SeeMyFriends sample code and this document for more information about mixing C and Objective-C:
Carbon-Cocoa Integration Guide
Last updated: 2009-08-06