| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/SyncServices.framework |
| Availability | Available in Mac OS X v10.5 and later. |
| Companion guide | |
| Declared in | ISyncSessionDriver.h |
| Related sample code |
An ISyncSessionDriver object encapsulates the complex process of syncing client records. Using ISyncSessionDriver is an alternative approach to creating and managing your own ISyncClient and ISyncSession objects. The driver takes care of the details by creating a client, registering schemas, and managing sync sessions. An ISyncSessionDriver object can be used for multiple sync operations.
An ISyncSessionDriver object uses an application-supplied data source object to provide application-specific information needed to manage a sync session. For example, during a sync session, a data source supplies records or changes to push and applies pulled changes to local records. Some data source methods are required and others are optional.
The driver also sends callback messages to a delegate before and after most phases of a sync session. A delegate may implement these callback methods to customize the behavior of sync sessions. For example, a delegate might verify changes, resolve relationships, and perform some local database operations. If no delegate is specified, the driver sends the delegate messages to the data source.
You create an ISyncSessionDriver object using the sessionDriverWithDataSource: method, passing a data source as the argument. The sessionDriverWithDataSource: method raises an exception if a data source does not implement required methods. Optionally, set the delegate to a different object using the setDelegate: method. All delegate methods are optional.
You perform a sync operation by sending sync or startAsynchronousSync: to an ISyncSessionDriver object. These methods perform all the phases of a sync operation: negotiating, pushing, mingling, and pulling. You can access the ISyncClient and ISyncSession objects directly using the client and session methods. However, session returns nil if there is no active sync session.
An ISyncSessionDriver object takes care of finishing and canceling a sync session. Therefore, you should not send finishSyncing or cancelSyncing directly to an ISyncSession object returned by the session method. Instead, send finishSyncing to an ISyncSessionDriver object to prematurely finish a sync session. If an error occurs during syncing, send lastError to the driver to get an NSError object describing the error.
See ISyncSessionDriverDataSource Protocol Reference for how to create a data source object and ISyncSessionDriverDelegate Protocol Reference for a description of the delegate methods.
Creates and returns a new driver object with the specified data source object.
+ (ISyncSessionDriver *)sessionDriverWithDataSource:(id < ISyncSessionDriverDataSource >)dataSource
The dataSource argument must conform to the ISyncSessionDriverDataSource protocol. This method may raise an exception if required methods are not implemented. The sync method sends messages to both the data source and delegate objects during a sync operation. If a delegate is not specified, then the data source also receives delegate messages.
ISyncSessionDriver.hReturns the client object used by the receiver to perform the sync operation.
- (ISyncClient *)client
ISyncSessionDriver.hReturns the data source object for the receiver.
- (id < ISyncSessionDriverDataSource >)dataSource
ISyncSessionDriver.hReturns the receiver’s delegate.
- (id)delegate
ISyncSessionDriver.hNotifies the sync engine that the client is done syncing.
- (void)finishSyncing
Invoking this method closes any open transactions in the pushing or pulling states. You should use this method to prematurely finish a sync session. Do not send finishSyncing directly to an ISyncSession object returned by the session method.
ISyncSessionDriver.hReturns a Boolean value indicating whether the receiver handles sync alerts.
- (BOOL)handlesSyncAlerts
YES if the receiver handles sync alerts; otherwise, NO.
By default, a session driver does not handle sync sessions. Use the setHandlesSyncAlerts: method to turn this feature on or off.
ISyncSessionDriver.hReturns the error that occurred during the last sync session.
- (NSError *)lastError
Typically, you use this method to get the error if sync returns NO or the sync session started by the startAsynchronousSync: method fails. The value returned is only valid until the start of the next sync session. Get the last error as follows:
BOOL success = [sessionDriver sync]; |
if (success == NO) myError = [sessionDriver lastError]; |
ISyncSessionDriver.hReturns the session object used to manage the sync session.
- (ISyncSession *)session
Typically, you use this method to check whether a sync session is in progress. Session objects returned from this method are valid only during the invocation of the sync method when a sync session is in progress. Otherwise, this method returns nil. If you retain a session object returned by this method, it is no longer valid after the sync method returns or after one of these delegate methods is invoked:
Use this method only during the same thread as the sync method.
You should not send finishSyncing or cancelSyncing directly to an ISyncSession object returned by this method. Send finishSyncing to an ISyncSessionDriver object to prematurely finish a sync session. Return an NSError object as one of the arguments to a delegate method to cancel a sync session.
ISyncSessionDriver.hSets the receiver’s delegate to the specified object.
- (void)setDelegate:(id)delegate
The messages sent to a delegate are described in “Creating a Session Driver.” The delegate doesn’t need to implement all of these methods. If no delegate is set or the delegate argument is nil, delegate messages are sent to the data source object instead.
ISyncSessionDriver.hSpecifies whether the receiver should handle sync alerts.
- (void)setHandlesSyncAlerts:(BOOL)flag
If YES, the receiver should handle sync alerts; otherwise, the receiver doesn’t handle sync alerts.
A session driver may optionally handle sync alerts for a client. If the session driver handles sync alerts, then it registers a sync alert handler and receives notifications for requests to join sync sessions. When the session driver receives a request, it initiates a sync session as if the startAsynchronousSync: method was invoked by the client so it doesn’t sync in the main thread. By default, a session driver does not handle sync sessions.
ISyncSessionDriver.hSyncs client records, specified by the data source, in a separate thread.
- (BOOL)startAsynchronousSync:(NSError **)outError
This method is similar to the sync method but returns immediately while performing a sync session asynchronously. Use the delegate methods described in “Creating a Session Driver” if you want to perform some operations at different phases during the sync session including receiving notification when the sync session is finished or cancelled. If the driver is unable to create a sync session, this method returns NO and the outError argument is set to an NSError object describing the error; otherwise, this method returns YES.
ISyncSessionDriver.hSyncs client records, specified by the data source, with the sync engine.
- (BOOL)sync
This method registers a client, registers schemas, and manages an entire sync session. It begins a sync session, negotiates a sync mode, pushes records, pulls records, and ends the sync session. During a sync session the data source is expected to supply records or changes to push and to apply pulled changes to local records. Optionally, use the delegate methods described in “Creating a Session Driver” if you want to perform some operations at different phases during the sync session. Use the finishSyncing method to cancel a sync session started by this method. This method returns YES if the sync session is successful; otherwise, NO.
ISyncSessionDriver.hLast updated: 2009-03-16
Mac OS X Reference Library Data Management: Syncing ISyncSessionDriver Class Reference