< Previous PageNext Page > Hide TOC

Registering Clients

Before you can sync any records, you need to register your client with the sync engine. You do this by specifying a unique client identifier and client description property list.

Contents:

When Do You Register a Client?
How to Register a Client
Client Description Properties


When Do You Register a Client?

The lifetime of a sync client is dependent on the lifetime of the data you are syncing, not the lifetime of the application or tool that syncs. The sync engine keeps a snapshot of the client records that it uses when mingling in order to compute the changes that will be pulled by the client—changes that were possibly made by other clients. This information is retained until you unregister your client.

If you unregister a client, the snapshot is removed along with all other information the sync engine knew about your client. Consequently, if you unregister your client when the application terminates, you will not be able to fast sync the next time it launches.

Typically, you use one client identifier per data source or data file containing the records you want to sync, and you reuse that client identifier each time your application or tool launches. For this reason, you typically use a reverse DNS-style name as your client identifier. For example, the client identifier for the Events example application is com.mycompany.syncexamples.events.

You can see whether a client exists before registering it (see the sample code in “How to Register a Client”). You unregister your client only if your data is corrupted or removed.

How to Register a Client

You register a client using the registerClientWithIdentifier:descriptionFilePath: method of ISyncManager. When you register a client, you specify a unique client identifier. For example, you can use a reverse DNS-style name such as com.mycompany.syncexamples.MediaAssets.

You also specify a client description property list that describes the client’s capabilities. You cannot sync any records without specifying the supported entities and properties in the client description. The client description may contain a subset of the entities and properties defined in a schema but must contain all the required properties. If a client does not support required properties it will fail to register. See “Client Description Properties” for a description of this property list.

You use the clientWithIdentifier: method of ISyncManager to get an existing registered client. In this sample code, the getSyncClient method returns a client if it exists; otherwise, it registers it:

// Returns a sync client for this application
- (ISyncClient *)getSyncClient {
    // Get an existing client
    ISyncClient *client =
         [[ISyncManager sharedManager] clientWithIdentifier:clientID];
    if (client != nil) {
        return client;
    }
 
    client = [[ISyncManager sharedManager] registerClientWithIdentifier:clientID
        descriptionFilePath:[[NSBundle mainBundle] pathForResource:@"ClientDescription" ofType:@"plist"]];
 
    return client;
}

Client Description Properties

The client description is a property list stored in a file so that it can be updated independent of the client process. The sync engine periodically checks the client description file for changes, and if the file changed, the sync engine updates the client’s capabilities.

The properties of a client description are as follows:

Property

Description

Type

A string identifying the type of client. This string must be one of the following predefined values: app (an application like iCal or Address Book), device (a phone, PDA or iPod), server (.Mac) or peer (a peer-to-peer client). The default is app.

DisplayName

A string containing the display name for this client.

ImagePath

Path to an image of the client. This must be an absolute path except when the description is taken from a file. If it is a relative path, then it is expected to be relative to the folder containing the client description file.

Entities

A dictionary mapping entity names to an array. The array contains an array of property names (both attributes and relationships) identifying the properties supported by the client on each record type. The array must include the com.apple.syncservices.RecordEntityName property. This key is required.

NeverFormatsRelationships

A boolean value set to true if the client never reformats the destination records of pulled relationships, false otherwise. The default value is false. If this property is set to true, then the sync engine can perform some optimizations on behalf of the client. Read “Formatting Records” for how to format records.

PullOnlyEntities

An array containing the names of the record types for which the client will pull changes from the engine but never push changes to the engine.

PushOnlyEntities

An array containing the names of the record types for which the client will only push changes to the engine but never pull changes from the engine.

SyncsWith

A dictionary specifying the kinds of clients this client wants to sync with. See the setShouldSynchronize:withClientsOfType: method of ISyncClient for details.

For example, the following client description property list is used by the MediaAssets and Events example applications to describe their client capabilities. It happens that the client descriptions for each application are the same—each application supports both entities, Event and Media, and all their properties.

<plist version="1.0">
<dict>
    <key>DisplayName</key>
    <string>Events</string>
    <key>ImagePath</key>
    <string>Events.icns</string>
    <key>Entities</key>
    <dict>
        <key>com.mycompany.syncexamples.Event</key>
        <array>
            <string>com.apple.syncservices.RecordEntityName</string>
            <string>date</string>
            <string>startDate</string>
            <string>endDate</string>
            <string>title</string>
            <string>media</string>
        </array>
        <key>com.mycompany.syncexamples.Media</key>
        <array>
            <string>com.apple.syncservices.RecordEntityName</string>
            <string>date</string>
            <string>imageURL</string>
            <string>title</string>
            <string>event</string>
        </array>
    </dict>
</dict>
</plist>

Syncs With Properties

The properties of the SyncsWith dictionaries are as follows:

Property

Description

SyncAlertTypes

An array of the client types that this client wants to sync with. This key is required.

SyncAlertToolPath

The path of a tool that the engine will invoke when a client of the specified type starts syncing. If it is a relative path, then it is expected to be relative to the folder containing the client description file. The tool is passed two key-value pairs as arguments on the command line. The "--sync" key is followed by the client identifier. The “--entitynames” key is followed by a string containing the entity names to be synced separated by commas. The order of the key-value pairs is arbitrary.

See “Setting Alert Handlers Using the Client Description” for an example of a client description property list that uses the SyncsWith property.



< Previous PageNext Page > Hide TOC


© 2004, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-10-31)


Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.