Connect

AW4. Connect

Contains all the Connect API methods

Constructor

new Connect(options)

Parameters:
Name Type Description
options Object

Configuration parameters for Connect

Properties
Name Type Attributes Default Description
connectLaunchWaitTimeoutMs Number <optional>
 5000

How long to wait in milliseconds for Connect to launch. If we reach this timeout without a successful request to Connect, Connect will go to FAILED status.
id String <optional>
 "aspera-web"

The DOM 'id' of the plug-in object to be inserted.
containerId String <optional>

The DOM 'id' of an existing element to insert the plug-in element into (replacing its contents). If not specified, the plug-in is appended to the document body. Note that the plug-in must not be hidden in order to be loaded.
sdkLocation String <optional>
 "//d3gcli72yxqn2z.cloudfront.net/connect/v4"

Specifies the custom SDK location to check for Connect installers. It has to be in the following format: '//domain/path/to/connect/sdk'. If you are hosting your own SDK, then you must provide the location to your copy of the SDK. This points to the /v4 folder of the provided SDK. The URL provided must be in the same level of security as the web page (HTTP/HTTPS), HTTPS preferred.
pollingTime Number <optional>
 2000

How often in milliseconds we want to get updates of transfer status.
maxActivityOutstanding Number <optional>
 2

The maximum number of oustanding transfer activity requests allowed before being skipped.
extensionRequestTimeout Number <optional>
 86400000

How long to wait in milliseconds for extension requests to return before failing. Only applies to file and folder dialog APIs.
minVersion String <optional>

Minimum version of Connect required by the web application in order to work. Format: "3.9.0".
dragDropEnabled Boolean <optional>
 false

Enable drag and drop of files/folders into the browser.
connectMethod "http" | "extension" <optional>

Specify the preferred method of Connect communication. Default is "extension" for minVersion >= 3.9.0. Otherwise, default is "http".
Example
let options = {
  minVersion: "3.9.0",
  dragDropEnabled: true
}
let asperaWeb = new AW4.Connect(options) // returns instance of AW4.Connect

Methods

addEventListener(type, listener) → {null|Error}

Subscribe for Connect events. The first time the listener is called it will receive an event for each of the transfers already displayed in Connect, such that the listener will know the complete state of all transfers.

Parameters:
Name Type Description
type EVENT

The type of event to receive events for.
listener function

The function that will be called when the event occurs. Format:

function(eventType, data) { ... }

"transfer" event types return data format: AllTransfersInfo
Example
// create a transfer listener
function transferListener(type, allTransfersInfo) {
  if (type === AW4.Connect.EVENT.TRANSFER) {
    console.log('Received transfer event!')
    handleTransferEvent(allTransfersInfo) // do something with the transfers data
  }
}
asperaWeb.addEventListener(AW4.Connect.EVENT.TRANSFER, transferListener)

authenticate(authSpec, callbacks) → {null|Error}

Test authentication credentials against a transfer server.

This method is asynchronous.

Parameters:
Name Type Description
authSpec Object

Authentication credentials.

Options for authSpec (subset of TransferSpec):

  • remote_host
  • ssh_port
  • remote_user
  • remote_password
  • token
callbacks Callbacks

success and error functions to receive results.

Object returned to success callback: {}

getAllTransfers(callbacks, iterationTokenopt) → {null}

Get statistics for all transfers.

This method is asynchronous.

Parameters:
Name Type Attributes Default Description
callbacks Callbacks

success and error functions to receive results.

Object returned to success callback: AllTransfersInfo
iterationToken String <optional>
 '0'

If specified, return only transfers that have had activity since the last call.

getChecksum(options, callbacks) → {null}

Calculates checksum of the given chunk size of the file.

This method is asynchronous.

Parameters:
Name Type Description
options Object

Object with options needed for reading a chunk.

Options:

  • path (String) - Absolute path to the file we want to read the chunk from.
  • offset (Number) - Offset (in bytes) that we want to start reading the file.
  • chunkSize (Number) - The size (in bytes) of the chunk we want.
  • checksumMethod (String) - The hash method we want to apply on chunk. Allowed checksum methods are "md5", "sha1", "sha256", "sha512".
callbacks Callbacks

success and error functions to receive results.

Object returned to success callback:

{
  "checksumMethod" : "md5"
  "checksum" : "35cf801a..."
}

getStatus() → {STATUS}

Get current status of Connect.

getTransfer(transferId, callbacks) → {null}

Get statistics for a single transfer.

Parameters:
Name Type Description
transferId String

The ID (uuid) of the transfer to retrieve.
callbacks Callbacks

success and error functions to receive results.

Object returned to success callback: See TransferInfo

{
 "transfer_info": TransferInfo
}

initSession(applicationIdopt) → {Object}

Call this method after creating the AW4.Connect object. It is mandatory to call this function before making use of any other function of the API. If called more than once on the same instance, it will return an error.

Return format:

{
 "app_id": "MjY2ZTM0YWItMGM2NC00ODdhLWJkNzQtNzU0YzVjN2FjYjJj"
}
Parameters:
Name Type Attributes Description
applicationId String <optional>

An ID to represent this session. Transfers initiated during this session will be associated with the ID. To continue a previous session, use the same ID as before. Use a unique ID in order to keep transfer information private from other websites. IF not specified, an ID is automatically generated for you.

modifyTransfer(transferId, options, callbacks) → {null}

Change the speed of a running transfer.

This method is asynchronous.

Parameters:
Name Type Description
transferId String

The ID of the transfer to modify
options Object

A subset of TransferSpec

Options:

  • rate_policy
  • target_rate_kbps
  • min_rate_kbps
  • target_rate_cap_kbps
  • lock_rate_policy
  • lock_target_rate
  • lock_min_rate
callbacks Callbacks

success and error functions to receive results.

Object returned to success callback: TransferSpec

readAsArrayBuffer(options, callbacks) → {null|Error}

Read file as 64-bit encoded data.

This method is asynchronous.

Parameters:
Name Type Description
options Object

Object with options needed for reading the file.

Options:

  • path (String) - Absolute path to the file we want to read.
callbacks Callbacks

success and error functions to receive results.

Object returned to success callback:

{
  "type" : "image/pjpeg",
  "data" : "/9j/4AAQSkZ..."
}

readChunkAsArrayBuffer(options, callbacks) → {null|Error}

Read 64-bit encoded chunk from file.

This method is asynchronous.

Parameters:
Name Type Description
options Object

Object with options needed for reading a chunk.

Options:

  • path (String) - Absolute path to the file we want to read the chunk from.
  • offset (Number) - Offset (in bytes) that we want to start reading the file.
  • chunkSize (Number) - The size (in bytes) of the chunk we want.
callbacks Callbacks

success and error functions to receive results.

Object returned to success callback:

{
  "type" : "image/pjpeg",
  "data" : "/9j/4AAQSkZ..."
}

removeEventListener(typeopt, listeneropt) → {Boolean}

Unsubscribe from Aspera Web events. If type is not specified, all versions of the listener with different types will be removed. If listener is not specified, all listeners for the type will be removed. If neither type nor listener are specified, all listeners will be removed.

Return values:

  • true - If we could find a listener with the parameters provided.
  • false - If we could not find a listener for the parameters provided.
Parameters:
Name Type Attributes Description
type EVENT <optional>

The type of event to stop receiving events for.
listener function <optional>

The function used to subscribe in AW4.Connect#addEventListener

removeTransfer(transferId, callbacks) → {null}

Remove the transfer - terminating it if necessary - from Connect.

This method is asynchronous.

Parameters:
Name Type Description
transferId String

The ID(uuid) of the transfer to delete.
callbacks Callbacks

success and error functions to receive results.

Object returned to success callback: TransferSpec

resumeTransfer(transferId, options, callbacks) → {null}

Resume a transfer that was stopped.

This method is asynchronous.

Parameters:
Name Type Description
transferId String

The ID(uuid) of the transfer to resume
options Object

A subset of TransferSpec

Options:

  • token
  • cookie
  • authentication
  • remote_user
  • remote_password
  • content_protection_passphrase
callbacks Callbacks

success and error functions to receive results.

Object returned to success callback: TransferSpec

setDragDropTargets(cssSelector, optionsopt, listener) → {null|Error}

Sets drag and drop options for the element given in the cssSelector. Please note that the dragDropEnabled option must have been set to true when creating the AW4.Connect object.

This method is asynchronous.

Parameters:
Name Type Attributes Description
cssSelector String

CSS selector for drop targets.
options Object <optional>

Drag and drop options for these targets.

Options:

  • dragEnter (Boolean) - true if drag enter event should trigger the listener. Default: false.
  • dragOver (Boolean) - true if drag over event should trigger the listener. Default: false.
  • dragLeave (Boolean) - true if drag leave event should trigger the listener. Default: false.
  • drop (Boolean) - true if drop event should trigger the listener. Default: true.
  • allowPropagation (Boolean) - true allow further propagation of events. Default: false.
listener function

Function to be called when each of the events occurs.

Format:

function(event, files) { ... }
  • event (Object) - DOM Event object as implemented by the browser.
  • files (Object) - See dataTransfer. This is only valid on drop events.

showAbout(callbacks) → {null}

Displays the IBM Aspera Connect "About" window.

This method is asynchronous.

Parameters:
Name Type Description
callbacks Callbacks

success and error functions to receive results.

Object returned to success callback: {}

showDirectory(transferId, callbacks) → {null}

Open the destination directory of the transfer using the system file browser.

This method is asynchronous.

Parameters:
Name Type Description
transferId String

The ID(uuid) of the transfer to show files for.
callbacks Callbacks

success and error functions to receive results.

Object returned to success callback: {}

showPreferences(callbacks) → {null}

Displays the IBM Aspera Connect "Preferences" window.

This method is asynchronous.

Parameters:
Name Type Description
callbacks Callbacks

success and error functions to receive results.

Object returned to success callback: {}

showPreferencesPage(options, callbacks) → {null}

Displays the IBM Aspera Connect "Preferences" window opened to a specifiic page.

This method is asynchronous

Parameters:
Name Type Description
options options

Options used when opening preferences.

Options:

  • page (String) - general, transfers, network, bandwidth, security
callbacks Callbacks

success and error functions to receive results.

Object returned to success callback: {}

showSaveFileDialog(callbacks, optionsopt) → {null|Error}

Displays a file chooser dialog for the user to pick a "save-to" path.

This method is asynchronous.

Parameters:
Name Type Attributes Description
callbacks Callbacks

success and error functions to receive results.

Object returned to success callback: See dataTransfer.
options Object <optional>

File chooser options

Options:

  • allowedFileTypes (FileFilters) - Filter the files displayed by file extension.
  • suggestedName (String) - The file name to pre-fill the dialog with.
  • title (String) - The name of the dialog window.

showSelectFileDialog(callbacks, optionsopt) → {null|Error}

Displays a file browser dialog for the user to select files. The select file dialog call(s) may be separated in time from the later startTransfer(s) call, but they must occur in the same Connect session.

This method is asynchronous.

Parameters:
Name Type Attributes Description
callbacks Callbacks

success and error functions to receive results.

Object returned to success callback: See dataTransfer.
options Object <optional>

File chooser options

Options:

  • allowedFileTypes (FileFilters) - Filter the files displayed by file extension.
  • allowMultipleSelection (Boolean) - Allow the selection of multiple files. Default: true.
  • title (String) - The name of the dialog window.

showSelectFileDialogPromise(optionsopt) → {Promise.<dataTransfer>}

Displays a file browser dialog for the user to select files. The select file dialog call(s) may be separated in time from the later startTransfer(s) call, but they must occur in the same Connect session.

Parameters:
Name Type Attributes Description
options Object <optional>

File chooser options

Options:

  • allowedFileTypes (FileFilters) - Filter the files displayed by file extension.
  • allowMultipleSelection (Boolean) - Allow the selection of multiple files. Default: true.
  • title (String) - The name of the dialog window.

showSelectFolderDialog(callbacks, optionsopt) → {null|Error}

Displays a file browser dialog for the user to select directories. The select folder dialog call(s) may be separated in time from the later startTransfer(s) call, but they must occur in the same Connect session.

This method is asynchronous.

Parameters:
Name Type Attributes Description
callbacks Callbacks

success and error functions to receive results.

Object returned to success callback: See dataTransfer.
options Object <optional>

File chooser options

Options:

  • allowMultipleSelection (Boolean) - Allow the selection of multiple folders. Default: true.
  • title (String) - The name of the dialog window.

showSelectFolderDialogPromise(optionsopt) → {Promise.<dataTransfer>}

Displays a file browser dialog for the user to select directories. The select folder dialog call(s) may be separated in time from the later startTransfer(s) call, but they must occur in the same Connect session.

Parameters:
Name Type Attributes Description
options Object <optional>

File chooser options

Options:

  • allowMultipleSelection (Boolean) - Allow the selection of multiple folders. Default: true.
  • title (String) - The name of the dialog window.

showTransferManager(callbacks) → {null}

Displays the IBM Aspera Connect "Activity" window.

This method is asynchronous.

Parameters:
Name Type Description
callbacks Callbacks

success and error functions to receive results.

Object returned to success callback: {}

showTransferMonitor(transferId, callbacks) → {null}

Displays the IBM Aspera Connect "Transfer Monitor" window for the transfer.

This method is asynchronous.

Parameters:
Name Type Description
transferId String

The ID(uuid) of the corresponding transfer.
callbacks Callbacks

success and error functions to receive results.

Object returned to success callback: {}

start() → {null|Error}

Start looking for Connect. Please note that this is called internally by AW4.Connect#initSession and it should only be called directly after a call to AW4.Connect#stop.

startTransfer(transferSpec, connectSpec, callbacks) → {Object|Error}

Initiates a single transfer. Call AW4.Connect#getAllTransfers to get transfer statistics, or register an event listener through AW4.Connect#addEventListener.

Return format:

{
 "request_id": "bb1b2e2f-3002-4913-a7b3-f7aef4e79132"
}

The request_id, which is returned immediately, may be used for matching this transfer with its events.

Parameters:
Name Type Description
transferSpec TransferSpec

Transfer parameters.
connectSpec ConnectSpec

Connect options
callbacks Callbacks

success and error functions to receive results. This call is successful if Connect is able to start the transfer. Note that an error could still occur after the transfer starts, e.g. if authentication fails. Use AW4.Connect#addEventListener to receive notifications about errors that occur during a transfer session. This call fails if validation fails or the user rejects the transfer.

Object returned to success callback: TransferSpecs

startTransferPromise(transferSpec, connectSpec) → {Promise.<TransferSpecs>}

Initiates a single transfer. Call AW4.Connect#getAllTransfers to get transfer statistics, or register an event listener through AW4.Connect#addEventListener.

Parameters:
Name Type Description
transferSpec TransferSpec

Transfer parameters.
connectSpec ConnectSpec

Connect options

startTransfers(transferSpecs, callbacks) → {Object|Error}

Initiates one or more transfers (currently only the first transfer_spec is used). It's recommended to instead use AW4.Connect#startTransfer. Call AW4.Connect#getAllTransfers to get transfer statistics, or register an event listener through AW4.Connect#addEventListener.

This method is asynchronous.

Return format:

{
 "request_id": "bb1b2e2f-3002-4913-a7b3-f7aef4e79132"
}

The request_id, which is returned immediately, may be used for matching this transfer with its events.

Parameters:
Name Type Description
transferSpecs Object

Transfer parameters.

Format: See TransferSpecs
callbacks Callbacks

success and error functions to receive results. This call is successful if Connect is able to start the transfer. Note that an error could still occur after the transfer starts, e.g. if authentication fails. Use AW4.Connect#addEventListener to receive notifications about errors that occur during a transfer session. This call fails if validation fails or the user rejects the transfer.

Object returned to success callback: TransferSpecs

stop() → {Boolean}

Stop all requests from Connect to restart activity, please create a new AW4.Connect object or call AW4.Connect#start.

stopTransfer(transferId, callbacks) → {null}

Terminate the transfer. Use AW4.Connect#resumeTransfer to resume.

This method is asynchronous.

Parameters:
Name Type Description
transferId String

The ID(uuid) of the transfer to stop.
callbacks Callbacks

success and error functions to receive results.

Object returned to success callback: {}

testSshPorts(options, callbacks) → {null}

Test that Connect can open a TCP connection to remote_host over the given ssh_port.

This method is asynchronous.

Parameters:
Name Type Description
options Object

Test options. Options:

  • remote_host (String) - Domain name of the transfer server.
  • ssh_port (Number) - SSH port. Default: 33001.
  • timeout_sec (Number) - Timeout value in seconds. Default: 3.
callbacks Callbacks

success and error functions to receive results.

Object returned to success callback: {}

version(callbacks) → {null}

Get the IBM Aspera Connect version and installation context.

This method is asynchronous.

Parameters:
Name Type Description
callbacks Callbacks

success and error functions to receive results.

Object returned to success callback:

{
  "system_wide": false,
  "version": "3.9.1.171801"
}