Sync API for iOS documentation

The Sync API is like having a private filesystem for your app with its very own Dropbox client running in the background. Your app can read, create, and modify files using familiar filesystem-like calls. Behind the scenes, the Sync API takes care of syncing changes to Dropbox and notifying your app when changes are made in Dropbox, so you can update your UI instantly.

This reference details the full set of classes used to interact with the Sync API. For more information on how to get started developing with the Sync API, see the Sync API tutorial.

In addition to files, Dropbox apps can also use datastores, which are ideal for keeping per-user data — like settings, bookmarks, or game state — in sync across multiple devices and operating systems. Datastores are simple embedded databases, which are synced to Dropbox. This SDK also includes datastore functionality, though it is covered in the separate Datastore API documentation.

General information

All classes and methods in the API are thread-safe unless otherwise marked. Writing a new version of a file is an atomic operation, and will be immediately visible to other threads in this process, and uploaded to the server in the background. Other file system changes, such as moving or deleting a file will be applied atomically in the same way. Remote changes from the server are integrated into the file system atomically in the background. If your app uses multiple threads, and requires synchronization across changes to multiple files, or across a read-modify-write sequence, you should synchronize at a higher level using locks, or serialize access to the API through a single thread.

DBAccountManager

The account manager is responsible for linking new users and persisting account information across runs of your app. You typically create an account manager at app startup with your app key and secret and keep it until your app terminates.

Class methods
  • + (void)setSharedManager:(DBAccountManager *)sharedManager

    A convenient place to store your app’s account manager.

  • + (DBAccountManager *)sharedManager

    A convenient place to get your app’s account manager.

Properties
  • @property (nonatomic, readonly) DBAccount *linkedAccount

    The currently linked account, or nil if there are no accounts currently linked.

    If your app needs to link multiple accounts at the same time, you should always use the linkedAccounts property.

  • @property (nonatomic, readonly) NSArray *linkedAccounts

    All currently linked accounts, or nil if there are no accounts currently linked.

    The accounts are ordered from the least recently to the most recently linked.

Instance methods
  • - (id)initWithAppKey:(NSString *)key secret:(NSString *)secret

    Create a new account manager with your app’s app key and secret. You can register your app or find your key at the apps page.

  • - (void)linkFromController:(UIViewController *)rootController

    This method begins the process for linking new accounts.

    Parameters

    rootController

    the topmost view controller in your controller hierarchy.

  • - (DBAccount *)handleOpenURL:(NSURL *)url

    You must call this method in your app delegate’s -application:openURL:sourceApplication:annotation: method in order to complete the link process.

    Returns

    The account object if the link was successful, or nil if the user cancelled.

  • - (void)addObserver:(id)observer block:(DBAccountManagerObserver)block

    Add block as an observer to get called whenever a new account is linked or an existing account is unlinked. The observer will be called regardless of whether the account was unlinked using -[DBAccount unlink] or by the user on the Dropbox website.

    Parameters

    observer

    this is only used as a handle to unregister blocks with the removeObserver: method.

  • - (void)removeObserver:(id)observer

    Use this method to remove all blocks associated with observer.

    Parameters

    observer

    the same value you provided to the addObserver:block: method.

Constants
  • typedef void (^DBObserver)()

    A generic block type used for observing changes throughout the Sync API

  • typedef void (^DBAccountManagerObserver)(DBAccount *account)

    An observer for the linkedAccount property

DBAccount

The account represents a particular user who has linked his account to your app. You can get account objects from the account manager.

Properties
  • @property (nonatomic, readonly) NSString *userId

    The user id of the account. This can be used to associate metadata with a given account.

  • @property (nonatomic, readonly, getter=isLinked) BOOL linked

    Whether the account is currently linked. Note that accounts can be unlinked via the unlink method or from the Dropbox website.

  • @property (nonatomic, readonly) DBAccountInfo *info

    Information about the user of this account, or nil if no info is available. Account info is fetched in the background. To be notified when account info is available or updated, use addObserver:block:.

Instance methods
  • This method unlinks a user’s account from your app.

    Once an account is unlinked, the local cache is deleted. If there is a filesystem object created with this account it will stop running.

  • - (void)addObserver:(id)observer block:(DBObserver)block

    Add block as an observer of an account to get notified whenever the account’s linked or info properties change.

  • - (void)removeObserver:(id)observer

    Remove all blocks associated with observer by the addObserver:block: method.

DBAccountInfo

Information about a user’s account.

Properties
  • @property (nonatomic, readonly) NSString *displayName

    The recommended string to display to identify an account.

    This is “userName” if orgName is nil, otherwise it’s “userName (orgName)”.

  • @property (nonatomic, readonly) NSString *userName

    The user’s name.

  • @property (nonatomic, readonly) NSString *orgName

    The user’s organization’s name if available, or nil otherwise.

DBError

The DBError class is a subclass of NSError that always has domain set to DBErrorDomain.

Any method that can potentially fail will return a DBError object via the last parameter. Additionally, errors that happen in the background via syncing can also be retrieved, such as the error property on DBFileStatus.

Instance methods
  • - (DBErrorCode)code

    The code on a DBError object is always listed in the DBErrorCode enum.

Constants
  • typedef enum DBErrorCode

    The type of error that occurred. It will be one of the following:

    DBErrorUnknownHey, we don't know either
    DBErrorCoreSystemSystem error, out of memory, etc
    DBErrorParamsAn error due to data passed into the API
    DBErrorParamsInvalidA parameter is invalid, such as a nil object
    DBErrorParamsNotFoundA file corresponding to a provided paths was not found
    DBErrorParamsExistsYou tried to create a file that already exists
    DBErrorParamsAlreadyOpenFile was already open
    DBErrorParamsParentParent folder does not exist or is not a folder
    DBErrorParamsNotEmptyDirectory is not empty
    DBErrorParamsNotCachedFile was not yet in cache
    DBErrorParamsDisallowedApp is not allowed to perform this operation
    DBErrorParamsNoThumbNo thumbnail is available
    DBErrorParamsIndexIndex is out of bounds
    DBErrorParamsTypeValue is of the wrong type
    DBErrorSystemAn error in the library occurred
    DBErrorSystemDiskSpaceAn error happened due to insufficient local disk space
    DBErrorNetworkAn error occurred making a network request
    DBErrorNetworkTimeoutA connection timed out
    DBErrorNetworkNoConnectionNo network connection available
    DBErrorNetworkSSLUnable to verify the server's SSL certificate. Often caused by an out-of-date clock
    DBErrorNetworkServerUnexpected server error
    DBErrorNetworkQuotaThe user's Dropbox space is full
    DBErrorAuthAn authentication related problem occurred
    DBErrorAuthUnlinkedThe user is no longer linked
    DBErrorAuthInvalidAppAn invalid app key or secret was provided

DBFilesystem

The filesystem object provides a files and folder view of a user’s Dropbox. The most basic operations are listing a folder and opening a file, but it also allows you to move, delete, and create files and folders.

Class methods
  • + (void)setSharedFilesystem:(DBFilesystem *)filesystem

    A convienent place to store your app’s filesystem

  • + (DBFilesystem *)sharedFilesystem

    A convienent place to get your app’s filesystem

Properties
  • @property (nonatomic, readonly) DBAccount *account

    The account object this filesystem was created with.

  • @property (nonatomic, readonly) BOOL completedFirstSync

    When a user’s account is first linked, the filesystem needs to be synced with the server before it can be used. This property indicates whether the first sync has completed and the filesystem is ready to use.

  • @property (nonatomic, readonly, getter=isShutDown) BOOL shutDown

    Whether the filesystem is currently shut down. The filesystem will shut down if the account associated with this filesystem becomes unlinked.

  • @property (nonatomic, readonly) DBSyncStatus status

    Returns a bitmask representing all the currently active states of the filesystem OR'ed together. See the DBSyncStatus enum for more details.

Instance methods
  • - (id)initWithAccount:(DBAccount *)account

    Create a new filesystem object with a linked account from the account manager.

  • - (NSArray *)listFolder:(DBPath *)path error:(DBError **)error

    Returns a list of DBFileInfo objects representing the files contained in the folder at path. If completedFirstSync is false, then this call will block until the first sync completes or an error occurs.

    Returns

    An array of DBFileInfo objects if successful, or nil if an error occurred.

  • - (DBFileInfo *)fileInfoForPath:(DBPath *)path error:(DBError **)error

    Returns the file info for the file or folder at path, or nil if an error occurred. If there is no file or folder at path, returns nil and sets error to DBErrorParamsNotFound.

  • - (DBFile *)openFile:(DBPath *)path error:(DBError **)error

    Opens an existing file and returns a file object representing the file at path.

    Files are opened at the newest cached version if the file is cached. Otherwise, the file will open at the latest server version and start downloading. Check the status property of the returned file object to determine whether it’s cached. Only 1 file can be open at a given path at the same time.

    Returns

    The file object if the file was opened successfully, or nil if an error occurred.

  • - (DBFile *)createFile:(DBPath *)path error:(DBError **)error

    Creates a new file at path and returns a file object open at that path.

    Returns

    The newly created file object if the file was opened successfuly, or nil if an error occurred.

  • - (DBFile *)openThumbnail:(DBPath *)path ofSize:(DBThumbSize)size inFormat:(DBThumbFormat)format error:(DBError **)error

    Opens a thumbnail for an existing file and returns a file object representing a thumbnail for the file at path.

    Thumbnails are opened at the newest cached version if the thumbnail is cached. Otherwise, the thumbnail will open at the latest version and start downloading. Check the status property of the returned file object to determine whether it’s cached.

    Thumbnails are generated on the server and cached separately. When offline a thumbnail might be unavailable even if the file contents are available. If a file is modified locally, the thumbnail will not be available until its upload completes. Check the thumbExists property of the file’s info to find out if a thumbnail is available for download.

    The DBFile object representing a thumbnail is unrelated to any DBFile opened on the file itself. Thumbnails are read-only – any attempt to write will fail. It is possible to open multiple thumbnails (for instance, of different sizes) on the same path.

    Thumbnails are scaled (not cropped) in a way which preserves the original images aspect ratio, to a size which fits within a bounding box defined by the size parameter.

    Returns

    The file object if the thumbnail was opened successfully, or nil if an error occurred.

  • - (BOOL)createFolder:(DBPath *)path error:(DBError **)error

    Creates a new folder at path.

    Returns

    YES if the folder was created successfully, or NO if an error occurred.

  • - (BOOL)deletePath:(DBPath *)path error:(DBError **)error

    Deletes the file or folder at path.

    Returns

    YES if the file or folder was deleted successfully, or NO if an error occurred.

  • - (BOOL)movePath:(DBPath *)fromPath toPath:(DBPath *)toPath error:(DBError **)error

    Moves a file or folder at fromPath to toPath.

    Returns

    YES if the file or folder was moved successfully, or NO if an error occurred.

  • - (NSString *)fetchShareLinkForPath:(DBPath *)path shorten:(BOOL)shorten error:(DBError **)error

    Returns a link to the file or folder at path, suitable for sharing. The link will optionally be shortened using the Dropbox URL shortener.

    If the file or folder was created locally but not yet uploaded, a link will be created, and viewing it before the upload is complete will result in a status page indicating the pending upload.

    This requires a server request. It will fail if the app is offline. It shouldn’t be called on the main thread.

    Returns

    the link URL, or nil if an error occurred.

  • - (BOOL)addObserver:(id)observer block:(DBObserver)block

    Add an observer to be notified any time a property of the filesystem changes.

    The block will be called anytime completedFirstSync, shutDown, or status changes.

  • - (BOOL)addObserver:(id)observer forPath:(DBPath *)path block:(DBObserver)block

    Add an observer to be notified any time the file or folder at path changes.

  • - (BOOL)addObserver:(id)observer forPathAndChildren:(DBPath *)path block:(DBObserver)block

    Add an observer to be notified any time the folder at path changes or a file or folder directly contained in path changes.

  • - (BOOL)addObserver:(id)observer forPathAndDescendants:(DBPath *)path block:(DBObserver)block

    Add an observer to be notified any time the folder at path changes or a file or folder contained somewhere beneath path changes.

  • - (void)removeObserver:(id)observer

    Unregister all blocks associated with observer from receiving updates.

  • - (void)shutDown

    Shuts down the filesystem, which stops all syncing.

    All associated DBFiles will be closed. Changes that were made to files before shutdown will be uploaded the next time a DBFilesystem is created.

    After this call, the DBFilesystem and its DBFiles can no longer be used. You should get a new DBFilesystem via initWithAccount:.

    The filesystem will be automatically shut down if the app is unlinked remotely.

Constants
  • typedef NSUInteger DBSyncStatus

    A bitset indicating the current status of the filesystem's syncing.

    The possible values set are:

    DBSyncStatusDownloadingAt least 1 file is currently downloading
    DBSyncStatusUploadingAt least 1 file is currently uploading
    DBSyncStatusSyncingDropbox is currently sending new file information
    DBSyncStatusActiveThe Sync API is actively monitoring for changes from Dropbox. This will be true when there are pending uploads or downloads, when DBFiles are open, or when path observers are registered.
  • typedef enum DBThumbSize

    Possible values for thumbnail size when opening a thumbnail. Thumbnails are scaled (not cropped) in a way which preserves the original images aspect ratio, to a size which fits within a bounding box defined by the size parameter.

    DBThumbSizeXSThumbnail scaled to fit in a 32x32 bounding box.
    DBThumbSizeSThumbnail scaled to fit in a 64x64 bounding box.
    DBThumbSizeMThumbnail scaled to fit in a 128x128 bounding box.
    DBThumbSizeLThumbnail scaled to fit in a 640x480 bounding box.
    DBThumbSizeXLThumbnail scaled to fit in a 1024x768 bounding box.
  • typedef enum DBThumbFormat

    Possible values for thumbnail format when opening a thumbnail.

    The available formats are:

    DBThumbFormatJPGThumbnail in JPG format
    DBThumbFormatPNGThumbnail in PNG format

DBPath

The path object represents a valid Dropbox path, and knows how to do correct path comparisons. It also has convenience methods for constructing new paths.

Class methods
  • + (DBPath *)root

    The top-most folder in your app’s view of the user’s Dropbox.

Instance methods
  • - (id)initWithString:(NSString *)pathStr

    Create a new path object from a string. Some special characters, names, or encodings a are not allowed in a Dropbox path. For more details see this article.

    Returns

    A new path object if the contents of pathStr are a valid Dropbox path, nil otherwise.

  • - (NSString *)name

    The unqualified name of the file or folder at this path. For the root, this will return the same as stringValue.

  • - (DBPath *)childPath:(NSString *)childName

    Create a new path by treating the current path as a path to a folder, and childName as the name of an item in that folder.

    Returns

    A new path, or nil if childName is invalid.

  • - (DBPath *)parent

    Create a new path that is the folder containing the current path. For the root, this will return the same as stringValue.

    Returns

    A new path, or nil if path is already at the root.

  • - (NSString *)stringValue

    The fully qualified path (relative to the root) as a string, with original casing.

DBFileInfo

The file info class contains basic information about a file or folder.

Properties
  • @property (nonatomic, readonly) DBPath *path

    The path of the file or folder.

  • @property (nonatomic, readonly) BOOL isFolder

    Whether the item at path is a folder or a file.

  • @property (nonatomic, readonly) NSDate *modifiedTime

    The last time the file or folder was modified.

  • @property (nonatomic, readonly) long long size

    The file’s size. This property is always 0 for folders.

  • @property (nonatomic, readonly) BOOL thumbExists

    Whether a thumbnail for this file can be requested from the server, based on the file format. Since thumbnails are generated only by the server, this value will be false on a locally-modified file until it finishes uploading.

  • @property (nonatomic, readonly) NSString *iconName

    The name of an appropriate icon to display for the file, taken from the Dropbox icon library. Will be nil if no suggested icon is available. For more information see the metadata documentation.

DBFile

The file object represents a particular file at a particular version. It has basic file operations such as reading and writing the file’s contents and getting info about the file. It can also tell you the current sync status, whether there’s a newer version available, and allows you to update to the newer version.

Properties
  • @property (nonatomic, readonly) DBFileInfo *info

    The DBFileInfo for the file.

    Note that the path of a file can change if a conflict occurs, so the value of file.info.path is not always equal to the path the file was opened at.

    If this DBFile represents a thumbnail, the info still reflects the full file contents.

  • @property (nonatomic, readonly, getter=isOpen) BOOL open

    Whether the file is currently open.

  • @property (nonatomic, readonly) DBFileStatus *status

    The current sync status for the file or thumbnail version represented by this DBFile.

  • @property (nonatomic, readonly) DBFileStatus *newerStatus

    The current sync status for the newer version of the file. If the file is the newest version, then this property is nil.

  • @property (nonatomic, readonly) BOOL isThumb

    Whether this DBFile represents a thumbnail, rather than the file contents.

Instance methods
  • - (NSFileHandle *)readHandle:(DBError **)error

    Returns a read-only file handle for the file. If the file is not cached then the method will block until the file is downloaded.

    Returns

    A file handle if the file can be read, or nil if an error occurred.

  • - (NSData *)readData:(DBError **)error

    A wrapper for readHandle: that reads the entire file contents into an NSData object.

    Returns

    The file’s contents if the file can be read, or nil if an error occurred.

  • - (NSString *)readString:(DBError **)error

    A wrapper for readHandle: that reads the entire file contents as a UTF8 encoded string.

    Returns

    The file’s contents decoded as UTF8 if the file can be read, or nil if an error occurred.

  • - (BOOL)writeContentsOfFile:(NSString *)localPath shouldSteal:(BOOL)shouldSteal error:(DBError **)error

    Updates the file’s contents with the contents of the file at localPath.

    Parameters

    shouldSteal

    whether the file at localPath should be moved from its current location (i.e. “stolen”) into management by the Sync SDK, or if it must be copied. If you are done with the file at localPath, then stealing is more efficient, but the behavior of writing to the file after stealing is undefined.

    Returns

    YES if the file was written successfully, or NO if an error occurred.

  • - (BOOL)writeData:(NSData *)data error:(DBError **)error

    Updates the contents of the file to be the bytes stored in data.

    Returns

    YES if the file was written successfully, or NO if an error occurred.

  • - (BOOL)writeString:(NSString *)string error:(DBError **)error

    Updates the contents of the file with the parameter string encoded in UTF8.

    Returns

    YES if the file was written successfully, or NO if an error occurred.

  • - (BOOL)appendData:(NSData *)data error:(DBError **)error

    Apppends the data supplied to the end of the file. If the file is not cached, then the method will block until the file is downloaded.

    Returns

    YES if the data was appended to the file successfully, or NO if an error occurred.

  • - (BOOL)appendString:(NSString *)string error:(DBError **)error

    Appends the UTF8 encoded string to the file. If the file is not cached, then the method will block until the file is downloaded.

    Returns

    YES if the string was appended to the file successfully, or NO if an error occured.

  • - (BOOL)update:(DBError **)error

    If there is a newer version of the file available, and it’s cached (determined by the cached property on newerStatus), then this method will update the file object to reference the newer version so it can be read from or written to.

    Returns

    YES if the file was written successfully, or NO if an error occurred.

  • - (void)close

    Closes the file, preventing any further operations to occur and allowing the file to be opened again. This happens automatically when the object is deallocated.

  • - (void)addObserver:(id)observer block:(DBObserver)block

    Add block as an observer when a property of the file changes.

  • - (void)removeObserver:(id)observer

    Remove all blocks registered for the given observer.

DBFileStatus

The file status object exposes information about the file’s current sync status, including whether it’s cached, if it’s uploading or downloading, and the progress of an upload or download.

Properties
  • @property (nonatomic, readonly) BOOL cached

    Whether the contents of the file are cached locally and can be read without making a network request.

  • @property (nonatomic, readonly) DBFileState state

    Whether the file is currently uploading, downloading, or neither (idle)

  • @property (nonatomic, readonly) float progress

    If the file is transferring, the progress of the transfer, between 0 and 1.

  • @property (nonatomic, readonly) DBError *error

    If the file needs to be transferred, but can’t for whatever reason (such as no internet connection), then this property is set to the last error that prevented the transfer.

Constants
  • typedef enum DBFileState

    An enum representing the current sync status of the file. Its possible values are:

    DBFileStateDownloadingThe file is currently downloading
    DBFileStateUploadingThe file is currently uploading
    DBFileStateIdleThe file is neither uploading or downloading