File-transfer API
chevron down
 

File-transfer API

Variable: outbox

Type: Outbox

New in SDK 3.0

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

import { outbox } from "file-transfer";

outbox
   .enqueueFile("app.txt")
   .then((ft) => {
     console.log(`Transfer of $‌{ft.name} successfully queued.`);
   })
   .catch((error) => {
     console.log(`Failed to schedule transfer: $‌{error}`);
   })

Interface: Outbox

New in SDK 3.0

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

Methods

enqueue()

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

Returns: Promise

Enqueue a file to be transferred, where the file data is passed from application memory.

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

enqueueFile()

enqueueFile(file: string, name?: string | undefined)

Returns: Promise

Enqueue a file to be transferred, where the data to be transferred resides on the filesystem.

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

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

import { inbox } from "file-transfer";

function processAllFiles() {
   let fileName;
   while (fileName = inbox.nextFile()) {
     // process each file
     console.log("Received:", fileName);
   }
}
inbox.addEventListener("newfile", processAllFiles);
processAllFiles();

Find out more about this API in the File Transfer Guide

Interface: Inbox

A file transfer represents data sent by a peer file sender that transmits data with a filename

When a new file transfer is received, it is staged (stored locally, but not yet visible in the application's accessible file system). This interface allows the application to be notified of the reception of new files, and to transfer them to a location on the file system where they can be accessed with the FileSystem API.

Properties

onnewfile

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

Event handler for newfile events of this Inbox object.

Methods

nextFile()

nextFile(name?: string | undefined)

Returns: string or undefined

Accept the next file available, if any, in the Inbox and make it available in the application's file system.

If this function throws an error, the file stays in the Inbox, and the caller should retry after the condition that triggered the error has been corrected.

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.