File-transfer API
chevron down
back search icon cancel search
 
 

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

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.

Parameter: data Data to be transferred. The data are copied to a system buffer and any changes made to the data after calling enqueue will not affect the file transfer. The representation of the data in the file depends on the options. If no options are passed, data must be an ArrayBuffer or ArrayBufferView and the file will contain the buffer's binary data as stored in memory. If options are passed with encoding equal to "ascii" or "utf-8", data must be a string and the file will contain the string characters encoded with the specified encoding. If options are passed with encoding equal to "cbor", data may be of any type and will be encoded as CBOR, according to the type encoding rules documented in the cbor module. If options are passed with encoding equal to "json", data may be of any type and will be encoded as JSON, using the same conventions as JSON.stringify(). If the data cannot be encoded, the returned Promise will be rejected.

enqueueFile()

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

Returns: Promise<FileTransfer>

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

Parameter: name If specified, the name under which the file data will be sent. If not specified, the file's base name (i.e. the file name without any path components or trailing separators) is used.

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.

Parameter: name Name under which the file, if any, will be available in the file system. If this parameter is omitted, the file will be available in the file system under the filename associated with the file by the sender.

Throws: Throws an error if the file could not be moved/copied to the application's file system as requested. In particular if the application has an open file descriptor for a file with the same name as the requested destination name.

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
FS API
Geolocation API
next