Monitoring availability of presentation displays

<p>

This code renders a button that is visible when there is at least one

compatible <a>presentation display</a> that can

present <code>https://example.com/presentation.html</code> <em>or</em>

<code>https://example.net/alternate.html</code>.

</p>

<p>

Monitoring of display availability is done by first creating

a <a>PresentationRequest</a> with the URLs you want to present, then

calling <a data-link-for="PresentationRequest">getAvailability</a> to

obtain a <a>PresentationAvailability</a> object whose <a>change</a>

event will fire when presentation availability changes state.

</p>

Starting a new presentation

<p>

When the user clicks <code>presentBtn</code>, this code requests

presentation of one of the URLs in the <a>PresentationRequest</a>.

When <a data-link-for="PresentationRequest">start</a> is called, the

browser typically shows a dialog that allows the user to select one of

the compatible displays that are available. The first URL in

the <a>PresentationRequest</a> that is compatible with the chosen

display will be presented on that display.

</p>

<p>

The <a data-link-for="PresentationRequest">start</a> method resolves

with a <a>PresentationConnection</a> object that is used to track the

state of the presentation, and exchange messages with the presentation

page once it's loaded on the display.

</p>

Reconnecting to an existing presentation

<p>

The presentation continues to run even after the original page that

started the presentation closes its <a>PresentationConnection</a>,

navigates, or is closed. Another page can use

the <a data-link-for="PresentationConnection">id</a> on

the <a>PresentationConnection</a> to reconnect to an existing

presentation and resume control of it. This is only guaranteed to

work from the same browser that started the presentation.

</p>

Starting a presentation by the controlling user agent

<p>

Some browsers have a way for users to start a presentation without

interacting directly with the controlling page. Controlling pages can

opt into this behavior by setting

the <a data-link-for="Presentation">defaultRequest</a> property

on <code>navigator.presentation</code>, and listening for

a <a>connectionavailable</a> event that is fired when a presentation

is started this way. The <a>PresentationConnection</a> passed with

the event behaves the same as if the page had

called <a data-link-for="PresentationRequest">start</a>.

</p>

Monitoring the connection state and exchanging data

<p>

Once a presentation has started, the

returned <a>PresentationConnection</a> is used to monitor its state

and exchange messages with it. Typically the user will be given the

choice to disconnect from or terminate the presentation from the

controlling page.

</p>

<p>

Since the the controlling page may connect to and disconnect from multiple

presentations during its lifetime, it's helpful to keep track of the

current <a>PresentationConnection</a> and its state. Messages can

only be sent and received on connections in

a <a data-link-for="PresentationConnectionState">connected</a> state.

</p>

Listening for incoming presentation connections

<p>

This code runs on the presented page

(<code>https://example.org/presentation.html</code>). Presentations

may be connected to from multiple controlling pages, so it's important

that the presented page listen for incoming connections on

the <a data-link-for="PresentationReceiver">connectionList</a> object.

</p>

<p>

It's possible for a controlling page to start and control two

independent presentations on two different presentation displays.

This code shows how a second presentation can be added to the first

one in the examples above.

</p>

When the <a data-link-for="PresentationConnection">terminate</a>

method is called on a

<code>message</code>, which does not bubble, is not cancelable, and has

<a data-link-for="PresentationConnection">close()</a>.

<code>close</code>,

<a>Fire a simple event</a> named <code>terminate</code> at <var>known

<a>Fire a simple event</a> named <code>terminate</code> at

<code>message</code>

<code>close</code>

<code>terminate</code>