Presentation API

6.2.1 Sending a message through PresentationSession

No specific transport for the connection between the controlling browsing context and the presenting 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 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, 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 presenting browsing context.
   2. Let destination browsing context be the presenting 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 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 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.
4. Queue a task to fire event at PresentationSession.

6.2.3 Closing a PresentationSession

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

1. If presentation session state of session is not connected, then abort these steps.
2. Set presentation session state of session to disconnected.
3. Queue a task to run the following steps in order:
   1. For each known session in the set of presentations:
      1. If the presentation session identifier of known session and session are equal, run the following steps:
         1. Queue a task to fire an event named statechange at session.

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

6.2.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:

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, P), initially empty, where:

1. A is a live Availability object;
2. availabilityUrl is the availabilityUrl passed to getAvailability() to create A.
3. P is the Promise that was returned by getAvailability() when A was created.

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 that 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 Availability objects, the user agent may monitor the list of available presentation displays continuously, so that pages can use the value property of an Availability 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() is rejected and the algorithm to monitor the list of available presentation displays will only run as part of the session start algorithm.

When there are no live Availability 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 UA may also keep track of whether the page holding an Availability 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 session, 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, P) 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. Set A's value property to newAvailability.
   4. If P is not settled, then resolve P with A.
   5. If previousAvailability is not equal to newAvailability, signal a presentation display availability change with A.
4. Set the list of available presentation displays to the value of newDisplays.

When an Availability 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, P) 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 session, cancel any pending task to monitor the set of presentation displays for power saving purposes.

The mechanism used to monitor presention displays availability and determine the compatibility of a presentation display with a given URL is left to the user agent.

6.4.1 Starting a presentation session

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

Input

presentationUrl, the presentation session URL

Output

P, a Promise

1. Let P be a new Promise.
2. Return P.
3. Run the following steps:
   1. Monitor the list of available presentation displays.
   2. Wait until the algorithm completes.
4. 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;
5. Then run the following steps:
   1. Reject P with a DOMException named "NotFoundError".
   2. Abort all remaining steps.
6. 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, run the following steps:
      1. Let I be a new valid presentation session identifier unique among all presentation session identifiers for known sessions in the set of presentations.
      2. Create a new PresentationSession S.
      3. Set the presentation session identifier of S to I, and set the presentation session state of S to disconnected.
      4. 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 the tuple {presentationUrl, S.id, S} to the set of presentations.
            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 display (granting permission), or cancel the selection (denying permission).

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.2 Joining a presentation session

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

Input

presentationUrl, the presentation session URL

presentationId, the presentation session 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 session in the set of presentations,
      If the presentation session URL of known session is equal to presentationUrl, and the presentation session identifier of known session is equal to presentationId, run the following steps:

      1. Let S be the presentation session of known session.
      2. Resolve P with S.
      3. Establish a presentation connection with S.
      4. 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.3 Establishing a presentation connection in a controlling browsing context

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

1. If the presentation session state of S is connected, then:
   1. Abort all remaining steps.
2. Queue a task T to connect the presentation session S to the presenting browsing context.
3. If T completes successfully, run the following steps:
   1. Set the presentation session state of S to connected.
   2. Queue a task T to run the following steps in order:
      1. For each known session in the set of presentations:
         1. If the presentation session identifier of known session and S are equal, then run the following steps:
            1. Queue a task to fire an event named statechange at s.

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.

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.4 Getting the presentation displays availability information

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

Input

availabilityUrl, a display availability URL

Output

P, a Promise

1. Let P be a new Promise.
2. Return P.
3. If the user agent is unable to continuously monitor the list of available presentation displays, then:
   1. Reject P.
   2. Abort all the remaining steps.
4. Otherwise, let A be a new Availability object with its value property set to false.
5. Create a tuple (A, availabilityUrl, P) and add it to the set of availability objects.
6. Run the algorithm to monitor the list of available presentation displays.

6.4.5 Establishing a presentation connection in a presenting browsing context

ISSUE 19: Specify behavior when multiple controlling pages are connected to the session

When a new presenting 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 sessions from controlling browsing contexts.

6.4.6 Monitoring incoming presentation sessions in a presenting browsing context

When the user agent is to start monitoring incoming presentation sessions in a presenting 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 new PresentationSession S.
   2. Let I be a new valid presentation session identifier unique among all presentation session identifiers for known sessions in the set of presentations.
   3. Set the presentation session identifier of S to I.
   4. Establish the connection between the controlling and presenting browsing contexts using an implementation specific mechanism.
   5. Set the presentation session state of S to connected.
   6. Add a tuple (undefined, presentation session identifier of S, S) to the set of presentations.
   7. Queue a task to fire an event named sessionavailable at NavigatorPresentation.

6.4.7 Getting the first connected presentation session on the startup of a presenting browsing context

When the getSession() 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 session added to the set of presentations.
   3. Resolve P with S.

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 getSession() will resolve with a presentation session that has its presentation session state set to disconnected.

6.4.8 Getting all connected presentation sessions in a presenting browsing context

When the getSessions() 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 session in the set of presentations
      1. Add known session to array.
   3. Resolve P with array.

6.4.9 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 NavigatorPresentation interface: