6.2.1 Controlling user agent

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

If set by the controller, the value of the defaultRequest attribute 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 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.

6.2.2 Receiving user agent

In a receiving user agent, the receiver attribute MUST return the PresentationReceiver instance associated with the receiving browsing context and created by the receiving user agent when the receiving browsing context is created. In any other browsing context, it MUST return null.

A user agent that is a receiving user agent but not a controlling user agent MUST always return null for the defaultRequest attribute. It MUST treat setting the defaultRequest attribute as a no-op.

A user agent that is a controlling user agent but not a receiving user agent MUST always return null for the receiver attribute.

6.3.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 the entry settings object, and let presentationUrl be the resulting absolute URL, if any.
2. If the resolve a URL algorithm failed, then throw a SyntaxError exception and abort the remaining steps.
3. Construct a new PresentationRequest object with presentationUrl as the constructor argument and return it.

6.3.2 Starting a presentation

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

Input

presentationRequest, the PresentationRequest object

presentationUrl, the presentation request URL

Output

A Promise

1. If the algorithm isn't allowed to show a popup, return a Promise rejected with an InvalidAccessError exception and abort these steps.
2. Using the document's settings object, run the prohibits mixed security contexts algorithm.
3. If the result of the algorithm is "Prohibits Mixed Security Contexts" and presentationUrl is an a priori unauthenticated URL, then return a Promise rejected with a SecurityError.
4. If there is already an unsettled Promise from a previous call to start for the same controlling browsing context, return a Promise rejected with an OperationError exception and abort all remaining steps.
5. Let P be a new Promise.
6. Return P, but continue running these steps in parallel.
7. If the user agent is not monitoring the list of available presentation displays, run the steps to monitor the list of available presentation displays in parallel.
8. Request user permission for the use of a presentation display and selection of one presentation display.
9. If either of the following is true:
   1. The list of available presentation displays is empty and will remain so before the request for user permission is completed.
   2. No member in the list of available presentation displays is a compatible presentation display for presentationUrl.
   Then run the following steps:
   1. Reject P with a NotFoundError exception.
   2. Abort all remaining steps.
10. If the user denied permission to use a display, reject P with an AbortError exception, and abort all remaining steps.
11. Otherwise, the user granted permission to use a display; let D be that display.
12. Let I be a new valid presentation identifier unique among all presentation identifiers for known presentation connections in the set of controlled presentations.
13. Create a new PresentationConnection S.
14. Set the presentation identifier of S to I.
15. Set the presentation URL of S to presentationUrl.
16. Set the presentation connection state of S to connecting.
17. Add S to the set of controlled presentations.
18. Resolve P with S.
19. Queue a task to fire a trusted event with the name connectionavailable, that uses the PresentationConnectionAvailableEvent interface, with the connection attribute initialized to S, at presentationRequest. The event must not bubble, must not be cancelable, and has no default action.
20. If any of the following steps fails, abort all remaining steps and close the presentation connection S with error as closeReason, and a human readable message describing the failure as closeMessage.
21. Create a receiving browsing context on D and let R be the result.
22. Navigate R to presentationUrl.
23. Establish a presentation connection with S.

6.3.3 Reconnecting to a presentation

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. Using the document's settings object, run the prohibits mixed security contexts algorithm.
3. If the result of the algorithm is "Prohibits Mixed Security Contexts" and the presentation request URL of presentationRequest is an a priori unauthenticated URL, then reject P with a SecurityError.
4. Return P, but continue running these steps in parallel.
5. Search the set of controlled presentations for a PresentationConnection that meets the following criteria: its controlling browsing context is the current browsing context, its presentation connection state is not terminated, its presentation URL is equal to the presentation request URL of presentationRequest, and its presentation identifier is equal to presentationId.
6. If such a PresentationConnection exists, run the following steps:
   1. Let S be that PresentationConnection.
   2. Resolve P with S.
   3. If the presentation connection state of S is connecting or connected, then abort all remaining steps.
   4. Set the presentation connection state of S to connecting.
   5. Establish a presentation connection with S.
   6. Abort all remaining steps.
7. Search the set of controlled presentations for the first PresentationConnection that meets the following criteria: its presentation connection state is not terminated, its presentation URL is equal to the presentation request URL of presentationRequest, and its presentation identifier is equal to presentationId.
8. If such a PresentationConnection exists, run the following steps:
   1. Create a new PresentationConnection S.
   2. Set the presentation identifier of S to presentationId.
   3. Set the presentation URL of S to the presentation request URL of presentationRequest.
   4. Set the presentation connection state of S to connecting.
   5. Add S to the set of controlled presentations.
   6. Resolve P with S.
   7. Queue a task to fire a trusted event with the name connectionavailable, that uses the PresentationConnectionAvailableEvent interface, with the connection attribute initialized to S, at presentationRequest. The event must not bubble, must not be cancelable, and has no default action.
   8. Establish a presentation connection with S.
   9. Abort all remaining steps.
9. Reject P with a NotFoundError exception.

6.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 PresentationRequest interface:

6.4.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 parameter passed to getAvailability() to create A.

6.4.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 a 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 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 presentation request URL if the user agent can reasonably guarantee that the presentation of the URL on that display will succeed.

6.4.3 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, but continue running these steps in parallel.
3. If the user agent is unable to monitor the list of available 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 NotSupportedError exception.
   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 none 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.4 Monitoring the list of available presentation displays

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

1. Retrieve available presentation displays (using an implementation specific mechanism) and let newDisplays be this list.
2. 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.
3. 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, cancel any pending task to monitor the list of available presentation displays for power saving purposes.

6.4.5 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 fires a trusted 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 each connection that is 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.

A receiving user agent fires a trusted event named connectionavailable on a PresentationReceiver when an incoming connection is created. It is fired at the PresentationConnectionList instance associated with 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 when monitoring incoming presentation connections.

6.5.1 Establishing a presentation connection

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

Input

presentationConnection, the PresentationConnection object that is to be connected. The presentation connection state of presentationConnection must be connecting.

1. Connect presentationConnection to the receiving browsing context.
2. If connection completes successfully, queue a task to run the following steps:
   1. Set the presentation connection state of presentationConnection to connected.
   2. Fire a simple event named connect at presentationConnection.

6.5.2 Sending a message through PresentationConnection

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 or binary.

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

Input

presentationConnection, the presentation connection connected to the other browsing context

messageOrData, the presentation message data to send to the other browsing context

1. If the state property of presentationConnection is not connected, throw an InvalidStateError exception.
2. If the closing procedure of presentationConnection has started, then abort these steps.
3. Let presentation message type messageType be binary if messageOrData is of type ArrayBuffer, ArrayBufferView, or Blob. Let messageType be text if messageOrData is of type DOMString.
4. Using an implementation specific mechanism, transmit the contents of messageOrData as the presentation message data and messageType as the presentation message type to the destination browsing context.
5. If the previous step encounters an unrecoverable error, then abruptly close the presentation connection presentationConnection with error as closeReason, and a closeMessage describing the error encountered.

6.5.3 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 to receive a message through a PresentationConnection:

Input

presentationConnection, the presentation connection receiving the message

messageType, the presentation message type of the message

messageData, the presentation message data of the message

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 messageType is text, then initialize event's data attribute to messageData with type DOMString.
   2. If messageType is binary, and binaryType attribute is set to "blob", then initialize event's data attribute to a new Blob object with messageData as its raw data.
   3. If messageType is binary, and binaryType attribute is set to "arraybuffer", then initialize event's data attribute to a new ArrayBuffer object whose contents are messageData.
4. Queue a task to fire event at presentationConnection.

If the user agent encounters an unrecoverable error while receiving a message through presentationConnection, it SHOULD abruptly close the presentation connection presentationConnection with error as closeReason, and a human readable description of the error encountered as closeMessage.

6.5.4 Interface PresentationConnectionClosedEvent

enum PresentationConnectionClosedReason {
    "error",
    "closed",
    "wentaway"
};
[Constructor(DOMString type, PresentationConnectionClosedEventInit eventInitDict)]
interface PresentationConnectionClosedEvent : Event {
    readonly attribute PresentationConnectionClosedReason reason;
    readonly attribute DOMString                          message;
};
dictionary PresentationConnectionClosedEventInit : EventInit {
    required PresentationConnectionClosedReason reason;
             DOMString                          message;
};

A PresentationConnectionClosedEvent is fired when a presentation connection enters a closed state. The reason attribute provides the reason why the connection was closed:

• error means that the mechanism for connecting or communicating with a presentation entered an unrecoverable error.
• closed means that either the controlling browsing context or the receiving browsing context that were connected by the PresentationConnection called close().
• wentaway means that the browser closed the connection, for example, because the browsing context that owned the connection navigated or was discarded.

When the reason attribute is error, the user agent SHOULD set the error message to a human readable description of how the communication channel encountered an error.

6.5.5 Closing a PresentationConnection

When the user agent is to start closing a presentation connection, it MUST do the following:

Input

presentationConnection, the presentation connection to be closed

closeReason, the PresentationConnectionClosedReason describing why the connection is to be closed

closeMessage, a human-readable message with details of why the connection was closed.

1. If the presentation connection state of presentationConnection is not connecting or connected then abort the remaining steps.
2. Set the presentation connection state of presentationConnection to closed.
3. Start to signal to the destination browsing context the intention to close the corresponding PresentationConnection, passing the closeReason to that context. The user agent does not need to wait for acknowledgement that the corresponding PresentationConnection was actually closed before proceeding to the next step.
4. If closeReason is not wentaway, then locally run the steps to close the presentation connection with presentationConnection, closeReason, and closeMessage.

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

Input

presentationConnection, the presentation connection to be closed

closeReason, the PresentationConnectionClosedReason describing why the connection is to be closed

closeMessage, a human-readable message with details of why the connection was closed.

1. If there is a pending close the presentation connection task for presentationConnection, or a close the presentation connection task has already run for presentationConnection, then abort the remaining steps.
2. Queue a task to run the following steps:
   1. If the presentation connection state of presentationConnection is not connecting, connected, or closed, then abort the remaining steps.
   2. If the presentation connection state of presentationConnection is not closed, set it to closed.
   3. Fire a trusted event with the name close, that uses the PresentationConnectionClosedEvent interface, with the reason attribute initialized to closeReason and the message attribute initialized to closeMessage, at presentationConnection. The event must not bubble, must not be cancelable, and has no default action.

6.5.6 Terminating a presentation in a controlling browsing context

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

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 controlled 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 queue a task to run the following steps:
      1. Set the presentation connection state of known connection to terminated.
      2. Fire a simple event named terminate at known connection.
3. Send a termination request for the presentation to its receiving user agent using an implementation specific mechanism.

6.5.7 Terminating a presentation in a receiving browsing context

When any of the following occur, the receiving user agent MUST terminate a presentation in a receiving browsing context:

1. The receiving user agent is to unload a document corresponding to the receiving browsing context, e.g. in response to a call to window.close() in the top-level browsing context or to a request to navigate that context to a new resource.
2. The user requests to terminate the presentation via the receiving user agent.
   Note

   This could happen by an explicit user action, or as a policy of the user agent. For example, the receiving user agent could be configured to terminate presentations that have no PresentationConnection objects whose presentation connection state is in the connected state after 30 minutes.

3. A controlling user agent sends a termination request to the receiving user agent for that presentation.

When a receiving user agent is to terminate a presentation in a receiving browsing context, it MUST run the following steps:

1. Let P be the presentation to be terminated.
2. If there is a receiving browsing context for P, and it has a document for P that is not unloaded, unload a document corresponding to that browsing context.
3. For each connection in the set of presentation controllers that were created for P, queue a task to run the following steps:
   1. If the presentation connection state of connection is not connected, then abort the following steps.
   2. Send a termination confirmation for P using an implementation specific mechanism to the controlling user agent that owns the destination browsing context for connection.
      Note

      Only one termination confirmation needs to be sent per controlling user agent.

6.5.8 Handling a termination confirmation in a controlling user agent

When a receiving user agent is to send a termination confirmation for a presentation P, and that confirmation was received by a controlling user agent, the controlling user agent SHOULD run the following steps:

1. For each connection in the set of controlled presentations that was connected to P, queue a task to run the following steps:
   1. If the presentation connection state of connection is not connected, then abort the following steps.
   2. Set the presentation connection state of connection to terminated.
   3. Fire a simple event named terminate at connection.

6.5.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 PresentationConnection interface:

6.6.1 Creating a receiving browsing context

Input

D, a presentation display chosen by the user

Output

R, a receiving browsing context

When the user agent is to create a receiving browsing context, it MUST run the following steps:

1. Create a new top-level browsing context C on the user agent connected to D.
2. Set the session history of C to be the empty list.
3. Set the sandboxed auxiliary navigation browsing context flag on C.
4. Set the sessionStorage attribute for the Window object associated with C to a new, empty storage area.
5. Set the localStorage attribute for the Window object associated with C to a new, empty storage area.
6. Set the cookie store for C to an empty cookie store.
7. Set the permission state of all Permissions for C to "denied".
8. Set the IndexedDB databases for C to an empty set of databases.
9. Return C.

When the receiving browsing context is closed, any associated browsing state, including session history, sessionStorage, localStorage, the cookie store, and databases MUST be discarded and not used for any other receiving browsing context.

6.7.1 Monitoring incoming presentation connections

When the receiving user agent is to start monitoring incoming presentation connections in a receiving browsing context from controlling browsing contexts, it MUST listen to and accept incoming connection requests from a controlling browsing context using an implementation specific mechanism. When a new connection request is received from a controlling browsing context, the receiving user agent MUST run the following steps:

1. Let I be the presentation identifier sent by the controlling browsing context in the incoming request.
2. Create a new PresentationConnection S.
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 S to the set of presentation controllers.
7. Queue a task to fire a trusted event with the name connectionavailable, that uses the PresentationConnectionAvailableEvent interface, with the connection attribute initialized to S, at the PresentationConnectionList instance associated with the PresentationReceiver object. The event must not bubble, must not be cancelable, and has no default action.

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

6.7.2 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 PresentationConnectionList interface: