Abstract
This specification defines an API to enable web content to access
external presentation-type displays and use them for presenting web
content.
Status of This Document
This section describes the status of this document at the time of
its publication. Other documents may supersede this document. A list of
current W3C publications and the latest revision of this technical
report can be found in the W3C
technical reports index at http://www.w3.org/TR/.
This document was published by the Second Screen Presentation
Working Group as a Working Draft. If you wish to make comments
regarding this document, please send them to public-secondscreen@w3.org
(subscribe,
archives).
All comments are welcome.
This document is a work in progress and is subject to change.
Some sections are still incomplete or underspecified. Security and privacy
considerations need to be adjusted based on feedback and
experience. Some open issues are noted inline; please check the group's
issue
tracker on GitHub for all open issues. Feedback from early
experimentations is encouraged to allow the Second Screen Presentation
Working Group to evolve the specification based on implementation
issues.
Publication as a Working 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 5 February 2004
W3C Patent Policy. W3C maintains a public list of any patent disclosures made in
connection with the deliverables of the group; that page also includes
instructions for disclosing a patent. An individual who has actual
knowledge of a patent 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 August 2014 W3C Process Document.
1
Introduction
This section is non-normative.
This specification aims to make presentation displays such
as projectors or connected TVs, available to the Web and takes into
account displays that are attached using wired (HDMI, DVI, or similar)
and wireless technologies (Miracast, Chromecast, DLNA, AirPlay, or
similar).
Devices with limited screen size lack the ability to show content to a
larger audience, for example, a group of colleagues in a conference
room, or friends and family at home. Showing content on an external
large presentation display helps to improve the perceived
quality and impact of the presented content.
At its core, this specification enables an exchange of messages between
a page that acts as the controller and another page that
represents the presentation shown in the
presentation display. How the messages are transmitted is
left to the UA in order to allow the use of presentation
display devices that can be attached in a wide variety of ways.
For example, when a presentation display device is
attached using HDMI or Miracast, the same UA that acts as the
controller renders the presentation. Instead
of displaying the presentation in another window on the
same device, however, it can use whatever means the operating system
provides for using the external presentation displays. In
such a case, both the controller and
presentation run on the same UA and the operating system
is used to route the presentation display output to the
presentation display. This specification imposes no
requirements on the presentation display devices connected
in such a manner.
If the presentation display is able to render HTML
documents and communicate with the controller, the
controller does not need to render the
presentation. In this case, the UA acts as a proxy that
requests the presentation display to show and render the
presentation itself. This way of attaching to displays
could be enhanced in the future by defining a standard protocol for
delivering these types of messages that display devices could choose to
implement.
The API defined here is intended to be used with UAs that attach to
presentation display devices through any of the above
means.
All diagrams, examples, and notes in this specification are
non-normative, as are all sections explicitly marked non-normative.
Everything else in this specification is normative.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in RFC
2119. For readability, these words do not appear in all uppercase
letters in this specification. [RFC2119]
Requirements phrased in the imperative as part of algorithms (such as
"strip any leading space characters" or "return false and terminate
these steps") are to be interpreted with the meaning of the key word
("must", "should", "may", etc.) used in introducing the algorithm.
Conformance requirements phrased as algorithms or specific steps may be
implemented in any manner, so long as the result is equivalent. (In
particular, the algorithms defined in this specification are intended
to be easy to follow, and not intended to be performant.)
5
Examples
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 http://example.org
(http://example.org/controller.html and
http://example.org/presentation.html). Please refer to the
comments in the code examples for further details.
5.1
Monitor availability of presentation displays example
<!-- controller.html -->
<button id="castBtn" style="display: none;">Cast</button>
<script>
// it is also possible to use relative presentation URL e.g. "presentation.html"
var presUrl = "http://example.com/presentation.html";
// the cast button is visible if at least one presentation display is available
var castBtn = document.getElementById("castBtn");
// show or hide cast button depending on display availability
var handleAvailabilityChange = function(available) {
castBtn.style.display = available ? "inline" : "none";
};
// Promise is resolved as soon as the presentation display availability is known.
navigator.presentation.getAvailability(presUrl).then(function(availability) {
// availability.value may be kept up-to-date by the 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, discovery of presentation
// displays will happen only after startSession() call. Pretend the devices are
// available for simplicity (one could implement the third state for the button).
handleAvailabilityChange(true);
});
</script>
5.2
Starting a new presentation session example
<!-- controller.html -->
<script>
// it is also possible to use relative presentation URL e.g. "presentation.html"
var presUrl = "http://example.com/presentation.html";
// Start new session.
navigator.presentation.startSession(presUrl)
// the new started session will be passed to setSession on success
.then(setSession)
// user cancels the selection dialog or an error is occurred
.catch(endSession);
</script>
5.3
Joining a presentation session example
<!-- controller.html -->
<script>
// read presId from localStorage if exists
var presId = localStorage && localStorage["presId"] || null;
// presId is mandatory for joinSession.
presId && navigator.presentation.joinSession(presUrl, presId)
// The joined session will be passed to setSession on success
.then(setSession)
// no session found for presUrl and presId or an error is occurred
.catch(endSession);
</script>
5.4
Handling an event for a UA initiated presentation session example
<!-- controller.html -->
<head>
<!-- the link element with rel='default-presentation' allows the page to specify -->
<!-- the presentation URL and id for when the UA initiates a presentation session -->
<link href="http://example.com/presentation.html" rel="default-presentation" >
</head>
<script>
navigator.presentation.ondefaultsessionstart = function (evt) {
setSession(evt.session);
};
</script>
5.5
Monitor session's state and exchange data example
<!-- controller.html -->
<script>
var session;
var setSession = function (theSession) {
// end existing session, if any
endSession();
// set the new session
session = theSession;
if (session) {
// save presId in localStorage
localStorage && (localStorage["presId"] = session.id);
// monitor session's state
session.onstatechange = function () {
if (this == session && this.state == "disconnected")
endSession();
};
// register message handler
session.onmessage = function (evt) {
console.log("receive message", evt.data);
};
// send message to presentation page
session.send("say hello");
}
};
var endSession = function () {
// close old session if exists
session && session.close();
// remove old presId from localStorage if exists
localStorage && delete localStorage["presId"];
};
</script>
<!-- presentation.html -->
<script>
var addSession = function(session) {
session.onstatechange = function () {
// session.state is either 'connected' or 'disconnected'
console.log("session's state is now", session.state);
};
session.onmessage = function (evt) {
if (evt.data == "say hello")
session.send("hello");
}
});
navigator.presentation.getSession().then(addSession);
navigator.presentation.onsessionavailable = function(evt) {
navigator.presentation.getSessions().then(function(sessions) {
addSession(sessions[sessions.length-1]);
});
};
</script>
6
API
Each presentation session is represented by a
PresentationSession object.
enum PresentationSessionState { "connected", "disconnected" /*, "resumed" */ };
enum BinaryType { "blob", "arraybuffer" };
interface PresentationSession : EventTarget {
readonly DOMString? id;
readonly attribute PresentationSessionState state;
void close();
attribute EventHandler onstatechange;
// Communication
attribute BinaryType binaryType;
EventHandler onmessage;
void send (DOMString message);
void send (Blob data);
void send (ArrayBuffer data);
void send (ArrayBufferView data);
};
The id attribute specifies the
presentation session's presentation session
identifier.
The state attribute represents the
presentation session's current state. It can take one of
the values of PresentationSessionState
depending on connection state.
When the send() method is called on a
PresentationSession object with a message,
the user agent must run the algorithm to send a message through a
PresentationSession.
When the close() method is called on a
PresentationSession, the user agent must run the
algorithm to close a presentation
session with 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:
- If the
state property of
PresentationSession is "disconnected",
abort these steps.
- 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.
- Initialize the event's data attribute as follows:
- If the presentation message type is
text, then initialize event's
data attribute to the contents of
presentation message data of type
DOMString.
- 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.
- 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.
-
Queue a task to
fire
event at
PresentationSession.
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:
|
Event handler
|
Event handler event type
|
onmessage
|
message
|
onstatechange
|
statechange
|
interface Availability : EventTarget {
readonly attribute boolean value;
attribute EventHandler onchange;
};
An Availability object is associated with a
presentation display and represents its
presentation display availability.
The value attribute must return the last value it was
set to. The value is updated by the monitor the list of
available presentation displays algorithm.
The onchange attribute is an event handler whose
corresponding event handler event
type is change.
When the user agent is to signal a presentation display
availability change using availability object, the
user agent must run the following steps:
-
Queue a task to
fire
an event named
change at availability
object.
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:
-
A is a live
Availability object;
-
availabilityUrl is the
availabilityUrl
passed to getAvailability() to create A.
-
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.
-
Queue a task to retrieve
available presentation displays (using an implementation specific
mechanism) and let newDisplays
be this list.
- Wait for the completion of that task.
- For each member (A, availabilityUrl, P) of the
set of availability objects:
- Set previousAvailability to the value of
A's
value property.
- 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.
- Set A's
value property to
newAvailability.
- If P is not settled, then
resolve P with A.
- If previousAvailability is not equal to
newAvailability, signal a presentation display
availability change with A.
- 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:
- Find and remove any entry (A, availabilityUrl, P) in
the set of availability objects for the newly deceased
A.
- 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.
partial interface Navigator {
readonly attribute NavigatorPresentation presentation;
};
The presentation attribute is
used to retrieve an instance of the
NavigatorPresentation interface.
interface NavigatorPresentation : EventTarget {
// This API used by controlling browsing context.
Promise<PresentationSession> startSession(DOMString url);
Promise<PresentationSession> joinSession(DOMString url, DOMString presentationId);
Promise<Availability> getAvailability(DOMString url);
attribute EventHandler ondefaultsessionstart;
// This API used by presenting browsing context.
Promise<PresentationSession> getSession();
Promise<PresentationSession[]> getSessions();
attribute EventHandler onsessionavailable;
};
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
- Let P be a new Promise.
- Return P.
- Run the following steps:
-
Monitor the list of available presentation
displays.
- Wait until the algorithm completes.
- If either of the following is true:
- The list of available presentation displays is
empty;
- No member if the list of available presentation displays is
a compatible presentation display for
presentationUrl;
- Then run the following steps:
-
Reject P with a
DOMException named
"NotFoundError".
- Abort all remaining steps.
-
Queue a task T
to request user permission for the use of a
presentation display
and selection of one presentation display.
- If T completes with the user granting
permission to use a display, run the following steps:
- Let I be a new valid presentation
session identifier unique among all
presentation session identifiers for known
sessions in the set of presentations.
- Create a new
PresentationSession
S.
- Set the presentation session identifier of
S to I, and set the
presentation session state of S to
disconnected.
-
Queue a task
C to create a new browsing context on the user-selected
presentation display and
navigate to
presentationUrl in it.
- If C completes successfully, run the
following steps:
- Add the tuple {presentationUrl,
S.id, S} to the set of
presentations.
-
Resolve P with
S.
-
Establish a presentation connection
with S.
- If C fails, run the following steps:
-
Reject P with a
DOMException named
"OperationError".
- If T completes with the user denying
permission, run the following steps:
-
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
- Let P be a new Promise.
- Return P.
-
Queue a task T
to run the following steps in order:
- For each known session in the set of
presentations,
-
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:
- If the presentation session state of S
is
connected, then:
- Abort all remaining steps.
-
Queue a task T
to connect the presentation session S to
the presenting browsing context.
- If T completes successfully, run the following steps:
- Set the presentation session state of
S to
connected.
-
Queue a task
T to run the following steps in order:
- For each known session in the set of
presentations:
- If the presentation session identifier
of known session and S are equal,
then run the following steps:
-
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.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:
- Let P be a new Promise.
- Return P.
-
Queue a
task to run the following steps in order:
- Let array be an empty array.
- For each known session in the set of
presentations
- Add known session to array.
-
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:
|
Event handler
|
Event handler event type
|
ondefaultsessionstart
|
defaultsessionstart
|
onsessionavailable
|
sessionavailable
|
6.5
Interface DefaultSessionStart
[Constructor(DOMString type, optional DefaultSessionStartEventInit eventInitDict)]
interface DefaultSessionStartEvent : Event {
readonly attribute PresentationSession session;
};
dictionary DefaultSessionStartEventInit : EventInit {
PresentationSession session;
};
An event named defaultsessionstart is fired when the UA
initiates a presentation on behalf of the page. It is fired at the
NavigatorPresentation object, using the
DefaultSessionStartEvent interface, with the
session attribute set to the
PresentationSession object provided by the
UA.
7
Security and privacy considerations
ISSUE 45:
Security and privacy considerations section
The change event fired on the Availability
object reveals one bit of information about the presence (or
non-presence) of a presentation screen typically
discovered through the 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.
If we allow the page to filter the set of presentation screens based on
capabilities, then more bits of more information would be revealed.
This feature, if implemented, should take privacy into consideration.
See ISSUE 9:
How to filter available screens according to the content being
presented?
We do not want to require user permission before disclosing the
presence of a presentation display, as it is counter to the initial
purpose of improving the user experience. See ISSUE 10: Is user
permission required to prompt for screen availability information?
7.2
Cross-origin access
A presentation session is allowed to be accessed across
origins; the presentation URL and presentation ID used to create the
presentation are the only information needed to join a session from any
origin in that user agent. In other words, a presentation is not tied
to a particular opening origin.
This design allows controlling contexts from different domains to
connect to a shared presentation resource. The security of the
presentation ID prevents arbitrary pages from connecting to an existing
presentation.
This specification does not prohibit a user agent from publishing
information about its set of presentations. The group
envisions a user agent on a another device (distinct from the
controller or presentation) becoming authorized to join the
presentation, either by user action or by discovering the
presentation's URL and id.
This section should provide informative guidance as to what constitutes
a reasonable context for a Web page to become authorized to control a
presentation session.
7.3
Device Access
The presentation API abstracts away what "local" means for displays,
meaning that it exposes network-accessible displays as though they were
local displays. 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.
7.4
Temporary identifiers and browser state
The presentation URL and presentation ID can be used to connect to a
presentation session from another browsing context. They can be
intercepted if an attacker can inject content into the controlling
page.
Should we restrict the API to some extent in non secure contexts?
7.5
Incognito mode and clearing of browsing data
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 presenting 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."
The spec should specify any restrictions on the presenting browsing
context when the opening browsing context is in "incognito" mode. See
ISSUE 14:
Define user agent context for rendering the presentation
The spec should clarify what is to happen to the set of known
presentations in "incognito" (private browsing context) mode.
7.6
Messaging between presentation sessions
This spec will not mandate communication protocols, but it should set
some guarantees of message confidentiality and authenticity.
ISSUE 80:
Define security requirements for messaging channel between secure
origins
8
References
- [FILEAPI]
- File API, Arun Ranganathan and Jonas Sicking. W3C.
- [HTML5]
- HTML5, Robin Berjon, Steve Faulkner, Travis Leithead et al.. W3C.
- [PROMGUIDE]
- Writing Promise-Using Specifications, Domenic Denicola. W3C.
- [RFC2119]
- Key words for use in RFCs to Indicate Requirement Levels, Scott Bradner. IETF.
- [URL]
- URL, Anne van Kesteren. WHATWG.
- [WEBIDL]
- Web IDL, Cameron McCormack. W3C.
- [WEBRTC]
- (Non-normative) WebRTC, Ian Hickson, Adam Bergkvist, Daniel C. Burnett et al.. W3C.
9
Acknowledgments
Thanks to Wayne Carr, Louay Bassbouss, Anssi Kostiainen, 闵洪波 (Hongbo
Min), Anton Vayvod, and Mark Foltz for help with editing, reviews and
feedback to this draft.