Datastore API for JavaScript documentation

Dropbox API client representing an user or an application.

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

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.

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

Get the client's OAuth credentials.

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.

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

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.

Alias for signOut.

Retrieves information about the logged in user.

Backwards-compatible name of getAccountInfo.

@deprecated

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.

Store a file into a user's Dropbox.

Atomic step in a resumable file upload.

Finishes a resumable file upload.

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

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

Alias for "stat" that matches the HTTP API.

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

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

Alias for "history" that matches the HTTP API.

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

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.

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

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

Alias for "revertFile" that matches the HTTP API.

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

Alias for "findByName" that matches the HTTP API.

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

Alias for "makeCopyReference" that matches the HTTP API.

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.

Alias for "pullChanges" that matches the HTTP API.

Checks whether changes have occurred in a user's Dropbox.

This method can be used together with Dropbox.Client#pullChanges to react to changes in Dropbox in a timely manner.

Creates a folder in a user's Dropbox.

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

node.js-friendly alias for "remove".

Alias for "remove" that matches the HTTP API.

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.

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

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.

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.

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.

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.

Change the client's OAuth credentials.

Unique identifier for the Dropbox application behind this client.

This method is intended to be used by OAuth drivers.

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

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

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

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

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

authStep value for a client that experienced an authentication error.

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

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.

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.

authStep value for a client that has an authorization code.

authStep value for a client that has an access token.

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

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

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.

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.

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

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

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

Creates an AccountInfo instance from a raw API response.

JSON representation of this user's information.

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

the user's email, or null if unavailable

two-letter country code, or null if unavailable

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

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

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

prefix for URLs to the application's files

the maximum amount of bytes that the user can store

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

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

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

Wraps a failed XHR call to the Dropbox API.

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

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

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

the URL of the failed request

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

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

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.

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.

Status value indicating an invalid input parameter.

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

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.

Status value indicating a malformed OAuth request.

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

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.

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.

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.

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.

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

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

Status value indicating a server issue.

The request should be retried after some time.

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.

Wraps an XHR error.

one of the Dropbox.AuthError constants

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

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

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.

Error code indicating a malformed OAuth request.

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

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.

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.

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.

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

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

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

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

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.

The OAuth 2.0 equivalent of a HTTP 503 error code.

This occurrs when the application is rate-limited.

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.

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

Checks that a string meets the constraints for datastore IDs.

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

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

Check that a string represents a shareable datastore ID.

This is a valid datastore ID starting with a '.'.

Gets the last time this datastore was modified.

Gets the title of this datastore. If the title was never set, the returned value is null.

Sets the title of this datastore

Returns whether this datastore is shareable. This is purely a function of the datastore ID. Only datastores created with Dropbox.Datastore.DatastoreManager#createDatastore (i.e. whose ID starts with ".") are shareable.

Gets the effective role of this datastore. This indicates the current user's access level. The OWNER and EDITOR roles give full control (reading, writing, changing roles); the VIEWER role gives read-only control. The OWNER role is established at datastore creation and cannot be changed. For non-shareable (private) datastores OWNER is the only role.

Returns whether this datastore is writable. This is a shorthand for testing whether Dropbox.Datastore#getEffectiveRole returns OWNER or EDITOR.

Gets the role for a principal, for a shareable datastore.

Sets the role for a principal, for a shareable datastore.

Deletes the role for a principal, for a shareable datastore.

Lists the roles for all principals, for a shareable datastore.

Creates a Table instance for a given table ID.

The IDs of all the tables in this datastore.

Tables with reserved names or containing no records are not listed.

Returns the number of records in this datastore.

Returns the size in bytes of this datastore.

The overall size of a datastore is calculated by summing the size of all records, plus the base size of an empty datastore itself.

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.

Returns this datastore's ID.

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.

The maximum number of records in a datastore.

The size in bytes of a datastore before accounting for the size of its records.

The overall size of a datastore is this value plus the size of all records.

This principal refers to the DfB team of the datastore's owner. This is only valid if the owner is a member of a DfB team.

This principal refers to the general public.

This role indicates the owner of a datastore.

This role indicates edit permission of a datastore.

This role indicates read-only viewing permission of a datastore.

This role indicates lack of access to a datastore.

Fires non-cancelable events every time a record changes, either due to a local or remote change.

Note: Since this is fired for local datastore changes, making further changes in the listener can lead to infinite loops. Use Dropbox.Datastore.RecordsChanged#isLocal to determine if a change was local or remote.

Fires non-cancelable events every time the sync status changes

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

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

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

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

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

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

Deleting a nonexistent datastore is not considered an error.

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.

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.

Returns the ID of the datastore.

Returns whether this datastore is shareable. This is purely a function of the datastore ID.

Returns the title of the datastore, if set.

Returns the last modification time of the datastore, if set.

Returns the effective role of the datastore.

Returns whether this datastore is writable. This is a shorthand for testing whether Dropbox.Datastore.DatastoreInfo#getEffectiveRole returns one of OWNER or EDITOR.

Returns a list containing current Dropbox.Datastore.DatastoreInfo objects for all datastores that your app can access.

Checks that a string meets the constraints for table IDs.

Table IDs must be strings containing 1-64 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.

Returns the table's ID.

Retrieves the record with the given ID.

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.

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. A unique record ID is assigned automatically.

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

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.

Checks that a string meets the constraints for record IDs.

Record IDs must be strings containing 1-64 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.

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.

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.

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.

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 the size in bytes of this record.

The overall size of a record is calculated by summing the size of all values in all fields, plus the base size of an empty record itself. A deleted record has a size of zero.

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.

Deletes this record from the datastore.

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

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

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 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 true if this record was deleted from the datastore

The size in bytes of a record before accounting for the sizes of its fields.

The overall size of a record is this value plus the sum of the sizes of its fields.

The size in bytes of a field before accounting for the sizes of its values.

The overall size of a field is this value plus:

• For String and Uint8Array: the length in bytes of the value.
• For Dropbox.Datastore.List: the sum of the size of each list item, where each item's size is computed as the size of the item value plus Dropbox.Datastore.List.BASE_ITEM_SIZE.
• For other atomic types: no additional contribution to the size of the field.

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

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

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

Returns the list element at index.

Sets the list element at index to value.

Returns the number of elements in the list.

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

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

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

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

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

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.

Removes the element at index and returns it.

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

Inserts the given value at index.

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

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.

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.

The size in bytes of a list item.

The overall size of a list item is this value plus the size of the item value.

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

JSON representation of this file / folder's metadata

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

the name of this file or folder

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

if true, this Stat instance describes a folder

if true, this Stat instance describes a file

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

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

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

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

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

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

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

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

the file or folder's last modification time

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

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

JSON representation of this file / folder's metadata

the raw reference, for use with Dropbox APIs

deadline for using the reference in a copy operation

Creates a ShareUrl instance from a raw API response.

JSON representation of this file / folder's metadata

the public URL

after this time, the URL is not usable

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

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

Wrapper for window.localStorage.

Drivers should call this method instead of using localStorage directly, to simplify stubbing.

Wrapper for window.location.

Drivers should call this method instead of using browser APIs directly, to simplify stubbing.

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

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

Sets up the OAuth driver.

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

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

Persists tokens.

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

Sets up an OAuth driver for a Chrome packaged application.

Uses the Chrome identity API to drive the OAuth 2 flow.

Communicates with the driver from the OAuth receiver page.

The easiest way for a Chrome 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.ChromeExtension#doAuthorize stays up to date as dropbox.js is updated.

Sets up an OAuth driver for a Chrome extension.

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

Sets up an OAuth driver for Cordova applications.

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

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

Starts up the node app that intercepts the browser redirect.

The /authorize response type.

URL to the node.js OAuth callback handler.

Opens the token

Opens the given URL in a browser.

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

Shuts down the HTTP server.

The driver will become unusable after this call.

Reads out an /authorize callback.

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

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

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.

Sets up a popup-based OAuth driver.

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

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

Sets up the redirect-based OAuth driver.

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

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

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

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

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

The application name entered in the app console.

The key used to fetch this application info.

true if the application has access to the Datastore API

true if the application has access to the Files API

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

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

The width (and height) of small application icons.

The width (and height) of large application icons.

Creates a PollResult instance from a /longpoll_delta API call result.

true if there have been changes in the user's Dropbox; Dropbox.Client#pullChanges can be called to obtain the changes

seconds that the client must wait for before making another Dropbox.Client#pollForChanges call

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

the path of the changed file or folder

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

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

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

Serializable representation of the pull cursor inside this object.

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

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

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

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

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

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

the file's total size, in bytes

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

Creates an UploadCursor instance from an API response.

JSON representation of this cursor.

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.

the server-generated ID for this upload

number of bytes that have already been uploaded

deadline for finishing the upload

Sets up an event source (publisher).

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.

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.

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.

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.

Generates a random OAuth 2 authentication state parameter value.

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

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

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

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.

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

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

Sets up an AJAX request.

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

Sets the function called when the HTTP request completes.

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

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.

Amends the request parameters to include an OAuth signature.

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

Adds an Authorize header containing an OAuth signature.

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

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

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.

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.

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.

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

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.

Fires off the prepared XHR request.

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

Handles the XHR readystate event.

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

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

The XMLHttpRequest object used to make the request.

This is null before Dropbox.Util.Xhr#prepare is called

Called when the HTTP request fails.

If the underlying XMLHttpRequest fails and this is not null, this callback will receive a Dropbox.ApiError instance as its first argument. The function is responsible for calling its 2nd argument and passing it the Dropbox.ApiError. If the function does not do that, the callback passed to Dropbox.Util.Xhr#send or Dropbox.Util.Xhr#setCallback will not be called