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.

Contributors

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 Keyboard, Mouse, Camera.
• 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.

USB Port Interface

Basic

 enum USBPortType { "storage", "keyboard", "mouse" };

 interface USBPort : EventTarget {
   readonly attribute DOMString id;
   readonly attribute DOMString name;
   readonly attribute USBPortType type;
   readonly attribute boolean connected;
 };

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.

name of type DOMString, readonly
The name of this USB port.

type of type USBPortType, readonly
The type of this USB port, value must be defined in the enum of USBPortType.

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

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 totalSpace;
   readonly attribute unsigned long long availableSpace;
   readonly attribute DOMString fileSystem;
            attribute EventHandler onAvailableSpaceChange;
   // Other possible hardware-dependent attributes.
 };

totalSpace of type unsigned long long, readonly
The total space of the USB storage device.

availableSpace of type unsigned long long, readonly
The available space of the USB storage device.

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

onAvailableSpaceChange of type EventHandler
Whenever the hardware detects a change on the available space, an simple event with the updated available space against the USB port should be fired.

Keyboard

 interface KeyboardUSBPort : USBPort {
   // Possible hardware-dependent attributes.
 };

Mouse

 interface MouseUSBPort : USBPort {
   // Possible hardware-dependent attributes.
 };

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.

Examples