Abstract

This specification defines an API to enable web content to access external presentation-type displays and use them for presenting web content.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document is a work in progress and is subject to change. Some sections are still incomplete or underspecified. Security and privacy considerations need to be adjusted based on feedback and experience. Some open issues are noted inline; please check the group's issue tracker on GitHub for all open issues. Feedback from early experimentations is encouraged to allow the Second Screen Presentation Working Group to evolve the specification based on implementation issues.

This document was published by the Second Screen Presentation Working Group as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-secondscreen@w3.org (subscribe, archives). All comments are welcome.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 September 2015 W3C Process Document.

Table of Contents

1. Introduction

This section is non-normative.

This specification aims to make presentation displays such as projectors or connected TVs, available to the Web and takes into account displays that are attached using wired (HDMI, DVI, or similar) and wireless technologies (Miracast, Chromecast, DLNA, AirPlay, or similar).

Devices with limited screen size lack the ability to show content to a larger audience, for example, a group of colleagues in a conference room, or friends and family at home. Showing content on an external large presentation display helps to improve the perceived quality and impact of the presented content.

At its core, this specification enables an exchange of messages between a page that acts as the controller and another page that represents the presentation shown in the presentation display. How the messages are transmitted is left to the UA in order to allow the use of presentation display devices that can be attached in a wide variety of ways. For example, when a presentation display device is attached using HDMI or Miracast, the same UA that acts as the controller renders the presentation. Instead of displaying the presentation in another window on the same device, however, it can use whatever means the operating system provides for using the external presentation displays. In such a case, both the controller and presentation run on the same UA and the operating system is used to route the presentation display output to the presentation display. This is commonly referred to as the 1-UA case. This specification imposes no requirements on the presentation display devices connected in such a manner.

If the presentation display is able to render HTML documents and communicate with the controller, the controller does not need to render the presentation. In this case, the UA acts as a proxy that requests the presentation display to show and render the presentation itself. This is commonly referred to as the 2-UA case. This way of attaching to displays could be enhanced in the future by defining a standard protocol for delivering these types of messages that display devices could choose to implement.

The API defined here is intended to be used with UAs that attach to presentation display devices through any of the above means.

2. Use cases and requirements

Use cases and requirements are captured in a separate Presentation API Use Cases and Requirements document.

3. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, SHOULD, and SHOULD NOT are to be interpreted as described in [RFC2119].

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and terminate these steps") are to be interpreted with the meaning of the key word ("MUST", "SHOULD", "MAY", etc.) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)

3.1 Conformance Classes

This specification describes the conformance criteria for two classes of user agents.

Controlling user agent

Web browsers that conform to the specifications of a controlling user agent must be able to start and control presentations by providing a controlling browsing context as described in this specification. This context implements the Presentation, PresentationConnection, PresentationConnectionAvailableEvent, and PresentationRequest interfaces.

Receiving user agent

Web browsers that conform to the specifications of a receiving user agent must be able to render presentations by providing a receiving browsing context as described in this specification. This context implements the Presentation, PresentationConnection, PresentationConnectionAvailableEvent, and PresentationReceiver interfaces.

One user agent may act both as a controlling user agent and as a receiving user agent, if it provides both browsing contexts and implements all of their required interfaces. This can happen when the same user agent is able to host the controlling browsing context and the receiving browsing context for a presentation, as in the 1-UA implementation of the API.

4. Terminology

The terms browsing context, event handler, event handler event type, firing an event, firing a simple event navigate, queue a task, trusted event, allowed to show a popup are defined in [HTML5].

This document provides interface definitions using the Web IDL standard ([WEBIDL]). The terms Promise, ArrayBuffer, ArrayBufferView and DOMException are defined in [WEBIDL].

The terms resolving a Promise, and rejecting a Promise are used as explained in [PROMGUIDE].

The term URL is defined in the WHATWG URL standard [URL].

The term Blob is defined in the File API specification [FILEAPI].

The term RTCDataChannel is defined in the WebRTC API specification ([WEBRTC]).

5. Examples

This section shows example codes that highlight the usage of main features of the Presentation API. In these examples, controller.html implements the controller and presentation.html implements the presentation. Both pages are served from the domain http://example.org (http://example.org/controller.html and http://example.org/presentation.html). Please refer to the comments in the code examples for further details.

5.1 Monitor availability of presentation displays example

Example 1
<!-- controller.html -->
<button id="castBtn" style="display: none;">Cast</button>
<script>
  // it is also possible to use relative presentation URL e.g. "presentation.html"
  var presUrl = "http://example.com/presentation.html";
  // the cast button is visible if at least one presentation display is available
  var castBtn = document.getElementById("castBtn");
  // show or hide cast button depending on display availability
  var handleAvailabilityChange = function(available) {
    castBtn.style.display = available ? "inline" : "none";
  };
  // Promise is resolved as soon as the presentation display availability is
  // known.
  var request = new PresentationRequest(presUrl);
  request.getAvailability().then(function(availability) {
    // availability.value may be kept up-to-date by the controlling UA as long
    // as the availability object is alive. It is advised for the web developers
    // to discard the object as soon as it's not needed.
    handleAvailabilityChange(availability.value);
    availability.onchange = function() { handleAvailabilityChange(this.value); };
  }).catch(function() {
    // Availability monitoring is not supported by the platform, so discovery of
    // presentation displays will happen only after request.start() is called.
    // Pretend the devices are available for simplicity; or, one could implement
    // a third state for the button.
    handleAvailabilityChange(true);
  });
</script>

5.2 Starting a new presentation example

Example 2
<!-- controller.html -->
<script>
  // Start new presentation.
  request.start()
    // The connection to the presentation will be passed to setConnection on
    // success.
    .then(setConnection)
    // User canceled the selection dialog or an error occurred.
    .catch(endConnection);
</script>

5.3 Reconnect to a presentation example

Example 3
<!-- controller.html -->
<script>
  // read presId from localStorage if exists
  var presId = localStorage && localStorage["presId"] || null;
  // presId is mandatory when reconnecting to a presentation.
  if (presId) {
    request.reconnect(presId)
      // The resumed connection to the presentation will be passed to
      // setConnection on success.
      .then(setConnection)
      // No connection found for presUrl and presId, or an error occurred.
      .catch(endConnection);
  }
</script>

5.4 Handling an event for a controlling UA initiated presentation example

Example 4
<!-- controller.html -->
<!-- Setting presentation.defaultRequest allows the page to specify the
     PresentationRequest to use when the controlling UA initiates a
     presentation. -->
<script>
  navigator.presentation.defaultRequest = new PresentationRequest(defaultUrl);
  navigator.presentation.defaultRequest.onconnectionavailable = function(evt) {
    setConnection(evt.connection);
  };
</script>

5.5 Monitor connection's state and exchange data example

Example 5
<!-- controller.html -->
<script>
  var connection;
  var setConnection = function (theConnection) {
    // end existing connection, if any
    endConnection();
    // set the new connection
    connection = theConnection;
    if (connection) {
      // save presId in localStorage
      localStorage && (localStorage["presId"] = connection.id);
      // monitor connection's state
      connection.onstatechange = function () {
        if (this == connection) {
          if (this.state == "closed") {
            // Offer the user a chance to reconnect(), e.g. if there was a
            // network disruption, or the user wishes to resume control.
          } else if (this.state == "terminated") {
            // The presentation has terminated.  Offer the user a chance to
            // start a new presentation.
          } else if (this.state == "connected") {
            // send initial message to presentation page
            connection.send("say hello");
          }
      };
      // register message handler
      connection.onmessage = function (evt) {
        console.log("receive message", evt.data);
      };
    }
  };
  var disconnectController = function () {
    // close old connection if exists
    connection && connection.close();
  };
  var endPresentation = function () {
    connection && connection.terminate();
    // remove old presId from localStorage if exists
    localStorage && delete localStorage["presId"];
  };
</script>

5.6 Presentation: monitor available connection(s) and say hello.

Example 6
<!-- presentation.html -->
<script>
  var addConnection = function(connection) {
    connection.onstatechange = function () {
      // connection.state is either 'connected,' 'closed,' or 'terminated'
      console.log("connection's state is now", connection.state);
    };
    connection.onmessage = function (evt) {
      if (evt.data == "say hello")
        connection.send("hello");
    };
  };
  navigator.presentation.receiver.getConnection().then(addConnection);
  navigator.presentation.receiver.onconnectionavailable = function(evt) {
    navigator.presentation.receiver.getConnections().then(function(connections) {
      addConnection(connections[connections.length-1]);
    });
  };
</script>

6. API

6.1 Common idioms

A presentation display refers to an external screen available to the user agent via an implementation specific connection technology.

A presentation connection is an object relating a controlling browsing context to its receiving browsing context and enables two-way-messaging between them. Each presentation connection has a presentation connection state, a presentation identifier to distinguish it from other presentations, and a presentation URL that is a URL used to create or resume the presentation. A valid presentation identifier consists of alphanumeric ASCII characters only, is at least 16 characters long, and is unique within the set of presentations.

A controlling browsing context (or controller for short) is a browsing context that has connected to a presentation by calling start() or reconnect(), or received a presentation connection via a connectionavailable event.

The receiving browsing context (or presentation for short) is the browsing context responsible for rendering to a presentation display. A receiving browsing context can reside in the same user agent as the controlling browsing context or a different one.

The set of presentations, initially empty, contains the presentations created by the controlling browsing contexts for the controlling user agent (or a specific user profile within that user agent). The set of presentations is represented by a list of tuples, where each tuple consists of a presentation URL, a presentation identifier, and the presentation connection itself. The presentation URL and presentation identifier uniquely identify the presentation.

6.2 Interface PresentationConnection

Each presentation connection is represented by a PresentationConnection object. Both the controlling user agent and receiving user agent MUST implement PresentationConnection. 

enum PresentationConnectionState {
    "connected",
    "closed",
    "terminated"
};

enum BinaryType {
    "blob",
    "arraybuffer"
};

interface PresentationConnection : EventTarget {
    readonly    attribute DOMString?                  id;
    readonly    attribute PresentationConnectionState state;
    void close();
    void terminate();
                attribute EventHandler                onstatechange;

    // Communication
                attribute BinaryType                  binaryType;
                attribute EventHandler                onmessage;
    void send(DOMString message);
    void send(Blob data);
    void send(ArrayBuffer data);
    void send(ArrayBufferView data);
};

The id attribute specifies the presentation connection's presentation identifier.

The state attribute represents the presentation connection's current state. It can take one of the values of PresentationConnectionState depending on connection state.

When the send() method is called on a PresentationConnection object with a message, the user agent MUST run the algorithm to send a message through a PresentationConnection.

When the close() method is called on a PresentationConnection, the user agent MUST run the algorithm to close a presentation connection with PresentationConnection.

6.2.1 Sending a message through PresentationConnection

Note
No specific transport for the connection between the controlling browsing context and the receiving browsing context is mandated, except that for multiple calls to send() it has to be ensured that messages are delivered to the other end reliably and in sequence. The transport should function equivalently to an RTCDataChannel in reliable mode.

Let presentation message data be the payload data to be transmitted between two browsing contexts. Let presentation message type be the type of that data, one of text and binary.

When the user agent is to send a message through a PresentationConnection S, it MUST run the following steps:

  1. If the state property of PresentationConnection is not "connected", throw an InvalidStateError exception.
  2. Let presentation message type messageType be binary if data is one of ArrayBuffer, ArrayBufferView, or Blob. Let messageType be text if data is of type DOMString)
  3. Assign the destination browsing context as follows:
    1. Let the destination browsing context be the controlling browsing context if send() is called in the receiving browsing context.
    2. Let destination browsing context be the receiving browsing context if send() is called from the controlling browsing context.
  4. Using an implementation specific mechanism, transmit the contents of the data argument as presentation message data and presentation message type messageType to the destination browsing context side.

6.2.2 Receiving a message through PresentationConnection

When the user agent has received a transmission from the remote side consisting of presentation message data and presentation message type, it MUST run the following steps:

  1. If the state property of PresentationConnection is not "connected", abort these steps.
  2. Let event be a newly created trusted event that uses the MessageEvent interface, with the event type message, which does not bubble, is not cancelable, and has no default action.
  3. Initialize the event's data attribute as follows:
    1. If the presentation message type is text, then initialize event's data attribute to the contents of presentation message data of type DOMString.
    2. If the presentation message type is binary, and binaryType is set to blob, then initialize event's data attribute to a new Blob object that represents presentation message data as its raw data.
    3. If the presentation message type is binary, and binaryType is set to arraybuffer, then initialize event's data attribute to a new ArrayBuffer object whose contents are presentation message data.
  4. Queue a task to fire event at PresentationConnection.

6.2.3 Closing a PresentationConnection

When the user agent is to close a presentation connection using connection, it MUST do the following:

  1. Queue a task to run the following steps in order:
    1. If the presentation connection state of connection is not connected, then abort these steps.
    2. Set presentation connection state of connection to closed.
    3. Fire an event named statechange at connection.
    4. If connection is owned by a controlling browsing context, signal the receiving browsing context to close the presentation connection that was created when connection was used to establish a presentation connection with the presentation via connection, using an implementation-specific mechanism.
    5. If connection is owned by a receiving browsing context, signal the controlling browsing context to close the presentation connection that was used to establish a presentation connection with the presentation via connection, using an implementation-specific mechanism.

6.2.4 Terminating a presentation

When a controlling user agent is to terminate a presentation using connection, it MUST run the following steps:

  1. Queue a task to run the following steps in order:
    1. If the presentation connection state of connection is not connected, then abort these steps.
    2. Otherwise, for each known connection in the set of presentations in the controlling user agent:
      1. If the presentation identifier of known connection and connection are equal, and the presentation connection state of known connection is connected, then run the following steps:
        1. Set presentation connection state of known connection to terminated.
        2. Fire an event named statechange at known connection.
    3. Signal the receiving user agent to terminate the presentation using an implementation specific mechanism.

When a receiving user agent is to terminate a presentation using connection, it MUST close the receiving browsing context (equivalent to calling window.close()).

In addition, the receiving user agent hosting the receiving browsing context that was closed SHOULD signal each controlling user agent that was connected to the presentation. In response, each controlling user agent SHOULD run the following steps:

  1. Queue a task to run the following steps:
    1. For each connection that was connected to the receiving browsing context:
      1. If the presentation connection state of connection is not connected, then abort the following steps.
      2. Let controllingConnection be the presentation connection in the controlling browsing context that was used to establish a presentation connection via connection.
      3. Set the presentation connection state of controllingConnection to terminated.
      4. Fire an event named statechange at controllingConnection.

6.2.5 Event Handlers

The following are the event handlers (and their corresponding event handler event types) that must be supported, as event handler IDL attributes, by objects implementing the PresentationConnection interface:

Event handler Event handler event type
onmessage message
onstatechange statechange

6.3 Interface PresentationAvailability 

interface PresentationAvailability : EventTarget {
    readonly    attribute boolean      value;

                attribute EventHandler onchange;
};

A PresentationAvailability object is associated with available presentation displays and represents the presentation display availability for a presentation request. If the controlling user agent can monitor the list of available presentation displays in the background (without a pending request to start()), the PresentationAvailability object MUST be implemented in a controlling browsing context.

The value attribute MUST return the last value it was set to. The value is updated by the monitor the list of available presentation displays algorithm.

The onchange attribute is an event handler whose corresponding event handler event type is change.

6.3.1 The set of availability objects

The user agent MUST keep track of the set of availability objects requested through the getAvailability() method. The set of availability objects is represented as a set of tuples (A, availabilityUrl), initially empty, where:

  1. A is a live PresentationAvailability object;
  2. availabilityUrl is the availabilityUrl passed to getAvailability() to create A.

6.3.2 The list of available presentation displays

The user agent MUST keep a list of available presentation displays. This current list of presentation displays may be used for starting new presentations, and is populated based on an implementation specific discovery mechanism. It is set to the most recent result of the algorithm to monitor the list of available presentation displays.

While there are live PresentationAvailability objects, the user agent MAY monitor the list of available presentation displays continuously, so that pages can use the value property of an PresentationAvailability object to offer presentation only when there are available displays. However, the user agent may not support continuous availability monitoring; for example, because of platform or power consumption restrictions. In this case the Promise returned by getAvailability() MUST be rejected and the algorithm to monitor the list of available presentation displays will only run as part of the start a presentation connection algorithm.

When there are no live PresentationAvailability objects (that is, the set of availability objects is empty), user agents SHOULD NOT monitor the list of available presentation displays to satisfy the power saving non-functional requirement. To further save power, the user agent MAY also keep track of whether the page holding a PresentationAvailability object is in the foreground. Using this information, implementation specific discovery of presentation displays can be resumed or suspended.

Some presentation displays may only be able to display a subset of Web content because of functional, security or hardware limitations. Examples are set-top boxes, smart TVs or networked speakers capable of rendering only audio. We say that such a display is a compatible presentation display for a display availability URL if the user agent can reasonably guarantee that the presentation of the URL on that display will succeed.

6.3.3 Monitor the list of available presentation displays

If set of availability objects is non-empty, or there is a pending request to start a presentation connection, the user agent MUST monitor the list of available presentation displays by running the following steps.

  1. Queue a task to retrieve available presentation displays (using an implementation specific mechanism) and let newDisplays be this list.
  2. Wait for the completion of that task.
  3. For each member (A, availabilityUrl) of the set of availability objects:
    1. Set previousAvailability to the value of A's value property.
    2. Let newAvailability be true if newDisplays is not empty and at least one display in newDisplays is a compatible presentation display for availabilityUrl. Otherwise, set newAvailability to false.
    3. If previousAvailability is not equal to newAvailability, then queue a task to run the following steps:
      1. Set A's value property to newAvailability.
      2. Fire a simple event named change at A.
  4. Set the list of available presentation displays to the value of newDisplays.

When a PresentationAvailability object is no longer alive (i.e., is eligible for garbage collection), the user agent SHOULD run the following steps:

  1. Find and remove any entry (A, availabilityUrl) in the set of availability objects for the newly deceased A.
  2. If the set of availability objects is now empty and there is no pending request to start a presentation connection, cancel any pending task to monitor the list of available presentation displays for power saving purposes.
Note
The mechanism used to monitor presentation displays availability and determine the compatibility of a presentation display with a given URL is left to the user agent.

6.4 Interface PresentationRequest 

[Constructor(DOMString url)]
interface PresentationRequest : EventTarget {
    Promise<PresentationConnection>   start();
    Promise<PresentationConnection>   reconnect(DOMString presentationId);
    Promise<PresentationAvailability> getAvailability();

                attribute EventHandler onconnectionavailable;
};

A PresentationRequest object is associated with a request to initiate or reconnect to a presentation made by a controlling browsing context. The PresentationRequest object MUST be implemented in a controlling browsing context provided by a controlling user agent.

When a PresentationRequest is constructed, the given url MUST be used as the presentation request URL which is the presentation URL for the PresentationRequest instance.

6.4.1 Constructing a PresentationRequest

When the PresentationRequest constructor is called, the controlling user agent MUST run these steps:

Input
url, the presentation request URL
Output
A PresentationRequest object
  1. Resolve url relative to the API base URL specified by entry settings, and let presentationUrl be the resulting absolute URL, if any.
  2. If the resolve a URL algorithm failed, then throw a DOMException named "SyntaxError" and abort the remaining steps.
  3. Construct a new PresentationRequest object with presentationUrl as the constructor argument and return it.

6.4.2 Starting a presentation connection

When the start method is called, the user agent MUST run the following steps to start a presentation connection:

Input
presentationRequest, the PresentationRequest object
presentationUrl, the presentation request URL
Output
P, a Promise
  1. If the algorithm isn't allowed to show a popup, return a Promise rejected with a DOMException named "InvalidAccessError" and abort these steps.
  2. If there is already an unsettled Promise from a previous call to start for the same controlling browsing context, return a Promise rejected with a DOMException named "OperationError" and abort these steps.
  3. Let P be a new Promise.
  4. Return P.
  5. Run the following steps:
    1. Monitor the list of available presentation displays.
    2. Wait until the algorithm completes.
  6. If either of the following is true:
    1. The list of available presentation displays is empty;
    2. No member if the list of available presentation displays is a compatible presentation display for presentationUrl;
  7. Then run the following steps:
    1. Reject P with a DOMException named "NotFoundError".
    2. Abort all remaining steps.
  8. Queue a task T to request user permission for the use of a presentation display and selection of one presentation display.
    1. If T completes with the user granting permission to use a display, queue a task C to create a new browsing context on the user-selected presentation display and navigate to presentationUrl in it.
      1. If C completes successfully, run the following steps:
        1. Let I be a new valid presentation identifier unique among all presentation identifiers for known presentations in the set of presentations.
        2. Create a new PresentationConnection S.
        3. Set the presentation identifier of S to I, and set the presentation connection state of S to disconnected.
        4. Add the tuple {presentationUrl, S.id, S} to the set of presentations.
        5. Resolve P with S.
        6. Queue a task to fire an event named connectionavailable at presentationRequest with S as its connection attribute.
        7. Establish a presentation connection with S.
      2. If C fails, run the following steps:
        1. Reject P with a DOMException named "OperationError".
    2. If T completes with the user denying permission, run the following steps:
      1. Reject P with a DOMException named "AbortError".
Note
The details of implementing the permission request and display selection are left to the user agent; for example it may show the user a dialog and allow the user to select an available display (granting permission), or cancel the selection (denying permission).
Note
The presentationUrl should name a resource accessible to the local or a remote user agent. This specification defines behavior for presentationUrl using the http or https schemes; behavior for other schemes is not defined by this specification.
Issue
Do we want to distinguish the permission-denied outcome from the no-screens-available outcome? Developers would be able to infer it anyway from getAvailability().

6.4.3 Reconnect to a presentation connection

When the reconnect(presentationId) method is called on a PresentationRequest presentationRequest, the user agent MUST run the following steps to reconnect to a presentation:

Input
presentationRequest, the PresentationRequest object that reconnect() was called on.
presentationId, a presentation identifier
Output
P, a Promise
  1. Let P be a new Promise.
  2. Return P.
  3. Queue a task T to run the following steps in order:
    1. For each known connection in the set of presentations,
      If the presentation URL of known connection is equal to the presentationUrl of presentationRequest, and the presentation identifier of known connection is equal to presentationId, run the following steps:
      1. Let S be the presentation connection of known connection.
      2. Resolve P with S.
      3. Queue a task to fire an event named connectionavailable at presentationRequest with S as its connection attribute.
      4. Establish a presentation connection with S.
      5. Abort the remaining steps of T.
    2. Reject P with a DOMException named "NotFoundError".
Issue
If no matching presentation is found, we could leave the Promise pending in case a matching presentation is started in the future.

6.4.4 Establishing a presentation connection in a controlling browsing context

When the user agent is to establish a presentation connection using a presentation connection S, it MUST run the following steps:

  1. Queue a task T to connect the presentation connection S to the receiving browsing context.
  2. If T completes successfully, run the following steps:
    1. Set the presentation connection state of S to connected.
    2. Queue a task T to run the following steps in order:
      1. For each known connection in the set of presentations:
        1. If the presentation identifier of known connection and S are equal, then run the following steps:
          1. Queue a task to fire an event named statechange at s.
Note
The mechanism that is used to present on the remote display and connect the controlling browsing context with the presented document is an implementation choice of the user agent. The connection must provide a two-way messaging abstraction capable of carrying DOMString payloads in a reliable and in-order fashion as described in the Send Message and Receive Message steps below.
Note
If T does not complete successfully, the user agent may choose to re-execute the Presentation Connection algorithm at a later time.
Issue
Do we want to notify the caller of a failure to connect, i.e. with an "error" onstatechange?
Issue
Do we want to pass the new state as a property of the statechange event?

6.4.5 Getting the presentation displays availability information

When the getAvailability() method is called, the user agent MUST run the following steps:

Input
presentationUrl, the presentation request URL
Output
P, a Promise
  1. Let P be a new Promise.
  2. Return P.
  3. If the user agent is unable to monitor presentation displays for the entire duration of the controlling browsing context (e.g., because the user has disabled this feature), then:
    1. Resolve P with a new PresentationAvailability object with its value property set to false.
    2. Abort all the remaining steps.
  4. If the user agent is unable to continuously monitor the list of available presentation displays but can find presentation displays in order to start a connection, then:
    1. Reject P with a DOMException named "NotSupportedError".
    2. Abort all the remaining steps.
  5. Let A be a new PresentationAvailability object with its value property set to false if the list of available presentation displays is empty or non of them is a compatible presentation display, true otherwise.
  6. Create a tuple (A, presentationUrl) and add it to the set of availability objects.
  7. Run the algorithm to monitor the list of available presentation displays.
  8. Resolve P with A.

6.4.6 Establishing a presentation connection in a receiving browsing context

When a new receiving browsing context has been created and navigated to the presentationUrl on a user-selected presentation display, the user agent MUST run the following steps:

  1. Queue a task to start monitoring incoming presentation connections from controlling browsing contexts.

6.4.7 Event Handlers

The following are the event handlers (and their corresponding event handler event types) that must be supported, as event handler IDL attributes, by objects implementing the PresentationRequest interface:

Event handler Event handler event type
onconnectionavailable connectionavailable

6.4.8 Interface PresentationConnectionAvailableEvent 

[Constructor(DOMString type, PresentationConnectionAvailableEventInit eventInitDict)]
interface PresentationConnectionAvailableEvent : Event {
    [SameObject]
    readonly    attribute PresentationConnection connection;
};

dictionary PresentationConnectionAvailableEventInit : EventInit {
    required PresentationConnection connection;
};

A controlling user agent MUST fire an event named connectionavailable on a PresentationRequest when a connection associated with the object is created. It is fired at the PresentationRequest instance, using the PresentationConnectionAvailableEvent interface, with the connection attribute set to the PresentationConnection object that was created. The event is fired for all connections that are created for the controller, either by the controller calling start() or reconnect(), or by the controlling user agent creating a connection on the controller's behalf via defaultRequest.

6.5 Interface PresentationReceiver 

interface PresentationReceiver : EventTarget {
    Promise<PresentationConnection>           getConnection();
    Promise<sequence<PresentationConnection>> getConnections();
                attribute EventHandler onconnectionavailable;
};

The PresentationReceiver object is available to a receiving browsing context in order to access the controlling browsing context and communicate with it. The PresentationReceiver object MUST be implemented in a receiving browsing context provided by a receiving user agent.

6.5.1 Monitoring incoming presentation connections in a receiving browsing context

When the receiving user agent is to start monitoring incoming presentation connections in a receiving browsing context from controlling browsing contexts, it MUST run the following steps:

  1. Queue a task T to wait for and accept an incoming connection request from a controlling browsing context using an implementation specific mechanism.
  2. When a new connection request is received from a controlling browsing context, run the following steps:
    1. Create a new PresentationConnection S.
    2. Let I be a new valid presentation identifier unique among all presentation identifiers for known presentations in the set of presentations.
    3. Set the presentation identifier of S to I.
    4. Establish the connection between the controlling and receiving browsing contexts using an implementation specific mechanism.
    5. Set the presentation connection state of S to connected.
    6. Add a tuple (undefined, presentation identifier of S, S) to the set of presentations.
    7. Queue a task to fire an event named connectionavailable at presentation.receiver.

A receiving user agent MUST fire an event named connectionavailable on a PresentationReceiver when a connection associated with the object is created. It is fired at the PresentationReceiver instance, using the PresentationConnectionAvailableEvent interface, with the connection attribute set to the PresentationConnection object that was created. The event is fired for all connections that are created for the presentation when monitoring incoming presentation connections.

The receiving user agent MUST fire the event as soon as it can create the PresentationConnection associated with the event.

6.5.2 Getting the first presentation connection on the startup of a receiving browsing context

When the getConnection() method is called, the user agent MUST run the following steps:

  1. Let P be a new Promise.
  2. Return P.
  3. Queue a task T to run the following steps in order:
    1. If the set of presentations is empty, then wait until at least one element is added to the set of presentations.
    2. Let S be the first presentation connection added to the set of presentations.
    3. Resolve P with S.
Note
If the set of presentations is empty, we leave the Promise pending until connecting request arrives from the controlling browsing context. If the first controlling browsing context disconnects after initial connection, then the Promise returned to subsequent calls to getConnection() will resolve with a presentation connection that has its presentation connection state set to closed.

6.5.3 Getting all connected presentation connections in a receiving browsing context

When the getConnections() method is called, the user agent MUST run the following steps:

  1. Let P be a new Promise.
  2. Return P.
  3. Queue a task to run the following steps in order:
    1. Let array be an empty array.
    2. For each known connection in the set of presentations
      1. Add known connection to array.
    3. Resolve P with array.

6.5.4 Event Handlers

The following are the event handlers (and their corresponding event handler event types) that must be supported, as event handler IDL attributes, by objects implementing the PresentationReceiver interface:

Event handler Event handler event type
onconnectionavailable connectionavailable

6.6 Interface Presentation 

partial interface Navigator {
    [SameObject]
    readonly    attribute Presentation presentation;
};

interface Presentation {
                attribute PresentationRequest?  defaultRequest;
    [SameObject]
    readonly    attribute PresentationReceiver? receiver;
};

The presentation attribute is used to retrieve an instance of the Presentation interface.

6.6.1 Controlling user agent

In a controlling user agent, the defaultRequest MUST return the default presentation request if any, null otherwise.

If set by the controller, the defaultRequest SHOULD be used by the controlling user agent as the default presentation request for that controller. When the controlling user agent wishes to initiate a PresentationConnection on the controller's behalf, it MUST start a presentation connection using the default presentation request for the controller (as if the controller had called defaultRequest.start()).

The controlling user agent SHOULD initiate presentation using the default presentation request only when the user has expressed an intention to do so, for example by clicking a button in the browser.

Note
Not all user agents may support initiation of a presentation connection outside of the content area. In this case setting defaultRequest has no effect.
Issue
It should be clear that user-intiated presentation via the user agent may have pre-selected the presentation display. In this case step 6 of start a presentation connection is optional. It may be cleaner to define a separate set of steps for initiating a default presentation.

6.6.2 Receiving user agent

In a receiving user agent, receiver MUST return PresentationReceiver instance in a receiving browsing context. In any other browsing context, it MUST return null.

7. Security and privacy considerations

Issue 45: Security and privacy considerations

We should complete the Security and privacy considerations section to the Presentation API once we're better aware of the threats.

The spec has been evaluated against Self-Review Questionnaire: Security and Privacy, with results documented in this issue. Furthermore, the Privacy Interest Group (PING) has produced documentation that may be helpful, namely Fingerprinting Guidance for Web Specification Authors and Privacy Considerations for Web Protocols. The Web Security IG review and PING review of the specification have been initiated. This sections should be crafted based on feedback from the respective reviews.

Personally identifiable information

The change event fired on the PresentationAvailability object reveals one bit of information about the presence (or non-presence) of a presentation display typically discovered through the local area network. This could be used in conjunction with other information for fingerprinting the user. However, this information is also dependent on the user's local network context, so the risk is minimized.

Cross-origin access

A presentation is allowed to be accessed across origins; the presentation URL and presentation ID used to create the presentation are the only information needed to reconnect to a connection from any origin in that user agent. In other words, a presentation is not tied to a particular opening origin.

This design allows controlling contexts from different domains to connect to a shared presentation resource. The security of the presentation ID prevents arbitrary pages from connecting to an existing presentation.

This specification does not prohibit a user agent from publishing information about its set of presentations. The group envisions a user agent on another device (distinct from the controller or presentation) becoming authorized to reconnect to the presentation, either by user action or by discovering the presentation's URL and id.

Issue
This section should provide informative guidance as to what constitutes a reasonable context for a Web page to become authorized to control a presentation connection.

Device Access

The presentation API abstracts away what "local" means for displays, meaning that it exposes network-accessible displays as though they were local displays. The Presentation API requires user permission for a page to access any display to mitigate issues that could arise, such as showing unwanted content on a display viewable by others.

Temporary identifiers and browser state

The presentation URL and presentation ID can be used to connect to a presentation from another browsing context. They can be intercepted if an attacker can inject content into the controlling page.

Issue
Should we restrict the API to some extent in non secure contexts?

Incognito mode and clearing of browsing data

The content displayed on the presentation is different from the controller. In particular, if the user is logged in in both contexts, then logs out of the controlling browsing context, she will not be automatically logged out from the receiving browsing context. Applications that use authentication should pay extra care when communicating between devices.

The set of presentations known to the user agent should be cleared when the user requests to "clear browsing data."

Issue 14: Define user agent context for rendering the presentation

The spec should specify any restrictions on the presenting browsing context when the opening browsing context is in "incognito" mode.

From public-webscreens and related threads:

The specification should define the behavior of the following Web features for the presenting page across presentation sessions. The goals are the following:

  1. Ensure that the same presentation will behave correctly in the 1-UA and 2-UA cases
  2. Information does not leak from presentation session to session in cases where the controlling pages may represent different authorization domains (e.g., logged-in users).

The following Web features have been discussed (and there may be others to consider):

Issue
The spec should clarify what is to happen to the set of known presentations in "incognito" (private browsing context) mode.

Messaging between presentation connections

This spec will not mandate communication protocols between the controlling browsing context and the receiving browsing context, but it should set some guarantees of message confidentiality and authenticity between corresponding presentation connections.

Issue 80: Define security requirements for messaging channel between secure origins

public-secondscreen thread:

While discussing the Hbb 2.0 TV standard, the issue of how WebSockets would be used to communicate between the controlling Web application and the presenting TV Web application.

If these Web applications are provided on secure (https://) origins, some guarantees of message confidentiality and authenticity of either party should be made to meet the standards set out by the Mixed Content proposal.

This issue will be addressed by a spec change to spell out the security requirements for the messaging channel as part of the Security and Privacy sections of the spec.

8. Acknowledgments

Thanks to Wayne Carr, Louay Bassbouss, Anssi Kostiainen, 闵洪波 (Hongbo Min), Anton Vayvod, and Mark Foltz for help with editing, reviews and feedback to this draft.

A. References

A.1 Normative references

[FILEAPI]
Arun Ranganathan; Jonas Sicking. File API. 21 April 2015. W3C Working Draft. URL: http://www.w3.org/TR/FileAPI/
[HTML5]
Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Edward O'Connor; Silvia Pfeiffer. HTML5. 28 October 2014. W3C Recommendation. URL: http://www.w3.org/TR/html5/
[PROMGUIDE]
Domenic Denicola. Writing Promise-Using Specifications. finding. URL: http://www.w3.org/2001/tag/doc/promises-guide
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[URL]
Anne van Kesteren; Sam Ruby. URL. 9 December 2014. W3C Working Draft. URL: http://www.w3.org/TR/url-1/
[WEBIDL]
Cameron McCormack; Boris Zbarsky. WebIDL Level 1. 4 August 2015. W3C Working Draft. URL: http://www.w3.org/TR/WebIDL-1/

A.2 Informative references

[WEBRTC]
Adam Bergkvist; Daniel Burnett; Cullen Jennings; Anant Narayanan. WebRTC 1.0: Real-time Communication Between Browsers. 10 February 2015. W3C Working Draft. URL: http://www.w3.org/TR/webrtc/