---

Introduction to Sync Services Programming Guide

Contents:

Who Should Read This Document?
Organization of This Document
See Also

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 .Mac. 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.

Who Should Read This Document?

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.

Organization of This Document

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. 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.

The following articles cover common tasks and contain sample code:

• “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.

An alternative approach 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 article 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.

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.

See Also

For an in-depth description of the Sync Services API, read:

• Sync Services Framework Reference

If you are using or extending an Apple Applications schema, such as contacts, bookmarks or calendars, read:

• Apple Applications Schema Reference

If you are accessing Sync Services from a C application, refer to the Carbon example in /Developer/Examples/Sync Services and this document for more information about mixing C and Objective-C:

• Carbon-Cocoa Integration Guide

The /Developer/Examples/Sync Services folder contains more in-depth code examples.

---