Class: Connection

Connection

The Connection object: One instance for each email id. Has Monologue methods mixed in.

new Connection(box, email)

Parameters:
Name Type Description
box Box The Box object though which this connection is managed.
email string The email account identifier to connect to.
Source:

Methods

<private> _emit(done)

The internal event emitter.

Do not call this method directly.
Parameters:
Name Type Description
done function The callback.
Source:
Fires:

<private> _longPoll(done)

The internal long-polling sequence.

Do not call this method directly.
Parameters:
Name Type Description
done optionalErrorCallback Called after finishing one round of long polling.
Source:
Fires:

<private> _request(segments, method, callback, query, payload, data, headers, pipe, config)

Perform an HTTP request on this connection.

Do not call this method directly. Use one of the wrapper API methods instead.
Parameters:
Name Type Argument Description
segments string | Array.<string> The path segments to append to the API base URL.
method string The HTTP verb to use for this request.
callback requestCallback The callback to invoke (with possible errors) when the request returns.
query Object <optional>
<nullable>
A map of query parameters.
payload Object <optional>
<nullable>
The request payload.
data external:Readable <optional>
<nullable>
Readable stream representing file data to be uploaded.
headers RequestHeaders <optional>
<nullable>
Additional headers.
pipe external:Writable <optional>
Writable stream representing file data to be saved.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:

<private> _revokeAccess()

Set the authentication tokens for this connection.

Do not call this function directly.
Source:

<private> _setTokens(tokens)

Set the authentication tokens for this connection.

Do not call this method directly.
Parameters:
Name Type Description
tokens AuthTokens The authentication tokens.
Source:
Fires:

<private> _trackEvent(event)

The internal tracker for remote events.

Do not call this method directly.
Parameters:
Name Type Description
event Object The event to push.
Source:

copyFile(id, parent_id, name, done, config)

Copy a File.

Used to create a copy of a file in another folder. The original version of the file will not be altered.
Parameters:
Name Type Argument Description
id number The file's ID.
parent_id number The destination parent folder's ID.
name string The destination file's name. Can be null.
done requestCallback The callback to invoke (with possible errors) when the request returns.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

copyFolder(id, parent_id, name, done, config)

Copy a Folder.

Used to create a copy of a folder in another folder. The original version of the folder will not be altered.
Parameters:
Name Type Argument Description
id number The source folder's ID.
parent_id number The destination parent folder's ID.
name string <nullable>
The destination folder's name.
done requestCallback The callback to invoke (with possible errors) when the request returns.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

createFolder(name, parent_id, done, config)

Create a New Folder.

Used to create a new empty folder. The new folder will be created inside of the specified parent folder.
Parameters:
Name Type Argument Description
name string The folder's name.
parent_id number The parent folder's ID.
done requestCallback The callback to invoke (with possible errors) when the request returns.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

deleteFile(id, done, headers, config)

Delete a file.

Discards a file to the trash. The etag of the file can be included as an header[If-Match] header to prevent race conditions.
Parameters:
Name Type Argument Description
id number The file's ID.
done requestCallback The callback to invoke (with possible errors) when the request returns.
headers RequestHeaders <optional>
<nullable>
Additional headers.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

deleteFileVersion(id, version, done, headers, config)

Delete an Old Version of a File.

Discards a specific file version to the trash.
Parameters:
Name Type Argument Description
id number The file's ID.
version number File version to promote.
done requestCallback The callback to invoke (with possible errors) when the request returns.
headers RequestHeaders <optional>
<nullable>
Additional headers.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

deleteFolder(id, opts, done, headers, config)

Delete a Folder.

Used to delete a folder. A recursive parameter must be included in order to delete folders that have items inside of them. An optional header[If-Match] header can be included to ensure that client only deletes the folder if it knows about the latest version.
Parameters:
Name Type Argument Description
id number The folder's ID.
opts external:OptsDeleteFolder <nullable>
Options to control recursive delete.
done requestCallback The callback to invoke (with possible errors) when the request returns.
headers RequestHeaders <optional>
<nullable>
Additional headers.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

deleteTrashedFile(id, done, config)

Permanently Delete a Trashed File.

Permanently deletes an item that is in the trash. The item will no longer exist in Box. This action cannot be undone.
Parameters:
Name Type Argument Description
id number The folder's ID.
done requestCallback The callback to invoke (with possible errors) when the request returns.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

deleteTrashedFolder(id, done, config)

Permanently Delete a Trashed Folder.

Permanently deletes an item that is in the trash. The item will no longer exist in Box. This action cannot be undone.
Parameters:
Name Type Argument Description
id number The folder's ID.
done requestCallback The callback to invoke (with possible errors) when the request returns.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

getAuthURL() → {string}

Get the authentication URL to manually navigate to.

The returned URL should be provided to the end user when running in standalone mode.
Source:
Returns:
The authentication URL.
Type
string

getFile(id, version, dest, done, config)

Download a File.

Retrieves the actual data of the file. An optional opts.version parameter can be set to download a previous version of the file.
Parameters:
Name Type Argument Description
id number The file's ID.
version number File version to download. Can be null (meaning get the latest).
dest string Full path to where the file should be saved.
done getFileCallback The callback to invoke (with possible errors) when the request returns.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

getFileComments(id, done, config)

View the Comments on a File.

Retrieves the comments on a particular file, if any exist.
Parameters:
Name Type Argument Description
id number The file's ID.
done requestCallback The callback to invoke (with possible errors) when the request returns.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

getFileInfo(id, done, headers, config)

Get Information About a File.

Used to retrieve the metadata about a file.
Parameters:
Name Type Argument Description
id number The file's ID.
done requestCallback The callback to invoke (with possible errors) when the request returns.
headers RequestHeaders <optional>
<nullable>
Additional headers.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

getFileTasks(id, done, config)

Get the tasks for a file.

Retrieves all of the tasks for given file.
Parameters:
Name Type Argument Description
id number The file's ID.
done requestCallback The callback to invoke (with possible errors) when the request returns.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

getFileThumbnail(id, opts, dest, done, config)

Get a Thumbnail for a File.

Retrieves a thumbnail, or smaller image representation, of this file. Sizes of 32x32, 64x64, 128x128, and 256x256 can be returned. Currently thumbnails are only available in .png format and will only be generated for image file formats.
Parameters:
Name Type Argument Description
id number The file's ID.
opts external:OptsGetFileThumbnail Thumbnail options.
dest string Full path to where the file should be saved.
done getFileCallback The callback to invoke (with possible errors) when the request returns.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

getFileVersions(id, done, config)

View Versions of a File.

If there are previous versions of this file, this method can be used to retrieve metadata about the older versions.
Parameters:
Name Type Argument Description
id number The file's ID.
done requestCallback The callback to invoke (with possible errors) when the request returns.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

getFolderCollaborations(id, done, config)

View a Folder’s Collaborations.

Use this to get a list of all the collaborations on a folder i.e. all of the users that have access to that folder.
Parameters:
Name Type Argument Description
id number The folder's ID.
done requestCallback The callback to invoke (with possible errors) when the request returns.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

getFolderInfo(id, done, headers, config)

Get Information About a Folder.

Retrieves the full metadata about a folder, including information about when it was last updated as well as the files and folders contained in it. The root folder of a Box account is always represented by the id “0″.
Parameters:
Name Type Argument Description
id number The folder's ID.
done requestCallback The callback to invoke (with possible errors) when the request returns.
headers RequestHeaders <optional>
<nullable>
Additional headers.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

getFolderItems(id, opts, done, config)

Retrieve a Folder’s Items.

Retrieves the files and/or folders contained within this folder without any other metadata about the folder. Any attribute in the full files or folders objects can be passed in with the opts.fields parameter to get specific attributes, and only those specific attributes back; otherwise, the mini format is returned for each item by default. Multiple attributes can be passed in separated by commas e.g. opts.fields=name,created_at. Paginated results can be retrieved using the opts.limit and opts.offset parameters.
Parameters:
Name Type Argument Description
id number The folder's ID.
opts external:OptsFLO <nullable>
Request options.
done requestCallback The callback to invoke (with possible errors) when the request returns.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

getTrashedFile(id, done, config)

Get a Trashed File.

Retrieves an item that has been moved to the trash.
Parameters:
Name Type Argument Description
id number The folder's ID.
done requestCallback The callback to invoke (with possible errors) when the request returns.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

getTrashedFolder(id, done, config)

Get a Trashed Folder.

Retrieves an item that has been moved to the trash.
Parameters:
Name Type Argument Description
id number The folder's ID.
done requestCallback The callback to invoke (with possible errors) when the request returns.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

getTrashedItems(opts, done, config)

Get the Items in the Trash.

Retrieves the files and/or folders that have been moved to the trash. Any attribute in the full files or folders objects can be passed in with the opts.fields parameter to get specific attributes, and only those specific attributes back; otherwise, the mini format is returned for each item by default. Multiple attributes can be passed in separated by commas e.g. opts.fields='name,created_at'. Paginated results can be retrieved using the opts.limit and opts.offset parameters.
Parameters:
Name Type Argument Description
opts external:OptsFLO <nullable>
Request options.
done requestCallback The callback to invoke (with possible errors) when the request returns.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

isAuthenticated() → {boolean}

Determine id the connection has been authenticated.
Source:
Returns:
True if authenticated.
Type
boolean

promoteFileVersion(id, version, done, config)

Promote an Old Version of a File.

If there are previous versions of this file, this method can be used to promote one of the older versions to the top of the stack. This actually mints a copy of the old version and puts it on the top of the versions stack. The file will have the exact same contents, the same SHA1/etag, and the same name as the original. Other properties such as comments do not get updated to their former values.
Parameters:
Name Type Argument Description
id number The file's ID.
version number File version to promote.
done requestCallback The callback to invoke (with possible errors) when the request returns.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

ready(callback)

Wait for a connection to get ready.
Parameters:
Name Type Description
callback optionalErrorCallback The callback with an optional err argument, to be invoked once ready.
Source:

restoreTrashedFile(id, name, parent_id, done, config)

Restore a Trashed Item.

Restores an item that has been moved to the trash. Default behavior is to restore the item to the folder it was in before it was moved to the trash. If that parent folder no longer exists or if there is now an item with the same name in that parent folder, the new parent folder and/or new name will need to be included in the request.
Parameters:
Name Type Argument Description
id number The file's ID.
name string <nullable>
The file's name.
parent_id number The parent folder's ID. Can be null.
done requestCallback The callback to invoke (with possible errors) when the request returns.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

restoreTrashedFolder(id, name, parent_id, done, config)

Restore a Trashed Folder.

Restores an item that has been moved to the trash. Default behavior is to restore the item to the folder it was in before it was moved to the trash. If that parent folder no longer exists or if there is now an item with the same name in that parent folder, the new parent folder and/or new name will need to be included in the request.
Parameters:
Name Type Argument Description
id number The folder's ID.
name string <nullable>
The folder's name.
parent_id number <nullable>
The parent folder's ID.
done requestCallback The callback to invoke (with possible errors) when the request returns.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

Search a user's account.

Provides a simple way of finding items that are accessible in a given user’s Box account.
Parameters:
Name Type Argument Description
query string The search keyword.
opts OptsSearch <nullable>
Additional search options.
done requestCallback The callback to invoke (with possible errors) when the request returns.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

setConcurrency(concurrency)

Set the maximum concurrent requests that this connection will process.

A connection starts with a default concurrency of 7. Note that long-polling will consume a request from the request pool, so it is generally not a good idea to set this to less than 2.
Parameters:
Name Type Description
concurrency number The number of concurrent requests.
Source:
Throws:
Concurrency must be an integer > 0.
Type
RangeError

startLongPolling()

Start long-polling for events.
Source:
See:
Fires:

stopLongPolling()

Stop a running long-polling process.
Source:
See:

updateFile(id, fields, done, headers, config)

Update a file’s information.

Used to update individual or multiple fields in the file object, including renaming the file, changing it’s description, and creating a shared link for the file. To move a file, change the ID of its parent folder. An optional header[If-Match] header can be included to ensure that client only updates the file if it knows about the latest version.
Parameters:
Name Type Argument Description
id number The file's ID.
fields external:FieldsUpdateFile The fields to update.
done requestCallback The callback to invoke (with possible errors) when the request returns.
headers RequestHeaders <optional>
<nullable>
Additional headers.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

updateFolder(id, fields, done, headers, config)

Update Information About a Folder.

Used to update information about the folder. To move a folder, update the ID of its parent. To enable an email address that can be used to upload files to this folder, update the fields.folder_upload_email attribute. An optional header[If-Match] header can be included to ensure that client only updates the folder if it knows about the latest version.
Parameters:
Name Type Argument Description
id number The folder's ID.
fields external:FieldsUpdateFolder The fields to update.
done requestCallback The callback to invoke (with possible errors) when the request returns.
headers RequestHeaders <optional>
<nullable>
Additional headers.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

uploadFile(name, parent_id, opts, done, headers, config)

Upload a File.

Use the Uploads API to allow users to add a new file. The user can then upload a file by specifying the destination folder for the file. If the user provides a file name that already exists in the destination folder, the user will receive an error. You can optionally specify a header[Content-MD5] header with the SHA1 hash of the file to ensure that the file is not corrupted in transit.
Parameters:
Name Type Argument Description
name string The fully qualified path to the local file.
parent_id number The parent folder's ID.
opts OptsUploadFile <nullable>
Request options.
done requestCallback The callback to invoke (with possible errors) when the request returns.
headers RequestHeaders <optional>
<nullable>
Additional headers.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

uploadFileNewVersion(name, id, opts, done, headers, config)

Upload a New Version of a File.

This method is used to upload a new version of an existing file in a user’s account. An optional header[If-Match] header can be included to ensure that client only overwrites the file if it knows about the latest version. The filename on Box will remain the same as the previous version.
Parameters:
Name Type Argument Description
name string The fully qualified path to the local file.
id number The file's ID.
opts OptsUploadFileNewVersion <nullable>
Request options.
done requestCallback The callback to invoke (with possible errors) when the request returns.
headers RequestHeaders <optional>
<nullable>
Additional headers.
config RequestConfig <optional>
<nullable>
Configure the request behaviour.
Source:
See:

Events

"polling.end"

Fires when a running long-polling process ends.
Source:
See:

"polling.error"

Fires when an error occurs during long-polling.
Type:
  • Error
Source:
See:

"polling.event.EVENT"

Fires when an event is read from the event stream during long-polling.
Type:
Source:

"polling.ready"

Fires when a stream position has been fixed. All events from here onwards will be captured.
Source:

"tokens.error"

Fires when an error occurs while setting access tokens have been set on this connection. Could be triggered more than once, so listeners must deregister after receiving the first event. Preferably use the Connection#ready method.
Type:
  • Error
Source:
See:

"tokens.set"

Fires when access tokens have been set on this connection. Could be triggered more than once, so listeners must deregister after receiving the first event. Preferably use the Connection#ready method.
Type:
Source:
See:
Copyright © 2014-2015 Aditya Mukhopadhyay
Documentation generated by JSDoc 3.2.2 on Sun Jul 27 2014 08:27:52 GMT+0530 (IST) using the DocStrap template.