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.

Registering 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;

}

Setting 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 listed in Table 1.

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>