User:Seanlin/USB Manager API

Goals

Provide DOM API access to the USB ports of devices. With USB Manager API, application developers are able to browse available USB ports of the current device, and detect whether a USB port has connected.

Status

This document is merely a public working draft of a potential specification. It has no official standing of any kind and does not represent the support or consensus of any standards organisation.

Features

• Enumerate available USB ports on the current device. So far supported types of USB ports include Storage.
• Support hot-plug detection on each USB port.

Proposed API

Navigator Interface

 partial interface Navigator {
   readonly attribute USBManager usb;
 };

USBManager Interface

 interface USBManager : EventTarget {
   Promise getUSBPorts ();
   attribute EventHandler onconnect;
   attribute EventHandler ondisconnect;
 };

getUSBPorts
This method makes a request to retrieve all the available USB ports on the device. It returns a new Promise that will be used to notify the caller about the result of the operation, which is an array of USBPort elements.

onconnect of type EventHandler
ondisconnect of type EventHandler
Whenever the hardware detects connection/disconnection, a USBConnectEvent or USBDisconnectEvent against this USB port should be fired.

Basic USB Port Interface

 enum USBPortType { "storage" };

 interface USBPort : EventTarget {
   readonly attribute DOMString id;
   readonly attribute USBPortType type;
   readonly attribute boolean connected;
            attribute EventHandler onconnect;
            attribute EventHandler ondisconnect;
 };

id of type DOMString, readonly
The unique identifier for the represented USB port. It MUST be unique to the application, and persistent between application sessions.

type of type USBPortType, readonly
The type of this USB port, value must be defined in the enum of USBPortType. So far only "storage" is supported. (This might be extended in the future.)

connected of type boolean, readonly
True if this USB port is connected, and vice versa.

onconnect of type EventHandler
ondisconnect of type EventHandler
Whenever the hardware detects connection/disconnection, a USBConnectEvent or USBDisconnectEvent against this USB port should be fired.

Specific USB Port Interface

Storage

In reality, a specific USB port may have its specific attributes and methods. And our goal is to collect the "common" ones as many as possible. However, with limited information, we will not focus on implementing hardware dependent members in this draft.

 interface StorageUSBPort : USBPort {
   readonly attribute unsigned long long totalVolume;
   readonly attribute unsigned long long availableVolume;
   readonly attribute DOMString fileSystem;
   // Other possible hardware-dependent attributes.
 };

totalVolume of type unsigned long long, readonly
The total volume of the USB storage device.

availableVolume of type unsigned long long, readonly
The available volume of the USB storage device.

fileSystem of type DOMString, readonly
The type of the file system, e.g. FAT32, NTFS, etc.

USB Port Connect/Disconnect Event Interface

 interface USBConnectEvent : Event {
   readonly attribute USBPort usbPort;
 };

 interface USBDisconnectEvent : Event {
   readonly attribute USBPort usbPort;
 };

usbPort of type USBPort, readonly
The connected/disconnected USB port.