Sync API for Android 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. If your app uses multiple processes, you must make use of the Sync API in only a single process, to avoid conflicting access to the cache on disk.

DbxAccountManager

This is the entry point for the Sync API. Use this class to initialize the Sync API and link it to a user's Dropbox account. The same account linking infrastructure applies whether you want to use files and folders, or datastores, or both.

Use getInstance to get an instance of DbxAccountManager. Then call getLinkedAccount() to see if there's already a linked Dropbox account. If that returns null use startLink(Activity, int) to begin the process of linking a user's Dropbox account.

Static methods
  • DbxAccountManager getInstance(android.content.Context applicationContext, String appKey, String appSecret)

    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.

    Parameters

    applicationContext

    the context of the current application. Must be an application context (getApplicationContext()), not just an Activity or other context.

    appKey

    your Dropbox API app key.

    appSecret

    your Dropbox API app secret.

    Throws

    DbxAccountManager.ConfigurationMismatchException

    if the app key or secret given doesn't match an earlier call.

Instance methods
  • void startLink(android.app.Activity activity, int callbackRequestCode)

    Starts the authentication process to link a new account. 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), or aren't using the Android support library, 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)

    Parameters

    activity

    the Activity that will be launched when linking is complete.

    callbackRequestCode

    the request code that will be passed to the given Activity's Activity.onActivityResult() when linking is complete. This can be any value, which the API will simply pass through.

    Throws

    DbxAccountManager.MultipleAccountsException

    if there's already an account linked.

  • void startLink(android.app.Fragment fragment, int callbackRequestCode)

    Starts the authentication process to link a new account. 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.

    Note that if you're using an older Android SDK (prior to API 11), or aren't using the Android support library, 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)

    Parameters

    fragment

    the Fragment that will be launched when linking is complete.

    callbackRequestCode

    the request code that will be passed to the given Fragment's Fragment.onActivityResult() when linking is complete. This can be any value, which the API will simply pass through.

    Throws

    DbxAccountManager.MultipleAccountsException

    if there's already an account linked.

  • void startLink(android.support.v4.app.Fragment fragment, int callbackRequestCode)

    Starts the authentication process to link a new account. 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.

    Note that if you're using an older Android SDK (prior to API 11), or aren't using the Android support library, 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)

    Parameters

    fragment

    the Fragment that will be launched when linking is complete.

    callbackRequestCode

    the request code that will be passed to the given Fragment's Fragment.onActivityResult() when linking is complete. This can be any value, which the API will simply pass through.

    Throws

    DbxAccountManager.MultipleAccountsException

    if there's already an account linked.

  • void unlink()

    Unlinks this app from the user's Dropbox account.

  • boolean hasLinkedAccount()

    Returns whether this application is linked to a Dropbox account.

  • DbxAccount getLinkedAccount()

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

  • void addListener(AccountListener l)

    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.

  • void removeListener(AccountListener l)

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

Constants
  • String SDK_VERSION_NAME

    The human-readable version number for this SDK.

Exceptions
  • DbxAccountManager.MultipleAccountsException   extends IllegalStateException

    Thrown when the app attempts to link with a Dropbox account while already linked.

  • DbxAccountManager.ConfigurationMismatchException   extends IllegalArgumentException

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

DbxAccountManager.AccountListener

Interface for receiving notifications of a new account being linked or an existing account being unlinked.

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

Instance methods
  • void onLinkedAccountChange(DbxAccountManager mgr, DbxAccount acct)

    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.

    Parameters

    mgr

    the account manager on which this listener was registered.

    acct

    the account that has been linked or unlinked. Examine this object to determine which one has occurred.

DbxAccount

Represents a specific user's Dropbox account.

Instance methods
  • String getUserId()

    Returns the user ID for this account.

  • boolean isLinked()

    Returns whether this account is currently linked.

  • DbxAccountInfo getAccountInfo()

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

  • void unlink()

    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.

  • void addListener(Listener l)

    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.

  • void removeListener(Listener l)

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

DbxAccount.Listener

Callback interface for listeners to be notified when a specific account changes. Changes include unlinking the account, or updated account info.

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

Instance methods
  • void onAccountChange(DbxAccount acct)

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

    Parameters

    acct

    the account on which the listener was registered.

DbxAccountInfo

Information about a user's Dropbox account.

Instance fields
  • String displayName

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

  • String userName

    The user's name.

  • String orgName

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

DbxException   extends IOException

Base class for exceptions. Inner subtypes distinguish types of Exceptions so your app can respond appropriately.

Exceptions
  • DbxException.AlreadyOpen   extends DbxException

    Specified file is already open.

  • DbxException.ApiUsage   extends DbxException

    Specific usage or arguments.

  • DbxException.Disallowed   extends DbxException

    The app attempted an operation that isn't allowed by its access level.

  • DbxException.Exists   extends DbxException

    Specified file or folder already exists.

  • DbxException.DiskSpace   extends DbxException.RecoverableSystem

    Insufficient storage space.

  • DbxException.InvalidParameter   extends DbxException

    Bad parameter value, such as attempting to delete or move the root directory.

  • DbxException.Network   extends DbxException

    Network failure.

  • DbxException.NetworkConnection   extends DbxException

    Failure to establish a network connection.

  • DbxException.NetworkTimeout   extends DbxException

    Network timeout.

  • DbxException.NotFound   extends DbxException

    Specified file or folder doesn't exist.

  • DbxException.NoThumb   extends DbxException

    No thumbnail is available.

  • DbxException.Parent   extends DbxException

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

  • DbxException.Quota   extends DbxException

    The user's Dropbox quota is full.

  • DbxException.RecoverableSystem   extends DbxException

    System failure that should be recoverable in some way.

  • DbxException.Server   extends DbxException

    Error reported by the server.

  • DbxException.Ssl   extends DbxException

    Failure to establish SSL communication.

  • DbxException.Unauthorized   extends DbxException

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

DbxFileSystem

Provides access to the files and folders in a user's Dropbox. Get an instance using forAccount().

A DbxFileSystem allows you to list folders, and open or create files as if they were local. You can also manipulate the directory structure through creation, moves, renames, and deletes. The DbxFileSystem automatically synchronizes changes with the Dropbox server in the background. Local changes to the DbxFileSystem are automatically uploaded. Remote changes to file and folder info are automatically downloaded. Remote changes to file content are downloaded when you open a DbxFile.

Background syncing will remain active if there are outstanding changes to upload or download, if there are open files, or if there are any listeners registered via addPathListener() or DbxFile.addListener(). Otherwise, syncing will be paused to preserve battery life until you access DbxFileSystem again. If syncing isn't active, and you want to ensure up-to-date data, call syncNowAndWait().

A DbxFileSystem instance is tied to a linked user account, and will be shut down if the account is unlinked. In this case, most methods will throw DbxException.Unauthorized.

Static methods
Instance methods
  • void shutDown()

    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 DbxException.ApiUsage. You should get a new DbxFileSystem via forAccount().

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

  • boolean isShutDown()

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

  • DbxAccount getAccount()

    Returns DbxAccount associated with this DbxFileSystem.

  • boolean hasSynced()

    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.

    Throws

    DbxException

    if there's a failure getting status.

  • void awaitFirstSync()

    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.

    Throws

    DbxException

    if the first sync fails.

  • void syncNowAndWait()

    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.

    Throws

    DbxException

    if the requested sync fails.

  • DbxSyncStatus getSyncStatus()

    Returns the status of background synchronization.

    Throws

    DbxException

    if there's a failure getting status.

  • void addSyncStatusListener(SyncStatusListener l)

    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.

  • void removeSyncStatusListener(SyncStatusListener l)

    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.

  • void addPathListener(PathListener l, DbxPath path, Mode mode)

    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.

    Parameters

    l

    the listener to register.

    path

    the path for which to listen.

    mode

    the type of events for which to listen.

  • void removePathListener(PathListener l, DbxPath path, Mode mode)

    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.

    Parameters

    l

    the listener to register.

    path

    the path for which to listen.

    mode

    the type of events for which to listen.

  • void removePathListenerForAll(PathListener l)

    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.

  • List<DbxFileInfo> listFolder(DbxPath path)

    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.

    Parameters

    path

    the path to the folder.

    Throws

    DbxException.NotFound

    if the folder doesn't exist.

    DbxException.InvalidParameter

    if the path refers to a file.

    DbxException

    if another failure occurs.

  • DbxFileInfo getFileInfo(DbxPath path)

    Returns info about a given file or folder by path.

    Throws

    DbxException.NotFound

    if the path doesn't exist.

    DbxException

    if another failure occurs.

  • boolean exists(DbxPath path)

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

    Parameters

    path

    the path to check.

    Throws

    DbxException

    if there's a failure checking file info.

  • boolean isFile(DbxPath path)

    Checks whether a file exists at the given path.

    Parameters

    path

    the path to check.

    Throws

    DbxException

    if there's a failure checking file info.

  • boolean isFolder(DbxPath path)

    Checks whether a folder exists at the given path.

    Parameters

    path

    the path to check.

    Throws

    DbxException

    if there's a failure checking file info.

  • DbxFile open(DbxPath 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.

    Parameters

    path

    the path to the file.

    Throws

    DbxException.NotFound

    if the file doesn't exist.

    DbxException.InvalidParameter

    if the path refers to a folder.

    DbxException.AlreadyOpen

    if there's already a DbxFile open for this file.

    DbxException

    if another failure occurs.

  • DbxFile create(DbxPath path)

    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.

    Parameters

    path

    the path to the file

    Throws

    DbxException.Exists

    if the file already exists, or one of its parents is a file rather than a folder.

    DbxException.InvalidParameter

    if the path refers to a folder.

    DbxException.AlreadyOpen

    if there's already a DbxFile open for this file.

    DbxException

    if another failure occurs.

  • DbxFile openThumbnail(DbxPath path, ThumbSize size, ThumbFormat format)

    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.

    Parameters

    path

    the path to the file.

    size

    the size of the thumbnail to open. The thumbnail is scaled (not cropped) in a way which preserves the original images aspect ratio, to a size which fits within a bounding box defined by this parameter.

    format

    the format for the thumbnail.

    Throws

    DbxException.NotFound

    if the file doesn't exist.

    DbxException.InvalidParameter

    if the path refers to a folder.

    DbxException.NoThumb

    if there is no thumbnail available for this file.

    DbxException

    if another failure occurs.

  • void createFolder(DbxPath folderPath)

    Creates a new folder, including parent folders if necessary.

    Parameters

    folderPath

    the path to the new folder.

    Throws

    DbxException.Exists

    if there's a file in the way of the specified folder.

    DbxException

    if another failure occurs.

  • void delete(DbxPath path)

    Deletes a file, or recursively deletes a folder.

    Parameters

    path

    the path to the file or folder.

    Throws

    DbxException.NotFound

    if the given path doesn't exist.

    DbxException.InvalidParameter

    if the given path is the root.

    DbxException

    if another failure occurs.

  • void move(DbxPath oldPath, DbxPath newPath)

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

    Parameters

    oldPath

    the path of the file or folder.

    newPath

    the new path of the file or folder, including its new name.

    Throws

    DbxException.NotFound

    if the source path doesn't exist.

    DbxException.Exists

    if one of the parents of the new path is a file rather than a folder.

    DbxException.InvalidParameter

    if either given path is the root.

    DbxException

    if another failure occurs.

  • URL fetchShareLink(DbxPath path, boolean shorten)

    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.

    Parameters

    path

    the path to the file or folder to share.

    shorten

    whether the URL should be shortened using the Dropbox URL shortening service.

    Throws

    DbxException.NotFound

    if the given file or folder doesn't exist.

    DbxException

    if another failure occurs.

Enums
  • DbxFileSystem.ThumbSize

    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.

    Values

    XS

    Thumbnail scaled to fit in a 32x32 bounding box.

    S

    Thumbnail scaled to fit in a 64x64 bounding box.

    M

    Thumbnail scaled to fit in a 128x128 bounding box.

    L

    Thumbnail scaled to fit in a 640x480 bounding box.

    XL

    Thumbnail scaled to fit in a 1024x768 bounding box.

  • DbxFileSystem.ThumbFormat

    Specifies the desired format when opening a thumbnail.

    Values

    JPG

    Thumbnail should be in JPG format.

    PNG

    Thumbnail should be in PNG format.

DbxFileSystem.PathListener

A listener to be called when there's a change at a given path, or optionally to its descendants. The change might be to file info, folder contents, or file contents.

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

Registered path listeners will cause the SDK to perform more frequent updates in the background to ensure changes are visible as soon as possible. To avoid consuming extra power, you should remove your listeners when your app isn't in use.

Instance methods
  • void onPathChange(DbxFileSystem fs, DbxPath registeredPath, Mode registeredMode)

    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.

    Parameters

    fs

    the DbxFileSystem on which the listener was registered.

    registeredPath

    the path on which this listener was registered. For changes to children or descendants, this path doesn't indicate which descendant has changed.

    registeredMode

    the type of event for which this listener was registered. This doesn't indicate which specific event triggered this call.

Enums
  • DbxFileSystem.PathListener.Mode

    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.

    Values

    PATH_ONLY

    Notify the listener only of changes to the file or folder at the given path.

    PATH_OR_CHILD

    For a folder, notify the listener of changes to the folder, or its direct child files and folders, non-recursively. For a file, this behaves as PATH_ONLY.

    PATH_OR_DESCENDANT

    For a folder, notify the listener of changes to the folder or its descendant files and folders, recursively. For a file, this behaves as PATH_ONLY.

DbxFileSystem.SyncStatusListener

A listener to be called when there's a change to the status of background synchronization, as reported by DbxFileSystem.getSyncStatus().

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

Instance methods
  • void onSyncStatusChange(DbxFileSystem fs)

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

    Parameters

    fs

    the DbxFileSystem on which the listener was registered.

DbxSyncStatus

The current status of background synchronization for a DbxFileSystem.

Instance fields
  • boolean isSyncActive

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

  • OperationStatus metadata

    Status of synchronizing info about files and folders. Metadata sync will only be considered in progress when it it is actively processing new changes, not when it is waiting for a periodic check for changes.

  • OperationStatus download

    Status of downloading file contents into the cache.

  • OperationStatus upload

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

Instance methods
  • boolean anyInProgress()

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

  • DbxException anyFailure()

    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.

DbxSyncStatus.OperationStatus

The current status of one type of background synchronization operation.

Instance fields
  • boolean inProgress

    Indicates that operations are in progress or queued for retry.

  • DbxException failure

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

DbxPath   implements Comparable

Represents a path in Dropbox, relative to the root which is visible to your app.

Dropbox paths always begin with a forward-slash, representing either the root of a user's Dropbox or the root of your app folder. Paths use forward-slashes to separate components. Mixed-case is allowed, but comparisons are case-insensitive.

Some special names, characters, or encodings aren't allowed in a Dropbox path, and will result in an InvalidPathException. Others are allowed, but may not sync properly to all platforms. For more details see this article.

Constructors
  • DbxPath(String path)

    Creates a new DbxPath.

    Parameters

    path

    the path, beginning with '/'

    Throws

    DbxPath.InvalidPathException

    if path isn't a legal Dropbox path

  • DbxPath(DbxPath parent, String childName)

    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"

    Parameters

    parent

    the parent path

    childName

    the name or sub-path for the new child

    Throws

    DbxPath.InvalidPathException

    if name isn't a legal Dropbox path

Instance methods
  • String log()

    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.

  • String getName()

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

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

  • DbxPath getParent()

    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"

  • DbxPath getChild(String name)

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

    Parameters

    name

    the unqualified name of the child.

    Throws

    DbxPath.InvalidPathException

    if the child name isn't legal for a Dropbox path.

  • boolean isDescendantOf(DbxPath path)

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

  • boolean isSameOrDescendantOf(DbxPath path)

    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.

Constants
  • DbxPath ROOT

    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.

Exceptions
  • DbxPath.InvalidPathException   extends IllegalArgumentException

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

DbxFileInfo   implements Comparable

Info about a Dropbox file system entry. Can either be a file or a folder.

DbxFileInfo provides a default comparison with path first, suitable for use in collections.

Instance fields
  • DbxPath path

    The path to the file or folder.

  • boolean isFolder

    Whether this is a folder.

  • long size

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

  • Date modifiedTime

    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.

  • boolean thumbExists

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

  • String iconName

    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.

DbxFile

Provides access to a file in Dropbox. Get an instance using DbxFileSystem.create() or DbxFileSystem.open().

A DbxFile represents a specific version of a file in Dropbox. You can use it to read or write the file's contents, or get info about the file. You can also check the file's sync status, and see when there's a newer version available.

Use addListener(), getNewerStatus(), and update() to update this file to a newer version when updates are available. If you don't, you can continue to read a stale cached version indefinitely, but writes will create a conflict.

Note that open files will cause the Sync API to perform more frequent updates in the background to ensure new file versions are available. To avoid consuming extra power, you shouldn't keep files open when your app isn't in use.

Instance methods
  • void close()

    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 IllegalStateException after a file is closed.

  • DbxPath getPath()

    Gets the path used to open or create this file.

  • boolean isThumb()

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

  • FileInputStream getReadStream()

    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.

    Throws

    DbxException

    on a failure downloading or reading the file.

    IOException

    on an I/O error in the local cache.

    DbxFile.StreamExclusionException

    if there's already a write stream open.

  • String readString()

    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.

    Throws

    DbxException

    on a failure downloading or reading the file.

    IOException

    on an I/O error in the local cache.

    DbxFile.StreamExclusionException

    if there's already a write stream open.

  • FileOutputStream getWriteStream()

    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.

    Throws

    DbxException

    on a failure writing the file.

    IOException

    on an I/O error in the local cache.

    DbxFile.StreamExclusionException

    if there's already a read or write stream open.

  • FileOutputStream getAppendStream()

    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.

    Throws

    DbxException

    on a failure appending to the file.

    IOException

    on an I/O error in the local cache.

    DbxFile.StreamExclusionException

    if there's already a read or write stream open.

  • void writeFromExistingFile(File file, boolean shouldSteal)

    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.

    Parameters

    file

    The file containing the new contents.

    shouldSteal

    whether the API should steal the file, moving it into the private cache rather than copying its contents.

    Throws

    DbxException

    on a failure writing the file.

    IOException

    on an I/O error in the local cache or the given file.

    DbxFile.StreamExclusionException

    if there's already a read or write stream open.

  • void writeString(String data)

    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.

    Parameters

    data

    The String to write into the file.

    Throws

    DbxException

    on a failure writing the file.

    IOException

    on an I/O error in the local cache.

    DbxFile.StreamExclusionException

    if there's already a read or write stream open.

  • void appendString(String data)

    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.

    Parameters

    data

    The String to append to the file.

    Throws

    DbxException

    on a failure appending to the file.

    IOException

    on an I/O error in the local cache.

    DbxFile.StreamExclusionException

    if there's already a read or write stream open.

  • DbxFileInfo getInfo()

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

    Throws

    DbxException

    on a failure getting file info.

  • boolean update()

    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.

    Throws

    DbxException

    if the update fails.

    DbxFile.StreamExclusionException

    if any read or write streams are open.

  • DbxFileStatus getSyncStatus()

    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.

    Throws

    DbxException

    if status can't be retrieved.

  • DbxFileStatus getNewerStatus()

    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.

    Throws

    DbxException.NotFound

    if this file was deleted after the version that was opened.

    DbxException

    if status can't be retrieved.

  • void addListener(Listener l)

    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.

  • void removeListener(Listener l)

    Removes a listener previously registered with addListener().

Exceptions
  • DbxFile.StreamExclusionException   extends IllegalStateException

    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.

DbxFile.Listener

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

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

Instance methods
  • void onFileChange(DbxFile file)

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

    Parameters

    file

    the file on which the listener was registered.

DbxFileStatus

Sync status for a DbxFile.

Instance fields
  • boolean isCached

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

  • boolean isLatest

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

  • PendingOperation pending

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

  • DbxException failure

    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.

  • long bytesTransferred

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

  • long bytesTotal

    The size of the file being uploaded or downloaded.

Enums
  • DbxFileStatus.PendingOperation

    Indicates the pending operation on a file.

    Values

    NONE

    The file isn't currently being uploaded or downloaded.

    UPLOAD

    The file is currently being uploaded.

    DOWNLOAD

    The file is currently being downloaded.