---

ISyncClient Class Reference

Overview

An ISyncClient object represents an application, tool, or device that syncs records—for example, Address Book, .Mac, or a mobile phone.

An ISyncClient object encapsulates information that assists the sync engine in identifying your client, determining its capabilities, and maintaining its state. For example, you use an ISyncClient object to get the list of entities that a client supports, find out when an entity was last synced, and setup filters. ISyncClient also provides some methods for controlling the sync mode.

You create an ISyncClient object by registering a unique client identifier with the shared ISyncManager object. Send either the registerClientWithIdentifier:descriptionFilePath: or clientWithIdentifier: message to the shared ISyncManager object. You obtain the shared instance by sending sharedManager to ISyncManager class. You unregister a client, remove all information the sync engine knows about that client, using the unregisterClient: ISyncManager method. See Sync Services Programming Guide for more information on registering and unregistering clients. You should never subclass or instantiate ISyncClient directly.

When you create a client using the registerClientWithIdentifier:descriptionFilePath: ISyncManager method, you specify the client’s capabilities using a client description file. Some of the ISyncClient methods are simply accessors that you can use to get or set the properties of this client description. For example, you use the client description to specify the entities and properties that a client supports, and you use the supportedEntityNames method to get those supported entities. You can also use the canPushChangesForEntityName: and canPullChangesForEntityName: methods to find out which entities your client can push and pull. See Sync Services Programming Guide to learn more about the properties of a client description file.

Typically, the user requests that an application or device be resets (so that all the records on the client are replaced by the records in the truth database). The preference panel or configuration tool that receives this user request sends a setShouldReplaceClientRecords:forEntityNames: message to the ISyncClient so that the next time the client syncs the truth is pulled. This is called a pull the truth sync mode and must be requested before the sync session enters the negotiation state.

Clients can optionally sync simultaneously. Use the setShouldSynchronize:withClientsOfType: method to specify the type of client your client is interested in syncing simultaneously with. If you want to participate in a sync when your application isn’t running, use the setSyncAlertToolPath: method to specify that an alert tool be launched. Otherwise, use the setSyncAlertHandler:selector: method to specify that a target and action be invoked when another client of the specified type syncs. If both a sync tool and sync target-action are registered, only the sync target-action is invoked.

If your application uses only a subset of the entities, attributes, and relationships defined in a schema, then you can restrict pulled records to that subset using custom filters. You set filters using the setFilters: method. Each filter is expected to conform to the ISyncFiltering protocol and are used to reject or accept records from the sync engine before they are pulled. Use the filters method to get the filters currently used by a client. See Sync Services Programming Guide for more information on using filters.

Tasks

Getting and Setting Attributes

• – clientIdentifier
• – clientType
• – displayName
• – imagePath
• – setDisplayName:
• – setImagePath:
• – objectForKey:
• – setObject:forKey:

Specifying Supported Entities

• – canPushChangesForEntityName:
• – canPullChangesForEntityName:
• – supportedEntityNames

Getting Sync Status

• – lastSyncDateForEntityName:
• – lastSyncStatusForEntityName:

Enabling Entities

• – enabledEntityNames
• – isEnabledForEntityName:
• – setEnabled:forEntityNames:

Replacing Records

• – setShouldReplaceClientRecords:forEntityNames:
• – shouldReplaceClientRecordsForEntityName:

Filtering

• – filters
• – setFilters:

Alerting Clients

• – shouldSynchronizeWithClientsOfType:
• – setShouldSynchronize:withClientsOfType:
• – setSyncAlertToolPath:
• – setSyncAlertHandler:selector:
• – syncAlertToolPath

Instance Methods

canPullChangesForEntityName:

Returns YES if the client supports pulling changes to entity records specified by entityName, NO otherwise.

- (BOOL)canPullChangesForEntityName:(NSString *)entityName

Discussion

Use this method to determine if a client is capable of pulling entity records. For example, an iPod or phone client might pull but never push changes to contacts and calendars. This property is set when registering the client.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – canPushChangesForEntityName: (ISyncManager)
• – registerClientWithIdentifier:descriptionFilePath:

Declared In

ISyncClient.h

canPushChangesForEntityName:

Returns YES if the client supports pushing changes to entity records specified by entityName, NO otherwise.

- (BOOL)canPushChangesForEntityName:(NSString *)entityName

Discussion

Use this method to determine if a client is capable of pushing entity records. For example, an iPod or phone client might pull but never push changes to contacts and calendars. This property is set when registering the client.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – canPullChangesForEntityName: (ISyncManager)
• – registerClientWithIdentifier:descriptionFilePath:

Declared In

ISyncClient.h

clientIdentifier

Returns the client’s identifier specified when registering the client.

- (NSString *)clientIdentifier

Discussion

You set the client identifier when registering the client using the registerClientWithIdentifier:descriptionFilePath: ISyncManager method. The client identifier is expected to be unique across all clients and is typically a DNS-style name.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

ISyncClient.h

clientType

Returns the receiver’s client type.

- (NSString *)clientType

Discussion

The returned string is expected to be one of the constants described in “Constants.” The client type is used to match clients that want to sync simultaneously. You specify the client type in the client description file when registering the client using the registerClientWithIdentifier:descriptionFilePath: ISyncManager method.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

ISyncClient.h

displayName

Returns the receiver’s display name specified in the client description file when registering the client or by sending setDisplayName: to the receiver.

- (NSString *)displayName

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – registerClientWithIdentifier:descriptionFilePath: (ISyncManager)

Declared In

ISyncClient.h

enabledEntityNames

Returns an array of NSString objects containing the names of the entities that are enabled.

- (NSArray*)enabledEntityNames

Discussion

The enabled entities may be a subset of the supported entities. Use setEnabled:forEntityNames: to enable or disable an entity. You should pass the returned array as the entityNames argument to one of the beginSessionWithClient... ISyncSession class methods when creating a session.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – isEnabledForEntityName:

Declared In

ISyncClient.h

filters

Returns an array of filters that define a subset of the records the client syncs.

- (NSArray*)filters

Discussion

Objects in the returned array are expected to conform to the ISyncFiltering protocol.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setFilters:

Declared In

ISyncClient.h

imagePath

Returns the absolute path to the image representation of the client.

- (NSString *)imagePath

Discussion

You can specify an image path in the client description file when registering a client or by sending setImagePath: to the receiver.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – registerClientWithIdentifier:descriptionFilePath: (ISyncManager)

Declared In

ISyncClient.h

isEnabledForEntityName:

Returns YES if the entity specified by entityName is enabled, NO otherwise.

- (BOOL)isEnabledForEntityName:(NSString *)entityName

Discussion

If this method returns NO, the sync engine does not allow the client to sync records of type entityName.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – enabledEntityNames
• – setEnabled:forEntityNames:

Declared In

ISyncClient.h

lastSyncDateForEntityName:

Returns the start date of the last time an entity, specified by entityName, was synced.

- (NSDate *)lastSyncDateForEntityName:(NSString *)entityName

Discussion

Returns a start date of the last sync even if the last sync failed. Returns the start date of the previous sync if the client is currently syncing the entity. Returns nil if the client never synced the specified entity or the entity is not supported.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – lastSyncStatusForEntityName:

Declared In

ISyncClient.h

lastSyncStatusForEntityName:

Returns the status of the last time an entity, specified by entityName was synced.

- (ISyncStatus)lastSyncStatusForEntityName:(NSString *)entityName

Discussion

For example, the last sync may have succeeded, may have failed, may be in progress, or may have been canceled (see “Constants” for other possible return values). Returns ISyncStatusNever if the client never synced the specified entity, or the entity is not supported.

The sync engine maintains the last sync information for as long as the client supports entityName. When a client stops supporting entityName, the last sync information for that entity is removed. If the client starts supporting entityName again, this method behaves as if the client never synced the entity.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – lastSyncDateForEntityName:

Declared In

ISyncClient.h

objectForKey:

Returns the object for key that was specified using the setObject:forKey: method.

- (id)objectForKey:(NSString *)key

Availability

• Available in Mac OS X v10.4 and later.

Declared In

ISyncClient.h

setDisplayName:

Sets the display name for the receiver to displayName.

- (void)setDisplayName:(NSString *)displayName

Discussion

The display name may be used by GUI applications to graphically identify the client to users. You can also specify a display name when registering the client using the client description file.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – registerClientWithIdentifier:descriptionFilePath: (ISyncManager)
• – displayName

Declared In

ISyncClient.h

setEnabled:forEntityNames:

If flag is YES, enables the entities specified by entityNames, otherwise disables them.

- (void)setEnabled:(BOOL)flag forEntityNames:(NSArray *)entityNames

Discussion

The entityNames array of NSString objects is expected to contain names of supported entities, otherwise an exception is raised.

The first time a client syncs, a panel appears asking the user if it’s OK to sync entities belonging to a data class (a panel may appear for each data class). If the user declines then the entities are disabled, otherwise they are enabled. If you want to allow the user to enable entities, invoke this method by passing YES as the flag argument and all the entity names in the data class as the entityNames argument. Then the next time the client syncs, a panel appears again asking the user if it’s OK to sync the data class.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – enabledEntityNames
• – isEnabledForEntityName:

Declared In

ISyncClient.h

setFilters:

Sets the receiver’s filters used to control the records pulled from the sync engine to filters, an array of objects conforming to the ISyncFiltering protocol.

- (void)setFilters:(NSArray *)filters

Discussion

You use filters to define a subset of the records that this client syncs.

When pulling changes, the sync engine passes each record to each filter before giving changes to that record to the client. If any one of the filters rejects the record, it is not given to the client. See ISyncFilter Class Reference for some default filters.

This method recomputes the records that need to be sent to the client during the next sync operation which can be expensive. Consequently, do not invoke this method frequently.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – filters

Declared In

ISyncClient.h

setImagePath:

Sets the receiver’s absolute image path to path.

- (void)setImagePath:(NSString *)path

Discussion

The image may be used by GUI applications to represent the client. You can also specify an image path when registering the client using the client description file.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – imagePath (ISyncManager)
• – registerClientWithIdentifier:descriptionFilePath:

Declared In

ISyncClient.h

setObject:forKey:

Associates arbitrary information specified by a key-value pair to the receiver.

- (void)setObject:(id < NSCoding >)value forKey:(NSString *)key

Discussion

This method retains value and copy key. Pass nil for value to release a previously retained value. Use objectForKey:to retrieve the value for a given key. The value is released when the client is unregistered.

This method is provided as a convenience for developers who have additional data they want to store with an object that is not defined in the schema. For example, use this method to store client-specific configuration information if multiple clients are associated with the same user defaults domain or if you want to store a sync anchor.

A sync anchor is an identifier exchanged between a client and a device, or between two clients running on different computers. Typically, the client that initiates a sync is passed a sync anchor to the device or another client at the end of a successful sync. The next time the client syncs, the recipient of the sync anchor passes the anchor back to the original client to verify that it is in a known state.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

ISyncClient.h

setShouldReplaceClientRecords:forEntityNames:

Sets whether or not a client should pull the truth—replace all its records for the specified entities on the next sync.

- (void)setShouldReplaceClientRecords:(BOOL)flag forEntityNames:(NSArray *)entityNames

Discussion

If flag is YES, the client should replace all its local records with the records pulled from the sync engine.

After invoking this method, sending shouldReplaceClientRecordsForEntityName: to any new sessions created for this client returns YES, and sending shouldPushChangesForEntityName: or shouldPushAllRecordsForEntityName: returns NO.

This request takes effect on the next session created after invoking this method and remains in effect until the client successfully passes through the pull phase of that session. The sync engine needs to know whether a client is going to pull the truth before entering the negotiation phase. This is necessary to detect conflicting push the truth and pull the truth requests.

A client should not remove its local records until after the records are successfully pulled from the sync engine. The local records can be safely removed after shouldReplaceClientRecordsForEntityName: returns YES.

This method is typically used by a configuration tool that allows the user to revert to the state of the truth.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

ISyncClient.h

setShouldSynchronize:withClientsOfType:

Adds the receiver as an observer of alerts when clients of the specified type sync.

- (void)setShouldSynchronize:(BOOL)flag withClientsOfType:(NSString *)clientType

Discussion

If flag is YES the receiver is added; otherwise the receiver is removed as an observer for alerts of the specified type. Alternatively, you can specify this information when registering the client using the client description file. You can invoke this method multiple times to register additional client types.

Typically, you use this method to setup a dependency between two clients. For example, Address Book might observe all types of clients, and is given an opportunity to join any syncs which synchronize entities defined in the contacts schema. The .Mac client might observe only device clients, so it can join a Palm or phone sync session. The client is notified only if it has entities in common with the client that initiated the sync.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – shouldSynchronizeWithClientsOfType: (ISyncManager)
• – setSyncAlertHandler:selector:
• – setSyncAlertToolPath:
• – registerClientWithIdentifier:descriptionFilePath:

Declared In

ISyncClient.h

setSyncAlertHandler:selector:

Sets the target and action to be invoked when an observed client creates a session and begins syncing.

- (void)setSyncAlertHandler:(id)handler selector:(SEL)selector

Discussion

When selector is sent to handler, your client has the opportunity to join the sync session.

The selector method is expected to take the receiver (an ISyncClient object) as the first argument and an array of entity names (an NSArray object) as the second argument. The method signature for selector should look like:

• - (void)client:(ISyncClient *)client willSyncEntityNames:(NSArray *)entityNames

If selector returns without creating a session, the sync engine assumes the client will not join the session. If this client already has another handler registered—for example, from another client process—this method raises an exception. An observer is automatically removed when the client terminates.

When you create a session using the beginSessionWithClient:entityNames:beforeDate: ISyncSession class method, you specify how long you are willing to wait for the sync session. This is the length of time you are willing to wait for all the other clients to join the session. If a client takes too long to join a session, the sync engine may proceed without it.

Use this method instead of setSyncAlertToolPath: if you want to notify a running application only. Use setShouldSynchronize:withClientsOfType: to specify the types of clients the receiver wishes to observe. If both a tool and an observer are registered, only the observer is notified.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – shouldSynchronizeWithClientsOfType:
• – syncAlertToolPath

Declared In

ISyncClient.h

setSyncAlertToolPath:

Specifies the absolute path to a tool that is launched when an observed client creates a session and begins syncing.

- (void)setSyncAlertToolPath:(NSString *)path

Discussion

The sync engine retains this path until the client is unregistered or you explicitly change the path using this method. Pass nil if you want to disable the sync alert tool.

When the tool is launched it passes the following command-line arguments:

• --sync <clientIdentifier> --entitynames <entityNames>

The clientIdentifier argument is the identifier of the observed client. The entityNames argument is a single string containing the entity names deliminated by commas that is synced. You can send componentsSeparatedByString: to the string with @"," as the argument to convert it to an array of entity names. The order of the key-value pairs, where --sync and --entitynames are keys, is arbitrary. If the tool terminates without creating a sync session, the sync engine assumes the client will not join the session.

When you create a session using the beginSessionWithClient:entityNames:beforeDate: ISyncSession class method, you specify how long you are willing to wait for the sync session. This is the time you are willing to wait for all the other clients to join the session. If a client takes too long to join a session, the sync engine may proceed without it.

Use this method instead of setSyncAlertHandler:selector: if you want to notify an application or tool that may not be running. Use setShouldSynchronize:withClientsOfType: to specify the types of clients the receiver wishes to observe. If both a tool and a handler are registered, only the handler is notified.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – shouldSynchronizeWithClientsOfType:
• – syncAlertToolPath

Declared In

ISyncClient.h

shouldReplaceClientRecordsForEntityName:

Returns YES if the client should replace all records for the entity specified by entityName during the next sync, NO otherwise.

- (BOOL)shouldReplaceClientRecordsForEntityName:(NSString *)entityName

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setShouldReplaceClientRecords:forEntityNames:

Declared In

ISyncClient.h

shouldSynchronizeWithClientsOfType:

Returns YES if the client is registered to receive alerts when clients of clientType sync, NO otherwise.

- (BOOL)shouldSynchronizeWithClientsOfType:(NSString *)clientType

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setShouldSynchronize:withClientsOfType:
• – setSyncAlertHandler:selector:
• – setSyncAlertToolPath:
• – syncAlertToolPath

Declared In

ISyncClient.h

supportedEntityNames

Returns an array of NSString objects containing the names of the entities the client supports.

- (NSArray*)supportedEntityNames

Discussion

This property is set when registering the client.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – registerClientWithIdentifier:descriptionFilePath: (ISyncManager)

Declared In

ISyncClient.h

syncAlertToolPath

Returns the path to the tool that is launched when an observed client begins syncing.

- (NSString *)syncAlertToolPath

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setShouldSynchronize:withClientsOfType:
• – setSyncAlertHandler:selector:
• – setSyncAlertToolPath:
• – shouldSynchronizeWithClientsOfType:

Declared In

ISyncClient.h

Constants

Use the following constants to specify the type of client you might want to sync simultaneously with using the setShouldSynchronize:withClientsOfType: method. The clientType method also returns one of these constants.

The following constants are returned by the lastSyncStatusForEntityName: method to indicate the state of the last sync session.

---