W3C

Presentation API

Editor's Draft 15 May 2015

This version:
http://w3c.github.io/presentation-api/
Latest published version:
http://www.w3.org/TR/presentation-api/
Latest editor's draft:
http://w3c.github.io/presentation-api/
Version history:
https://github.com/w3c/presentation-api/commits/
Participate:
Send feedback to public-secondscreen@w3.org or open a new issue (open issues)
Editors:
Mark Foltz, Google
Dominik Röttsches, Intel (until April 2015)

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 was published by the Second Screen Presentation Working Group as an Editor's Draft. If you wish to make comments regarding this document, please send them to public-secondscreen@w3.org (subscribe, archives). All comments are welcome.

This document is a work in progress and is subject to change. It builds on the final report (dated 18 November 2014) produced by the Second Screen Presentation Community Group. Algorithms have been drafted in particular. Most sections are still incomplete or underspecified. Privacy and security considerations are missing. A few open issues are noted inline. Please check the group's issue tracker on GitHub for an accurate list. Feedback from early experimentations is encouraged to allow the Second Screen Presentation Working Group to evolve the specification based on implementation issues.

Publication as a First Public Working Draft does not imply endorsement by the W3C Membership. This draft document 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 that 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 August 2014 W3C Process Document.

Table of Contents

  1. 1 Introduction
  2. 2 Use cases and requirements
    1. 2.1 Use cases
    2. 2.2 Requirements
      1. 2.2.1 Functional requirements
      2. 2.2.2 Non-functional requirements
  3. 3 Conformance
  4. 4 Terminology
  5. 5 Examples
    1. 5.1 Monitor availability of presentation displays example
    2. 5.2 Starting a new presentation session example
    3. 5.3 Joining a presentation session example
    4. 5.4 Handling an event for a UA initiated presentation session example
    5. 5.5 Monitor session's state and exchange data example
  6. 6 Specifying the default presentation URL and id.
  7. 7 API
    1. 7.1 Common idioms
    2. 7.2 Common definitions
    3. 7.3 Interface PresentationSession
      1. 7.3.1 Sending a message through PresentationSession
      2. 7.3.2 Receiving a message through PresentationSession
      3. 7.3.3 Closing a PresentationSession
      4. 7.3.4 Event Handlers
    4. 7.4 Interface NavigatorPresentation
      1. 7.4.1 Starting a presentation session
      2. 7.4.2 Initiating the presentation session by the user agent
      3. 7.4.3 Joining a presentation session
      4. 7.4.4 Establishing a presentation connection
      5. 7.4.5 The onavailablechange EventHandler
        1. 7.4.5.1 Adding an EventHandler to onavailablechange
        2. 7.4.5.2 Removing an EventHandler
        3. 7.4.5.3 Monitoring the list of available presentation displays
    5. 7.5 Interface AvailableChangeEvent
    6. 7.6 Interface DefaultSessionStart
  8. 8 Security and privacy considerations
  9. 9 References
  10. 10 Acknowledgments

1 Introduction

This section is non-normative.

This specification aims to make secondary displays such as a projector or a connected TV 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 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 requesting page and a presentation page shown in the secondary display. How those messages are transmitted is left to the UA in order to allow for the use of display devices that can be attached to a wide variety of ways. For example, when a display device is attached using HDMI or MiraCast, the UA on the requesting device can render the requested presentation page in that same UA. Instead of displaying in a window on that same device, however, it can use whatever means the operating system provides for using those external displays. In that case, both the requesting page and the presentation page run on the requesting device and the operating system is used to route the presentation display output to the other display device. The second display device doesn't need to know anything about this spec or that the content involves HTML5.

Alternately, some types of external displays may be able to render HTML5 themselves and may have defined their way to send messages to that content. In that case, the UA on the requesting device would not need to render the presentation page itself. Instead, the UA could act as a proxy translating the request to show a page and the messages into the form understood by the display device.

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 display devices through any of the above means.

2 Use cases and requirements

2.1 Use cases

Presentations
A user is preparing a set of slides for a talk. Using a web-based service, she is editing her slides and speaker notes on the primary screen while the secondary larger screen shows a preview of the current slide. When the slides are done, her mobile phone allows her to access them from an online service while on the go. Coming to the conference, using wireless display technology, she would like to present her slides on the stage screen from her mobile phone. The phone's touch screen helps her to navigate slides and presents a slide preview while the projector shows her slides to the audience.
Video and image sharing
Using an online video or image sharing service, a user would like to show memorable moments to her friends. Using a device with a small screen, however, a user cannot show the content to a large group of people. Connecting an external TV screen or projector to her device - with a cable or wirelessly - the online sharing service now makes use of the connected display, allowing a wider audience to enjoy the content. The web page shows UI elements that allow the user to trigger displaying content on the secondary display (e.g., a "send to second screen" ) only if there is at least one secondary screen available.
Multiplayer gaming
Splitting the gaming experience into a near screen controller and a large screen visual experience can create new gaming experiences. Accessing the local display on the small screen device and an external larger display allows for richer web-based gaming experiences.

ISSUE 27: Define a multiplayer gaming use case

Media flinging to multiple screens
Alice enters a video sharing site using a browser on her tablet. Next, Alice picks her favorite video from the site, and the video starts to play on her tablet. While the video is playing Alice clicks a button "Share on different screen". The browser provides a user interface that lists all the screens Alice has at her home, asking her to select one. The screens are identified by names that are familiar to Alice. Alice picks one screen from the list, "Alice's big TV", and the video playback continues seamlessly on the selected screen. Next she decides to switch the playback to a different screen. She clicks the same button "Share on different screen" provided by the site, and the browser presents the user interface that lists all the screens. Alice picks another screen from the list, "Alice's kitchen TV", and the playback resumes on that screen. Video site also provides a feature to see the action (Alice is watching a soccer game) from a different angle. Alice clicks a button "Select screen for additional angle", and the browser asks Alice similarly to select the screen for playback. Alice picks "Alice's Projector" and the soccer game is shown on the projector from a different angle, in parallel to the content being played back on "Alice's kitchen TV".

ISSUE 40: Screen availability mechanism for multiple sessions

2.2 Requirements

The requirements enumerated in this section are derived from the use cases.

2.2.1 Functional requirements

Discovery & availability
The UA must provide a way to find out whether at least one secondary screen is available.
Launching presentation
The UA must provide a way to start sending content to the secondary screen. This may occur at the request of the page or at the request of the UA.
Resuming presentation
The UA must be able to resume an existing session with the content being displayed on the secondary screen.
Communication
The UA must enable exchanging data between the primary and the secondary screen in order to have a control channel between the primary and secondary page. The UA must not make assumptions about the execution locality of the UA of the remote page it communicates with (i.e. the secondary page might run on a remote UA, and thus the link between these two pages must be loosely coupled).
Signaling disconnection
The UA must signal disconnection from the presentation page to the primary page and vice versa.

Multi-screen enumeration and named identification requirement was removed after discussion on the mailing list.

2.2.2 Non-functional requirements

Power saving friendly
All API design decisions must be analyzed from a power efficiency point of view. Especially when using wireless display technologies or querying availability over a radio channel, care needs to be taken to design the API in a way that does not pose obstacles to using radio resources in an efficient way. For example, powering up the wireless display detection only when needed.

3 Conformance

All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. For readability, these words do not appear in all uppercase letters in this specification. [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.)

4 Terminology

The terms browsing context, event handlers, event handler event types, firing an event, navigate, queing a task, link elements are defined in [HTML5].

The term DOMException is defined in [DOM].

The term Promise is defined in [ES6]. 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 terms ArrayBuffer, ArrayBufferView are defined in the Typed Array specification: [TYPEDARRAY].

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

This document provides interface definitions using the [WEBIDL] standard.

5 Examples

ISSUE 42: Make the Example section more concise

This section shows example codes that highlight the usage of main features of the Presentation API. In these examples, controller.html represents the controlling page that runs in the opener UA and presentation.html represents the presenting page that runs in the presenting UA. 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

<!-- controller.html -->
<button id="castBtn" style="display: none;">Cast</button>
<script>
  // the cast button is visible if at least one presentation display is available
  var castBtn = document.getElementById("castBtn");
  // availablechange event is fired when the presentation display availability changes
  navigator.presentation.onavailablechange = function (evt) {
    // show or hide cast button depending on display availability
    castBtn.style.display = evt.available ? "inline" : "none";
  };
</script>

5.2 Starting a new presentation session example

<!-- controller.html -->
<script>
  // it is also possible to use relative presentation URL e.g. "presentation.html"
  var presUrl = "http://example.com/presentation.html";
  // create random presId
  var presId = Math.random().toFixed(6).substr(2);
  // Start new session. presId is optional.
  navigator.presentation.startSession(presUrl, presId)
    // the new started session will be passed to setSession on success
    .then(setSession)
    // user cancels the selection dialog or an error is occurred
    .catch(endSession);
</script>

5.3 Joining a presentation session example

<!-- controller.html -->
<script>
  // read presId from localStorage if exists
  var presId = localStorage && localStorage["presId"] || null;
  // presId is mandatory for joinSession.
  presId && navigator.presentation.joinSession(presUrl, presId)
    // The joined session will be passed to setSession on success
    .then(setSession)
    // no session found for presUrl and presId or an error is occurred
    .catch(endSession);
</script>

5.4 Handling an event for a UA initiated presentation session example

<!-- controller.html -->
<head>
  <!-- the link element with rel='default-presentation' allows the page to specify -->
  <!-- the presentation URL and id for when the UA initiates a presentation session -->
  <link href="http://example.com/presentation.html" rel="default-presentation" id="ABCD1234" >
</head>
<script>
  navigator.presentation.ondefaultsessionstart = function (evt) {
    setSession(evt.session);
  };
</script>

5.5 Monitor session's state and exchange data example

<!-- controller.html -->
<script>
  var session;
  var setSession = function (theSession) {
    // end existing session, if any
    endSession();
    // set the new session
    session = theSession;
    if (session) {
      // save presId in localStorage
      localStorage && (localStorage["presId"] = session.id);
      // monitor session's state
      session.onstatechange = function () {
        if (this == session && this.state == "disconnected")
          endSession();
      };
      // register message handler
      session.onmessage = function (evt) {
        console.log("receive message", evt.data);
      };
      // send message to presentation page
      session.send("say hello");
    }
  };
  var endSession = function () {
    // close old session if exists
    session && session.close();
    // remove old presId from localStorage if exists
    localStorage && delete localStorage["presId"];
  };
</script>
<!-- presentation.html -->
<script>
  var session = navigator.presentation.session;
  session.onstatechange = function () {
    // session.state is either 'connected' or 'disconnected'
    console.log("session's state is now", session.state);
  };
  session.onmessage = function (evt) {
    if (evt.data == "say hello")
      session.send("hello");
  };
</script>

6 Specifying the default presentation URL and id.

The default-presentation keyword can be used with a [HTML5] link element. This keyword allows to specify the URL to use by the UA when the UA initiates a presentation. An optional id attribute also allows specifying a presentation session identifier to use for the UA initiated presentation.

Link type Effect on... Brief description
link a and area
default-presentation External Resource not allowed Links to a presentation url.

In cases where more than one link element with a default-presentation link type appears in a Document, the user agent uses the first link element in tree order and ignores all subsequent link element with a default-presentation link type (even if the first element was erroneous).

The default presentation URL may be used by the UA to filter the available screens while monitoring the list of available presentation displays.

7 API

7.1 Common idioms

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

A presentation is an active connection between a user agent and a presentation display for displaying web content on the latter at the request of the former.

A presentation session is an object relating an opening browsing context to its presentation display and enabling two-way-messaging between them. Each such object has a presentation session state and a presentation session identifier to distinguish it from other presentation sessions.

An opening browsing context is a browsing context that has initiated or resumed a presentation session by calling startSession() or joinSession() or received a presentation session via ondefaultsessionstart event.

The presenting browsing context is the browsing context responsible for rendering to a presentation display. A presenting browsing context can reside in the same user agent as the opening browsing context or a different one.

7.2 Common definitions

Let D be the set of presentations that are currently known to the user agent (regardles of their state). D is represented as a set of tuples (U, I, S) where U is the URL that is being presented; I is an alphanumeric identifier for the presentation; and S is the user agent's PresentationSession for the presentation. U and I together uniquely identify the PresentationSession of the corresponding presentation.

7.3 Interface PresentationSession

Each presentation session is represented by a PresentationSession object.

enum PresentationSessionState { "connected", "disconnected" /*, "resumed" */ };
enum BinaryType { "blob", "arraybuffer" };

interface PresentationSession : EventTarget {
  readonly DOMString? id;
  readonly attribute PresentationSessionState state;
  void close();
  attribute EventHandler onstatechange;

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

The id attribute holds the alphanumeric presentation session identifier.

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

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

When the close() method is called on a PresentationSession, the user agent must run the algorithm to close a presentation session.

ISSUE 34: Specify the presentation initialization algorithm

ISSUE 46: Define send behavior

7.3.1 Sending a message through PresentationSession

Presentation API does not mandate a specific protocol for the connection between the opening browsing context and the presenting browsing context except that for multiple calls to send it has to be ensured that messages are delivered to the other end in sequence.

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 PresentationSession S, it must run the following steps:

  1. If the state property of PresentationSession is "disconnected", throw an InvalidStateError exception.
  2. Let presentation message type messageType be binary if data is one of ArrayBuffer or Blob. Let messageType be text if data is of type DOMString)
  3. Assign the destination browsing context as follows:
    1. Let the the destination browsing context be the opening browsing context if send is called in the presenting browsing context.
    2. Let destination browsing context be the presenting browsing context if send is called from the opening 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.

7.3.2 Receiving a message through PresentationSession

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 PresentationSession is "disconnected", 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 event's origin attribute to the Unicode serialization of the URL that the opening browsing context and the presenting browsing context have in common.

    ISSUE 63: Define (cross) origin relationship between opener and presenting page

  4. 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 initialise 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 initialise event's data attribute to a new ArrayBuffer object whose contents are presentation message data.
  5. Queue a task to fire event at PresentationSession.

7.3.3 Closing a PresentationSession

When the user agent is to close a presentation session S, it must run the following steps:

  1. If S.state is not connected, then:
    1. Abort these steps.
  2. Set S.state to disconnected.
  3. Let D be the set of presentations known by the user agent.
  4. Queue a task T to run the following steps in order:
    1. For each presentation (U, I, S') in D,
      1. Let u equal U, i equal I, and s equal S'.
      2. If u is equal to S.url and i is equal to S.id, run the following steps:
        1. Queue a task to fire an event named statechange at s.onstatechange.

ISSUE 35: Refine how to do session teardown/disconnect/closing

7.3.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 PresentationSession interface:

Event handler Event handler event type
onmessage message
onstatechange statechange

7.4 Interface NavigatorPresentation

partial interface Navigator {
  readonly attribute NavigatorPresentation presentation;
};

The presentation attribute is used to retrieve an instance of the NavigatorPresentation interface, the main interface of Presentation API.

interface NavigatorPresentation : EventTarget {
  readonly attribute PresentationSession? session;
  Promise<PresentationSession> startSession(DOMString url, DOMString? presentationId);
  Promise<PresentationSession> joinSession(DOMString url, DOMString? presentationId);
  attribute EventHandler onavailablechange;
  attribute EventHandler ondefaultsessionstart;
};

ISSUE 52: Specify the NavigatorPresentation.session attribute and its related algorithms

7.4.1 Starting a presentation session

When the startSession(presentationUrl, presentationId) method is called, the user agent must run the following steps:

Input
presentationUrl, the URL of the document to be presented
presentationId, an optional identifier for the presentation
Output
P, a Promise
  1. Let P be a new Promise.
  2. Return P.
  3. If the user agent does not monitor presentation display availability, run the following steps:
    1. Monitor presentation display availability.
    2. Wait until the algorithm completes.
  4. If the list of available presentation displays is empty, then:
    1. Reject P with a DOMException named "NotFoundError".
    2. Abort all remaining steps.
  5. 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 screen, run the following steps:
      1. If presentationId is not undefined, assign I to that that presentationId.
      2. If presentationId is undefined, let I be a random alphanumeric value of at least 16 characters drawn from the characters [A-Za-z0-9].
      3. Create a new PresentationSession S.
      4. Set S.url to presentationUrl, set S.id to I, and set S.state to disconnected.
      5. 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. Add (S.url, S.id, S) to D.
          2. Resolve P with S.
          3. 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".

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 screen (granting permission), or cancel the selection (denying permission).

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 onavailablechange.

7.4.2 Initiating the presentation session by the user agent

When the user agent starts a presentation session, it must run the following steps:

Input
defaultPresentationURL, the URL of the document to be presented, specified via the default presentation link element.
defaultPresentationId, an optional identifier for the presentation, specified via the id attribute of the default-presentation link element.
Output
S, a presentation session
  1. If the user agent does not monitor presentation display availability, run the following steps:
    1. Monitor presentation display availability.
    2. Wait until the algorithm completes.
  2. If the list of available presentation displays is empty, then abort all remaining steps.
  3. 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 screen, run the following steps:
      1. If defaultPresentationId is not undefined, assign I to that that defaultPresentationId.
      2. If defaultPresentationId is undefined, let I be a random alphanumeric value of at least 16 characters drawn from the characters [A-Za-z0-9].
      3. Create a new PresentationSession S.
      4. Set S.url to defaultPresentationUrl, set S.id to I, and set S.state to disconnected.
      5. Queue a task C to create a new browsing context on the user-selected presentation display and navigate to defaultPresentationUrl in it.
        1. If C completes successfully, run the following steps:
          1. Add (S.url, S.id, S) to D.
          2. Queue a task to fire an event named defaultsessionstart at navigator.presentation.ondefaultsessionstart with S.
          3. Establish a presentation connection with S.
        2. If C fails, abort all the remaining steps.
    2. If T completes with the user denying permission, abort all the remaining steps.

7.4.3 Joining a presentation session

When the joinSession(presentationUrl, presentationId) method is called, the user agent must run the following steps:

Input
presentationUrl, the URL of the document being presented
presentationId, the identifier for the presentation
Output
P, a Promise
  1. Let P be a new Promise.
  2. Return P.
  3. Let D be the set of presentations known by the user agent.
  4. Queue a task T to run the following steps in order:
    1. For each presentation (U, I, S) in D,
      1. Let u equal U, i equal I, and s equal S.
      2. If u is equal to presentationUrl and i is equal to presentationId, run the following steps:
        1. Resolve P with S.
        2. Establish a presentation connection with S.
        3. 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.

7.4.4 Establishing a presentation connection

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

  1. If S.state is connected, then:
    1. Abort all remaining steps.
  2. Queue a task T to connect S to the document that is presenting S.url.
  3. If T completes successfully, run the following steps:
    1. Set S.state to connected.
    2. Let D be the set of presentations known by the user agent.
    3. Queue a task T to run the following steps in order:
      1. For each presentation (U, I, S') in D,
        1. Let u equal U, i equal I, and s equal S'.
        2. If u is equal to S.url and i is equal to S.id, run the following steps:
          1. Queue a task to fire an event named statechange at s.onstatechange.

The mechanism that is used to present on the remote display and connect the opening 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.

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?

7.4.5 The onavailablechange EventHandler

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 PresentationSession interface:

Event handler Event handler event type
onavailablechange availablechange

In order to satisfy the power saving non-functionional requirements the user agent must keep track of the number of EventHandlers registered to the onavailable event. Using this information, implementation specific discovery of presentation displays can be resumed or suspended, in order to save power.

The user agent must keep a list of available presentation displays. According to the number of event handlers for onavailablechange, the user agent must also keep the list up to date by running the algorithm for monitoring the list of available presentation displays.
7.4.5.1 Adding an EventHandler to onavailablechange

When an event handler is added to the list of event handlers registered for the onavailablechange event, the user agent must run the algorithm to monitor the list of available presentation displays.

7.4.5.2 Removing an EventHandler

When an event handler is removed from the list of event handlers registered to the onavailablechange event, the user agent must run the following steps:

7.4.5.3 Monitoring the list of available presentation displays

When the user agent is to monitor the list of available presentation displays, it must run the following steps:

While there are event handlers added to NavigatorPresentation.onavailablechange, the user agent must continuously keep track the list of available presentation displays and repeat the following steps:

  1. Queue a task to retrieve the list of curently available presentation displays and let newDisplays be this list.
  2. Wait for the completion of that task.
  3. If the list of available presentation displays is empty and newDisplays is not empty, then
    1. Queue a task to fire an event named availablechange at with the event's available property set to true.
  4. If the list of available presentation displays is not empty and newDisplays is empty, then:
    1. Queue a task to fire an event named availablechange with the event's available property set to false.
  5. Set the list of available presentation displays to the value of newDisplays.

The mechanism used to monitor presention displays availability is left to the user agent. The user agent may choose search for screens at any time, not just when event handlers are added to NavigatorPresentation.onavailablechange.

The user agent may use the default presentation URL specified by the main frame of the page to filter the available presention displays if the mechanism of monitoring allows filtering.

When the user agent is to cancel monitoring the list of available presentation displays, it must run the following steps:

  1. Cancel any tasks to retrieve the list of available presentation displays.
  2. Set the list of available presentation displays to empty.
  3. Queue a task to fire an event named availablechange at E (and only E) with the event's available property set to false.

7.5 Interface AvailableChangeEvent

[Constructor(DOMString type, optional AvailableChangeEventInit eventInitDict)]
interface AvailableChangeEvent : Event {
  readonly attribute boolean available;
};

dictionary AvailableChangeEventInit : EventInit {
  boolean available;
};

An event named availablechange is fired during the execution of the monitoring presentation display availability algorithm when the presentation display availability changes. It is fired at the PresentationSession object, using the AvailableChangeEvent interface, with the available attribute set to the boolean value that the algorithm determined.

7.6 Interface DefaultSessionStart

[Constructor(DOMString type, optional DefaultSessionStartEventInit eventInitDict)]
interface DefaultSessionStartEvent : Event {
  readonly attribute PresentationSession session;
};

dictionary DefaultSessionStartEventInit : EventInit {
  PresentationSession session;
};



An event named defaultsessionstart is fired when the UA initiates a presentation on behalf of the page. It is fired at the NavigatorPresentation object, using the DefaultSessionStartEvent interface, with the session attribute set to the PresentationSession object provided by the UA.

8 Security and privacy considerations

ISSUE 45: Security and privacy considerations section

9 References

[DOM]
DOM, Anne van Kesteren, Aryeh Gregor and Ms2ger. WHATWG.
[ES6]
ECMA-262 6th Edition / Draft. ECMA / Jason Orendorff.
[FILEAPI]
File API, Arun Ranganathan and Jonas Sicking. W3C.
[HTML5]
HTML5, Robin Berjon, Steve Faulkner, Travis Leithead et al.. W3C.
[PROMGUIDE]
Writing Promise-Using Specifications, Domenic Denicola. W3C.
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels, Scott Bradner. IETF.
[TYPEDARRAY]
Typed Array, David Herman and Kenneth Russel. Khronos.
[URL]
URL, Anne van Kesteren. WHATWG.
[WEBIDL]
Web IDL, Cameron McCormack. W3C.

10 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.