File-transfer API
chevron down
back search icon cancel search
 
 

File-transfer API

Variable: outbox

Type: Outbox

The File Transfer API Outbox allows companions to enqueue new file transfers and list currently queued file transfers.

import { outbox } from "file-transfer";
outbox.enqueue(filename, data)
   .then((ft) => {
     console.log(`Transfer of ${ft.name} successfully queued.`);
   })
   .catch((error) => {
     console.log(`Failed to queue ${filename}: ${error}`);
   })

Interface: Outbox

The Outbox allows companions to enqueue new file transfers and list currently queued file transfers.

Methods

enqueue()

enqueue(name: string, data: ArrayBuffer | ArrayBufferView)

Returns: Promise<FileTransfer>

Enqueue a file to be transferred.

If a file transfer with the same name is already in the queue (and therefore in the pending or transferring state), it will be canceled automatically and a new entry will be created for the new file. In that case, the readyState property of the existing file transfer will become canceled (and a change event emitted) if and when the promise is resolved.

The name of the file must be between 1 and 64 characters from the following set: a-z, A-Z, 0-9, !, #, $, %, &, ', (, ), -, @, ^, _, `, `{`, `}`, `~`, `+`, `,`, `.`, `;`, `=`,, The name must not be . or start with ... If the name is invalid, the promise will be rejected.

The data will be copied to a system buffer and any changes made to the data after calling enqueue will not affect the file transfer.

enumerate()

Returns: Promise<FileTransfer[]>

Obtain a list of file transfers currently in the queue.

NOTE: only file transfers in the pending or transferring state are in the queue.

Variable: inbox

Type: Inbox

New in SDK 3.0

The File Transfer API offers an incoming inbox queue of file transfers.

import { inbox } from "file-transfer";

// Process the inbox queue for files, and read their contents as text
async function processAllFiles() {
   let file;
   while ((file = await inbox.pop())) {
     const payload = await file.text();
     console.log(`file contents: $‌{payload}`);
   }
}

// Process new files as they are received
inbox.addEventListener("newfile", processAllFiles);

// Also process any files that arrived when the companion wasn’t running
processAllFiles()

Find out more about this API in the File Transfer Guide

Interface: Inbox

New in SDK 3.0

A file transfer represents data sent by a peer file sender that transmits data with a filename (see FileTransfer Outbox).

When a new file transfer is received, it is stored locally until the companion application is ready to receive it. This interface allows the application to be notified of the reception of incoming files.

Properties

onnewfile

((this: Inbox, event: Event) => any) or undefined

Event handler for newfile events of this Inbox object.

Methods

pop()

Returns: Promise<InboxItem or null>

Accept the next file available, if any, in the Inbox.

Interface: InboxItem

New in SDK 3.0

Item that represents a file received in the transfer inbox.

Properties

readonly bodyUsed

boolean

Indicates whether the file contents have been consumed or not. If this property is true, the body data is no longer accessible through any of the body-consuming methods, which would throw an exception if called. The body-consuming methods are:

  • arrayBuffer()
  • cbor()
  • json()
  • text()
readonly length

number

Size of the file data, in bytes.

readonly name

string

Name under which the file data was sent.

Methods

arrayBuffer()

Returns: Promise<ArrayBuffer>

Consume the file contents and load it into an ArrayBuffer.

cbor()

Returns: Promise<any>

Consume the file contents and parse it as CBOR.

json()

Returns: Promise<any>

Consume the file contents and parse it as JSON.

text()

Returns: Promise<string>

Consume the file contents and decode it as UTF-8 into a string.

Interface: FileTransfer

Properties

readonly name

string

Name of the file being transferred.

onchange

((this: FileTransfer, event: Event) => any) or undefined

Event handler for change events emitted by this FileTransfer object.

readonly readyState

"error" or "pending" or "transferring" or "transferred" or "canceled"

Current state of the file transfer.

  • pending means that the transfer has not started yet
  • transferring means that the transfer is in progress
  • transferred means that the transfer is complete
  • canceled means that the transfer has been canceled because cancel was called or because a new file with the same name was enqueued.
  • error means that the transfer failed because of an error that is not recoverable.

NOTE: the error state should be a very rare state, because the system takes care of retransmissions for all error conditions that are recoverable.

Methods

cancel()

Returns: void

This method requests that the transfer be canceled. This will cause the state of the file transfer to become canceled immediately.

If the file transfer is in the transferred, canceled or error state, this method has no effect.

previous
Fetch API
Form-data API
next