Goals

Provide DOM API access to the input ports of devices. With Input Port API, application developers are able to browse available input ports of the current device, retrieve media content provided by a particular port, detect whether an input port has connected to a source provider.

Contributors

Shih-Chiang Chien, Shelly Lin, James Cheng

Status

• bug 1028799

Features

• Enumerate available input ports on the current device. Supported types of input ports include A/V, DisplayPort and HDMI.
• Retrieve media content from an input port, provided by its source provider. Presented as a MediaStream object.
• Support hot-plug detection on each input port.

Proposed API

Basic Port Interface

 [Pref="dom.inputport.enabled", CheckPermissions="inputport", AvailableIn=CertifiedApps]
 interface InputPort : EventTarget {
   readonly attribute DOMString id;
   readonly attribute MediaStream stream;
   readonly attribute boolean connected;
   attribute EventHandler onconnect;
   attribute EventHandler ondisconnect;
 };

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

This idea is referenced from the attribute deviceId of MediaDevice.

stream of type MediaStream, readonly
The media content of this input port, represented as a MediaStream object.
The reference of this object remains unchanged during the life time of its belonging InputPort; Dispatch of connect or disconnect event responses to the state of hardware connection, isolating to the fact of whether the media content is playable or not; Behaviour of stream with non-playable content should be the same as behavior of muted media tracks, described in section "Life-cycle and Media Flow".

connected of type boolean, readonly
True if this input port is connected to a source provider, and vice versa.

onconnect of type EventHandler,
ondisconnect of type EventHandler,
Whenever the hardware detects a connection/disconnection of this input port, UA must queue a task to fire a simple event name connect/disconnect at its InputPort object.

Specific Port Interfaces

A/V

In reality, a specific input port has its specific attributes and methods, our goal is to collect those "common" cases as much as possible. However, with limit information, we will not focus on implementing hardware dependent attributes and methods in this draft.

 [Pref="dom.inputport.enabled", CheckPermissions="inputport", AvailableIn=CertifiedApps]
 interface AVInputPort : InputPort {
   // Possible hardware-dependent attributes.
 };

HDMI/DisplayPort

 [Pref="dom.inputport.enabled", CheckPermissions="inputport", AvailableIn=CertifiedApps] 
 interface HDMIInputPort : InputPort {
   // Possible hardware-dependent attributes.
 };

 [Pref="dom.inputport.enabled", CheckPermissions="inputport", AvailableIn=CertifiedApps]
 interface DisplayPortInputPort : InputPort {
   // Possible hardware-dependent attributes.
 };

InputPortManager

This will be an object in window.navigator named InputPortManager with the following interface:

 partial interface Navigator {
   [Throws, Pref="dom.inputport.enabled", CheckPermissions="inputport", AvailableIn=CertifiedApps]
   readonly attribute InputPortManager inputPortManager;
 };

 [Pref="dom.inputport.enabled", CheckPermissions="inputport", AvailableIn=CertifiedApps]
 interface InputPortManager {
   [Throws]
   Promise<sequence<InputPort>> getInputPorts();
 };

getInputPorts
This method makes a request to retrieve all the available input ports on a 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 InputPort elements belong to the InputPortManager.

Examples

  var inputPortMgr = navigator.inputPortManager;
  inputPortMgr.getInputPorts().then(
    function(aPorts) {
      for (var i=0; i < aPorts.length; ++i) {
        var port = aPorts[i];
        if(port instanceof HDMIInputPort) {
          //....
        }
      }
    },
    function(aError) {
      //error
    }
  );