Datastore API for JavaScript documentation

Datastores are an easy way to keep an app's 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 reference details the full set of classes needed when working with datastores. You can also read the Datastore API tutorial for a detailed example of how to use them.

General information

The JavaScript Datastore API supports Internet Explorer 10, Safari 6 on Mac OS, and recent versions of Firefox and Chrome. Support for other environments may be added in the future.

Storage size limits

Datastores have limits on their maximum size to ensure good performance across platforms. You should keep these in mind as guidelines when modeling your datastores.

The overall size of a datastore is calculated by summing the sizes of all values of all fields, plus 1000 bytes for the datastore itself. Your app can store up to 5MB of data across all its datastores without counting against the user's storage quota. Any data beyond the first 5MB is factored into the user's Dropbox storage quota, and writing can be limited in these cases when a user is over quota.

Dropbox.Client

Represents a user accessing the application.

Instance Methods
  • constructor(options)

    Dropbox API client representing an user or an application.

    For an optimal user experience, applications should use a single client for all Dropbox interactions.

    Parameters

    options (Object)

    the application type and API key; alternatively, the result of a previous Dropbox.Client#credentials call can be passed in to create a Dropbox.Client instance for the same user

    Options parameter

    key (String)

    the Dropbox application's key (client identifier, in OAuth 2.0 vocabulary)

    secret (String)

    (optional) the Dropbox application's secret (client secret, in OAuth 2.0 vocabulary); browser-side applications should not use this option

    token (String)

    (optional) the user's OAuth 2.0 access token

    uid (String)

    (optional) the user's Dropbox UID

  • Dropbox.Client authDriver(driver)

    Plugs in the OAuth / application integration code.

    This replaces any driver set up by previous calls to Dropbox.Client#authDriver. On most supported platforms, an OAuth driver can be configured automatically.

    Parameters

    driver (Dropbox.AuthDriver)

    provides the integration between the application and the OAuth 2.0 flow used by the Dropbox API

    Returns

    this, for easy call chaining

  • String dropboxUid()

    The authenticated user's Dropbx user account ID.

    This user account ID is guaranteed to be consistent across API calls from the same application (not across applications, though).

    Returns

    a short ID that identifies the user account; null if no user is authenticated

  • Object credentials()

    Get the client's OAuth credentials.

    Returns

    a plain object whose properties can be passed to Dropbox.Client#setCredentials or to the Dropbox.Client constructor to reuse this client's login credentials

  • Dropbox.Client authenticate(options, callback)

    Authenticates the app's user to Dropbox's API server.

    In most cases, the process will involve sending the user to an authorization server on the Dropbox servers. If the user clicks "Allow", the application will be authorized. If the user clicks "Deny", the method will pass a Dropbox.AuthError to its callback, and the error's code will be Dropbox.AuthError.ACCESS_DENIED.

    Parameters

    options (Object)

    (optional) one or more of the options below

    callback (function(Dropbox.ApiError|Dropbox.AuthError, Dropbox.Client))

    (optional) called when the authentication completes; if successful, the second parameter is this client and the first parameter is null

    Options parameter

    interactive (Boolean)

    if false, the authentication process will stop and call the callback whenever it would have to wait for an authorization; true by default; this is useful for determining if the authDriver has cached credentials available

    Returns

    this, for easy call chaining

  • Boolean isAuthenticated()

    Checks if this client can perform API calls on behalf of a user.

    Returns

    true if this client has a user's OAuth 2 access token and can be used to make API calls; false otherwise

  • XMLHttpRequest signOut(options, callback)

    Invalidates and forgets the user's Dropbox OAuth 2 access token.

    This should be called when the user explicitly signs off from your application, to meet the users' expectation that after they sign out, their access tokens will not be persisted on the machine.

    Parameters

    options (Object)

    (optional) one or more of the options below

    callback (function(Dropbox.ApiError))

    called after the user's token is forgotten; if successful, the error parameter is null; this method will always succeed if mustInvalidate isn't true

    Options parameter

    mustInvalidate (Boolean)

    when true, the method will fail if the API call for invalidating the token fails; by default, the access token is forgotten and the method reports success even if the API call fails

    Returns

    the XHR object used for this API call

    Throws

    Error

    if this client doesn't have Dropbox credentials associated with it; call Dropbox.Client#isAuthenticated to find out if a client has credentials

  • void signOff()

    Alias for signOut.

  • XMLHttpRequest getAccountInfo(options, callback)

    Retrieves information about the logged in user.

    Parameters

    options (Object)

    (optional) the advanced settings below

    callback (function(Dropbox.ApiError, Dropbox.AccountInfo, Object))

    called with the result of the /account/info HTTP request; if the call succeeds, the second parameter is a Dropbox.AccountInfo instance, the third parameter is the parsed JSON data behind the Dropbox.AccountInfo instance, and the first parameter is null

    Options parameter

    httpCache (Boolean)

    if true, the API request will be set to allow HTTP caching to work; by default, requests are set up to avoid CORS preflights; setting this option can make sense when making the same request repeatedly

    Returns

    the XHR object used for this API call

  • void getUserInfo()

    Backwards-compatible name of getAccountInfo.

    @deprecated

  • XMLHttpRequest readFile(path, options, callback)

    Retrieves the contents of a file stored in Dropbox.

    Some options are silently ignored in Internet Explorer 9 and below, due to insufficient support in its proprietary XDomainRequest replacement for XHR. Currently, the options are: arrayBuffer, blob, length, start.

    Parameters

    path (String)

    the path of the file to be read, relative to the user's Dropbox or to the application's folder

    options (Object)

    (optional) one or more of the options below

    callback (function(Dropbox.ApiError, String, Dropbox.File.Stat, Dropbox.Http.RangeInfo))

    called with the result of the /files (GET) HTTP request; the second parameter is the contents of the file, the third parameter is a Dropbox.File.Stat instance describing the file, and the first parameter is null; if the start and/or length options are specified, the fourth parameter describes the subset of bytes read from the file

    Options parameter

    versionTag (String)

    the tag string for the desired version of the file contents; the most recent version is retrieved by default

    rev (String)

    alias for "versionTag" that matches the HTTP API

    arrayBuffer (Boolean)

    if true, the file's contents will be passed to the callback in an ArrayBuffer; this is the recommended method of reading non-UTF8 data such as images, as it is well supported across modern browsers; requires XHR Level 2 support, which is not available in IE <= 9

    blob (Boolean)

    if true, the file's contents will be passed to the callback in a Blob; this is a good method of reading non-UTF8 data, such as images; requires XHR Level 2 support, which is not available in IE <= 9

    buffer (Boolean)

    if true, the file's contents will be passed to the callback in a node.js Buffer; this only works on node.js

    binary (Boolean)

    if true, the file will be retrieved as a binary string; the default is an UTF-8 encoded string; this relies on hacks and should not be used if the environment supports XHR Level 2 API

    length (Number)

    the number of bytes to be retrieved from the file; if the start option is not present, the last "length" bytes will be read; by default, the entire file is read

    start (Number)

    the 0-based offset of the first byte to be retrieved; if the length option is not present, the bytes between "start" and the file's end will be read; by default, the entire file is read

    httpCache (Boolean)

    if true, the API request will be set to allow HTTP caching to work; by default, requests are set up to avoid CORS preflights; setting this option can make sense when making the same request repeatedly

    Returns

    the XHR object used for this API call

  • XMLHttpRequest writeFile(path, data, options, callback)

    Store a file into a user's Dropbox.

    Parameters

    path (String)

    the path of the file to be created, relative to the user's Dropbox or to the application's folder

    data (String, ArrayBuffer, ArrayBufferView, Blob, File, Buffer)

    the contents written to the file; if a File is passed, its name is ignored

    options (Object)

    (optional) one or more of the options below

    callback (function(Dropbox.ApiError, Dropbox.File.Stat))

    called with the result of the /files (POST) HTTP request; the second parameter is a Dropbox.File.Stat instance describing the newly created file, and the first parameter is null

    Options parameter

    lastVersionTag (String)

    the identifier string for the version of the file's contents that was last read by this program, used for conflict resolution; for best results, use the versionTag attribute value from the Dropbox.File.Stat instance provided by readFile

    parentRev (String)

    alias for "lastVersionTag" that matches the HTTP API

    noOverwrite (Boolean)

    if set, the write will not overwrite a file with the same name that already exists; instead the contents will be written to a similarly named file (e.g. "notes (1).txt" instead of "notes.txt")

    Returns

    the XHR object used for this API call

  • XMLHttpRequest resumableUploadStep(data, cursor, callback)

    Atomic step in a resumable file upload.

    Parameters

    data (String, ArrayBuffer, ArrayBufferView, Blob, File, Buffer)

    the file contents fragment to be uploaded; if a File is passed, its name is ignored

    cursor (Dropbox.Http.UploadCursor)

    (optional) the cursor that tracks the state of the resumable file upload; the cursor information will not be updated when the API call completes

    callback (function(Dropbox.ApiError, Dropbox.Http.UploadCursor))

    called with the result of the /chunked_upload HTTP request; the second parameter is a Dropbox.Http.UploadCursor instance describing the progress of the upload operation, and the first parameter is null if no error occurs

    Returns

    the XHR object used for this API call

  • XMLHttpRequest resumableUploadFinish(path, options, callback)

    Finishes a resumable file upload.

    Parameters

    path (String)

    the path of the file to be created, relative to the user's Dropbox or to the application's folder

    options (Object)

    (optional) one or more of the options below

    callback (function(Dropbox.ApiError, Dropbox.File.Stat))

    called with the result of the /files (POST) HTTP request; the second parameter is a Dropbox.File.Stat instance describing the newly created file, and the first parameter is null

    Options parameter

    lastVersionTag (String)

    the identifier string for the version of the file's contents that was last read by this program, used for conflict resolution; for best results, use the versionTag attribute value from the Dropbox.File.Stat instance provided by readFile

    parentRev (String)

    alias for "lastVersionTag" that matches the HTTP API

    noOverwrite (Boolean)

    if set, the write will not overwrite a file with the same name that already exists; instead the contents will be written to a similarly named file (e.g. "notes (1).txt" instead of "notes.txt")

    Returns

    the XHR object used for this API call

  • XMLHttpRequest stat(path, options, callback)

    Reads the metadata of a file or folder in a user's Dropbox.

    Parameters

    path (String)

    the path to the file or folder whose metadata will be read, relative to the user's Dropbox or to the application's folder

    options (Object)

    (optional) one or more of the options below

    callback (function(Dropbox.ApiError, Dropbox.File.Stat, Array<Dropbox.File.Stat>))

    called with the result of the /metadata HTTP request; if the call succeeds, the second parameter is a Dropbox.File.Stat instance describing the file / folder, and the first parameter is null; if the readDir option is true and the call succeeds, the third parameter is an array of Dropbox.File.Stat instances describing the folder's entries

    Options parameter

    version (Number)

    if set, the call will return the metadata for the given revision of the file / folder; the latest version is used by default

    removed (Boolean)

    if set to true, the results will include files and folders that were deleted from the user's Dropbox

    deleted (Boolean)

    alias for "removed" that matches the HTTP API; using this alias is not recommended, because it may cause confusion with JavaScript's delete operation

    readDir (Boolean, Number)

    only meaningful when stat-ing folders; if this is set, the API call will also retrieve the folder's contents, which is passed into the callback's third parameter; if this is a number, it specifies the maximum number of files and folders that should be returned; the default limit is 10,000 items; if the limit is exceeded, the call will fail with an error

    versionTag (String)

    the tag string for the desired version of the file or folder metadata; the most recent version is retrieved by default

    rev (String)

    alias for "versionTag" that matches the HTTP API

    contentHash (String)

    used for saving bandwidth when getting a folder's contents; if this value is specified and it matches the folder's contents, the call will fail with a Dropbox.ApiError.NO_CONTENT error status; a folder's version identifier can be obtained from the contentHash property of the Stat instance describing the folder

    hash (String)

    alias for "contentHash" that matches the HTTP API

    httpCache (Boolean)

    if true, the API request will be set to allow HTTP caching to work; by default, requests are set up to avoid CORS preflights; setting this option can make sense when making the same request repeatedly

    Returns

    the XHR object used for this API call

  • XMLHttpRequest readdir(path, options, callback)

    Lists the files and folders inside a folder in a user's Dropbox.

    Parameters

    path (String)

    the path to the folder whose contents will be retrieved, relative to the user's Dropbox or to the application's folder

    options (Object)

    (optional) one or more of the options below

    callback (function(Dropbox.ApiError, Array<String>, Dropbox.File.Stat, Array<Dropbox.File.Stat>))

    called with the result of the /metadata HTTP request; if the call succeeds, the second parameter is an array containing the names of the files and folders in the given folder, the third parameter is a Dropbox.File.Stat instance describing the folder, the fourth parameter is an array of Dropbox.File.Stat instances describing the folder's entries, and the first parameter is null

    Options parameter

    removed (Boolean)

    if set to true, the results will include files and folders that were deleted from the user's Dropbox

    deleted (Boolean)

    alias for "removed" that matches the HTTP API; using this alias is not recommended, because it may cause confusion with JavaScript's delete operation

    limit (Boolean, Number)

    the maximum number of files and folders that should be returned; the default limit is 10,000 items; if the limit is exceeded, the call will fail with an error

    versionTag (String)

    the tag string for the desired version of the file or folder metadata; the most recent version is retrieved by default

    contentHash (String)

    used for saving bandwidth when getting a folder's contents; if this value is specified and it matches the folder's contents, the call will fail with a Dropbox.ApiError.NO_CONTENT error status; a folder's version identifier can be obtained from the contentHash property of the Stat instance describing the folder

    httpCache (Boolean)

    if true, the API request will be set to allow HTTP caching to work; by default, requests are set up to avoid CORS preflights; setting this option can make sense when making the same request repeatedly

    Returns

    the XHR object used for this API call

  • void metadata()

    Alias for "stat" that matches the HTTP API.

  • XMLHttpRequest makeUrl(path, options, callback)

    Creates a publicly readable URL to a file or folder in the user's Dropbox.

    Parameters

    path (String)

    the path to the file or folder that will be linked to; the path is relative to the user's Dropbox or to the application's folder

    options (Object)

    (optional) one or more of the options below

    callback (function(Dropbox.ApiError, Dropbox.File.ShareUrl))

    called with the result of the /shares or /media HTTP request; if the call succeeds, the second parameter is a Dropbox.File.ShareUrl instance, and the first parameter is null

    Options parameter

    download (Boolean)

    if set, the URL will be a direct download URL, instead of the usual Dropbox preview URLs; direct download URLs are short-lived (currently 4 hours), whereas regular URLs virtually have no expiration date (currently set to 2030); no direct download URLs can be generated for directories

    downloadHack (Boolean)

    if set, a long-living download URL will be generated by asking for a preview URL and using the officially documented hack at https://www.dropbox.com/help/201 to turn the preview URL into a download URL

    long (Boolean)

    if set, the URL will not be shortened using Dropbox's shortner; the download and downloadHack options imply long

    longUrl (Boolean)

    synonym for long; makes life easy for RhinoJS users

    Returns

    the XHR object used for this API call

  • XMLHttpRequest history(path, options, callback)

    Retrieves the revision history of a file in a user's Dropbox.

    Parameters

    path (String)

    the path to the file whose revision history will be retrieved, relative to the user's Dropbox or to the application's folder

    options (Object)

    (optional) one or more of the options below

    callback (function(Dropbox.ApiError, Array<Dropbox.File.Stat>))

    called with the result of the /revisions HTTP request; if the call succeeds, the second parameter is an array with one Dropbox.File.Stat instance per file version, and the first parameter is null

    Options parameter

    limit (Number)

    if specified, the call will return at most this many versions

    httpCache (Boolean)

    if true, the API request will be set to allow HTTP caching to work; by default, requests are set up to avoid CORS preflights; setting this option can make sense when making the same request repeatedly

    Returns

    the XHR object used for this API call

  • void revisions()

    Alias for "history" that matches the HTTP API.

  • String thumbnailUrl(path, options)

    Computes a URL that generates a thumbnail for a file in the user's Dropbox.

    Parameters

    path (String)

    the path to the file whose thumbnail image URL will be computed, relative to the user's Dropbox or to the application's folder

    options (Object)

    (optional) one or more of the options below

    Options parameter

    png (Boolean)

    if true, the thumbnail's image will be a PNG file; the default thumbnail format is JPEG

    format (String)

    value that gets passed directly to the API; this is intended for newly added formats that the API may not support; use options such as "png" when applicable

    size (String)

    specifies the image's dimensions; this gets passed directly to the API; currently, the following values are supported: 'small' (32x32), 'medium' (64x64), 'large' (128x128), 's' (64x64), 'm' (128x128), 'l' (640x480), 'xl' (1024x768); the default value is "small"

    Returns

    a URL to an image that can be used as the thumbnail for the given file

  • XMLHttpRequest readThumbnail(path, options, callback)

    Retrieves the image data of a thumbnail for a file in the user's Dropbox.

    This method is intended to be used with low-level painting APIs. Whenever possible, it is easier to place the result of thumbnailUrl in a DOM element, and rely on the browser to fetch the file.

    Parameters

    path (String)

    the path to the file whose thumbnail image URL will be computed, relative to the user's Dropbox or to the application's folder

    options (Object)

    (optional) one or more of the options below

    callback (function(?Dropbox.ApiError, String|Blob, Dropbox.File.Stat))

    called with the result of the /thumbnails HTTP request; if the call succeeds, the second parameter is the image data as a String or Blob, the third parameter is a Dropbox.File.Stat instance describing the thumbnailed file, and the first argument is null

    Options parameter

    png (Boolean)

    if true, the thumbnail's image will be a PNG file; the default thumbnail format is JPEG

    format (String)

    value that gets passed directly to the API; this is intended for newly added formats that the API may not support; use options such as "png" when applicable

    size (String)

    specifies the image's dimensions; this gets passed directly to the API; currently, the following values are supported: 'small' (32x32), 'medium' (64x64), 'large' (128x128), 's' (64x64), 'm' (128x128), 'l' (640x480), 'xl' (1024x768); the default value is "small"

    arrayBuffer (Boolean)

    if true, the file's contents will be passed to the callback in an ArrayBuffer; this is the recommended method of reading thumbnails, as it is well supported across modern browsers; requires XHR Level 2 support, which is not available in IE <= 9

    blob (Boolean)

    if true, the file's contents will be passed to the callback in a Blob; requires XHR Level 2 support, which is not available in IE <= 9

    buffer (Boolean)

    if true, the file's contents will be passed to the callback in a node.js Buffer; this only works on node.js

    Returns

    the XHR object used for this API call

  • Dropbox.Util.Xhr thumbnailXhr()

    Sets up an XHR for reading a thumbnail for a file in the user's Dropbox.

    Returns

    an XMLHttpRequest wrapper configured for fetching the thumbnail

  • XMLHttpRequest revertFile(path, versionTag, callback)

    Reverts a file's contents to a previous version.

    This is an atomic, bandwidth-optimized equivalent of reading the file contents at the given file version (readFile), and then using it to overwrite the file (writeFile).

    Parameters

    path (String)

    the path to the file whose contents will be reverted to a previous version, relative to the user's Dropbox or to the application's folder

    versionTag (String)

    the tag of the version that the file will be reverted to; maps to the "rev" parameter in the HTTP API

    callback (function(Dropbox.ApiError, Dropbox.File.Stat))

    called with the result of the /restore HTTP request; if the call succeeds, the second parameter is a Dropbox.File.Stat instance describing the file after the revert operation, and the first parameter is null

    Returns

    the XHR object used for this API call

  • void restore()

    Alias for "revertFile" that matches the HTTP API.

  • XMLHttpRequest findByName(path, namePattern, options, callback)

    Finds files / folders whose name match a pattern, in the user's Dropbox.

    Parameters

    path (String)

    the path that will serve as the root of the search, relative to the user's Dropbox or to the application's folder

    namePattern (String)

    the string that file / folder names must contain in order to match the search criteria

    options (Object)

    (optional) one or more of the options below

    callback (function(Dropbox.ApiError, Array<Dropbox.File.Stat>))

    called with the result of the /search HTTP request; if the call succeeds, the second parameter is an array with one Dropbox.File.Stat instance per search result, and the first parameter is null

    Options parameter

    limit (Number)

    if specified, the call will return at most this many versions

    removed (Boolean)

    if set to true, the results will include files and folders that were deleted from the user's Dropbox; the default limit is the maximum value of 1,000

    deleted (Boolean)

    alias for "removed" that matches the HTTP API; using this alias is not recommended, because it may cause confusion with JavaScript's delete operation

    httpCache (Boolean)

    if true, the API request will be set to allow HTTP caching to work; by default, requests are set up to avoid CORS preflights; setting this option can make sense when making the same request repeatedly

    Returns

    the XHR object used for this API call

  • void search()

    Alias for "findByName" that matches the HTTP API.

  • XMLHttpRequest makeCopyReference(path, callback)

    Creates a reference used to copy a file to another user's Dropbox.

    Parameters

    path (String)

    the path to the file whose contents will be referenced, relative to the uesr's Dropbox or to the application's folder

    callback (function(Dropbox.ApiError, Dropbox.File.CopyReference))

    called with the result of the /copy_ref HTTP request; if the call succeeds, the second parameter is a Dropbox.File.CopyReference instance, and the first parameter is null

    Returns

    the XHR object used for this API call

  • void copyRef()

    Alias for "makeCopyReference" that matches the HTTP API.

  • XMLHttpRequest pullChanges(cursor, callback)

    Fetches a list of changes in the user's Dropbox since the last call.

    This method is intended to make full sync implementations easier and more performant. Each call returns a cursor that can be used in a future call to obtain all the changes that happened in the user's Dropbox (or application directory) between the two calls.

    Parameters

    cursor (Dropbox.Http.PulledChanges, String)

    the result of a previous Dropbox.Client#pullChanges call, or a string containing a tag representing the Dropbox state that is used as the baseline for the change list; this should either be the Dropbox.Http.PulledChanges obtained from a previous call to Dropbox.Client#pullChanges, the return value of Dropbox.Http.PulledChanges#cursor, or null / omitted on the first call to Dropbox.Client#pullChanges

    callback (function(Dropbox.ApiError, Dropbox.Http.PulledChanges))

    called with the result of the /delta HTTP request; if the call succeeds, the second parameter is a Dropbox.Http.PulledChanges describing the changes to the user's Dropbox since the pullChanges call that produced the given cursor, and the first parameter is null

    Returns

    the XHR object used for this API call

  • void delta()

    Alias for "pullChanges" that matches the HTTP API.

  • XMLHttpRequest mkdir(path, callback)

    Creates a folder in a user's Dropbox.

    Parameters

    path (String)

    the path of the folder that will be created, relative to the user's Dropbox or to the application's folder

    callback (function(Dropbox.ApiError, Dropbox.File.Stat))

    called with the result of the /fileops/create_folder HTTP request; if the call succeeds, the second parameter is a Dropbox.File.Stat instance describing the newly created folder, and the first parameter is null

    Returns

    the XHR object used for this API call

  • XMLHttpRequest remove(path, callback)

    Removes a file or directory from a user's Dropbox.

    Parameters

    path (String)

    the path of the file to be read, relative to the user's Dropbox or to the application's folder

    callback (function(Dropbox.ApiError, Dropbox.File.Stat))

    called with the result of the /fileops/delete HTTP request; if the call succeeds, the second parameter is a Dropbox.File.Stat instance describing the removed file or folder, and the first parameter is null

    Returns

    the XHR object used for this API call

  • node.js-friendly alias for "remove".

  • void delete()

    Alias for "remove" that matches the HTTP API.

  • XMLHttpRequest copy(from, toPath, callback)

    Copies a file or folder in the user's Dropbox.

    This method's "from" parameter can be either a path or a copy reference obtained by a previous call to Dropbox.Client#makeCopyReference.

    The method treats String arguments as paths and CopyReference instances as copy references. The CopyReference constructor can be used to get instances out of copy reference strings, or out of their JSON representations.

    Parameters

    from (String, Dropbox.File.CopyReference)

    the path of the file or folder that will be copied, or a Dropbox.File.CopyReference instance obtained by calling Dropbox.Client#makeCopyReference or Dropbox.File.CopyReference.parse; if this is a path, it is relative to the user's Dropbox or to the application's folder

    toPath (String)

    the path that the file or folder will have after the method call; the path is relative to the user's Dropbox or to the application folder

    callback (function(Dropbox.ApiError, Dropbox.File.Stat))

    called with the result of the /fileops/copy HTTP request; if the call succeeds, the second parameter is a Dropbox.File.Stat instance describing the file or folder created by the copy operation, and the first parameter is null

    Returns

    the XHR object used for this API call

  • XMLHttpRequest move(fromPath, toPath, callback)

    Moves a file or folder to a different location in a user's Dropbox.

    Parameters

    fromPath (String)

    the path of the file or folder that will be moved, relative to the user's Dropbox or to the application's folder

    toPath (String)

    the path that the file or folder will have after the method call; the path is relative to the user's Dropbox or to the application's folder

    callback (function(Dropbox.ApiError, Dropbox.File.Stat))

    called with the result of the /fileops/move HTTP request; if the call succeeds, the second parameter is a Dropbox.File.Stat instance describing the moved file or folder at its new location, and the first parameter is null

    Returns

    the XHR object used for this API call

  • XMLHttpRequest appInfo(appKey, callback)

    Fetches information about a Dropbox Platform application.

    This method retrieves the same information that is displayed on the OAuth authorize page, in a machine-friendly format. It is intended to be used in IDEs and debugging.

    Parameters

    appKey (String)

    (optional) the App key of the application whose information will be retrieved; if not given, the App key passed to this Client will be used instead

    callback (function(Dropbox.ApiError, Dropbox.Http.AppInfo))

    called with the result of the /app/info HTTP request; if the call succeeds, the second parameter is a Dropbox.Http.AppInfo instance describing the application whose key was given

    Returns

    the XHR object used for this API call

  • XMLHttpRequest isAppDeveloper(userId, appKey, callback)

    Checks if a user is a developer for a Dropbox Platform application.

    This is intended to be used by IDEs to validate Dropbox App keys that their users input. This method can be used to make sure that users go to /developers and generate their own App keys, instead of copy-pasting keys from code samples. The metod can also be used to enable debugging / logging in applications.

    Parameters

    userId (String, Dropbox.AccountInfo)

    the user whose developer status will be checked

    appKey (String, Dropbox.Http.AppInfo)

    (optional) the API key of the application whose developer list will be checked

    callback (function(Dropbox.ApiError, Boolean))

    called with the result of the /app/check_developer HTTP request; if the call succeeds, the second argument will be true if the user with the given ID is a developer of the given application, and false otherwise

    Returns

    the XHR object used for this API call

  • XMLHttpRequest hasOauthRedirectUri(redirectUri, appKey, callback)

    Checks if a given URI is an OAuth redirect URI for a Dropbox application.

    This is intended to be used in IDEs and debugging. The same information can be obtained by checking the HTTP status in an /oauth2/authorize HTTP GET with request_uri set to the desired URI.

    Parameters

    redirectUri (String)

    the URI that will be checked against the app's list of allowed OAuth redirect URIs

    appKey (String, Dropbox.Http.AppInfo)

    (optional) the API key of the application whose list of allowed OAuth redirect URIs will be checked

    callback (function(Dropbox.ApiError, Boolean))

    called with the result of the /app/check_redirect_uri HTTP request; if the call succeeds, the second argument will be true if the given URI is on the application's list of allowed OAuth redirect URIs, and false otherwise

    Returns

    the XHR object used for this API call

  • Dropbox.Client reset()

    Forgets all the user's information.

    Dropbox.Client#signOut should be called when the user expresses an intent to sign off the application. This method resets user-related fields from the Client instance, but does not work with the OAuth driver to do a full sign out. For example, the user's OAuth 2 access token might remain in localStorage.

    Returns

    this, for easy call chaining

  • Dropbox.Client setCredentials(credentials)

    Change the client's OAuth credentials.

    Parameters

    credentials (Object)

    the result of a prior call to Dropbox.Client#credentials

    Returns

    this, for easy call chaining

  • String appHash()

    Unique identifier for the Dropbox application behind this client.

    This method is intended to be used by OAuth drivers.

    Returns

    a string that uniquely identifies the Dropbox application of this client

  • Dropbox.Datastore.DatastoreManager getDatastoreManager()

    Returns a DatastoreManager, which lets you access the user's datastores in Dropbox.

    Returns

    a datastore manager

Properties
  • onXhr (Dropbox.Util.EventSource<Dropbox.Util.Xhr>)

    fires cancelable events every time when a network request to the Dropbox API server is about to be sent; if the event is canceled by returning a falsey value from a listener, the network request is silently discarded; whenever possible, listeners should restrict themselves to using the xhr property of the Dropbox.Util.Xhr instance passed to them; everything else in the Dropbox.Util.Xhr API is in flux

  • onError (Dropbox.Util.EventSource<Dropbox.ApiError>)

    fires non-cancelable events every time when a network request to the Dropbox API server results in an error

  • onAuthStepChange (Dropbox.Util.EventSource<Dropbox.Client>)

    fires non-cancelable events every time this client's authStep property changes; this can be used to update UI state

  • authStep (Number)

    This property is intended to be used by OAuth drivers. Dropbox.Client#isAuthenticated is a better method of checking whether a client can be used to perform API calls.

    the client's progress in the authentication process

Constants
  • ERROR

    authStep value for a client that experienced an authentication error.

  • RESET

    authStep value for a properly initialized client with no user credentials.

  • PARAM_SET

    authStep value for a client that has an /authorize state parameter value.

    This state is entered when the state parameter is set directly by Dropbox.Client#authenticate. Auth drivers that need to save the OAuth state parameter value during Dropbox.AuthDriver#doAuthorize should do so when the client is in this state.

  • PARAM_LOADED

    authStep value for a client that has an /authorize state parameter value.

    This state is entered when the state parameter is loaded from an external data source, by Dropbox.Client#setCredentials or Dropbox.Client#constructor. Auth drivers that need to save the OAuth state during Dropbox.AuthDriver#doAuthorize should check for authorization completion in this state.

  • AUTHORIZED

    authStep value for a client that has an authorization code.

  • DONE

    authStep value for a client that has an access token.

  • SIGNED_OUT

    authStep value for a client that voluntarily invalidated its access token.

Dropbox.AuthDriver

The interface implemented by dropbox.js OAuth drivers.

This class exists solely for the purpose of documenting the OAuth driver interface. It should not be instantiated or inherited from.

Instance Methods
  • String authType()

    The authorization grant type used by this driver.

    Currently, server application drivers should return "code" to use Authorization Code Grant (RFC 6749 Section 4.1) and drivers that run in browsers or mobile clients should return "token" to use Implicit Grant (RFC 6749 Section 4.2).

    Returns

    one of the OAuth 2.0 authorization grant types implemented by dropbox.js

  • String url()

    The redirect URL that should be supplied to the OAuth 2 /authorize call.

    The driver must be able to intercept redirects to the returned URL and extract the OAuth 2.0 authorization code or access token from the URL.

    OAuth 2.0 redirect URLs must be configured on the application's page in the Dropbox App console.

    Returns

    an URL on the application's list of OAuth 2 redirect URLs

  • void doAuthorize(authUrl, stateParam, client, callback)

    Redirects users to /authorize and waits for them to get redirected back.

    This method is called when the OAuth 2 process reaches the Dropbox.Client.PARAM_SET step, meaning that the user must be shown an /authorize page on the Dropbox servers, and the application must intercept a redirect from that page. The redirect URL contains an OAuth 2 authorization code or access token.

    Parameters

    authUrl (String)

    the URL that users should be sent to in order to authorize the application's token; this points to a webpage on Dropbox's server

    stateParam (String)

    the nonce sent as the OAuth 2 state parameter; the Dropbox Web server will echo this nonce in the 'state' query parameter when redirecting users to the URL returned by Dropbox.AuthDriver#url; the driver should silently ignore any request that does not contain the correct 'state' parameter value

    client (Dropbox.Client)

    the client driving the OAuth 2 process

    callback (function(Object<String, String>))

    called when users have completed the authorization flow; the driver should call this when Dropbox redirects users to the URL returned by the url() method, and the "state" query parameter matches the value passed in "state"; the callback should receive the query parameters in the redirect URL

  • void getStateParam(client, callback)

    (optional) Called to obtain the state param used in the OAuth 2 process.

    If a driver does not define this method, Dropbox.Util.Oauth.randomAuthStateParam is used to generate a random state param value.

    Server-side drivers should provide custom implementations that use a derivative of the CSRF token associated with the user's session cookie. This prevents CSRF attacks that would trick the application's server into using an attacker's OAuth 2 access token to store anoher user's data in the attacker's Dropbox.

    Client-side drivers only need to supply a custom implementation if the state parameter must be persisted across page reloads, e.g. if the authorization is done via redirects.

    Parameters

    client (Dropbox.Client)

    the client driving the OAuth 2 process

    callback (function(String))

    called with the state parameter value that should be used in the OAuth 2 authorization process

  • void resumeAuthorize(stateParam, client, callback)

    (optional) Called to process the /authorize redirect.

    This method is called when the OAuth 2 process reaches the Dropbox.Client.PARAM_LOADED step, meaning that an OAuth 2 state parameter value was loaded when the Dropbox.Client object was constructed, or during a Dropbox.Client#setCredentials call. This means that Dropbox.AuthDriver#doAuthorize was called earlier, saved that state parameter, and did not complete the OAuth 2 process. This happens when the OAuth 2 process requires page reloads, e.g. if the authorization is done via redirects.

    Parameters

    stateParam (String)

    the nonce sent as the OAuth 2 state parameter; the Dropbox Web server will echo this nonce in the 'state' query parameter when redirecting users to the URL returned by Dropbox.AuthDriver#url; the driver should silently ignore any request that does not contain the correct 'state' parameter value

    client (Dropbox.Client)

    the client driving the OAuth 2 process

    callback (function(Object<String, String>))

    called when the user has completed the authorization flow; the driver should call this when Dropbox redirects the user to the URL returned by Dropbox.AuthDriver#url, and the "state" query parameter matches the value passed in "state"; the callback should receive the query parameters in the redirect URL

  • void onAuthStateChange(client, callback)

    If defined, called when there is some progress in the OAuth 2 process.

    The OAuth process goes through the following states:

    • Dropbox.Client.RESET - the client has no OAuth credentials, and is about to ask for an authorization code or access token
    • Dropbox.Client.AUTHORIZED - the client has an authorization code, and is about to exchange it for an access token
    • Dropbox.Client.DONE - the client has an OAuth 2 access token that can be used for all API calls; the OAuth 2 process is complete, and the callback passed to authorize is about to be called
    • Dropbox.Client.SIGNED_OUT - the client's Dropbox.Client#signOut() was called, and the client's OAuth 2 access token was invalidated
    • Dropbox.Client.ERROR - the client encounered an error during the OAuth 2 process; the callback passed to authorize is about to be called with the error information
    Parameters

    client (Dropbox.Client)

    the client performing the OAuth process

    callback (function())

    called when onAuthStateChange acknowledges the state change

Dropbox.AccountInfo

Information about a Dropbox user account.

Class Methods
  • Dropbox.AccountInfo parse(accountInfo)

    Creates an AccountInfo instance from a raw API response.

    Parameters

    accountInfo (Object)

    the result of parsing a JSON API response that describes a user account

    Returns

    an AccountInfo instance wrapping the given API response

Instance Methods
  • Object json()

    JSON representation of this user's information.

    Returns

    an object that can be serialized using JSON; the object can be passed to Dropbox.AccountInfo.parse to obtain an AccountInfo instance with the same information

Properties
  • name (String)

    the user's name, in a form that is fit for display

  • email (String)

    the user's email, or null if unavailable

  • countryCode (String)

    two-letter country code, or null if unavailable

  • uid (String)

    unique ID for the user; this ID matches the unique ID returned by the authentication process

  • referralUrl (String)

    the user's referral link; the user might benefit if others use the link to sign up for Dropbox

  • publicAppUrl (String)

    Specific to applications whose access type is "public app folder".

    prefix for URLs to the application's files

  • quota (Number)

    the maximum amount of bytes that the user can store

  • usedQuota (Number)

    the number of bytes taken up by the user's data

  • privateBytes (Number)

    the number of bytes taken up by the user's data that is not shared with other users

  • sharedBytes (Number)

    the number of bytes taken up by the user's data that is shared with other users

Dropbox.ApiError

Information about a failed call to the Dropbox API.

Instance Methods
  • constructor(method, url, xhr)

    Wraps a failed XHR call to the Dropbox API.

    Parameters

    method (String)

    the HTTP verb of the API request (e.g., 'GET')

    url (String)

    the URL of the API request

    xhr (XMLHttpRequest)

    the XMLHttpRequest instance of the failed request

Properties
  • status (Number)

    This number should be compared against the constants defined on Dropbox.ApiError.

    the HTTP error code (e.g., 403)

  • method (String)

    the HTTP method of the failed request (e.g., 'GET')

  • url (String)

    the URL of the failed request

  • responseText (String)

    the body of the HTTP error response; can be null if the error was caused by a network failure or by a security issue

  • response (Object)

    the result of parsing the JSON in the HTTP error response; can be null if the API server didn't return JSON, or if the HTTP response body is unavailable

Constants
  • NETWORK_ERROR

    Status value indicating an error at the XMLHttpRequest layer.

    This indicates a network transmission error on modern browsers. Internet Explorer might cause this code to be reported on some API server errors.

  • NO_CONTENT

    Status value indicating that the API call will not receive a response.

    This happens when the contentHash parameter passed to a Dropbox.Client#readdir or Dropbox.Client#stat matches the most recent content, so the API call response is omitted, to save bandwidth.

  • INVALID_PARAM

    Status value indicating an invalid input parameter.

    The error property on Dropbox.ApiError.response should indicate which input parameter is invalid and why.

  • INVALID_TOKEN

    Status value indicating an expired or invalid OAuth token.

    The OAuth token used for the request will never become valid again, so the user should be re-authenticated.

    The authStep property of the Dropbox.Client used to make the API call will automatically transition from Dropbox.Client.DONE to Dropbox.Client.ERROR when this error is received.

  • OAUTH_ERROR

    Status value indicating a malformed OAuth request.

    This indicates a bug in dropbox.js and should never occur under normal circumstances.

  • NOT_FOUND

    Status value indicating that a file or path was not found in Dropbox.

    This happens when trying to read from a non-existing file, readdir a non-existing directory, write a file into a non-existing directory, etc.

  • INVALID_METHOD

    Status value indicating that the HTTP method is not supported for the call.

    This indicates a bug in dropbox.js and should never occur under normal circumstances.

  • NOT_ACCEPTABLE

    Status value indicating that the API call disobeys some constraints.

    This happens when a Dropbox.Client#readdir or Dropbox.Client#stat call would return more than a maximum amount of directory entries.

  • CONFLICT

    Status value indicating that the server received a conflicting update.

    This is used by some backend methods to indicate that the client needs to download server-side changes and perform conflict resolution. Under normal usage, errors with this code should never surface to the code using dropbox.js.

  • RATE_LIMITED

    Status value indicating that the application is making too many requests.

    Rate-limiting can happen on a per-application or per-user basis.

  • SERVER_ERROR

    Status value indicating a server issue.

    The request should be retried after some time.

  • OVER_QUOTA

    Status value indicating that the user's Dropbox is over its storage quota.

    The application UI should communicate to the user that their data cannot be stored in Dropbox.

Dropbox.AuthError

Information about an OAuth 2.0 error returned from the Dropbox API.

Instance Methods
  • constructor(queryString)

    Wraps an XHR error.

    Parameters

    queryString (Object)

    a parsed response from the /authorize or /token OAuth 2.0 endpoints

    Throws

    Error

    if queryString does not represent an OAuth 2.0 error response

Properties
  • code (String)

    one of the Dropbox.AuthError constants

  • description (String)

    developer-friendly explanation of the error; can be null if the API server does not provide an explanation

  • uri (String)

    URL to a developer-friendly page; can be null if the API server does not provide an URL

Constants
  • ACCESS_DENIED

    Error code indicating the user did not authorize the application.

    This error is reported when a user clicks the Deny button on the OAuth authorization page on the Dropbox site.

  • INVALID_REQUEST

    Error code indicating a malformed OAuth request.

    This indicates a bug in dropbx.js and should never occur under normal circumstanes.

  • UNAUTHORIZED_CLIENT

    Error code indicating that the client is not allowed to use a OAuth method.

    This is most likely due to an error in the application's configuration.

  • INVALID_GRANT

    Error code indicating an invalid or already-used authorization code.

    This indicates a bug in dropbox.js and should never occur under normal circumstances. A faulty OAuth driver might cause this error.

  • INVALID_SCOPE

    Error code indicating an invalid scope parameter.

    This version of dropbox.js does not use OAuth 2.0 scopes, so this error indicates a bug in the library, or that the library must be updated.

  • UNSUPPORTED_GRANT_TYPE

    Error code indicating an un-implemented or invalid authorization method.

    This indicates a bug in dropbox.js and should never occur under normal circumstances.

  • UNSUPPORTED_RESPONSE_TYPE

    Error code indicating an un-implemented or invalid authorization method.

    This indicates a bug in dropbox.js and should never occur under normal circumstances.

  • SERVER_ERROR

    The OAuth 2.0 equivalent of a HTTP 500 error code.

    This indicates a bug in the Dropbox API server. The application and/or dropbox.js will have to be modified to work around the bug.

  • TEMPORARILY_UNAVAILABLE

    The OAuth 2.0 equivalent of a HTTP 503 error code.

    This occurrs when the application is rate-limited.

Dropbox.Datastore

Stores and synchronizes structured data.

Datastores store Dropbox.Datastore.Records, which are key-value pairs. Records are grouped in Dropbox.Datastore.Tables, for efficient retrieval.

Synchronization happens at the datastore scope, so only records that are in the same datastore can be changed together in an atomic fashion.

Datastores are obtained from a Dropbox.Datastore.DatastoreManager.

Class Methods
  • Number int64(x)

    A Number instance that will be written to the datastore as a 64-bit integer.

    Since JavaScript does not support 64-bit integers natively, an int64 is a boxed JavaScript number that approximates the 64-bit integer as closely as possible, with an added property dbxInt64 that holds the precise signed integer value in decimal representation as a string. For integers that are at most 2^53 in magnitude, the approximation is exact.

    Parameters

    x (String, Number)

    an integer, a string holding a signed 64-bit integer in decimal representation, or the return value of a Dropbox.Datastore.int64 call

    Returns

    an int64 value

    Throws

    Error

    if the argument cannot be interpreted as an int64

  • Boolean isInt64()

    Returns true if the argument is an int64 value as returned by Dropbox.Datastore.int64.

  • Boolean isValidId(datastoreId)

    Checks that a string meets the constraints for datastore IDs.

    Valid IDs come in two forms. The first form has 1-32 characters from the set a-z, 0-9, dot (.), minus sign (-), underscore (_), and may not begin or end with dot.

    The second form begins with a dot (.), followed by 1-100 characters from the set a-z, A-Z, 0-9, minus sign (-), underscore (_).

    Parameters

    datastoreId (String)

    the string to be checked

    Returns

    true if datastoreId can be used as a datastore ID, false otherwise

Instance Methods
  • Dropbox.Datastore.Table getTable(tableId)

    Creates a Table instance for a given table ID.

    Parameters

    tableId (String)

    the table's ID

    Returns

    a Table object that can be used to insert or access records in the table with the given ID. If this is a new table ID, the table will not be visible in Dropbox.Datastore#listTableIds until a record is inserted.

    Throws

    Error

    if tableId is not a valid table ID

  • Array<String> listTableIds()

    The IDs of all the tables in this datastore.

    Tables that contain no records are not listed.

    Returns

    the IDs of the tables in this datastore

  • void close()

    Closes the datastore.

    After a call to Dropbox.Datastore#close, you can no longer call methods that read or modify tables or records of the datastore.

    The datastore will stop syncing once all outgoing changes have been received by the server.

  • String getId()

    Returns this datastore's ID.

  • Object getSyncStatus()

    Returns an object representing the sync status of the datastore.

    The returned object has a single property:

    • uploading: true if there are changes to the datastore that have not been synced to the server yet. This state should be transient unless, for example, the application is temporarily offline. false otherwise.
    Returns

    a plain object with an "uploading" property as described above

Properties

Dropbox.Datastore.DatastoreManager

Lets you open, create, delete, and list datastores.

Multiple instances of your app (running in different browser windows / tabs) can open the same datastore at the same time, and a single instance of your app can open multiple datastores at the same time. But a single instance of your app can only have one Dropbox.Datastore instance for a each datastore at any time -- opening the same datastore twice is not allowed (unless you close it in between).

Instance Methods
  • void close()

    Shuts down the DatastoreManager. All Dropbox.Datastore instances obtained through this DatastoreManager become invalid.

  • void openDefaultDatastore(callback)

    Asynchronously opens your app's default datastore for the current user, then calls callback with the corresponding Datastore object (or an error).

    Parameters

    callback (function(Dropbox.ApiError, Dropbox.Datastore))

    called when the operation completes; if successful, the second parameter is the default datastore and the first parameter is null

  • void openDatastore(datastoreId, callback)

    Asynchronously opens the datastore with the given ID, then calls callback with the corresponding Datastore object (or an error).

    Parameters

    datastoreId (String)

    the ID of the datastore to be opened

    callback (function(Dropbox.ApiError, Dropbox.Datastore))

    called when the operation completes; if successful, the second parameter is the datastore and the first parameter is null

  • void createDatastore(callback)

    Asynchronously creates a new datastore, then calls callback with the corresponding Datastore object (or an error).

    Parameters

    callback (function(Dropbox.ApiError, Dropbox.Datastore))

    called when the operation completes; if successful, the second parameter is the created datastore and the first parameter is null

  • void deleteDatastore(datastoreId, callback)

    Asynchronously deletes the datastore with the given ID, then calls callback.

    Deleting a nonexistent datastore is not considered an error.

    Parameters

    datastoreId (String)

    the ID of the datastore to be opened

    callback (function(Dropbox.ApiError))

    called when the operation completes; if successful, the parameter it is called with is null

  • void listDatastores(callback)

    Asynchronously retrieves Dropbox.Datastore.DatastoreInfo objects for all datastores accessible to your app as the current user, then calls callback with the result (or an error).

    After creating, deleting, or modifying a datastore, there may be a delay before the change is reflected in the list of datastores.

    Parameters

    callback (function(Dropbox.ApiError, Array<Dropbox.Datastore.DatastoreInfo>))

    called when the operation completes; if successful, the second parameter is an Array of Dropbox.Datastore.DatastoreInfo and the first parameter is null

Properties
  • datastoreListChanged (Dropbox.Util.EventSource<Dropbox.Datastore.DatastoreListChanged>)

    Fires non-cancelable events every time the datastore list changes. A listener that is added always receives at least one call with the initial state.

    After creating or deleting a datastore, there may be a delay before the corresponding event is fired.

Dropbox.Datastore.DatastoreInfo

Metadata about a datastore.

Instance Methods
  • String getId()

    Returns the ID of the datastore.

Dropbox.Datastore.DatastoreListChanged

An event indicating an update to the list of datastores.

Use DatastoreManager.datastoreListChanged.addListener() to receive these events.

Instance Methods

Dropbox.Datastore.Table

Stores structured data and organizes it for retrieval.

Tables are designed to store similar records in a manner that supports retrieving subsets of the records that meet certain conditions.

Datastore tables do not have the constraints associated with tables in SQL databases. A datastore table does not place any constraints on the fields in its records.

Tables are created and deleted on-demand as records get added and removed. Table instances just keep track of the records associated with a table.

Table instances can be obtained by calling Dropbox.Datastore#getTable. Table objects should not be constructed directly.

Class Methods
  • Boolean isValidId(tableId)

    Checks that a string meets the constraints for table IDs.

    Table IDs must be strings containing 1-32 characters from the set a-z, A-Z, 0-9, dot (.), underscore (_), plus sign (+), minus sign (-), equal sign (=), forward slash (/). The first character may also be a colon (:), but such table IDs are reserved.

    This character set accomodates base64-encoded strings, as well as URL-safe base64-encoded strings.

    Parameters

    tableId (String)

    the string to be checked

    Returns

    true if tableId can be used as a table ID, false otherwise

Instance Methods
  • String getId()

    Returns the table's ID.

    Returns

    the table's ID; table IDs are unique across a datastore

  • ?Dropbox.Datastore.Record get(recordId)

    Retrieves the record with the given ID.

    Parameters

    recordId (String)

    the ID of the record to be returned

    Returns

    the record in this table with the given ID; null if no record with the given ID exists

    Throws

    Error

    if recordId is not a valid record Id

  • Dropbox.Datastore.Record getOrInsert(recordId, defaultValues)

    Retrieves the record with the given ID, creating a new record if there is no existing record with that ID.

    If a new record is created, it is populated with the specified default values. The defaultValues parameter takes the same form as the fieldValues parameter in Dropbox.Datastore.Record#update.

    Parameters

    recordId (String)

    the ID of the record to be returned

    defaultValues (Object<String, String|Number|Boolean|Date|Uint8Array|Array|null>)

    if a new record is created on-demand, this parameter will be used to populate the record's fields

    Returns

    the record in this table with the given ID; if no record with the given ID exists, a new record is created, with the fields specified by the defaultFields parameter

    Throws

    Error

    if recordId is not a valid record ID

  • Dropbox.Datastore.Record insert(fieldValues)

    Creates a new record in this table, populated with the given field values.

    The fieldValues parameter takes the same form as the fieldValues parameter in Dropbox.Datastore.Record#update. The record ID is assigned automatically.

    Parameters

    fieldValues (Object)

    maps field names to the values that the fields should have in the newly created record

    Returns

    the newly created record

  • Array<Dropbox.Datastore.Record> query(fieldValues)

    Retrieves the records from this table whose fields match some values.

    Parameters

    fieldValues (Object)

    maps field names to values; only records where each field matches the given value will be returned. This is equivalent to the AND operator in SQL queries.

    Returns

    all the records in the table whose field values match the values in the fieldValues parameter

  • Dropbox.Datastore.Table setResolutionRule(fieldName, rule)

    Sets a resolution rule for conflicts involving the given field, which will be used when automatically merging local and remote changes. The rule applies to all records in this table, and any previously-set rule for the same field of the same table is replaced. The "remote" rule is used by default if no rule is set.

    The valid rules are:

    • "remote": Resolves conflicts by selecting the remote change from the Dropbox server. This is the default conflict resolution rule.
    • "local": Resolves conflicts by selecting the local change on this client.
    • "max": Resolves conflicts by selecting the largest value, based on type-specific ordering.
    • "min": Resolves conflicts by selecting the smallest value, based on type-specific ordering.
    • "sum": Resolves conflicts by calculating a value such that all additions to or subtractions from a numerical value are preserved and combined. This allows a numerical value to act as a counter or accumulator without losing any updates. For non-numerical values this resolution rule behaves as "remote".

    Rules are not persistent, so you should always set up any non-default resolution rules before making any changes to your datastore.

    Parameters

    fieldName (String)

    the field that the rule applies to

    rule (String)

    one of "remote", "local", "min", "max", or "sum"

    Returns

    this, for easy call chaining

Dropbox.Datastore.Record

Stores key-value pairs.

Records belong to datastores, and are grouped into tables. Changes to records in the same datastore can be synchronized atomically.

Record instances can be obtained by calling the methods defined in Dropbox.Datastore.Table. Record objects should not be constructed directly.

Values of record fields are owned by the record and should not be mutated directly, except for Lists, which can be mutated with the List methods.

Class Methods
  • Boolean isValidId(recordId)

    Checks that a string meets the constraints for record IDs.

    Record IDs must be strings containing 1-32 characters from the set a-z, A-Z, 0-9, dot (.), underscore (_), plus sign (+), minus sign (-), equal sign (=), forward slash (/). The first character may also be a colon (:), but such record IDs are reserved.

    This character set accomodates base64-encoded strings, as well as URL-safe base64-encoded strings.

    Parameters

    recordId (String)

    the string to be checked

    Returns

    true if recordId can be used as a record ID, false otherwise

Instance Methods
  • String|Number|Boolean|Date|Uint8Array|Dropbox.Datastore.List|null get(fieldName)

    Returns a field's value, or null if the field does not exist.

    The returned object will have one of the following types:

    • String
    • Number
    • Boolean
    • Date
    • Uint8Array
    • Dropbox.Datastore.List

    The returned value can also be null, which indicates that the specified field does not exist on this record.

    Note that if the field holds a 64-bit integer, the return value will be a boxed Number that approximates the 64-bit integer as closely as possible, with an additional property dbxInt64 that holds the precise signed integer value in decimal representation as a string (see Dropbox.Datastore.int64). For integers that are at most 2^53 in magnitude, the approximation is exact.

    Parameters

    fieldName (String)

    the name of the field whose value will be returned

    Returns

    the value associated with the field

  • Dropbox.Datastore.Record set(fieldName, value)

    Changes a field's value.

    A field can store a single value. This method discards the field's old value. Future Dropbox.Datastore.Record#get calls will return the new value.

    The value can be one of several native JavaScript types:

    • String
    • Number
    • Boolean
    • Date
    • Uint8Array
    • Array

    Setting a value of null deletes the field from the record. Special considerations apply to certain types:

    • Number: By default, a regular JavaScript number will be stored as a double for other platforms. To store the value instead as a 64-bit integer, use Dropbox.Datastore.int64 to create a boxed number.
    • Array: Each element of the array can be any of the supported types except Array. Elements of the array need not be of the same type. When this field value is retrieved using Dropbox.Datastore.Record#get, it will be returned as a Dropbox.Datastore.List.
    Parameters

    fieldName (String)

    the name of the field whose value will be modified

    value (String|Number|Boolean|Date|Uint8Array|Array|null)

    the value to store in the field

    Returns

    this, for easy call chaining

  • Dropbox.Datastore.List getOrCreateList(fieldName)

    Returns a Dropbox.Datastore.List from the given field of the record, creating an empty one if the field does not currently exist on this record. An error is thrown if the field exists but contains a value that is not a Dropbox.Datastore.List.

    Using this method is usually preferable to calling Dropbox.Datastore.Record#set with an empty list: in cases where multiple clients create a list on the same field at the same time, Dropbox.Datastore.Record#getOrCreateList allows their changes to be merged while Dropbox.Datastore.Record#set does not.

    Parameters

    fieldName (String)

    the name of the field containing the Dropbox.Datastore.List

    Returns

    the existing Dropbox.Datastore.List in the given field, or a newly created empty Dropbox.Datastore.List if the field did not previously exist

  • Object<String, String|Number|Boolean|Date|Uint8Array|Dropbox.Datastore.List> getFields()

    Returns the values of all the fields in this record.

    A new object is created every time this method is called. Performance-conscious code should not assume that this method caches its return value.

    See Dropbox.Datastore.Record#get for a more in-depth discussion of possible return values.

    Returns

    a JavaScript object whose properties are the names of this record's fields, and whose values are the corresponding field values

    Throws

    Error

    if this record was deleted from the datastore

  • Dropbox.Datastore.Record update(a)

    Updates this record with the given field name/value pairs.

    A field can store a single value. This method discards the old values of the modified fields. Future Dropbox.Datastore.Record#get calls will return the new values.

    This method is conceptually equivalent to calling Dropbox.Datastore.Record#set for each field. For a detailed discussion on possible field values, see Dropbox.Datastore.Record#set.

    Parameters

    a (Object<String, String|Number|Boolean|Date|Uint8Array|Array|null>)

    JavaScript object whose properties are the names of the fields whose values will be changed, and whose values are the values that will be assigned to the fields

    Returns

    this, for easy call chaining

  • Dropbox.Datastore.Record deleteRecord()

    Deletes this record from the datastore.

    Once a record is deleted, the Record methods that operate on fields will throw exceptions.

    Returns

    this, for easy call chaining

  • Boolean has(fieldName)

    Returns true if this record has a value stored in a field.

    Parameters

    fieldName (String)

    the name of the field whose value will be looked up

    Returns

    true if this record has a value stored in the given field, false otherwise

  • String getId()

    Returns this record's ID.

    A record's ID is established when the record is created, and cannot be changed afterwards. Record IDs are unique in a table.

    Dropbox.Datastore.Table#get can be used to look up records by ID.

    Returns

    this record's ID; record IDs are unique in a table

  • Dropbox.Datastore.Table getTable()

    Returns the table that this record belongs to.

    The association between a record and its table is established when the record is created. Records cannot be moved between tables.

    Returns

    the table that this record belongs to

  • Boolean isDeleted()

    Returns true if this record was deleted from the datastore

    Returns

    true if this record was deleted from the datastore

Dropbox.Datastore.RecordsChanged

An event indicating an update to a set of records.

RecordsChanged events are fired for changes that this instance of the app made locally as well as for changes synced from other (remote) instances of the app. Use Dropbox.Datastore.RecordsChanged#isLocal to tell the difference.

Use Datastore.recordsChanged.addListener() to receive these events.

Instance Methods
  • Object<String, Array<Dropbox.Datastore.Record>> affectedRecordsByTable()

    Returns a map of table IDs to lists of record objects that have changed.

    Returns

    a map storing the records that were changed

  • Array<Dropbox.Datastore.Record> affectedRecordsForTable(tableId)

    Returns the list of record objects that have changed in table tableId.

    Parameters

    tableId (String)

    the ID of a table

    Returns

    the list of record objects that changed in the given table

  • Boolean isLocal()

    Returns true if the event was generated as a result of local changes, rather than changes synchronized from the server.

    Returns

    whether the event was generated by local changes

Dropbox.Datastore.List

A list of values stored in a field of a record.

Instances of this class are returned by Dropbox.Datastore.Record#getOrCreateList, and by Dropbox.Datastore.Record#get after the field has been set to an array value.

Each list element can be a String, Boolean, Number (including Dropbox.Datastore.int64), Date, or Uint8Array. Lists can mix elements of different types.

Modifications of the list will result in modifications of the datastore record field where the list is stored.

List elements are owned by the list and should not be mutated.

Whenever a method takes an index argument, negative numbers count from the end of the list.

Instance Methods
  • String|Number|Boolean|Date|Uint8Array get(index)

    Returns the list element at index.

    Parameters

    index (Number)

  • void set(index, value)

    Sets the list element at index to value.

    Parameters

    index (Number)

    value (String|Number|Boolean|Date|Uint8Array)

  • Number length()

    Returns the number of elements in the list.

    Returns

    the length of the list

  • String|Number|Boolean|Date|Uint8Array pop()

    Like Array.pop, removes the last element from the list and returns it.

    Returns

    the element that was removed

  • void push(value)

    Like Array.push, appends the given value to the end of the list.

    Parameters

    value (String|Number|Boolean|Date|Uint8Array)

  • String|Number|Boolean|Date|Uint8Array shift()

    Like Array.shift, removes the first element from the list and returns it.

    Returns

    the element that was removed

  • void unshift(value)

    Like Array.unshift, inserts the given value at the beginning of the list.

    Parameters

    value (String|Number|Boolean|Date|Uint8Array)

    the value to insert

  • Array<String|Number|Boolean|Date|Uint8Array> splice(index, howMany)

    Like Array.splice, removes howMany consecutive elements from the list starting at index, then inserts elements (if any) at index.

    Parameters

    index (Number)

    howMany (Number)

    the number of elements to remove

    Returns

    the removed elements as an Array

  • void move(oldIndex, newIndex)

    Moves the element at oldIndex to position newIndex.

    This is similar to removing an element from oldIndex, then inserting it at newIndex, except that this is expressed as a "move" operation for conflict resolution, which means it won't result in duplicate elements like a removal and insertion would.

    After the move, the element formerly at oldIndex will be at newIndex.

    This method does nothing if oldIndex and newIndex are the same.

    Parameters

    oldIndex (Number)

    newIndex (Number)

  • String|Number|Boolean|Date|Uint8Array remove(index)

    Removes the element at index and returns it.

    Elements with indexes greater than index are shifted to the left.

    Parameters

    index (Number)

    Returns

    the removed element

  • void insert(index, value)

    Inserts the given value at index.

    Elements with indexes greater than or equal to index are shifted to the right.

    Parameters

    index (Number)

    value (String|Number|Boolean|Date|Uint8Array)

  • Array<String|Number|Boolean|Date|Uint8Array> slice(from, to)

    Returns an array that contains the elements of this list between from (inclusive) and to (exclusive).

    The returned array is a copy, so the elements will not update as changes are applied.

    Parameters

    from (Number)

    to (Number)

  • Array<String|Number|Boolean|Date|Uint8Array> toArray()

    Returns an array with the same elements as this list.

    The returned array is a copy, so the elements will not update as changes are applied.

Dropbox.File.Stat

Metadata about a file or directory in a user's Dropbox.

Class Methods
  • Dropbox.File.Stat parse(metadata)

    Creates a Stat instance from a raw "metadata" response.

    Parameters

    metadata (Object)

    the result of parsing JSON API responses that are called "metadata" in the REST API documentation

    Returns

    an instance wrapping the given API response

Instance Methods
  • Object json()

    JSON representation of this file / folder's metadata

    Returns

    an object that can be serialized using JSON; the object can be passed to Dropbox.File.Stat.parse to obtain a Stat instance with the same information

Properties
  • path (String)

    the path of this file or folder, relative to the user's Dropbox or to the application's folder

  • name (String)

    the name of this file or folder

  • inAppFolder (Boolean)

    if true, the file or folder's path is relative to the application's folder; otherwise, the path is relative to the user's Dropbox

  • isFolder (Boolean)

    if true, this Stat instance describes a folder

  • isFile (Boolean)

    if true, this Stat instance describes a file

  • isRemoved (Boolean)

    if true, the file or folder described by this Stat instance was from the user's Dropbox, and was obtained by an API call that returns deleted items

  • typeIcon (String)

    name of an icon in Dropbox's icon library that most accurately represents this file or folder.

    See the REST API documentation to obtain the Dropbox icon library

  • versionTag (String)

    an identifier for the contents of the described file or directories; this can used to restore a file's contents to a previous version, or to save bandwidth by not retrieving the same folder contents twice

  • contentHash (String)

    A hash over the folder's contents; this can be used to save bandwidth when repeatedly reading a directory's content.

  • mimeType (String)

    a guess of the MIME type representing the file or folder's contents

  • size (Number)

    the size of the file, in bytes; null for folders

  • humanSize (String)

    the size of the file, in a human-readable format, such as "225.4KB"; the format of this string is influenced by the API client's locale

  • hasThumbnail (Boolean)

    if false, the URL generated by thumbnailUrl does not point to a valid image, and should not be used

  • modifiedAt (Date)

    the file or folder's last modification time

  • clientModifiedAt (Date)

    the file or folder's last modification time, as reported by the Dropbox client that uploaded the file; this time should not be trusted, but can be used for UI (display, sorting); this is null if the server does not report any time

Dropbox.File.CopyReference

Reference to a file that can be used to make a copy across users' Dropboxes.

Class Methods
  • Dropbox.File.CopyReference parse(refData)

    Creates a CopyReference instance from a raw reference or API response.

    Parameters

    refData (Object, String)

    the parsed JSON describing a copy reference, or the reference string

    Returns

    a CopyReference instance wrapping the given reference

Instance Methods
  • Object json()

    JSON representation of this file / folder's metadata

    Returns

    an object that can be serialized using JSON; the object can be passed to Dropbox.File.CopyReference.parse to obtain a CopyReference instance with the same information

Properties
  • tag (String)

    the raw reference, for use with Dropbox APIs

  • expiresAt (Date)

    deadline for using the reference in a copy operation

Dropbox.File.ShareUrl

Wraps an URL to a Dropbox file or folder that can be shared with other users.

ShareUrl instances are created by calling Dropbox.Client#makeUrl. They can be safely shared with other users, as they do not contain the user's access token.

Class Methods
  • Dropbox.File.ShareUrl parse(urlData, isDirect)

    Creates a ShareUrl instance from a raw API response.

    Parameters

    urlData (Object, String)

    the parsed JSON describing a shared URL

    isDirect (Boolean)

    true if this is a direct download link, false if it's a file / folder preview link

    Returns

    a ShareUrl instance wrapping the given shared URL information

Instance Methods
  • Object json()

    JSON representation of this file / folder's metadata

    Returns

    an object that can be serialized using JSON; the object can be passed to Dropbox.File.CopyReference.parse to obtain a ShareUrl instance with the same information

Properties
  • url (String)

    the public URL

  • expiresAt (Date)

    after this time, the URL is not usable

  • isDirect (Boolean)

    true if this is a direct download URL, false for URLs to preview pages in the Dropbox web app; folders cannot have direct links

  • isPreview (Boolean)

    true if this is URL points to a file's preview page in Dropbox, false for direct links

Dropbox.File

Namespace for the APIs that work with Dropbox files and folders.

Dropbox.Http

Namespace for objects associated to the low-level HTTP API.

The APIs in Dropbox.Http are intended to be used as building blocks for higher-level APIs. Most applications should not need to use them directly.

Dropbox.Util

Namespace for internal functions that are only exposed for testing purposes.

The APIs in Dropbox.Util are not covered by the library's semver promise, and can change on a whim.

Dropbox.AuthDriver.BrowserBase

Base class for OAuth drivers that run in the browser.

Inheriting from this class makes a driver use HTML5 localStorage to preserve OAuth tokens across page reloads.

Class Methods
  • String currentLocation()

    Wrapper for window.location, for testing purposes.

    Returns

    the current page's URL

  • void cleanupLocation()

    Removes the OAuth 2 access token from the current page's URL.

    This hopefully also removes the access token from the browser history.

Instance Methods
  • constructor(options)

    Sets up the OAuth driver.

    Subclasses should pass the options object they receive to the superclass constructor.

    Parameters

    options (Object)

    (optional) one or more of the options below

    Options parameter

    scope (String)

    embedded in the localStorage key that holds the authentication data; useful for having multiple OAuth tokens in a single application

    rememberUser (Boolean)

    if false, the user's OAuth tokens are not saved in localStorage; true by default

  • void authType()

    Browser-side authentication should always use OAuth 2 Implicit Grant.

  • void onAuthStepChange()

    Persists tokens.

    See Also

    Dropbox.AuthDriver#onAuthStepChange

  • String locationStateParam(the)

    Figures out if a URL is an OAuth 2.0 /authorize redirect URL.

    Parameters

    the (String)

    URL to check; if null, the current location's URL is checked

    Returns

    the state parameter value received from the /authorize redirect, or null if the URL is not the result of an /authorize redirect

Dropbox.AuthDriver.Chrome

OAuth driver specialized for Chrome apps and extensions.

Class Methods
  • void oauthReceiver()

    Communicates with the driver from the OAuth receiver page.

    The easiest way for a Chrome application or extension to keep up to date with dropbox.js is to set up a popup receiver page that loads dropbox.js and calls this method. This guarantees that the code used to communicate between the popup receiver page and Dropbox.AuthDriver.Popup#doAuthorize stays up to date as dropbox.js is updated.

Instance Methods
  • String expandUrl(url)

    Expands an URL relative to the Chrome extension / application root.

    Parameters

    url (String)

    a resource URL relative to the extension root

    Returns

    the absolute resource URL

  • constructor(options)

    Sets up an OAuth driver for Chrome.

    Parameters

    options (Object)

    (optional) one or more of the options below

    Options parameter

    receiverPath (String)

    the path of page that receives the /authorize redirect and calls Dropbox.AuthDriver.Chrome.oauthReceiver; the path should be relative to the extension folder; by default, is 'chrome_oauth_receiver.html'

  • void onAuthStepChange()

    Saves token information when appropriate.

  • void doAuthorize()

    Shows the authorization URL in a new tab, waits for it to send a message.

  • Dropbox.AuthDriver.Chrome openWindow(url, callback)

    Creates a popup window.

    Parameters

    url (String)

    the URL that will be loaded in the popup window

    callback (function(Object))

    called with a handle that can be passed to Dropbox.AuthDriver.Chrome#closeWindow

    Returns

    this

  • void url()

    URL of the redirect receiver page that messages the app / extension.

Properties

Dropbox.AuthDriver.Cordova

OAuth driver that uses a Cordova InAppBrowser to complete the flow.

Instance Methods
  • constructor(options)

    Sets up an OAuth driver for Cordova applications.

    Parameters

    options (Object)

    (optional) one of the settings below

    Options parameter

    scope (String)

    embedded in the localStorage key that holds the authentication data; useful for having multiple OAuth tokens in a single application

    rememberUser (Boolean)

    if false, the user's OAuth tokens are not saved in localStorage; true by default

  • String url()

    URL of the page that the user will be redirected to.

    Returns

    a page on the Dropbox site that will not redirect; this is not a new point of failure, because the OAuth flow already depends on the Dropbox site being up and reachable

  • void doAuthorize()

    Shows the authorization URL in a pop-up, waits for it to send a message.

Dropbox.AuthDriver.NodeServer

OAuth driver that redirects the browser to a node app to complete the flow.

This is useful for testing node.js libraries and applications.

Instance Methods
  • constructor(options)

    Starts up the node app that intercepts the browser redirect.

    Parameters

    options (Object)

    (optional) one or more of the options below

    Options parameter

    port (Number)

    the number of the TCP port that will receive HTTPS requests; defaults to 8912

    tls (Object)

    one or more of the options accepted by tls.createServer in the node.js standard library; at a minimum, the key option should be provided

  • void authType()

    The /authorize response type.

  • void url()

    URL to the node.js OAuth callback handler.

  • void doAuthorize()

    Opens the token

  • void openBrowser()

    Opens the given URL in a browser.

  • void createApp()

    Creates and starts up an HTTP server that will intercept the redirect.

  • void closeServer()

    Shuts down the HTTP server.

    The driver will become unusable after this call.

  • void doRequest()

    Reads out an /authorize callback.

  • void closeBrowser()

    Renders a response that will close the browser window used for OAuth.

Dropbox.AuthDriver.Popup

OAuth driver that uses a popup window and postMessage to complete the flow.

Class Methods
  • String locationOrigin(location)

    The origin of a location, in the context of the same-origin policy.

    Parameters

    location (String)

    the URL whose origin is computed

    Returns

    the location's origin

  • void oauthReceiver()

    Communicates with the driver from the OAuth receiver page.

    The easiest way for an application to keep up to date with dropbox.js is to set up a popup receiver page that loads dropbox.js and calls this method. This guarantees that the code used to communicate between the popup receiver page and Dropbox.AuthDriver.Popup#doAuthorize stays up to date as dropbox.js is updated.

Instance Methods
  • constructor(options)

    Sets up a popup-based OAuth driver.

    Parameters

    options (Object)

    (optional) one or more of the options below

    Options parameter

    receiverUrl (String)

    URL to the page that receives the /authorize redirect and performs the postMessage

    receiverFile (String)

    the URL to the receiver page will be computed by replacing the file name (everything after the last /) of the current location with this parameter's value

    scope (String)

    embedded in the localStorage key that holds the authentication data; useful for having multiple OAuth tokens in a single application

    rememberUser (Boolean)

    if false, the user's OAuth tokens are not saved in localStorage; true by default

  • String url()

    URL of the redirect receiver page, which posts a message back to this page.

    Returns

    receiver page URL

  • void doAuthorize()

    Shows the authorization URL in a pop-up, waits for it to send a message.

Dropbox.AuthDriver.Redirect

OAuth driver that uses a redirect and localStorage to complete the flow.

Instance Methods
  • constructor(options)

    Sets up the redirect-based OAuth driver.

    Parameters

    options (Object)

    (optional) one more of the options below

    Options parameter

    redirectUrl (String)

    URL to the page that receives the /authorize redirect

    redirectFile (String)

    the URL to the receiver page will be computed by replacing the file name (everything after the last /) of the current location with this parameter's value

    scope (String)

    embedded in the localStorage key that holds the authentication data; useful for having multiple OAuth tokens in a single application

    rememberUser (Boolean)

    if false, the user's OAuth tokens are not saved in localStorage; true by default

  • String url()

    URL of the page that the user will be redirected to.

    Returns

    the URL of the app page that the user will be redirected to after /authorize; if no constructor option is set, this will be the current page

  • void doAuthorize()

    Saves the OAuth 2 credentials, and redirects to the authorize page.

  • void resumeAuthorize()

    Finishes the OAuth 2 process after the user has been redirected.

Dropbox.Http.AppInfo

Wraps the description of a Dropbox Platform application.

AppInfo instances contain the same information that is displayed on the OAuth authorize page, in a machine-friendly format.

Class Methods
  • Dropbox.Http.AppInfo parse(appInfo, appKey)

    Creates an AppInfo instance from an /app/info API call result.

    Parameters

    appInfo (Object)

    the parsed JSON of an /app/info API call result

    appKey (String)

    (optional) the app key used to make the/app/info API call; if missing, the key will be obtained from appInfo, or it will be null

    Returns

    an AppInfo instance wrapping the given info on a platform application

Instance Methods
  • void icon(width, height)

    An icon that can be used as the application's logo.

    Parameters

    width (Number)

    the desired icon width

    height (Number)

    (optional) the desired icon height; by default, equals the width argument

Properties
  • name (String)

    The application name entered in the app console.

  • key (String)

    The key used to fetch this application info.

  • canUseDatastores (Boolean)

    true if the application has access to the Datastore API

  • canUseFiles (Boolean)

    true if the application has access to the Files API

  • hasAppFolder (Boolean)

    true if the application has its own folder in the user's Dropbox

  • canUseFullDropbox (Boolean)

    true if the application has access to all the files in the user's Dropbox

Constants
  • ICON_SMALL

    The width (and height) of small application icons.

  • ICON_LARGE

    The width (and height) of large application icons.

Dropbox.Http.PulledChange

Wraps a single change in a pullChanges result.

Class Methods
  • Dropbox.Http.PulledChange parse(entry)

    Creates a PulledChange instance wrapping an entry in a /delta result.

    Parameters

    entry (Object)

    the parsed JSON of a single entry in a /delta API call result

    Returns

    a PulledChange instance wrapping the given entry of a /delta API call response

Properties
  • path (String)

    the path of the changed file or folder

  • wasRemoved (Boolean)

    if true, this change is a deletion of the file or folder at the change's path; if a folder is deleted, all its contents (files and sub-folders) were also be deleted; pullChanges might not return separate changes expressing for the files or sub-folders

  • stat (Dropbox.File.Stat)

    a Stat instance containing updated information for the file or folder; this is null if the change is a deletion

Dropbox.Http.PulledChanges

Wraps the result of pullChanges, describing the changes in a user's Dropbox.

Class Methods
  • Dropbox.Http.PulledChanges parse(deltaInfo)

    Creates a PulledChanges instance from a /delta API call result.

    Parameters

    deltaInfo (Object)

    the parsed JSON of a /delta API call result

    Returns

    a PulledChanges instance wrapping the given Dropbox changes

Instance Methods
  • String cursor()

    Serializable representation of the pull cursor inside this object.

    Returns

    an ASCII string that can be passed to pullChanges instead of this PulledChanges instance

Properties
  • blankSlate (Boolean)

    if true, the application should reset its copy of the user's Dropbox before applying the changes described by this instance

  • cursorTag (String)

    encodes a cursor in the list of changes to a user's Dropbox; a pullChanges call returns some changes at the cursor, and then advance the cursor to account for the returned changes; the new cursor is returned by pullChanges, and meant to be used by a subsequent pullChanges call

  • shouldPullAgain (Boolean)

    if true, the pullChanges call returned a subset of the available changes, and the application should repeat the call immediately to get more changes

  • shouldBackOff (Boolean)

    if true, the API call will not have any more changes available in the nearby future, so the application should wait for at least 5 minutes before issuing another pullChanges request

Dropbox.Http.RangeInfo

Parsed HTTP Content-Range header.

Class Methods
  • Dropbox.Http.RangeInfo parse(headerValue)

    Creates a RangeInfo instance from the value of a Content-Range HTTP header.

    Parameters

    headerValue (String)

    a Content-Range HTTP header

    Returns

    a RangeInfo instance representing the Content-Range information

Properties
  • start (Number)

    0-based position of the first byte read from the file

  • size (Number)

    the file's total size, in bytes

  • end (Number)

    0-based position of the last byte read from the file

Dropbox.Http.UploadCursor

Tracks the progress of a resumable upload.

Class Methods
  • Dropbox.Http.UploadCursor parse(cursorData)

    Creates an UploadCursor instance from an API response.

    Parameters

    cursorData (Object, String)

    the parsed JSON describing the status of a partial upload, or the upload ID string

    Returns

    an UploadCursor instance wrapping the given cursor information

Instance Methods
  • Object json()

    JSON representation of this cursor.

    Returns

    an object that can be serialized using JSON; the object can be passed to Dropbox.Http.UploadCursor.parse to obtain an UploadCursor instance with the same information

  • constructor(cursorData)

    Creates an UploadCursor instance from a raw reference or API response.

    This constructor should only be called directly to obtain a cursor for a new file upload. Dropbox.Http.UploadCursor.parse should be preferred for any other use.

    Parameters

    cursorData (Object, String)

    the parsed JSON describing a copy reference, or the reference string

Properties
  • tag (String)

    the server-generated ID for this upload

  • offset (Number)

    number of bytes that have already been uploaded

  • expiresAt (Date)

    deadline for finishing the upload

Dropbox.Util.EventSource

Event dispatch following a publisher-subscriber (PubSub) model.

Instance Methods
  • constructor(options)

    Sets up an event source (publisher).

    Parameters

    options (Object)

    one or more of the options below

    Options parameter

    cancelable (Boolean)

    if true, events dispatched from this source can be canceled from a listener, by returning false

  • Dropbox.Util.EventSource addListener(listener)

    Registers a listener (subscriber) to events coming from this source.

    This is a simplified version of the addEventListener DOM API. Listeners must be functions, and they can be removed by calling removeListener.

    This method is idempotent, so a function will not be added to the list of listeners if was previously added.

    Parameters

    listener (function(Object))

    called every time an event is fired; if the event is cancelable, the function can return false to cancel the event, or any other value to allow it to propagate; the return value is ignored for non-cancelable events

    Returns

    this, for easy call chaining

  • Dropbox.Util.EventSource removeListener(listener)

    Un-registers a listener (subscriber) previously added by addListener.

    This is a simplified version of the removeEventListener DOM API. The listener must be exactly the same object supplied to addListener.

    This method is idempotent, so it will fail silently if the given listener is not registered as a subscriber.

    Parameters

    listener (function(Object))

    function that was previously passed in an addListener call

    Returns

    this, for easy call chaining

  • Boolean dispatch(event)

    Informs the listeners (subscribers) that an event occurred.

    Event sources configured for non-cancelable events call all listeners in an unspecified order. Sources configured for cancelable events stop calling listeners as soon as one listener returns false value.

    Parameters

    event (Object)

    passed to all the registered listeners

    Returns

    sources of cancelable events return false if the event was canceled and true otherwise; sources of non-cancelable events always return true

Dropbox.Util.Oauth

Stripped-down OAuth 2 implementation that works with the Dropbox API server.

Class Methods
  • Object<String, String> queryParamsFromUrl(url)

    Extracts the query parameters in an /authorize redirect URL.

    This is provided as a helper for dropbox.js OAuth drivers. It is not a general-purpose URL parser, but it will handle the URLs generated by the Dropbox API server.

    Parameters

    url (String)

    a redirect URL generated by Dropbox's OAuth authorization page

    Returns

    the OAuth 2 parameters passed in the URL; this should be passed to the callback of Dropbox.AuthDriver#doAuthorize or Dropbox.AuthDriver#resumeAuthorize

  • String randomAuthStateParam()

    Generates a random OAuth 2 authentication state parameter value.

    This is used for authentication drivers that do not implement Dropbox.AuthDriver#getStateParam.

    Returns

    a randomly generated parameter

Instance Methods
  • Boolean checkAuthStateParam(stateParam)

    Verifies the "state" query parameter in an /authorize redirect.

    If this method returns false, the /authorize redirect should be ignored.

    Parameters

    stateParam (String)

    the value of the "state" query parameter in the request caused by an /authorize HTTP redirect

    Returns

    true if the given value matches the "state" parameter sent to /authorize; false if no /authorize redirect was expected, or if the value doesn't match

Dropbox.Util.Xhr

Dispatches low-level HTTP requests.

This wraps XMLHttpRequest or its equivalents (XDomainRequest on IE 9 and below) and works around bugs and inconsistencies in various implementations.

Class Methods
  • String urlEncode(object)

    Encodes an associative array (hash) into a x-www-form-urlencoded String.

    For consistency, the keys are sorted in alphabetical order in the encoded output.

    Parameters

    object (Object)

    the JavaScript object whose keys will be encoded

    Returns

    the object's keys and values, encoded using x-www-form-urlencoded

  • String urlEncodeValue(object)

    Encodes an object into a x-www-form-urlencoded key or value.

    Parameters

    object (Object)

    the object to be encoded; the encoding calls toString() on the object to obtain its string representation

    Returns

    encoded string, suitable for use as a key or value in an x-www-form-urlencoded string

  • Object urlDecode(string)

    Decodes an x-www-form-urlencoded String into an associative array (hash).

    Parameters

    string (String)

    the x-www-form-urlencoded String to be decoded

    Returns

    an associative array whose keys and values are all strings

Instance Methods
  • constructor(method, baseUrl)

    Sets up an AJAX request.

    Parameters

    method (String)

    the HTTP method used to make the request ('GET', 'POST', 'PUT', etc.)

    baseUrl (String)

    the URL that receives the request; this URL might be modified, e.g. by appending parameters for GET requests

  • Dropbox.Util.Xhr setParams(params)

    Sets the parameters (form field values) that will be sent with the request.

    Parameters

    params (?Object)

    an associative array (hash) containing the HTTP request parameters

    Returns

    this, for easy call chaining

  • Dropbox.Util.Xhr setCallback(callback)

    Sets the function called when the HTTP request completes.

    This function can also be set when calling Dropbox.Util.Xhr#send.

    Parameters

    callback (function(Dropbox.ApiError, Object, Object, Object))

    called when the XMLHttpRequest completes; if an error occurs, the first parameter will be a Dropbox.ApiError; otherwise, the first parameter will be null, the second parameter will be an instance of the required response type (e.g., String, Blob), the third parameter will be the JSON-parsed 'x-dropbox-metadata' header, and the fourth parameter will be an object containing all the headers

    Returns

    this, for easy call chaining

  • Dropbox.Util.Xhr signWithOauth(oauth, cacheFriendly)

    Amends the request parameters to include an OAuth signature.

    The OAuth signature will become invalid if the parameters are changed after the signing process.

    This method automatically decides the best way to add the OAuth signature to the current request. Modifying the request in any way (e.g., by adding headers) might result in a valid signature that is applied in a sub-optimal fashion. For best results, call this right before Dropbox.Util.Xhr#prepare.

    Parameters

    oauth (Dropbox.Util.Oauth)

    OAuth instance whose key and secret will be used to sign the request

    cacheFriendly (Boolean)

    if true, the signing process choice will be biased towards allowing the HTTP cache to work; by default, the choice attempts to avoid the CORS preflight request whenever possible

    Returns

    this, for easy call chaining

  • Dropbox.Util.Xhr addOauthParams(oauth)

    Amends the request parameters to include an OAuth signature.

    The OAuth signature will become invalid if the parameters are changed after the signing process.

    Parameters

    oauth (Dropbox.Util.Oauth)

    OAuth instance whose key and secret will be used to sign the request

    Returns

    this, for easy call chaining

  • Dropbox.Util.Xhr addOauthHeader(oauth)

    Adds an Authorize header containing an OAuth signature.

    The OAuth signature will become invalid if the parameters are changed after the signing process.

    Parameters

    oauth (Dropbox.Util.Oauth)

    OAuth instance whose key and secret will be used to sign the request

    Returns

    this, for easy call chaining

  • Dropbox.Util.Xhr setBody(body)

    Sets the body (piece of data) that will be sent with the request.

    Parameters

    body (String, Blob, ArrayBuffer)

    the body to be sent in a request; GET requests cannot have a body

    Returns

    this, for easy call chaining

  • Dropbox.Util.Xhr setResponseType(responseType)

    Sends off an HTTP request and requests a custom response type.

    This method requires XMLHttpRequest Level 2 support, which is not available in Internet Explorer 9 and older.

    Parameters

    responseType (String)

    the value that will be assigned to the XHR's responseType property

    Returns

    this, for easy call chaining

  • Dropbox.Util.Xhr setHeader(headerName, value)

    Sets the value of a custom HTTP header.

    Custom HTTP headers require a CORS preflight in browsers, so requests that use them will take more time to complete, especially on high-latency mobile connections.

    Parameters

    headerName (String)

    the name of the HTTP header

    value (String)

    the value that the header will be set to

    Returns

    this, for easy call chaining

  • Dropbox.Util.Xhr reportResponseHeaders()

    Requests that the response headers be reported to the callback.

    Response headers are not returned by default because the parsing is non-trivial and produces many intermediate strings.

    Response headers are not available on Internet Explorer 9 and below.

    Returns

    this, for easy call chaining

  • void setFileField(fieldName, fileName, fileData, contentType)

    Simulates having an <input type="file"> being sent with the request.

    Parameters

    fieldName (String)

    the name of the form field / parameter (not of the uploaded file)

    fileName (String)

    the name of the uploaded file (not the name of the form field / parameter)

    fileData (String, Blob, File)

    contents of the file to be uploaded

    contentType (?String)

    the MIME type of the file to be uploaded; if fileData is a Blob or File, its MIME type is used instead

  • Dropbox.Util.Xhr prepare()

    Sets up an XHR request.

    This method completely sets up a native XHR object and stops short of calling its send() method, so the API client has a chance of customizing the XHR. After customizing the XHR, Dropbox.Util.Xhr#send should be called.

    Returns

    this, for easy call chaining

  • Dropbox.Util.Xhr send(callback)

    Fires off the prepared XHR request.

    Dropbox.Util.Xhr#prepare should be called exactly once before this method is called.

    Parameters

    callback (function(?Dropbox.ApiError, ?Object, ?Object))

    called when the XHR completes; if an error occurs, the first parameter will be a Dropbox.ApiError instance; otherwise, the second parameter will be an instance of the required response type (e.g., String, Blob), and the third parameter will be the JSON-parsed 'x-dropbox-metadata' header

    Returns

    this, for easy call chaining

  • void onReadyStateChange()

    Handles the XHR readystate event.

  • void onXdrLoad()

    Handles the XDomainRequest onload event. (IE 8, 9)

  • void onXdrError()

    Handles the XDomainRequest onload event. (IE 8, 9)

Properties