Sync API for OS X documentation

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

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

The most recently 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 use the linkedAccounts property.

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.

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.

This method begins the process for linking new accounts.

This will open the auth flow in a sheet. If parentWindow is nil it will open in a new window. When the user exits the flow, block will be called with the linked account which might be nil if the user cancelled or if there were errors.

Your app can call this method repeatedly to link more than one account (such as personal and a business account).

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.

Use this method to remove all blocks associated with observer.

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

An observer for the linkedAccount property

A completion block called after linking with linkFromWindow:withCompletionBlock:

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

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

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:.

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.

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

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

The recommended string to display to identify an account.

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

The user’s name.

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

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

The type of error that occurred. It will be one of the following codes. Note that those codes marked as "Fatal" will generally cause exceptions rather than being returned as DBError. However you may see those codes in background sync status.

Information about the error which caused this exception to be raised.

A convienent place to store your app’s filesystem

A convienent place to get your app’s filesystem

The account object this filesystem was created with.

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.

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

The status of background synchronization.

The current total disk space consumed by files in the cache.

The configured maximum size of files in the cache.

Once set, this setting will remain in effect across app restarts. When the cache size is lowered, this method will immediately clean up the cache based on the new limit. See the class documentation for more information on cache management.

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

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 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.

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.

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

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.

Creates a new folder at path.

Deletes the file or folder at path.

Moves a file or folder at fromPath to toPath.

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.

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.

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

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

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

Unregister all blocks associated with observer from receiving updates.

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.

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.

Possible values for thumbnail format when opening a thumbnail.

Background synchronization is actively processing or waiting for changes. Syncing is active when a DBFilesystem is first created until it completes its first file info sync. After that point it is active whenever there are changes to download or upload, or when there are any files open or path observers registered.

Status of synchronizing info about files and folders. Metadata sync is only considered in progress when it is actively processing new changes, not when it is simply watching for changes.

Status of downloading file contents into the cache.

Status of uploading changes to the server. This includes changes to file contents, as well as creation, deletion, and renames.

Convenience property for checking whether any type of operation is in progress.

Convenience property for determining whether any operation failed, and getting an appropriate DBError. If there are multiple failures, the DBError returned will be taken from metadata, download, or upload status in that order.

Indicates that operations are in progress or queued for retry.

If the most recent operation failed, the failure is represented here. Otherwise this field is nil.

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

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.

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

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.

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

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

The path of the file or folder.

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

The last time the file or folder was modified.

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

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.

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.

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.

Whether the file is currently open.

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

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

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

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.

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

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

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

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

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

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.

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

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.

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.

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

Remove all blocks registered for the given observer.

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

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

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

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.

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