Inherits from NSObject
Conforms to TICDSApplicationRegistrationOperationDelegate
TICDSDocumentDeletionOperationDelegate
TICDSRemoveAllRemoteSyncDataOperationDelegate
Declared in TICDSApplicationSyncManager.h

Overview

TICDSDocumentSyncManager describes the generic behavior provided by an Application Sync Manager in the TICoreDataSync framework.

The Application Sync Manager is responsible for application-wide synchronization settings. You typically have only one in an application.

Don’t instantiate this class directly, but instead use one of the subclasses:

  1. TICDSFileManagerBasedApplicationSyncManager
  2. TICDSDropboxSDKBasedApplicationSyncManager

%warning%
Warning: You must register the application sync manager before you can use it to perform any other tasks, or register any documents.

Tasks

Application-Wide Sync Manager

One-Shot Application Registration

Delayed Application Registration

Continuing Registration

Accessing Previously Synchronized Documents

Clearing Encryption Password

Accessing Client Information

Deleting Documents

Removing all Sync Data

Other Tasks Process

Background State Processing

Methods Overridden by Subclasses

Properties

Operation Queues

Relative Paths

Properties

appIdentifier

The App Identifier used for registration.

@property (nonatomic, readonly, copy) NSString *appIdentifier

Discussion

Set the identifier when registering with registerWithDelegate:globalAppIdentifier:uniqueClientIdentifier:description:userInfo:.

Declared In

TICDSApplicationSyncManager.h

applicationUserInfo

The User Info used for registration.

@property (nonatomic, readonly, strong) NSDictionary *applicationUserInfo

Discussion

Set the user info when registering with registerWithDelegate:globalAppIdentifier:uniqueClientIdentifier:description:userInfo:.

Declared In

TICDSApplicationSyncManager.h

backgroundTaskID

Unique task identifier used when Sync Manager is performing a series of tasks that should be continued after app goes into background state

@property (nonatomic, assign) UIBackgroundTaskIdentifier backgroundTaskID

Declared In

TICDSApplicationSyncManager.h

clientDescription

The Client Description used for registration.

@property (nonatomic, readonly, copy) NSString *clientDescription

Discussion

Set the description when registering with registerWithDelegate:globalAppIdentifier:uniqueClientIdentifier:description:userInfo:.

Declared In

TICDSApplicationSyncManager.h

clientIdentifier

The Client Identifier used for registration.

@property (nonatomic, readonly, copy) NSString *clientIdentifier

Discussion

Set the identifier when registering with registerWithDelegate:globalAppIdentifier:uniqueClientIdentifier:description:userInfo:.

Declared In

TICDSApplicationSyncManager.h

configured

Used to indicate if the application sync manager has been configured via the configureWithDelegate:globalAppIdentifier:uniqueClientIdentifier:description:userInfo: method.

@property (nonatomic, getter=isConfigured) BOOL configured

Declared In

TICDSApplicationSyncManager.h

delegate

The Application Sync Manager Delegate.

@property (nonatomic, weak) id<TICDSApplicationSyncManagerDelegate> delegate

Declared In

TICDSApplicationSyncManager.h

fileManager

A File Manager for use by the application sync manager.

@property (nonatomic, readonly, strong) NSFileManager *fileManager

Declared In

TICDSApplicationSyncManager.h

otherTasksQueue

The operation queue used for non-registration tasks.

@property (nonatomic, readonly, strong) NSOperationQueue *otherTasksQueue

Discussion

The queue is suspended until registration has completed successfully.

Declared In

TICDSApplicationSyncManager.h

registrationQueue

The operation queue used for registration operations.

@property (nonatomic, readonly, strong) NSOperationQueue *registrationQueue

Declared In

TICDSApplicationSyncManager.h

relativePathToClientDevicesDirectory

The path to the ClientDevices directory, relative to the root of the remote file structure.

@property (weak, nonatomic, readonly) NSString *relativePathToClientDevicesDirectory

Declared In

TICDSApplicationSyncManager.h

relativePathToClientDevicesThisClientDeviceDirectory

The path to this client’s directory inside the ClientDevices directory, relative to the root of the remote file structure.

@property (weak, nonatomic, readonly) NSString *relativePathToClientDevicesThisClientDeviceDirectory

Declared In

TICDSApplicationSyncManager.h

relativePathToDocumentsDirectory

The path to the Documents directory, relative to the root of the remote file structure.

@property (weak, nonatomic, readonly) NSString *relativePathToDocumentsDirectory

Declared In

TICDSApplicationSyncManager.h

relativePathToEncryptionDirectory

The path to the Encryption directory, relative to the root of the remote file structure.

@property (weak, nonatomic, readonly) NSString *relativePathToEncryptionDirectory

Declared In

TICDSApplicationSyncManager.h

relativePathToEncryptionDirectorySaltDataFilePath

The path to the salt.ticdsync file inside the Encryption directory, relative to the root of the remote file structure.

@property (weak, nonatomic, readonly) NSString *relativePathToEncryptionDirectorySaltDataFilePath

Declared In

TICDSApplicationSyncManager.h

relativePathToEncryptionDirectoryTestDataFilePath

The path to the test.ticdsync file inside the Encryption directory, relative to the rot of the remote file structure.

@property (weak, nonatomic, readonly) NSString *relativePathToEncryptionDirectoryTestDataFilePath

Declared In

TICDSApplicationSyncManager.h

relativePathToInformationDeletedDocumentsDirectory

The path to the DeletedDocuments directory inside the Information directory, relative ot the root of the remote file structure.

@property (weak, nonatomic, readonly) NSString *relativePathToInformationDeletedDocumentsDirectory

Declared In

TICDSApplicationSyncManager.h

relativePathToInformationDirectory

The path to the Information directory, relative to the root of the remote file structure.

@property (weak, nonatomic, readonly) NSString *relativePathToInformationDirectory

Declared In

TICDSApplicationSyncManager.h

shouldContinueProcessingInBackgroundState

Indicates whether the application sync manager should be setup to continue processing after the app has been moved from the Active to Background state

@property (nonatomic, assign) BOOL shouldContinueProcessingInBackgroundState

Declared In

TICDSApplicationSyncManager.h

shouldUseCompressionForWholeStoreMoves

Used to indicate whether the application sync manager should use zip compression when moving the whole store.

@property (nonatomic, assign) BOOL shouldUseCompressionForWholeStoreMoves

Discussion

This value is set automatically during the application sync manager configuration process.

Declared In

TICDSApplicationSyncManager.h

shouldUseEncryption

Used to indicate whether the application sync manager should use encryption for the remote files.

@property (nonatomic, assign) BOOL shouldUseEncryption

Discussion

This value is set automatically during the application registration process.

Declared In

TICDSApplicationSyncManager.h

state

Application Sync Manager State.

@property (nonatomic, readonly) TICDSApplicationSyncManagerState state

Discussion

The state of the application sync manager indicates whether it is ready to synchronize.

Possible values are defined in TICDSTypesAndEnums.h.

Declared In

TICDSApplicationSyncManager.h

Class Methods

defaultApplicationSyncManager

Returns an application-wide sync manager.

+ (id)defaultApplicationSyncManager

Return Value

The default application-wide sync manager (if one doesn’t exist, it will be created).

Discussion

Use this method to get the default application sync manager. If this is the first time you’ve requested one, a new one will be created.

%warning%
Warning: Don’t call this method on TICDSApplicationSyncManager; if you do, you’ll receive a generic application sync manager object. Instead call it on one of the subclasses, for example [TICDSFileManagerBasedApplicationSyncManager defaultSyncManager].

Declared In

TICDSApplicationSyncManager.h

setDefaultApplicationSyncManager:

Set the application-wide sync manager.

+ (void)setDefaultApplicationSyncManager:(TICDSApplicationSyncManager *)aSyncManager

Parameters

aSyncManager

The new sync manager to set as the application-wide default.

Discussion

Use this method if you need to release an existing default manager, or wish to use a different default one for some reason.

Declared In

TICDSApplicationSyncManager.h

Instance Methods

applicationRegistrationOperation

Returns an application registration operation.

- (TICDSApplicationRegistrationOperation *)applicationRegistrationOperation

Return Value

A correctlyconfigured subclass of TICDSApplicationRegistrationOperation.

Discussion

Subclasses of TICDSApplicationSyncManager use this method to return a correctlyconfigured application registration operation for their particular sync method.

Declared In

TICDSApplicationSyncManager.h

cancelNonBackgroundStateOperations

Initiate cancellation of tasks that are not marked as being supported in background state

- (void)cancelNonBackgroundStateOperations

Declared In

TICDSApplicationSyncManager.h

cancelOtherTasks

Cancel any operations in the ApplicationSyncManager’s OtherTasks op queue

- (void)cancelOtherTasks

Declared In

TICDSApplicationSyncManager.h

cancelRegistrationWithoutProvidingEncryptionPassword

Cancel registration after being asked for an encryption password.

- (void)cancelRegistrationWithoutProvidingEncryptionPassword

Discussion

Use this method to cancel registration if the user is unable to provide the correct encryption password.

%warning%
Warning: Using this method at other times will result in undefined behavior.

Declared In

TICDSApplicationSyncManager.h

clearSyncEncryptionPassword

Clears the encryption password from the keychain. Intended for use after encryption errors are found.

- (void)clearSyncEncryptionPassword

Discussion

This method will wipe the encyption password from the keychain, causing the application sync manager to request it during the next registration. The application sync manager should be reregistered after this method is called.

Declared In

TICDSApplicationSyncManager.h

configureWithDelegate:globalAppIdentifier:uniqueClientIdentifier:description:userInfo:

Configure an application but don’t immediately register it.

- (void)configureWithDelegate:(id<TICDSApplicationSyncManagerDelegate>)aDelegate globalAppIdentifier:(NSString *)anAppIdentifier uniqueClientIdentifier:(NSString *)aClientIdentifier description:(NSString *)aClientDescription userInfo:(NSDictionary *)someUserInfo

Parameters

aDelegate

The object you wish to be notified regarding application-related sync information; this object must conform to the TICDSApplicationSyncManagerDelegate protocol, which includes some required methods.

anAppIdentifier

The identification string used to identify the synchronization information across multiple clients. If you wish to be able to synchronize Mac and iOS, this app identifier should be the same on both platforms. This identifier will also be used as the root level of the remote file structure.

aClientIdentifier

An identification string for this client. Every client wishing to synchronize must have a string to identify itself (i.e., the application instance on a machine) uniquely. You would typically create a UUID string the first time your app is launched and store this in preferences.

aClientDescription

A human-readable string used to identify this client, e.g. the computer name.

someUserInfo

A dictionary of information that will be saved throughout all future synchronizations. Because this information is saved in a plist, everything in the dictionary must be archivable.

Discussion

Use this method to configure the sync manager in environments where you may not have a permanent internet connection, such as an iOS device, or a desktop WebDAV client, etc.

This will configure everything necessary to track changes made by the user. When you wish to initiate a sync, or perform any other task, you’ll need to call the registerConfiguredApplicationSyncManager method first to initiate registration.

Declared In

TICDSApplicationSyncManager.h

continueRegisteringWithEncryptionPassword:

Continue registering an application for the first time specifying whether to use encryption, or an existing application that requires an encryption password.

- (void)continueRegisteringWithEncryptionPassword:(NSString *)aPassword

Parameters

aPassword

The password to use, or nil to specify no encryption on a new application registration.

Discussion

If you are requesting the registration process continue for a new application, and do not want to enable encryption, specify nil for the password, otherwise supply the password the user wishes to use.

If you are requesting the registration process continue for an existing application that requires an encryption password, you must specify a password other than nil.

Declared In

TICDSApplicationSyncManager.h

deleteDocumentWithIdentifier:

Delete the specified document, if it exists, from the remote.

- (void)deleteDocumentWithIdentifier:(NSString *)anIdentifier

Parameters

anIdentifier

The identifier of the document to be deleted.

Discussion

As well as delegate methods indicating the status of the overall deletion process, applicationSyncManager:willDeleteDirectoryForDocumentWithIdentifier: and applicationSyncManager:didDeleteDirectoryForDocumentWithIdentifier: methods will be called either side of the deletion of the actual document directory.

Declared In

TICDSApplicationSyncManager.h

documentDeletionOperationForDocumentWithIdentifier:

Returns an operation to delete a document with a given identifier.

- (TICDSDocumentDeletionOperation *)documentDeletionOperationForDocumentWithIdentifier:(NSString *)anIdentifier

Parameters

anIdentifier

The unique synchronization identifier of the document to delete.

Return Value

A correctlyconfigured subclass of TICDSDocumentDeletionOperation.

Discussion

Subclasses of TICDSApplicationSyncManager use this method to return a correctlyconfigured document deletion operation for their particular sync method.

Declared In

TICDSApplicationSyncManager.h

listOfApplicationRegisteredClientsOperation

Returns an operation to fetch a list of registered clients for an application.

- (TICDSListOfApplicationRegisteredClientsOperation *)listOfApplicationRegisteredClientsOperation

Return Value

A correctlyconfigured subclass of TICDSListOfApplicationRegisteredClientsOperation.

Discussion

Subclasses of TICDSApplicationSyncManager use this method to return a correctlyconfigured operation for their particular sync method.

Declared In

TICDSApplicationSyncManager.h

listOfPreviouslySynchronizedDocumentsOperation

Returns an operation to fetch a list of previously synchronized documents.

- (TICDSListOfPreviouslySynchronizedDocumentsOperation *)listOfPreviouslySynchronizedDocumentsOperation

Return Value

A correctlyconfigured subclass of TICDSListOfPreviouslySynchronizedDocumentsOperation.

Discussion

Subclasses of TICDSApplicationSyncManager use this method to return a correctlyconfigured list of documents operation for their particular sync method.

Declared In

TICDSApplicationSyncManager.h

registerConfiguredApplicationSyncManager

Register an application that has already been preconfigured.

- (void)registerConfiguredApplicationSyncManager

Discussion

Use this method to register an application sync manager that you have already configured using the configureWithDelegate:globalAppIdentifier:uniqueClientIdentifier:description:userInfo: method.

Declared In

TICDSApplicationSyncManager.h

registerWithDelegate:globalAppIdentifier:uniqueClientIdentifier:description:userInfo:

Register an application ready for future synchronization.

- (void)registerWithDelegate:(id<TICDSApplicationSyncManagerDelegate>)aDelegate globalAppIdentifier:(NSString *)anAppIdentifier uniqueClientIdentifier:(NSString *)aClientIdentifier description:(NSString *)aClientDescription userInfo:(NSDictionary *)someUserInfo

Parameters

aDelegate

The object you wish to be notified regarding application-related sync information; this object must conform to the TICDSApplicationSyncManagerDelegate protocol, which includes some required methods.

anAppIdentifier

The identification string used to identify the synchronization information across multiple clients. If you wish to be able to synchronize Mac and iOS, this app identifier should be the same on both platforms. This identifier will also be used as the root level of the remote file structure.

aClientIdentifier

An identification string for this client. Every client wishing to synchronize must have a string to identify itself (i.e., the application instance on a machine) uniquely. You would typically create a UUID string the first time your app is launched and store this in preferences.

aClientDescription

A human-readable string used to identify this client, e.g. the computer name.

someUserInfo

A dictionary of information that will be saved throughout all future synchronizations. Because this information is saved in a plist, everything in the dictionary must be archivable.

Discussion

Use this method to register the sync manager ready for document registration and synchronization (via TICDSDocumentSyncManager objects).

This will automatically spawn a TICDSApplicationRegistrationOperation, and notify you of progress through the TICDSApplicationSyncManagerDelegate methods.

If this is the first time you have registered a client with this app identifier, registration will automatically create the file structure necessary at the remote end for this and other clients to synchronize. See [TICDSUtilities remoteGlobalAppDirectoryHierarchy] for the structure that will be created.

Declared In

TICDSApplicationSyncManager.h

relativePathToDocumentDirectoryForDocumentWithIdentifier:

The path to a document’s directory within the Documents directory, relative to the root of the remote file structure.

- (NSString *)relativePathToDocumentDirectoryForDocumentWithIdentifier:(NSString *)anIdentifier

Parameters

anIdentifier

The unique sync identifier of the document.

Declared In

TICDSApplicationSyncManager.h

relativePathToWholeStoreDirectoryForDocumentWithIdentifier:

The path to a document’s WholeStore directory, relative to the root of the remote file structure.

- (NSString *)relativePathToWholeStoreDirectoryForDocumentWithIdentifier:(NSString *)anIdentifier

Parameters

anIdentifier

The unique sync identifier of the document.

Declared In

TICDSApplicationSyncManager.h

removeAllSyncDataFromRemote

Remove the entire remote directory structure from the remote.

- (void)removeAllSyncDataFromRemote

Discussion

This will spawn a TICDSRemoveAllSyncDataOperation and notify the delegate of progress.

Declared In

TICDSApplicationSyncManager.h

removeAllSyncDataOperation

Returns an operation to remove all remote sync data.

- (TICDSRemoveAllRemoteSyncDataOperation *)removeAllSyncDataOperation

Return Value

A correctlyconfigured subclass of TICDSRemoveAllSyncDataOperation.

Discussion

Subclasses of TICDSApplicationSyncManager use this method to return a correctlyconfigured ‘remove all sync data’ operation for their particular sync method.

Declared In

TICDSApplicationSyncManager.h

requestDownloadOfDocumentWithIdentifier:toLocation:

Download a document that has previously been synchronized for this application.

- (void)requestDownloadOfDocumentWithIdentifier:(NSString *)anIdentifier toLocation:(NSURL *)aLocation

Parameters

anIdentifier

The unique synchronization identifier string for the requested document. If you’re requesting the download of a document represented by a dictionary supplied from a request for the list of previously synchronized documents, use the value for its kTICDSDocumentIdentifier key.

aLocation

The location on disc to which the persistent store file should be downloaded - including the file name.

Discussion

This method will automatically spawn a TICDSDocumentDownloadOperation, and notify you of progress through the TICDSApplicationSyncManagerDelegate methods.

%warning%
Warning: The document will first be downloaded to a temporary location. If any file already exists at the location specified by aLocation, it will be removed once the dowload completes, before the newly-downloaded temporary file is moved to aLocation.

Declared In

TICDSApplicationSyncManager.h

requestListOfPreviouslySynchronizedDocuments

Request a list of documents that have previously been synchronized for this application, by any client.

- (void)requestListOfPreviouslySynchronizedDocuments

Discussion

This method will automatically spawn a TICDSListOfPreviouslySynchronizedDocumentsOperation, and notify you of progress through the TICDSApplicationSyncManagerDelegate methods.

Declared In

TICDSApplicationSyncManager.h

requestListOfSynchronizedClientsIncludingDocuments:

Request a list of clients that are registered to synchronize with this application.

- (void)requestListOfSynchronizedClientsIncludingDocuments:(BOOL)includeDocuments

Parameters

includeDocuments

YES if the request should also include a list of documents that each client is registered to synchronize, otherwise NO.

Discussion

This method returns a dictionary containing as keys the client identifiers, and as values the deviceInfo.plist information. If you specify YES for includeDocuments, each dictionary will also include an array containing the identifiers of documents for which the client is registered.

Declared In

TICDSApplicationSyncManager.h

wholeStoreDownloadOperationForDocumentWithIdentifier:

Returns an operation to download a document with a given identifier.

- (TICDSWholeStoreDownloadOperation *)wholeStoreDownloadOperationForDocumentWithIdentifier:(NSString *)anIdentifier

Parameters

anIdentifier

The unique synchronization identifier of the document to download.

Return Value

A correctlyconfigured subclass of TICDSWholeStoreDownloadOperation.

Discussion

Subclasses of TICDSApplicationSyncManager use this method to return a correctlyconfigured whole store download operation for their particular sync method.

Declared In

TICDSApplicationSyncManager.h