Advanced Search

Log In | Not a Member?

Contact ADC

Next Page > Hide TOC

ISyncSessionDriver Class Reference

Overview

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.

Tasks

Creating a Session Driver

• + sessionDriverWithDataSource:

Syncing

• – sync
• – startAsynchronousSync:
• – finishSyncing

Error Handling

• – lastError

Getting and Setting Properties

• – dataSource
• – setDelegate:
• – delegate
• – client
• – session
• – setHandlesSyncAlerts:
• – handlesSyncAlerts

Controlling Sync Behavior

• – sessionDriver:didRegisterClientAndReturnError:  delegate method
• – sessionDriver:willPushAndReturnError:  delegate method
• – sessionDriver:didPushAndReturnError:  delegate method
• – sessionDriver:willPullAndReturnError:  delegate method
• – sessionDriver:didPullAndReturnError:  delegate method
• – sessionDriver:willFinishSessionAndReturnError:  delegate method
• – sessionDriverDidFinishSession:  delegate method
• – sessionDriverWillCancelSession:  delegate method
• – sessionDriverDidCancelSession:  delegate method

Class Methods

sessionDriverWithDataSource:

Creates and returns a new driver object with the specified data source object.

+ (ISyncSessionDriver *)sessionDriverWithDataSource:(id <ISyncSessionDriverDataSource>)dataSource

Discussion

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.

Availability

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

See Also

• – dataSource
• – sync

Declared In

Instance Methods

client

Returns the client object used by the receiver to perform the sync operation.

- (ISyncClient *)client

Availability

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

Declared In

dataSource

Returns the data source object for the receiver.

- (id <ISyncSessionDriverDataSource>)dataSource

Availability

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

See Also

• + sessionDriverWithDataSource:

Declared In

delegate

Returns the receiver’s delegate.

- (id)delegate

Availability

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

See Also

• – setDelegate:

Declared In

finishSyncing

Notifies the sync engine that the client is done syncing.

- (void)finishSyncing

Discussion

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.

Availability

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

See Also

• – session
• – sync

Declared In

handlesSyncAlerts

Returns a Boolean value indicating whether the receiver handles sync alerts.

- (BOOL)handlesSyncAlerts

Return Value

YES if the receiver handles sync alerts; otherwise, NO.

Discussion

By default, a session driver does not handle sync sessions. Use the setHandlesSyncAlerts: method to turn this feature on or off.

Availability

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

See Also

• – setHandlesSyncAlerts:

Declared In

lastError

Returns the error that occurred during the last sync session.

- (NSError *)lastError

Discussion

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

Availability

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

See Also

• – startAsynchronousSync:
• – sync

Declared In

session

Returns the session object used to manage the sync session.

- (ISyncSession *)session

Discussion

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:

• sessionDriverDidFinishSession:

• sessionDriverDidCancelSession:

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.

Availability

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

See Also

• – sync
• – finishSyncing

Declared In

setDelegate:

Sets the receiver’s delegate to the specified object.

- (void)setDelegate:(id)delegate

Discussion

The messages sent to a delegate are described in “Controlling Sync Behavior.” 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.

Availability

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

See Also

• – delegate
• + sessionDriverWithDataSource:

Declared In

setHandlesSyncAlerts:

Specifies whether the receiver should handle sync alerts.

- (void)setHandlesSyncAlerts:(BOOL)flag

Parameters

flag

If YES, the receiver should handle sync alerts; otherwise, the receiver doesn’t handle sync alerts.

Discussion

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.

Availability

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

See Also

• – startAsynchronousSync:
• – handlesSyncAlerts
• – sync

Declared In

startAsynchronousSync:

Syncs client records, specified by the data source, in a separate thread.

- (BOOL)startAsynchronousSync:(NSError **)outError

Discussion

This method is similar to the sync method but returns immediately while performing a sync session asynchronously. Use the delegate methods described in “Controlling Sync Behavior” 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.

Availability

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

See Also

• – sync
• – finishSyncing

Declared In

sync

Syncs client records, specified by the data source, with the sync engine.

- (BOOL)sync

Discussion

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 “Controlling Sync Behavior” 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.

Availability

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

See Also

• – startAsynchronousSync:
• – finishSyncing

Declared In

Delegate Methods

sessionDriver:didPullAndReturnError:

Informs the receiver that changes were pulled from the sync engine.

- (BOOL)sessionDriver:(ISyncSessionDriver *)sender didPullAndReturnError:(NSError **)outError

Discussion

If an error occurs, this method returns NO and sets outError to an NSError object that describes the error.

Availability

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

Declared In

sessionDriver:didPushAndReturnError:

Informs the receiver that client changes were pushed to the sync engine.

- (BOOL)sessionDriver:(ISyncSessionDriver *)sender didPushAndReturnError:(NSError **)outError

Discussion

If an error occurs, this method returns NO and sets outError to an NSError object that describes the error.

Availability

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

Declared In

sessionDriver:didRegisterClientAndReturnError:

Informs the receiver that a client was registered.

- (BOOL)sessionDriver:(ISyncSessionDriver *)sender didRegisterClientAndReturnError:(NSError **)outError

Discussion

If an error occurs, this method returns NO and sets outError to an NSError object that describes the error.

Availability

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

Declared In

sessionDriver:willFinishSessionAndReturnError:

Informs the receiver that a session will be finished.

- (BOOL)sessionDriver:(ISyncSessionDriver *)sender willFinishSessionAndReturnError:(NSError **)outError

Discussion

If an error occurs, this method returns NO and sets outError to an NSError object that describes the error.

Availability

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

Declared In

sessionDriver:willPullAndReturnError:

Informs the receiver that changes will be pulled from the sync engine.

- (BOOL)sessionDriver:(ISyncSessionDriver *)sender willPullAndReturnError:(NSError **)outError

Discussion

If an error occurs, this method returns NO and sets outError to an NSError object that describes the error.

Availability

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

Declared In

sessionDriver:willPushAndReturnError:

Informs the receiver that client changes will be pushed to the sync engine.

- (BOOL)sessionDriver:(ISyncSessionDriver *)sender willPushAndReturnError:(NSError **)outError

Discussion

If an error occurs, this method returns NO and sets outError to an NSError object that describes the error.

Availability

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

Declared In

sessionDriverDidCancelSession:

Informs the receiver that a session was cancelled.

- (void)sessionDriverDidCancelSession:(ISyncSessionDriver *)sender

Availability

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

Declared In

sessionDriverDidFinishSession:

Informs the receiver that a session was finished.

- (void)sessionDriverDidFinishSession:(ISyncSessionDriver *)sender

Availability

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

Declared In

sessionDriverWillCancelSession:

Informs the receiver that a session will be cancelled.

- (void)sessionDriverWillCancelSession:(ISyncSessionDriver *)sender

Availability

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

Declared In

Next Page > Hide TOC

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.

	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. | Terms of use | Privacy Notice