Copyright © 2018 W3C ® ( MIT , ERCIM , Keio , Beihang ). W3C liability , trademark and permissive document license rules apply.
This specification defines an API to enable Web content to access presentation displays and use them for presenting Web content.
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 https://www.w3.org/TR/.
This document was published by the Second Screen Working Group as an Editor's Draft. Comments regarding this document are welcome. Please send them to public-secondscreen@w3.org ( subscribe , archives ).
Please see the Working Group's implementation report .
Since
publication
as
Candidate
Recommendation
on
14
July
2016
,
the
Working
Group
updated
most
algorithms
in
the
spec
to
fix
issues
identified
through
testing
and
implementation
feedback.
Interfaces
defined
in
this
document
did
not
change,
except
PresentationConnectionClosedReason
and
PresentationConnectionClosedEvent
,
which
were
renamed
to
improve
consistency
with
the
rest
of
the
Web
platform.
The
API
was
also
restricted
to
secure
contexts.
See
the
list
of
changes
for
details.
No feature has been identified as being at risk .
The Second Screen Working Group will refine the test suite for the Presentation API during the Candidate Recommendation period and update the preliminary implementation report . For this specification to advance to Proposed Recommendation, two independent, interoperable implementations of each feature must be demonstrated, as detailed in the Candidate Recommendation exit criteria section.
Publication as an Editor's 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 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 February 2018 W3C Process Document .
This section is non-normative.
The Presentation API aims to make presentation displays such as projectors, attached monitors, and network-connected TVs available to the Web. It 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 Web content to a larger audience: a group of colleagues in a conference room, or friends and family at home, for example. Web content shown on a larger presentation display has greater perceived quality, legibility, and impact.
At its core, the Presentation API enables a controller page to show a presentation page on a presentation display and exchange messages with it. How the presentation page is transmitted to the display and how messages are exchanged between it and the controller page are left to the implementation; this allows the use of a wide variety of display technologies.
For example, if the presentation display is connected by HDMI or Miracast, which only allow audio and video to be transmitted, the user agent (UA) hosting the controller will also render the presentation . It then uses the operating system to send the resulting graphical and audio output to the presentation display. We refer to this situation as the 1-UA mode implementation of the Presentation API. The only requirements are that the user agent is able to send graphics and audio from rendering the presentation to the presentation display, and exchange messages internally between the controller and presentation pages.
If the presentation display is able to render HTML natively and communicate with the controller via a network, the user agent hosting the controller does not need to render the presentation . Instead, the user agent acts as a proxy that requests the presentation display to load and render the presentation page itself. Message exchange is done over a network connection between the user agent and the presentation display. We refer to this situation as the 2-UA mode implementation of the Presentation API.
The Presentation API is intended to be used with user agents that attach to presentation displays in 1-UA mode , 2-UA mode , and possibly other means not listed above. To improve interoperability between user agents and presentation displays, standardization of network communication between browsers and displays is being considered in the Second Screen Community Group .
This section is non-normative.
Use cases and requirements are captured in a separate Presentation API Use Cases and Requirements document.
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 , MUST NOT , OPTIONAL , 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.)
This specification describes the conformance criteria for two classes of user agents .
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
,
PresentationAvailability
,
PresentationConnection
,
PresentationConnectionAvailableEvent
,
and
PresentationConnectionCloseEvent
interfaces.
PresentationRequest
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
,
PresentationConnectionCloseEvent
,
and
PresentationConnectionList
interfaces.
PresentationReceiver
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 mode implementation of the API.
Conformance requirements phrased against a user agent apply either to a controlling user agent , a receiving user agent or to both classes, depending on the context.
The following terms are defined in [ HTML51 ]:
EventHandler
Navigator
The term JavaScript realm is defined in [ ECMASCRIPT ].
The
terms
EventTarget
,
Event
,
EventInit
are
defined
in
[
DOM
].
The
term
MessageEvent
is
defined
in
[
WEBMESSAGING
].
This document provides interface definitions using the Web IDL standard [ WEBIDL-2 ].
The terms throw , Promise , ArrayBuffer , ArrayBufferView , and the following exception names are defined in [ WEBIDL-2 ]:
InvalidAccessError
NotFoundError
NotSupportedError
OperationError
SecurityError
SyntaxError
NotAllowedError
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 header Accept-Language is defined in HTTP/1.1 [ rfc7231 ].
HTTP authentication is defined in HTTP/1.1: Authentication [ rfc7235 ].
The
term
RTCDataChannel
is
defined
in
the
WebRTC
API
specification
[
WEBRTC
].
The term cookie store is defined in RFC 6265 [ COOKIES ].
The term UUID is defined in RFC 4122 [ rfc4122 ].
The terms permission descriptor type and permission state are defined in [ PERMISSIONS ].
The term database is defined in [ INDEXEDDB ].
The terms local storage areas and session storage areas are defined in [ WEBSTORAGE ].
The term a priori authenticated URL is defined in [ MIXED-CONTENT ].
The terms service worker , a list of registered service worker registrations , caches , window client and worker client are defined in [ SERVICE-WORKERS ].
This section is non-normative.
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
https://example.org
(
https://example.org/controller.html
and
https://example.org/presentation.html
).
These
examples
assume
that
the
controlling
page
is
managing
one
presentation
at
a
time.
Please
refer
to
the
comments
in
the
code
examples
for
further
details.
<!-- controller.html -->
<button id="presentBtn" style="display: none;">Present</button>
<script>
// The Present button is visible if at least one presentation display is available
var presentBtn = document.getElementById("presentBtn");
// It is also possible to use relative presentation URL e.g. "presentation.html"
var presUrls = ["https://example.com/presentation.html",
"https://example.net/alternate.html"];
// show or hide present button depending on display availability
var handleAvailabilityChange = function(available) {
presentBtn.style.display = available ? "inline" : "none";
};
// Promise is resolved as soon as the presentation display availability is
// known.
var request = new PresentationRequest(presUrls);
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>
<!-- controller.html -->
<script>
presentBtn.onclick = function () {
// Start new presentation.
request.start()
// The connection to the presentation will be passed to setConnection on
// success.
.then(setConnection);
// Otherwise, the user canceled the selection dialog or no screens were
// found.
};
</script>
<!-- controller.html -->
<button id="reconnectBtn" style="display: none;">Reconnect</button>
<script>
var reconnect = function () {
// read presId from localStorage if exists
var presId = localStorage["presId"];
// presId is mandatory when reconnecting to a presentation.
if (!!presId) {
request.reconnect(presId)
// The new connection to the presentation will be passed to
// setConnection on success.
.then(setConnection);
// No connection found for presUrl and presId, or an error occurred.
}
};
// On navigation of the controller, reconnect automatically.
document.addEventListener("DOMContentLoaded", reconnect);
// Or allow manual reconnection.
const reconnectBtn = document.querySelector("#reconnectBtn");
reconnectBtn.onclick = reconnect;
</script>
<!-- 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(presUrls);
navigator.presentation.defaultRequest.onconnectionavailable = function(evt) {
setConnection(evt.connection);
};
</script>
<!-- controller.html -->
<button id="disconnectBtn" style="display: none;">Disconnect</button>
<button id="stopBtn" style="display: none;">Stop</button>
<script>
let connection;
// The Disconnect and Stop buttons are visible if there is a connected presentation
const stopBtn = document.querySelector("#stopBtn");
const disconnectBtn = document.querySelector("#disconnectBtn");
stopBtn.onclick = _ => {
connection && connection.terminate();
};
disconnectBtn.onclick = _ => {
connection && connection.close();
};
function setConnection(newConnection) {
// Disconnect from existing presentation, if not attempting to reconnect
if (connection && connection != newConnection && connection.state != 'closed') {
connection.onclosed = undefined;
connection.close();
}
// Set the new connection and save the presentation ID
connection = newConnection;
localStorage["presId"] = connection.id;
function showConnectedUI() {
// Allow the user to disconnect from or terminate the presentation
stopBtn.style.display = "inline";
disconnectBtn.style.display = "inline";
reconnectBtn.style.display = "none";
}
function showDisconnectedUI() {
disconnectBtn.style.display = "none";
stopBtn.style.display = "none";
reconnectBtn.style.display = localStorage["presId"] ? "inline" : "none";
}
// Monitor the connection state
connection.onconnect = _ => {
showConnectedUI();
// Register message handler
connection.onmessage = message => {
console.log(`Received message: ${message.data}`);
};
// Send initial message to presentation page
connection.send("Say hello");
};
connection.onclose = _ => {
connection = null;
showDisconnectedUI();
};
connection.onterminate = _ => {
// Remove presId from localStorage if exists
delete localStorage["presId"];
connection = null;
showDisconnectedUI();
};
};
</script>
<!-- presentation.html -->
<script>
var addConnection = function(connection) {
this.onmessage = function (message) {
if (message.data == "say hello")
this.send("hello");
};
};
navigator.presentation.receiver.connectionList.then(function (list) {
list.connections.map(function (connection) {
addConnection(connection);
});
list.onconnectionavailable = function (evt) {
addConnection(evt.connection);
};
});
</script>
<!-- controller.html -->
<script>
connection.send("{string: '你好,世界!', lang: 'zh-CN'}");
connection.send("{string: 'こんにちは、世界!', lang: 'ja'}");
connection.send("{string: '안녕하세요, 세계!', lang: 'ko'}");
connection.send("{string: 'Hello, world!', lang: 'en-US'}");
</script>
<!-- presentation.html -->
<script>
connection.onmessage = function (message) {
var messageObj = JSON.parse(message.data);
var spanElt = document.createElement("SPAN");
spanElt.lang = messageObj.lang;
spanElt.textContent = messageObj.string;
document.appendChild(spanElt);
};
</script>
A presentation display refers to a graphical and/or audio output device 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 unique presentation identifier to distinguish it from other presentations , and a presentation URL that is a URL used to create or reconnect to the presentation . A valid presentation identifier consists of alphanumeric ASCII characters only and is at least 16 characters long.
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 an available presentation display for a presentation URL if the controlling user agent can reasonably guarantee that presentation of the URL on that display will succeed.
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.
In
algorithms
for
,
the
controlling
browsing
context
is
the
responsible
browsing
context
whose
JavaScript
realm
was
used
to
construct
the
PresentationRequest
.
PresentationRequest
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. A receiving browsing context is created by following the steps to create a receiving browsing context .
In a procedure, the destination browsing context is the receiving browsing context when the procedure is initiated at the controlling browsing context , or the controlling browsing context if it is initiated at the receiving browsing context .
The
set
of
controlled
presentations
,
initially
empty,
contains
the
presentation
connections
created
by
the
controlling
browsing
contexts
for
the
controlling
user
agent
(or
a
specific
user
profile
within
that
user
agent).
The
set
of
controlled
presentations
is
represented
by
a
list
of
PresentationConnection
objects
that
represent
the
underlying
presentation
connections
.
Several
PresentationConnection
objects
may
share
the
same
presentation
URL
and
presentation
identifier
in
that
set,
but
there
can
be
only
one
PresentationConnection
with
a
specific
presentation
URL
and
presentation
identifier
for
a
given
controlling
browsing
context
.
The
set
of
presentation
controllers
,
initially
empty,
contains
the
presentation
connections
created
by
a
receiving
browsing
context
for
the
receiving
user
agent
.
The
set
of
presentation
controllers
is
represented
by
a
list
of
PresentationConnection
objects
that
represent
the
underlying
presentation
connections
.
All
presentation
connections
in
this
set
share
the
same
presentation
URL
and
presentation
identifier
.
In
a
receiving
browsing
context
,
the
presentation
controllers
monitor
,
initially
set
to
null
,
exposes
the
current
set
of
presentation
controllers
to
the
receiving
application.
The
presentation
controllers
monitor
is
represented
by
a
PresentationConnectionList
.
In
a
receiving
browsing
context
,
the
presentation
controllers
promise
,
which
is
initially
set
to
null
,
provides
the
presentation
controllers
monitor
once
the
initial
presentation
connection
is
established.
The
presentation
controllers
promise
is
represented
by
a
Promise
that
resolves
with
the
presentation
controllers
monitor
.
In
a
controlling
browsing
context
,
the
default
presentation
request
,
which
is
initially
set
to
null
,
represents
the
request
to
use
when
the
user
wishes
to
initiate
a
presentation
connection
from
the
browser
chrome.
The task source for the tasks mentioned in this specification is the presentation task source .
Unless otherwise specified, the JavaScript realm for script objects constructed by algorithm steps is the current realm .
Presentation
[SecureContext,
Exposed=Window]
interface Presentation
{
};
The
attribute
is
used
to
retrieve
an
instance
of
the
presentation
Presentation
interface.
It
MUST
return
the
Presentation
instance.
Controlling user agents MUST implement the following partial interface:
partial interface Presentation
{
attribute PresentationRequest
? defaultRequest
;
};
The
defaultRequest
attribute
MUST
return
the
default
presentation
request
if
any,
null
otherwise.
On
setting,
the
default
presentation
request
MUST
be
set
to
the
new
value.
The controlling user agent SHOULD initiate presentation using the default presentation request only when the user has expressed an intention to do so via a user gesture, for example by clicking a button in the browser chrome.
To initiate presentation using the default presentation request , the controlling user agent MUST follow the steps to start a presentation from a default presentation request .
Support for initiating a presentation using the default presentation request is OPTIONAL .
defaultRequest
.
Receiving user agents MUST implement the following partial interface:
partial interface Presentation
{
readonly attribute PresentationReceiver
? receiver
;
};
The
receiver
attribute
MUST
return
the
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
(including
nested
browsing
contexts
of
the
receiving
browsing
context
)
it
MUST
return
PresentationReceiver
null
.
Web developers can use navigator.presentation.receiver to detect when a document is loaded as a presentation.
PresentationRequest
[Constructor(USVString url),
Constructor(sequence<USVString> urls),
SecureContext,
Exposed=Window]
interface PresentationRequest
: EventTarget
{
Promise<PresentationConnection
> start
();
Promise<PresentationConnection
> reconnect
(USVString presentationId);
Promise<PresentationAvailability
> getAvailability
();
};
A
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
.
PresentationRequest
When
a
is
constructed,
the
given
PresentationRequest
urls
MUST
be
used
as
the
list
of
presentation
request
URLs
which
are
each
a
possible
presentation
URL
for
the
instance.
PresentationRequest
PresentationRequest
When
the
PresentationRequest
constructor
is
called,
the
controlling
user
agent
MUST
run
these
steps:
PresentationRequest
object
SecurityError
and
abort
these
steps.
NotSupportedError
and
abort
all
remaining
steps.
SyntaxError
exception
and
abort
all
remaining
steps.
NotSupportedError
and
abort
all
remaining
steps.
SecurityError
and
abort
these
steps.
PresentationRequest
object
with
presentationUrls
as
its
presentation
request
URLs
and
return
it.
When
the
start
method
is
called,
the
user
agent
MUST
run
the
following
steps
to
select
a
presentation
display
.
PresentationRequest
object
that
received
the
call
to
start
InvalidAccessError
exception
and
abort
these
steps.
start
in
topContext
or
any
browsing
context
in
the
list
of
descendant
browsing
contexts
of
topContext
,
return
a
new
Promise
rejected
with
an
OperationError
exception
and
abort
all
remaining
steps.
NotFoundError
exception.
NotAllowedError
exception,
and
abort
all
remaining
steps.
When the user expresses an intent to start presentation of a document on a presentation display using the browser chrome (via a dedicated button, user gesture, or other signal), that user agent MUST run the following steps to start a presentation from a default presentation request . If no default presentation request is set on the document, these steps MUST not be run.
null
value
of
navigator.presentation.defaultRequest
set
on
W
When the user agent is to start a presentation connection , it MUST run the following steps:
PresentationRequest
that
is
used
to
start
the
presentation
connection
PresentationConnection
S
.
connecting
.
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.
error
as
closeReason
,
and
a
human
readable
message
describing
the
failure
as
closeMessage
.
http
or
https
schemes;
behavior
for
other
schemes
is
not
defined
by
this
specification.
When
the
reconnect
method
is
called,
the
user
agent
MUST
run
the
following
steps
to
reconnect
to
a
presentation
:
PresentationRequest
object
that
reconnect
was
called
on
PresentationConnection
that
meets
the
following
criteria:
terminated
PresentationConnection
exists,
run
the
following
steps:
PresentationConnection
.
connecting
or
connected
,
then
abort
all
remaining
steps.
connecting
.
PresentationConnection
that
meets
the
following
criteria:
terminated
PresentationConnection
exists,
run
the
following
steps:
PresentationConnection
.
PresentationConnection
newConnection
.
connecting
.
connectionavailable
,
that
uses
the
PresentationConnectionAvailableEvent
interface,
with
the
connection
attribute
initialized
to
newConnection
,
at
presentationRequest
.
The
event
must
not
bubble,
must
not
be
cancelable,
and
has
no
default
action.
NotFoundError
exception.
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
|
PresentationConnection
Each
presentation
connection
is
represented
by
a
PresentationConnection
object.
Both
the
controlling
user
agent
and
receiving
user
agent
MUST
implement
PresentationConnection
.
enumPresentationConnectionState
{ "connecting", "connected", "closed", "terminated" }; enumBinaryType
{ "blob", "arraybuffer" }; [SecureContext, Exposed=Window] interfacePresentationConnection
:EventTarget
{ readonly attribute USVStringid
; readonly attribute USVStringurl
; readonly attributePresentationConnectionState
state
; voidclose
(); voidterminate
(); attribute EventHandleronconnect
; attribute EventHandleronclose
; attribute EventHandleronterminate
; // Communication attributeBinaryType
binaryType
; attribute EventHandleronmessage
; voidsend
(DOMString message); voidsend
(Blob
data); voidsend
(ArrayBuffer data); voidsend
(ArrayBufferView data); };
The
id
attribute
specifies
the
presentation
connection
's
presentation
identifier
.
The
url
attribute
specifies
the
presentation
connection
's
presentation
URL
.
The
state
attribute
represents
the
presentation
connection
's
current
state.
It
can
take
one
of
the
values
of
PresentationConnectionState
depending
on
the
connection
state:
connecting
means
that
the
user
agent
is
attempting
to
establish
a
presentation
connection
with
the
destination
browsing
context
.
This
is
the
initial
state
when
a
PresentationConnection
object
is
created.
connected
means
that
the
presentation
connection
is
established
and
communication
is
possible.
closed
means
that
the
presentation
connection
has
been
closed,
or
could
not
be
opened.
It
may
be
re-opened
through
a
call
to
reconnect
.
No
communication
is
possible.
terminated
means
that
the
receiving
browsing
context
has
been
terminated.
Any
presentation
connection
to
that
presentation
is
also
terminated
and
cannot
be
re-opened.
No
communication
is
possible.
When
the
close
method
is
called
on
a
PresentationConnection
S
,
the
user
agent
MUST
start
closing
the
presentation
connection
S
with
closed
as
closeReason
and
an
empty
message
as
closeMessage
.
When
the
terminate
method
is
called
on
a
PresentationConnection
S
in
a
controlling
browsing
context
,
the
user
agent
MUST
run
the
algorithm
to
terminate
a
presentation
in
a
controlling
browsing
context
using
S
.
When
the
terminate
method
is
called
on
a
PresentationConnection
S
in
a
receiving
browsing
context
,
the
user
agent
MUST
run
the
algorithm
to
terminate
a
presentation
in
a
receiving
browsing
context
using
S
.
The
binaryType
attribute
can
take
one
of
the
values
of
BinaryType
.
When
a
PresentationConnection
object
is
created,
its
binaryType
attribute
MUST
be
set
to
the
string
"
arraybuffer
".
On
getting,
it
MUST
return
the
last
value
it
was
set
to.
On
setting,
the
user
agent
MUST
set
the
attribute
to
the
new
value.
blob
",
binary
data
is
returned
in
Blob
form;
by
setting
it
to
"
arraybuffer
",
it
is
returned
in
ArrayBuffer
form.
The
attribute
defaults
to
"
arraybuffer
".
This
attribute
has
no
effect
on
data
sent
in
a
string
form.
When
the
send
method
is
called
on
a
PresentationConnection
S
,
the
user
agent
MUST
run
the
algorithm
to
send
a
message
through
S
.
When
a
PresentationConnection
object
S
is
discarded
(because
the
document
owning
it
is
navigating
or
is
closed)
while
the
presentation
connection
state
of
S
is
connecting
or
connected
,
the
user
agent
MUST
start
closing
the
presentation
connection
S
with
wentaway
as
closeReason
and
an
empty
closeMessage
.
If
the
user
agent
receives
a
signal
from
the
destination
browsing
context
that
a
PresentationConnection
S
is
to
be
closed,
it
MUST
close
the
presentation
connection
S
with
closed
or
wentaway
as
closeReason
and
an
empty
closeMessage
.
When the user agent is to establish a presentation connection using a presentation connection , it MUST run the following steps:
PresentationConnection
object
that
is
to
be
connected
connecting
,
then
abort
all
remaining
steps.
connected
.
connect
at
presentationConnection
.
error
as
closeReason
,
and
a
human
readable
message
describing
the
failure
as
closeMessage
.
DOMString
and
binary
payloads
in
a
reliable
and
in-order
fashion
as
described
in
the
Send
a
Message
and
Receive
a
Message
steps
below.
PresentationConnection
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
or
binary
.
When the user agent is to send a message through a presentation connection , it MUST run the following steps:
state
property
of
presentationConnection
is
not
connected
,
throw
an
InvalidStateError
exception.
binary
if
messageOrData
is
of
type
ArrayBuffer
,
ArrayBufferView
,
or
Blob
.
Let
messageType
be
text
if
messageOrData
is
of
type
DOMString
.
error
as
closeReason
,
and
a
closeMessage
describing
the
error
encountered.
To assist applications in recovery from an error sending a message through a presentation connection , the user agent should include details of which attempt failed in closeMessage , along with a human readable string explaining the failure reason. Example renditions of closeMessage :
Unable
to
send
text
message
(network_error):
"hello"
for
DOMString
messages,
where
"hello"
is
the
first
256
characters
of
the
failed
message.
Unable
to
send
binary
message
(invalid_message)
for
ArrayBuffer
,
ArrayBufferView
and
Blob
messages.
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
:
state
property
of
presentationConnection
is
not
connected
,
abort
these
steps.
MessageEvent
interface,
with
the
event
type
message
,
which
does
not
bubble,
is
not
cancelable,
and
has
no
default
action.
text
,
then
initialize
event
's
data
attribute
to
messageData
with
type
DOMString
.
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.
binary
,
and
binaryType
attribute
is
set
to
"
arraybuffer
",
then
initialize
event
's
data
attribute
to
a
new
ArrayBuffer
object
whose
contents
are
messageData
.
If
the
user
agent
encounters
an
unrecoverable
error
while
receiving
a
message
through
presentationConnection
,
it
MUST
abruptly
close
the
presentation
connection
presentationConnection
with
error
as
closeReason
.
It
SHOULD
use
a
human
readable
description
of
the
error
encountered
as
closeMessage
.
PresentationConnectionCloseEvent
enumPresentationConnectionCloseReason
{ "error", "closed", "wentaway" }; [Constructor(DOMString type,PresentationConnectionCloseEventInit
eventInitDict), SecureContext, Exposed=Window] interfacePresentationConnectionCloseEvent
:Event
{ readonly attributePresentationConnectionCloseReason
reason
; readonly attribute DOMStringmessage
; }; dictionaryPresentationConnectionCloseEventInit
:EventInit
{ requiredPresentationConnectionCloseReason
reason
; DOMStringmessage
= ""; };
A
PresentationConnectionCloseEvent
is
fired
when
a
presentation
connection
enters
a
closed
state.
The
reason
attribute
provides
the
reason
why
the
connection
was
closed.
It
can
take
one
of
the
values
of
PresentationConnectionCloseReason
:
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
message
attribute
to
a
human
readable
description
of
how
the
communication
channel
encountered
an
error.
When
the
PresentationConnectionCloseEvent
constructor
is
called,
the
user
agent
MUST
construct
a
new
PresentationConnectionCloseEvent
object,
with
its
reason
attribute
set
to
the
reason
member
of
the
PresentationConnectionCloseEventInit
object
passed
to
the
constructor,
and
its
message
attribute
set
to
the
message
member
of
this
PresentationConnectionCloseEventInit
object
if
set,
to
an
empty
string
otherwise.
PresentationConnection
When the user agent is to start closing a presentation connection , it MUST do the following:
PresentationConnectionCloseReason
describing
why
the
connection
is
to
be
closed
connecting
or
connected
then
abort
the
remaining
steps.
closed
.
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.
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:
PresentationConnectionCloseReason
describing
why
the
connection
is
to
be
closed
connecting
,
connected
,
or
closed
,
then
abort
the
remaining
steps.
closed
,
set
it
to
closed
.
close
,
that
uses
the
PresentationConnectionCloseEvent
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.
When a controlling user agent is to terminate a presentation in a controlling browsing context using connection , it MUST run the following steps:
connected
or
connecting
,
then
abort
these
steps.
connected
or
connecting
,
then
queue
a
task
to
run
the
following
steps:
terminated
.
terminate
at
known
connection
.
When any of the following occur, the receiving user agent MUST terminate a presentation in a receiving browsing context :
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
whose
PresentationConnection
objects
are
all
closed
for
30
minutes.
When a receiving user agent is to terminate a presentation in a receiving browsing context , it MUST run the following steps:
connected
,
then
add
connection
to
connectedControllers
.
terminated
.
Only one termination confirmation needs to be sent per 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 MUST run the following steps:
connected
or
connecting
,
then
abort
the
following
steps.
terminated
.
terminate
at
connection
.
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
|
onconnect
|
connect
|
onclose
|
close
|
onterminate
|
terminate
|
PresentationReceiver
[SecureContext,
Exposed=Window]
interface PresentationReceiver
{
readonly attribute Promise<PresentationConnectionList
> connectionList
;
};
The
PresentationReceiver
interface
allows
a
receiving
browsing
context
to
access
the
controlling
browsing
contexts
and
communicate
with
them.
The
PresentationReceiver
interface
MUST
be
implemented
in
a
receiving
browsing
context
provided
by
a
receiving
user
agent
.
On
getting,
the
connectionList
attribute
MUST
return
the
result
of
running
the
following
steps:
null
,
return
the
presentation
controllers
promise
and
abort
all
remaining
steps.
PresentationReceiver
object.
null
,
resolve
the
presentation
controllers
promise
with
the
presentation
controllers
monitor
.
When the user agent is to create a receiving browsing context , it MUST run the following steps:
"denied"
.
All nested browsing contexts created by the presented document, i.e. that have the receiving browsing context as their top-level browsing context , MUST also have restrictions 2-4 above. In addition, they MUST have the sandboxed top-level navigation browsing context flag set. All of these browsing contexts MUST also share the same browsing state (storage) for features 5-10 listed above.
The top-level browsing context MUST NOT be allowed to navigate itself, except by navigating to a fragment identifier . This allows the user to grant permission based on the presentation URL shown when selecting a presentation display .
Window clients and worker clients associated with the receiving browsing context and its list of descendant browsing contexts must not be exposed to service workers associated with each other.
When the receiving browsing context is terminated, any service workers associated with it and the browsing contexts in its list of descendant browsing contexts MUST be unregistered and terminated. Any browsing state associated with the receiving browsing context and the browsing contexts in its list of descendant browsing contexts , including session history , the cookie store , any HTTP authentication state, the application cache , any databases , the session storage areas , the local storage areas , the list of registered service worker registrations and the caches MUST be discarded and not used for any other browsing context .
This algorithm is intended to create a well defined environment to allow interoperable behavior for 1-UA and 2-UA presentations, and to minimize the amount of state remaining on a presentation display used for a 2-UA presentation.
The receiving user agent SHOULD fetch resources in a receiving browsing context with an HTTP Accept-Language header that reflects the language preferences of the controlling user agent (i.e., with the same Accept-Language that the controlling user agent would have sent). This will help the receiving user agent render the presentation with fonts and locale-specific attributes that reflect the user's preferences.
Given the operating context of the presentation display , some Web APIs will not work by design (for example, by requiring user input) or will be obsolete (for example, by attempting window management); the receiving user agent should be aware of this. Furthermore, any modal user interface will need to be handled carefully. The sandboxed modals flag is set on the receiving browsing context to prevent most of these operations.
PresentationConnectionList
[SecureContext,
Exposed=Window]
interface PresentationConnectionList
: EventTarget
{
readonly attribute FrozenArray<PresentationConnection
> connections
;
};
The
connections
attribute
MUST
return
the
non-terminated
set
of
presentation
connections
in
the
set
of
presentation
controllers
.
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:
PresentationConnection
S
.
connected
.
Otherwise,
set
the
presentation
connection
state
of
S
to
closed
and
abort
all
remaining
steps.
null
,
run
the
following
steps
in
parallel
.
PresentationConnectionList
constructed
in
the
JavaScript
realm
of
the
PresentationReceiver
object
of
the
receiving
browsing
context
.
null
,
resolve
the
presentation
controllers
promise
with
the
presentation
controllers
monitor
.
connectionavailable
,
that
uses
the
PresentationConnectionAvailableEvent
interface,
with
the
connection
attribute
initialized
to
S
,
at
the
presentation
controllers
monitor
.
The
event
must
not
bubble,
must
not
be
cancelable,
and
has
no
default
action.
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:
Event handler | Event handler event type |
---|---|
onconnectionavailable
|
connectionavailable
|
This section is non-normative.
The
change
event
fired
on
the
PresentationAvailability
object
reveals
one
bit
of
information
about
the
presence
or
absence
of
a
presentation
display
,
often
discovered
through
the
browser's
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.
The API enables monitoring the list of available presentation displays . How the user agent determines the compatibility and availability of a presentation display with a given URL is an implementation detail. If a controlling user agent matches a presentation request URL to a DIAL application to determine its availability, this feature can be used to probe information about which DIAL applications the user has installed on the presentation display without user consent.
A presentation is allowed to be accessed across origins; the presentation URL and presentation identifier used to create the presentation are the only information needed to reconnect to a presentation from any origin in the controlling user agent. In other words, a presentation is not tied to a particular opening origin.
This design allows controlling contexts from different origins to connect to a shared presentation resource. The security of the presentation identifier prevents arbitrary origins from connecting to an existing presentation.
This
specification
also
allows
a
receiving
user
agent
to
publish
information
about
its
set
of
controlled
presentations
,
and
a
controlling
user
agent
to
reconnect
to
presentations
started
from
other
devices.
This
is
possible
when
the
controlling
browsing
context
obtains
the
presentation
URL
and
presentation
identifier
of
a
running
presentation
from
the
user,
local
storage,
or
a
server,
and
then
connects
to
the
presentation
via
reconnect
.
This
specification
makes
no
guarantee
as
to
the
identity
of
any
party
connecting
to
a
presentation.
Once
connected,
the
presentation
may
wish
to
further
verify
the
identity
of
the
connecting
party
through
application-specific
means.
For
example,
the
presentation
could
challenge
the
controller
to
provide
a
token
via
send
that
the
presentation
uses
to
verify
identity
and
authorization.
When the user is asked permission to use a presentation display during the steps to select a presentation display , the controlling user agent should make it clear what origin is requesting presentation and what origin will be presented.
Display of the origin requesting presentation will help the user understand what content is making the request, especially when the request is initiated from a nested browsing context . For example, embedded content may try to convince the user to click to trigger a request to start an unwanted presentation.
The sandboxed top-level navigation browsing context flag is set on the receiving browsing context to enforce that the top-level origin of the presentation remains the same during the lifetime of the presentation.
When a user starts a presentation , the user will begin with exclusive control of the presentation. However, the Presentation API allows additional devices (likely belonging to distinct users) to connect and thereby control the presentation as well. When a second device connects to a presentation, it is recommended that all connected controlling user agents notify their users via the browser chrome that the original user has lost exclusive access, and there are now multiple controllers for the presentation.
In addition, it may be the case that the receiving user agent is capable of receiving user input, as well as acting as a presentation display . In this case, the receiving user agent should notify its user via browser chrome when a receiving browsing context is under the control of a remote party (i.e., it has one or more connected controllers).
The presentation API abstracts away what "local" means for displays, meaning that it exposes network-accessible displays as though they were directly attached to the user's device. 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.
The presentation URL and presentation identifier 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.
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."
When in private browsing mode ("incognito"), the initial set of controlled presentations in that browsing session must be empty. Any presentation connections added to it must be discarded when the session terminates.
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 .
Thanks to Addison Phillips, Anne Van Kesteren, Anssi Kostiainen, Anton Vayvod, Chris Needham, Christine Runnegar, Daniel Davis, Domenic Denicola, Erik Wilde, François Daoust, 闵洪波 (Hongbo Min), Hongki CHA, Hubert Sablonnière, Hyojin Song, Hyun June Kim, Jean-Claude Dufourd, Joanmarie Diggs, Jonas Sicking, Louay Bassbouss, Mark Watson, Martin Dürst, Matt Hammond, Mike West, Mounir Lamouri, Nick Doty, Oleg Beletski, Philip Jägenstedt, Richard Ishida, Shih-Chiang Chien, Takeshi Kanai, Tobie Langel, Tomoyuki Shimizu, Travis Leithead, and Wayne Carr for help with editing, reviews and feedback to this draft.
AirPlay , HDMI , Chromecast , DLNA and Miracast are registered trademarks of Apple Inc., HDMI Licensing LLC., Google Inc., the Digital Living Network Alliance, and the Wi-Fi Alliance, respectively. They are only cited as background information and their use is not required to implement the specification.
For this specification to be advanced to Proposed Recommendation, there must be, for each of the conformance classes it defines ( controlling user agent and receiving user agent ), at least two independent, interoperable implementations of each feature. Each feature may be implemented by a different set of products, there is no requirement that all features be implemented by a single product. Additionally, implementations of the controlling user agent conformance class must include at least one implementation of the 1-UA mode , and one implementation of the 2-UA mode . 2-UA mode implementations may only support non http/https presentation URLs. Implementations of the receiving user agent conformance class may not include implementations of the 2-UA mode .
The API was recently restricted to secure contexts. Deprecation of the API in non secure contexts in early implementations takes time. The group may request transition to Proposed Recommendation with implementations that still expose the API in non secure contexts, provided there exists a timeline to restrict these implementations in the future.
For the purposes of these criteria, we define the following terms:
This section is non-normative.
This section lists changes made to the spec since it was first published as Candidate Recommendation in July 2016, with links to related issues on the group's issue tracker.