Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
Registering a Client
Registering a client needs to occur only once during the initial startup of the client. After that initial registration, the truth database will remember the application until it unregisters itself. The registering of a client is a simple matter of pushing a plist to the ISyncManager, which provides all the information the truth database needs to know about the application.
Client Description
As part of the client registration process, you hand off the location of a client description file to the ISyncManager. This description file contains all the data that the truth database needs to know about your application. This client description file is a simple plist with the keys described in the following table.
|
Key |
Description |
|
Type |
A string identifying the type of client. This string must be one of the following predefined values: app(an application such as iCal or AddressBook), 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. |
|
Image Path |
Path to an image of the client, which must be an absolute path except when the description is taken from a file. If it is a relative path, 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) that identify the properties supported by the client on each record type. This key is required. |
|
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 |
Any 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: ISyncClient method for details. |
With these properties, I have defined the client description file as follows. The bookmarks schema is published by Apple, so I can get the information I need about the entities directly from them:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>DisplayName</key> <string>bookmarkSyncer</string> <key>Type</key> <string>app</string> <key>ImagePath</key> <string>app.icns</string> <key>Entities</key> <dict> <key>com.apple.bookmarks.Bookmark</key> <array> <string>name</string> <string>position</string> <string>url</string> <string>parent</string> </array> <key>com.apple.bookmarks.Folder</key> <array> <string>name</string> <string>position</string> <string>children</string> <string>parent</string> </array> </dict> <key>SyncsWith</key> <dict> <key>SyncAlertTypes</key> <array> <string>app</string> <string>device</string> <string>server</string> </array> </dict> </dict> </plist>
The entities and their attributes and relationships are taking directly from Apple’s published schema reference. I did not define the PullOnlyEntities or the PushOnlyEntities in this description because I want to be able to both push and pull in this example. If I were going to only read the bookmarks, I would define the entities as pull only, and vice versa if I only wanted to write bookmarks out to the database.
Helper Application
SyncAlertToolPath is one area of the client description that I will not discuss in detail in this article. This property defines a helper application that will be called only when the primary application is not currently running. If you want your application to be kept up to date—even when the application is not running—you could write a small command-line app to receive changes from the truth database while your primary application is not running and manage the data updates for you. If, however, it is sufficient to just receive data updates while your application is running, this property and command-line tool can be skipped.
Registering the Client
Once the client description is written, it is a simple matter of notifying the ISyncManager that you want to register a client. After adding the Sync framework to your project and importing it into your application, simply call the ISyncManager:
ISyncClient *syncClient = [[ISyncManager sharedManager] registerClientWithIdentifier:clientIdentifier descriptionFilePath:plistPath];
The clientIdentifer is a string identifier that is unique to your application. Apple recommends using a reverse dns style name for this identifier such as com.mycompany.myapp. The plist path is the absolute path for the client description file.
Once your client has been registered the first time, you can retrieve a reference to the ISyncClient on subsequent executions of your application by calling the following:
ISyncClient *syncClient = [[ISyncManager sharedManager] clientWithIdentifier:clientIdentifier];
As with the previous call, the clientIdentifier is the unique identifier for your application.