Sync API for Android documentation

Initializes the Dropbox Sync API if necessary, and returns an object for interacting with the Sync API. This method can be called multiple times but you must always pass the same app key and app secret.

Starts the authentication process to link a new account, initiated from an Activity. This will prompt the user to log in and authorize this app to use their Dropbox account. Once linking is complete, the given activity will receive a result via Activity.onActivityResult() with the request code you specify.

If your app is already linked, you can call this method again to prompt the user to link a different account, allowing your app to use multiple accounts at once (e.g. a personal and a business account).

Note that if you're using an older Android SDK (prior to API 11), you may see an error about the type of the first argument to this method and the other overloads. You can avoid this error using an explicit cast of the first argument to force this method to be chosen. For instance: startLink((Activity)this, code)

Starts the authentication process to link a new account, initiated from a Fragment. This will prompt the user to log in and authorize this app to use their Dropbox account. Once linking is complete, the given activity will receive a result via Activity.onActivityResult() with the request code you specify.

Note that if you're using an older Android SDK (prior to API 11), you may see an error about the type of the first argument to this method and the other overloads. You can avoid this error using an explicit cast of the first argument to force this method to be chosen. For instance: startLink((Fragment)this, code)

Starts the authentication process to link a new account, initiated from a Fragment using the V4 support library. This will prompt the user to log in and authorize this app to use their Dropbox account. Once linking is complete, the given activity will receive a result via Fragment.onActivityResult() with the request code you specify.

This method uses a unique name to avoid compilation issues in apps which do not use the support library.

Unlinks this app from Dropbox. If multiple accounts have been linked, this method will unlink all of them. To unlink a single account use DbxAccount.unlink().

Returns whether this application is linked to at least one Dropbox account.

Returns the DbxAccount for the most recently linked Dropbox account, if any. If no account has been linked, this method will return null.

If your app needs to link multiple accounts at the same time, you should use getLinkedAccounts() instead.

Returns the DbxAccount for all currently linked Dropbox accounts. If no accounts have been linked, this method will return an empty list.

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

Adds an DbxAccountManager.AccountListener which will be called whenever a new account is linked or an existing account is unlinked. The listener will be called regardless of whether the account was unlinked using DbxAccount.unlink() or by the user on the Dropbox website.

Registering the same listener more than once will have no additional effect. A single call to removeListener() will still remove it.

Removes a listener previously added by a call to addListener().

The human-readable version number for this SDK.

Thrown when getInstance() was called with two different configurations in the same application.

Called whenever a new account is linked, or an existing account is unlinked. An unlink notification indicates that the DbxFileSystem will be shut down so the app should disable Dropbox functionality.

Listeners are called on the main UI thread. To keep your UI responsive, you shouldn't do anything slow in your listener.

Returns the user ID for this account.

Returns whether this account is currently linked.

Returns the DbxAccountInfo for this account, if available, or null otherwise. Account info is fetched in the background. To be notified when account info is available or updated, use addListener().

Unlinks this app from the user's Dropbox account. This will also shut down the corresponding DbxFileSystem and delete any locally cached data for the user.

This method has no effect if this account isn't linked.

Adds a DbxAccount.Listener which will be called each time the account changes: i.e. it is unlinked, or the account info is updated.

Registering the same listener more than once will have no additional effect. A single call to removeListener() will still remove it.

Removes a listener previously added by a call to addListener().

Called when the observed account is unlinked, or account info changes. After an account is unlinked, listeners will receive no further calls.

The recommended string to display to identify an account. This is "userName" if orgName is null, otherwise it's "userName (orgName)".

The user's name.

The user's organization's name, if available, or null otherwise.

Re-throws this exception.

Attempt to open a file or datastore which is already open.

An operation was cancelled by another thread.

Insufficient local storage space.

The app attempted an operation that isn't allowed by its access level, or that the user does not have permission to perform.

Operation failed because the target already exists.

I/O error accessing a file outside of the SDK's cache.

The thread was interrupted.

An attempt to perform an invalid API operation such as attempting to delete or move the root directory.

Network failure.

No network connection available.

Timeout in network communication.

File, folder, or datastore doesn't exist.

No thumbnail is available.

Parent of a specified file or folder doesn't exist, or is a file rather than a folder.

The user's Dropbox quota is full.

There was an attempt to modify a read-only file or folder.

Server indicated that a request is invalid.

Invalid response from server.

Rate limited by the server.

Error reported by the Dropbox server.

Failure to establish secure communication via SSL/TLS.

Application or user isn't authorized. This may indicate that the application has been unlinked by the user via the website.

Re-throws this exception.

Unchecked exception type used when the server denies access.

Unchecked exception type used to indicate use of a bad index into a list or array.

Unchecked exception type used to indicate an object is in a bad state for an attempted operation.

Unchecked exception type used to indicate use of an object of the wrong type.

Unchecked exception type used to indicate an error in the SDK's local cache storage.

Unchecked exception type used to indicate an object was used after it was closed.

Unchecked exception type used to indicate an object was used after it was deleted.

Unchecked exception type used to indicate an illegal argument passed to the SDK.

Unchecked exception type used to indicate an internal error or assertion in the SDK.

Unchecked exception type used to indicate memory exhaution in the SDK.

Unchecked exception type used to indicate a file is not in the cache when it should be.

Unchecked exception type used to indicate an object was used after it was shut down.

Unchecked exception type used to indicate exceeding a fixed limit, such as the maximum size of a datastore.

Unchecked exception type used to indicate an error with OS functionality (such as threads or disk I/O) inside the SDK.

Re-throws this instance, which will always be either a DbxException or an unchecked DbxRuntimeException.

Gets the failure message, as with the Throwable method.

Gets the cause of this exception, as with the Throwable method.

Returns the appropriate DbxFileSystem for the given account, creating it if necessary.

Shuts down this DbxFileSystem and stops background synchronization. It isn't necessary to call this method before an app terminates, but you can call it to ensure that background synchronization is stopped and resources are freed immediately.

Before shutting down you should ensure that all files are closed. Outstanding changes to unclosed files may be lost. Local changes to closed files that haven't yet been uploaded will remain queued for upload the next time a DbxFileSystem is created for this account.

After this call, most DbxFileSystem and DbxFile methods will fail with DbxRuntimeException.Shutdown. You should get a new DbxFileSystem via forAccount().

This method will have no effect if the DbxFileSystem is already shut down.

Checks whether this instance has been shut down, either explicitly with a call to shutDown(), or implicitly when its account was unlinked.

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

Gets the configured maximum amount of space in the local file system to use for cached files.

Sets the maximum amount of space in the local file system to use for cached files.

Once set, this setting will remain in effect across app restarts. See the DbxFileSystem class documentation for more information on cache management.

When the cache size is lowered, this method will immediately clean up the cache based on the new limit.

Returns whether the cached state has ever been synced since this app was first linked. Until the first sync completes, listFolder() will block, and any files you create may conflict with files already on the server. Once the first sync completes and cached state is available, this value will remain true even after a restart.

Unlike awaitFirstSync() this method won't fail if the sync fails, but will continue to return false until a sync is successful.

Waits for the first sync of this cache to be complete (as defined by hasSynced(), so that valid file info is available.

This method will stop waiting if the first sync fails, and will throw an exception indicating the sync failure.

Forces a check for new file info from the server, and waits for it to complete. This method will stop waiting if the sync fails, and will throw an exception indicating the sync failure.

Returns the status of background synchronization.

Registers a listener that will be called when there's a change to the status of background synchronization, as returned by getSyncStatus().

Adding the same listener more than once will have no effect. A single call to removeSyncStatusListener() will cause it to no longer be called. This method will be ignored, and listeners won't be called if this DbxFileSystem is shut down.

Listeners are called on the main UI thread. To keep your UI responsive, you shouldn't do anything slow in your listener.

Removes a listener previously registered with addSyncStatusListener().

Calling this method with a listener that was never added will have no effect. This method will be ignored, and listeners won't be called if this DbxFileSystem is shut down.

Registers a listener that will be called when there's a change to info or contents of a file or folder at the given path, or optionally to its children or descendants.

The same listener can be registered for a different combination of path and type. Adding the same listener for the same combination will have no additional effect. A single call to removePathListener() with the same combination will remove it.

This method will be ignored, and listeners won't be called if this DbxFileSystem is shut down.

Listeners are called on the main UI thread. To keep your UI responsive, you shouldn't do anything slow in your listener.

Removes a listener previously registered with addPathListener() for a given combination of path and mode.

This will remove the given listener for the given combination of path and type only, having no effect on distinct registrations of the same listener. Calling this method for a listener and parameter combination that was never registered will have no effect.

This method will be ignored, and listeners won't be called if this DbxFileSystem is shut down.

Unregisters a listener previously registered using addPathListener(), for all combinations of path and mode.

This will have no effect if the given listener was never registered.

This method will be ignored, and listeners won't be called if this DbxFileSystem is shut down.

Lists the contents of a folder. This call will block to wait for the first sync to be complete, as described in hasSynced() before returning.

Returns info about a given file or folder by path.

Checks whether a file or folder exists at the given path.

Checks whether a file exists at the given path.

Checks whether a folder exists at the given path.

Opens an existing file, using the latest cached revision if any exists, or otherwise using the latest known version. Opening a file will trigger a download of the latest version, and you can use methods on DbxFile to check the status of the download or update to a newer revision when it becomes available.

This method will fail if the same file is already open, or if the file doesn't exist. Use create() to create a new file.

You must call DbxFile.close() when you are finished with the file.

Creates a new file, including any nonexistent parent folders. The new file will be available to write immediately, and you can use methods on DbxFile to check the status of the upload, or check for newer versions created on the server.

This method will fail if file already exists. Use open() to open an existing file.

You must call DbxFile.close() when you are finished with the file.

Opens a thumbnail for existing file, using the latest cached thumbnail if any exists, or otherwise using the latest known version of the file. Opening a thumbnail will trigger a download of the latest thumbnail, and you can use methods on DbxFile to check the status of the download or update to a newer thumbnail when it becomes available.

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 won't be available until its upload completes. Check the DbxFileInfo.thumbExists field of the file's info to see if a thumbnail is available for download.

The DbxFile object representing a thumbnail is unrelated to any DbxFile 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.

You must call DbxFile.close() when you are finished with the thumbnail.

Creates a new folder, including parent folders if necessary.

Deletes a file, or recursively deletes a folder.

Moves a file or folder, including its contents, to a new location.

Returns a link to a specified file or folder in Dropbox, suitable for sharing. 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 method makes a server request. It will fail if the app is offline. It shouldn't be called on the main UI thread.

Specifies the desired 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.

Specifies the desired format when opening a thumbnail.

Called when there's a change to a path for which a listener is registered. The listener can use DbxFileSystem methods to list files and folders for changes.

Specifies the situations in which a listener should be notified. If the target path doesn't refer to a folder, then all options are equivalent.

Called when there has been a change to the status of background synchronization. Call DbxFileSystem.getSyncStatus() to fetch the latest status.

Background synchronization is actively processing or waiting for changes. Syncing is active when a DbxFileSystem 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 listeners 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 method for checking whether any type of operation is in progress.

Convenience method for determining whether any operation failed, and getting an appropriate exception to throw. If there are multiple failures, the exception returned will be taken from metadata, download, and 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 null.

Creates a new DbxPath.

Creates a new DbxPath representing a child or descendant of a parent path.

• DbxPath(ROOT, "Photos") → "/Photos"
• DbxPath(DbxPath("/Photos/Recent"), "Home.jpg") → "/Photos/Recent/Home.jpg"
• DbxPath(DbxPath("/Photos"), "Recent/Home.jpg") → "/Photos/Recent/Home.jpg"

Gets a version of this path suitable for logging. It will be hashed in a way that makes it possible to identify it across different log messages, but doesn't reveal any private user data.

Returns the unqualified name of the file or folder at this path.

• getName("/") → ""
• getName("/Photos") → "Photos"
• getName("/Photos/Recent/Home.jpg") → "Home.jpg"

Returns the path of the folder containing this path, or null if the path is "/".

• getParent("/") → null
• getParent("/Photos") → "/"
• getParent("/Photos/Recent/Home.jpg") → "/Photos/Recent"

Treats this path as a folder and returns the path of a child file or folder with the given name.

Returns whether the given path is a descendant of this one. This method returns false if the given path is equal to this one.

Returns whether the given path is the same as or a descendant of this one. This method returns true if the given path is equal to this one.

Dropbox paths always begin with a forward-slash and ROOT is always a single forward-slash. ROOT refers either to the root of a user's Dropbox, or to the root of your app's folder, depending on your app permissions.

Thrown when a given string isn't a valid Dropbox path, due to invalid characters, names, or encodings. For more details see this article.

The path to the file or folder.

Whether this is a folder.

The size, in bytes, of the file content. Undefined for folders.

The time that this file was last modified based on the system clock of the local device, not Dropbox's servers. It should not be used to determine if a file has changed, only as a way to order files in the UI or display a modified time.

Whether a thumbnail can be requested from the server for this file.

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

Closes this file, as well as any open read or write streams, and finalizes any outstanding writes. Must be called to release this file when you're finished with it.

If there is a failure finalizing writes, it will be logged as a warning but will not result in an exception. Calling this method again on a closed file will have no effect. Other methods will throw DbxRuntimeException.Closed after a file is closed.

Gets the path used to open or create this file.

Determines whether this instance represents a thumbnail, as opposed to file contents.

Returns a stream that can be used to read data from this file. This method will block until the file has been downloaded into the cache before returning.

Once a read stream has been opened on this file, no writes can be made to this file until this stream is closed, or the file is closed. Multiple read streams can be open at once. Read streams aren't thread-safe, so each should be used on only one thread, or synchronized externally.

Callers can use the file-descriptor backing this stream if they need direct access to the file. The file-descriptor represents a file in the cache, and shouldn't be written, but can be freely read until this stream is closed.

Reads the full contents of this file as a String in UTF-8 encoding. This method will block until the file has been downloaded into the cache before reading.

Returns a stream that can be used to write data to this file. The write won't be visible in Dropbox until the stream is closed, or the file is closed.

No other reads or writes (including appends) can be made to this file while a write stream is open. Write streams aren't thread-safe, so each should be used on only one thread, or synchronized externally.

Callers can use the file-descriptor backing this stream if they need direct access to the file. The file-descriptor represents a new empty file, which will become the new file version when this stream is closed.

Returns a stream that can be used to append data to this file. The new write won't be visible in Dropbox until the stream is closed, or the file is closed.

No other reads or writes (including appends) can be made to this file while an append stream is open. Append streams aren't thread-safe, so each should be used on only one thread, or synchronized externally.

Callers can use the file-descriptor backing this stream if they need direct access to the file. The file-descriptor represents a temporary file containing the contents of the previous version of the file, which will become the new file version when this append stream is closed.

Replaces the contents of this file with the contents of a given file. Sync API will attempt to sync the new contents of the file passed to this method as soon as this method completes.

Optionally, the API can "steal" the given file, moving it into the private cache to avoid the need for copying data. If stealing is allowed, no future attempts should be made to access the file.

Replaces the contents of this file with the given string, encoded in UTF-8. Sync API will attempt to sync the new contents of the file as soon as this method completes.

Appends the given string encoded in UTF-8 to the file. Sync API will attempt to sync the new contents of the file method as soon as this method completes.

Returns info about this file. If this DbxFile represents a thumbnail, the returned info still reflects the full file contents.

Updates this DbxFile to a newer cached version of the same file, as reflected by getNewerStatus(). This method will have no effect if there's no newer version, or the newer version isn't yet cached. This operation is equivalent to closing the file and reopening it, except that it will properly follow the file across local rename and move operations.

Returns the current status of synchronizing this version of this file. If this DbxFile represents a thumbnail, the result reflects the sync status of the thumbnail, not the full file contents.

Checks for newer versions of this file, and returns the synchronization status of a newer version, if any. This method will report on the newest known version that has at least begun downloading. The version indicated may still be downloading, as reflected in the returned status. Once it is finished downloading and in a cached state, you can switch to it with a call to update().

A return value of null indicates that this file version is the newest known version.

Adds a listener that will be called when there's a change to the sync status, file info, or contents of this file or other versions of the same file.

Adding the same listener multiple times will have no additional effect. A single call to removeListener() will still remove it. This method will be ignored, and listeners won't be called if the file is closed or the file system has been shut down.

Listeners are called on the main UI thread. To keep your UI responsive, you shouldn't do anything slow in your listener.

Removes a listener previously registered with addListener().

Thrown when attempt was made to read or write this DbxFile when an existing stream is already open. There can be only one write stream, or multiple read streams open at once.

Called when there's a change to the sync status, file info, or contents of this file.

Whether this file revision is available in the local cache. If true, this file is ready to be read.

Whether this file revision is the latest known revision. If false, there's a newer revision, and you can check its status using DbxFile.getNewerStatus().

What operation is pending on this file revision, if any.

Whether the pending operation has failed, and what the failure is. Failed operations will be retried later. Will be null if there's no pending operation, or the operation is still in progress.

The amount of a pending upload or download operation that has been completed, in bytes. Will be -1 when no transfer is in progress.

The size of the file being uploaded or downloaded.

Indicates the pending operation on a file.