| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/SyncServices.framework |
| Availability | Available in Mac OS X v10.4 and later. |
| Companion guide | |
| Declared in | ISyncManager.h SyncServicesErrors.h |
| Related sample code |
You use an ISyncManager object to communicate directly with the sync engine to perform administrative operations. A client must register itself with an ISyncManager object before it can sync its data. If a client is not using an existing schema, it must register the schema before it registers itself. You also use an ISyncManager to look up an existing client and unregister a client.
There’s only one ISyncManager instance per client process you obtain using the sharedManager class method. You should never instantiate or subclass ISyncManager directly.
Sync Services provides three canonical schemas: Bookmarks.syncschema, Contacts.syncschema, and Calendars.syncschema. If you want to extend one of these existing schemas or define your own schema, then you need to register that schema with the shared ISyncManager object. You use the registerSchemaWithBundlePath: method to register a schema with the sync engine or update an existing schema. Occasionally, you might use unregisterSchemaWithName: to remove a schema and all associated records. Removing a schema impacts every client that uses that schema. Typically, you just register a schema once and reregister it when it changes.
You also use the shared ISyncManager object to create and register a sync client—that is, an instance of ISyncClient—with a unique identifier that you specify. Use registerClientWithIdentifier:descriptionFilePath: to register your client—this method returns either a new client object or an existing client. You also use this method to describe the capabilities of the client—for example, describe what entities and properties the client supports. You use the unregisterClient: method to unregister a client. See Sync Services Programming Guide for more information on registering and unregistering clients.
Returns a shared ISyncManager object.
+ (ISyncManager *)sharedManager
ISyncManager.hAdds a mode to the set of run-loop input modes that the receiver uses for connection requests.
- (void)addRequestMode:(NSString *)mode
The mode to add to the receiver. See NSRunLoop Class Reference for more information on input modes.
Clients that register sync alert handlers may use this method to manage the request modes of connections that are sent alerts by the sync engine. This method is similar to the addRequestMode: method of NSConnection. For example, a client that registers a sync alert handler in a process that might present a modal dialog to the user, should add the appropriate request mode to the run-loop, so alerts can be handled in a timely manner even when the application is blocked for user input.
– removeRequestMode:– requestModes– addRequestMode: (NSConnection)ISyncManager.hReturns the sync client identified by clientIdentifier, or nil if not found.
- (ISyncClient *)clientWithIdentifier:(NSString *)clientIdentifier
ISyncManager.hNotifies the sync engine that a client needs to sync the next time another client is syncing the same data classes.
- (void)clientWithIdentifier:(NSString *)clientId needsSyncing:(BOOL)flag
The unique identifier for the client that needs to sync.
YES if the client needs to sync; otherwise, NO.
The MobileMe client is optimized to avoid syncing when it has no changes to push and the sync engine is not aware of any changes MobileMe needs to pull. Sync clients should trickle sync whenever possible. However, if you have a sync client that frequently slow syncs and only syncs by joining other sync sessions—for example, only syncs when MobileMe syncs, then use this method to tell the sync engine when this sync client needs to sync.
ISyncManager.hReturns NO if the sync engine is disabled, YES otherwise.
- (BOOL)isEnabled
You should not begin a sync session when this method returns NO. However, you can register for the ISyncAvailabilityChangedNotification notification, which is sent when the sync engine state changes.
ISyncManager.hReturns an existing or new sync client uniquely identified by clientIdentifier.
- (ISyncClient *)registerClientWithIdentifier:(NSString *)clientIdentifier descriptionFilePath:(NSString *)descriptionFilePath
There are no restrictions on the content or length of clientIdentifier, but it must be unique across all clients. Typically, it’s a DNS-style name such as com.apple.iCal.
The client description file located at descriptionFilePath is a property list that specifies client information that the sync engine needs to know to sync its records. For example, the client description file a list of the client supported entities and properties. See Sync Services Programming Guide for a complete description of the client description file.
If the client already exists, then invoking this method updates the client description. If the set of supported entities and properties changes, the sync engine may force the client to slow sync the next time it syncs. This can be expensive, so only reregister a client if necessary.
– clientWithIdentifier:– unregisterClient:– canPullChangesForEntityName: (ISyncClient)– canPushChangesForEntityName: (ISyncClient)– displayName (ISyncClient)– imagePath (ISyncClient)ISyncManager.hRegisters a schema property list located in a bundle at bundlePath.
- (BOOL)registerSchemaWithBundlePath:(NSString *)bundlePath
The schema can define new entities and properties, and extend existing entities. The schema bundle may contain other files, such as images and localization files. See Sync Services Programming Guide for more details on the schema format and contents of the schema bundle.
If a schema of the same name exists, invoking this method updates that schema. Consequently, records and properties of records may be removed if an entity or property is removed from the schema. This action may cause clients that use this schema to slow sync the next time they sync. This process can be expensive, so reregister a schema only if necessary.
Returns YES if successful, NO otherwise.
ISyncManager.hRemoves a mode from the set of run-loop input modes the receiver uses for connection requests.
- (void)removeRequestMode:(NSString *)mode
The mode to remove. See NSRunLoop Class Reference for more information on input modes.
– addRequestMode:– requestModes– removeRequestMode: (NSConnection)ISyncManager.hReturns the set of request modes the receiver registers with its NSRunLoop object.
- (NSArray *)requestModes
An array of NSString objects that represents the set of request modes that the receiver registers. See NSRunLoop Class Reference for more information on input modes.
– addRequestMode:– removeRequestMode:– requestModes (NSConnection)ISyncManager.hReturns an immutable snapshot of the records for entityNames from the truth database.
- (ISyncRecordSnapshot *)snapshotOfRecordsInTruthWithEntityNames:(NSArray *)entityNames usingIdentifiersForClient:(ISyncClient *)client
The truth database stores a copy of all the synced records and contains the amalgamation of all entities and properties from all clients. The snapshot is made of the records for entities specified by the entityNames argument, an array of NSString objects containing the names of entities. You access the records by sending messages to the returned ISyncRecordSnapshot object.
Each client has its own name space for record identifiers. The client argument specifies the name space you want to use. If client is nil or invalid, the record identifiers from the sync engine’s global name space are used.
The snapshot is an immutable copy of the records taken at the time returned object is created. If the truth database is subsequently modified, the changes are not be reflected in the snapshot. You should create a new snapshot if you want up-to-date records.
Do not use this method if you are syncing and want a snapshot that is consistent with the sync session. Another client may be pushing changes that you have not pulled yet. Instead, you can use the ISyncSession snapshotOfRecordsInTruth method to get the state of a session.
ISyncManager.hReturns the reason the sync engine may be disabled.
- (NSError *)syncDisabledReason
The reason the sync engine is disabled. Contains an information dictionary with a value for the NSLocalizedDescriptionKey key suitable for displaying an error message to the user. The error codes are described in “ISyncServerDisabledReason.”
Use this method after sending the isEnabled message to the receiver.
ISyncManager.hUnregisters a sync client represented by client.
- (void)unregisterClient:(ISyncClient *)client
Does nothing if client is not registered.
ISyncManager.hUnregisters a schema uniquely identified by schemaName, and removes all associated records.
- (void)unregisterSchemaWithName:(NSString *)schemaName
This action causes clients that use this schema to slow sync the next time they sync. This can be expensive and results in the loss of data, so only unregister a schema if necessary. This method does nothing if the schema is not registered.
ISyncManager.h
Exceptions thrown by instances of this class.
extern NSString * const ISyncServerUnavailableException;
ISyncServerUnavailableExceptionA string aggregating the name, reason, and user info from the originating exception. Thrown by any ISyncManager method when communication to the server is lost.
Available in Mac OS X v10.4 and later.
Declared in ISyncManager.h.
See Sync Services Constants Reference for other exceptions that instances of this class might raise.
Indicates the reason the sync engine may be unavailable.
typedef enum {
ISyncServerDisabledReasonNone = 1000,
ISyncServerDisabledReasonByPreference,
ISyncServerDisabledReasonSharedNetworkHome,
ISyncServerDisabledReasonUnresponsive,
ISyncServerDisabledReasonUnknown,
} ISyncServerDisabledReason;
ISyncServerDisabledReasonNoneThe sync engine is enabled.
Available in Mac OS X v10.6 and later.
Declared in SyncServicesErrors.h.
ISyncServerDisabledReasonByPreferenceThe sync engine is disabled because of a preference setting.
Available in Mac OS X v10.6 and later.
Declared in SyncServicesErrors.h.
ISyncServerDisabledReasonSharedNetworkHomeThe sync engine is busy syncing a network home directory.
Available in Mac OS X v10.6 and later.
Declared in SyncServicesErrors.h.
ISyncServerDisabledReasonUnresponsiveSending the isEnabled message to the sync engine timed out.
Available in Mac OS X v10.6 and later.
Declared in SyncServicesErrors.h.
ISyncServerDisabledReasonUnknownThe sync engine fails to respond due to an unexpected error.
Available in Mac OS X v10.6 and later.
Declared in SyncServicesErrors.h.
Posted by the distributed notification center when syncing is enabled or disabled. The notification object is an NSString equal to "YES" if enabled and "NO" if disabled. The receiver should still invoke isEnabled before beginning a sync session. This notification does not contain a userInfo dictionary.
ISyncManager.h
Last updated: 2009-03-30
