Copyright - © 2014 W3C® (MIT, ERCIM, + © 2014 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. - W3C Beihang). W3C liability, trademark @@ -150,368 +152,379 @@
- This specification defines an API to enable web content to access - external presentation-type 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 http://www.w3.org/TR/. -
-- This document was published by the Second Screen Presentation Working - Group as an Editor's 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. It - builds on the final report - (dated 18 November 2014) produced by the Second Screen Presentation - Community Group. Algorithms have been drafted in particular. Most - sections are still incomplete or underspecified. Privacy and security - considerations are missing. A few open issues are noted inline. Please - check the group's issue tracker on - GitHub for an accurate list. Feedback from early experimentations is - encouraged to allow the Second Screen Presentation Working Group to - evolve the specification based on implementation issues. -
-- 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 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. -
-- This specification aims to make secondary displays such as a projector or - a connected TV 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 - 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 - requesting page and a presentation page shown in the secondary display. - How those messages are transmitted is left to the UA in order to allow - for use of display devices that can be attached in a wide variety of - ways. For example, when a display device is attached using HDMI or - MiraCast, the UA on the requesting device can render the requested - presentation page in that same UA, but instead of displaying in a window - on that same device, it can use whatever means the operating system - provides for using those external displays. In that case, both the - requesting page and the presentation page run on the requesting device - and the operating system is used to route the presentation display output - to the other display device. The second display device doesn't need to - know anything about this spec or that the content involves HTML5. -
-- Alternately, some types of external displays may be able to render HTML5 - themselves and may have defined their own way to send messages to that - content. In that case, the UA on the requesting device would not need to - render the presentation page itself. Instead, the UA could act as a proxy - translating the request to show a page and the messages into the form - understood by the display device. -
-- This way of attaching to displays could be enhanced in the future through - definition of a standard protocol for delivering these types of messages - that display devices could choose to implement. -
-- The API defined here is intended be used with UAs that attach to display - devices through any of the above means. -
-- ISSUE 42: - Carve out the Requirements and Example sections -
-- A user is preparing a set of slides for a talk. Using a web based - service, she is editing her slides and speaker notes on the primary - screen, while the secondary larger screen shows a preview of the current - slide. When the slides are done, her mobile phone allows her to access - them from an online service while on the go. Coming to the conference, - using wireless display technology, she would like to present her slides - on the stage screen from her mobile phone. The phone's touch screen helps - her to navigate slides and presents a slide preview, while the projector - shows her slides to the audience. -
-- Requirements: R1, R3, R4, R5, R7 -
-- Using an online video or image sharing service, a user would like to show - memorable moments to her friends. Using a device with a small screen, it - is impossible to show the content to a large group of people. Connecting - an external TV screen or projector to her device - with a cable or - wirelessly - the online sharing service now makes use of the connected - display, allowing a wider audience to enjoy the content. -
-- The web page shows UI elements that allow the user to trigger displaying - content on the secondary display (e.g a "send to second screen" ) only if - there is at least one secondary screen available. -
-- Requirements: R1, R3, R4, R5, R7 -
-- Splitting the gaming experience into a near screen controller and a large - screen visual experience, new gaming experiences can be created. - Accessing the local display on the small screen device and an external - larger display allows for richer web-based gaming experiences. -
-- Requirements: R1, R3, R4, R5, R7 -
-- ISSUE 27: - Define a Multiplayer Gaming Use Case -
-- Alice enters a video sharing site using a browser on her tablet. Next, - Alice picks her favorite video from the site, and the video starts to - play on her tablet. While the video is playing Alice clicks a button - "Share on different screen". The browser provides a user interface that - lists all the screens Alice has around her home, asking her to select - one. The screens are identified by names that are familiar to Alice. - Alice picks one screen from the list, "Alice's big TV", and the video - playback continues seamlessly on the selected screen. Next she decides to - switch the playback to a different screen. She clicks the same button - "Share on different screen" provided by the site, and the browser - presents the user interface that lists all the screens. Alice picks - another screen from the list, "Alice's kitchen TV", and the playback - resumes on that screen. Video site also provides a feature to see the - action (Alice is watching a soccer game) from different angle. Alice - clicks a button "Select screen for additional angle", and the browser - asks Alice similarly to select the screen to be used for playback. Alice - picks "Alice's Projector" and the soccer game is shown on the projector - from a different angle, in parallel to the content being played back on - "Alice's kitchen TV". -
-- ISSUE 40: - Screen availability mechanism for multiple sessions -
-- Requirements: R1, R3, R4, R5, R6, R7 -
-- Multi-Screen enumeration and named identification removed, after - discussion on the mailing list, cmp. - http://lists.w3.org/Archives/Public/public-webscreens/2014Feb/0021.html : -
-- 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 end result is equivalent. (In - particular, the algorithms defined in this specification are intended to - be easy to follow, and not intended to be performant.) -
-- The terms browsing context, - event handlers, event handler - event types, firing an event, navigate, queing a task are defined in HTML5. -
-- The term Promise is defined in ES6. 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. -
-- This document provides interface definitions using the - WEBIDL standard. -
-
- Running in a compliant user agent, code for presenting a page
- http://example.org/presentation.html on the presentation
- display looks as follows:
-
++ ++ 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 First Public 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. It + builds on the final report + (dated 18 November 2014) produced by the Second Screen Presentation + Community Group. Algorithms have been drafted in particular. Most + sections are still incomplete or underspecified. Privacy and security + considerations are missing. A few open issues are noted inline. Please + check the group's issue tracker on + GitHub for an accurate list. 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 First Public 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. +
++ ++ Table of Contents +
++ ++ Introduction +
This section is non-normative. ++ This specification aims to make secondary displays such as a projector + or a connected TV 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 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 requesting page and a presentation page shown in the secondary + display. How those messages are transmitted is left to the UA in order + to allow for use of display devices that can be attached in a wide + variety of ways. For example, when a display device is attached using + HDMI or MiraCast, the UA on the requesting device can render the + requested presentation page in that same UA, but instead of displaying + in a window on that same device, it can use whatever means the + operating system provides for using those external displays. In that + case, both the requesting page and the presentation page run on the + requesting device and the operating system is used to route the + presentation display output to the other display device. The second + display device doesn't need to know anything about this spec or that + the content involves HTML5. +
++ Alternately, some types of external displays may be able to render + HTML5 themselves and may have defined their own way to send messages to + that content. In that case, the UA on the requesting device would not + need to render the presentation page itself. Instead, the UA could act + as a proxy translating the request to show a page and the messages into + the form understood by the display device. +
++ This way of attaching to displays could be enhanced in the future + through definition of a standard protocol for delivering these types of + messages that display devices could choose to implement. +
++ The API defined here is intended be used with UAs that attach to + display devices through any of the above means. +
++ ++ Use cases and requirements +
++ ++ Use cases +
++
+- + Presentations +
+- + A user is preparing a set of slides for a talk. Using a web based + service, she is editing her slides and speaker notes on the primary + screen, while the secondary larger screen shows a preview of the + current slide. When the slides are done, her mobile phone allows + her to access them from an online service while on the go. Coming + to the conference, using wireless display technology, she would + like to present her slides on the stage screen from her mobile + phone. The phone's touch screen helps her to navigate slides and + presents a slide preview, while the projector shows her slides to + the audience. +
+- + Video and image sharing +
+- + Using an online video or image sharing service, a user would like + to show memorable moments to her friends. Using a device with a + small screen, it is impossible to show the content to a large group + of people. Connecting an external TV screen or projector to her + device - with a cable or wirelessly - the online sharing service + now makes use of the connected display, allowing a wider audience + to enjoy the content. The web page shows UI elements that allow the + user to trigger displaying content on the secondary display (e.g a + "send to second screen" ) only if there is at least one secondary + screen available. +
+- + Multiplayer gaming +
+- + Splitting the gaming experience into a near screen controller and a + large screen visual experience, new gaming experiences can be + created. Accessing the local display on the small screen device and + an external larger display allows for richer web-based gaming + experiences. + +
+- + Media flinging to multiple screens +
+- + Alice enters a video sharing site using a browser on her tablet. + Next, Alice picks her favorite video from the site, and the video + starts to play on her tablet. While the video is playing Alice + clicks a button "Share on different screen". The browser provides a + user interface that lists all the screens Alice has around her + home, asking her to select one. The screens are identified by names + that are familiar to Alice. Alice picks one screen from the list, + "Alice's big TV", and the video playback continues seamlessly on + the selected screen. Next she decides to switch the playback to a + different screen. She clicks the same button "Share on different + screen" provided by the site, and the browser presents the user + interface that lists all the screens. Alice picks another screen + from the list, "Alice's kitchen TV", and the playback resumes on + that screen. Video site also provides a feature to see the action + (Alice is watching a soccer game) from different angle. Alice + clicks a button "Select screen for additional angle", and the + browser asks Alice similarly to select the screen to be used for + playback. Alice picks "Alice's Projector" and the soccer game is + shown on the projector from a different angle, in parallel to the + content being played back on "Alice's kitchen TV". +
++ ISSUE + 40: Screen availability mechanism for multiple sessions +
++ ++ Requirements +
++ The requirements enumerated in this section are derived from the + use cases. +
++ ++ Functional requirements +
++
+- + Discovery & availability +
+- + The UA must provide a way to find out whether at least one + secondary screen is available. +
+- + Launching presentation +
+- + The UA must provide a means of start sending content to the + secondary screen. +
+- + Resuming presentation +
+- + The UA must be able to resume an existing session with content + being displayed on the secondary screen. +
+- + Communication +
+- + The UA must enable exchanging data between the primary and the + secondary screen in order to have a control channel between the + primary and secondary page. The UA must not make assumptions + about the the execution locality of the user agent of the remote + page it communicates with (i.e. the secondary page might run on a + remote user agent and thus the link between the two pages' UA + must be loosely coupled). +
+- + Signaling disconnection +
+- + The UA must signal disconnection from the presentation page to + the primary page and vice versa. +
++ Multi-screen enumeration and named identification requirement was + removed after + discussion on the mailing list. +
++ ++ Non-functional requirements +
++
+- + Power saving friendly +
+- + All API design decisions must be analyzed from a power efficiency + point of view. Especially when using wireless display + technologies or querying availability over a radio channel, care + needs to be taken to design the API in a way that does not pose + obstacles to using radio resources in an efficient way. For + example, powering up the wireless display detection only when + needed. +
++ ++ Conformance +
++ 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 end result is equivalent. (In + particular, the algorithms defined in this specification are intended + to be easy to follow, and not intended to be performant.) +
++ ++ Terminology +
++ The terms browsing context, + event handlers, event handler + event types, firing an event, navigate, queing a task are defined in + HTML5. +
++ The term Promise is defined in ES6. 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. +
++ This document provides interface definitions using the + WEBIDL standard. +
++ ++ Example +
++ ISSUE 42: + Make the Example section more concise +
++ Running in a compliant user agent, code for presenting a page +
+http://example.org/presentation.htmlon the presentation + display looks as follows: +/* controller.html */ <button disabled id=show>Show</button> @@ -587,175 +600,187 @@-} </script>
- We could simplify the example, and perhaps remove UI button state - management for the sake of clarity. -
-- The availability monitoring for secondary screens begins when the page - adds an event listener for the
-availablechangeevent on the -navigator.presentationobject. If there are already - available screens when the page adds the first event listener for the - event, the UA synthesizes a singleavailablechangeevent to - signal the availability. -- ISSUE 8: - Timing of availablechange event to signal screen availability -
-- ISSUE 9: How - to filter available screens according to the content being presented -
-- Starting new presentations or manually connecting to existing - presentations -
-- The "Show" button's state (initially disabled) informs the user of the - availability of secondary screen(s), and the button's state is updated if - the availability changes. (The rationale of putting the actual boolean - information into a property of the event
-e.availableis to - allow the implementation to optimize power consumption for network - discovery of remote wireless screens. If this information was provided in - a globally accessible flag, the network discovery could never be - suspended for keeping the flag up to date.) -- Clicking the "Show" button calls -
-navigator.presentation.startSession(), which causes the user - agent to request from the user a screen to show the presentation. The -urlargument indicates the content to be presented. The -presentationIdargument (optional) allows the page to - identify this presentation instance, and control which other pages may - connect to it by setting a hard-to-guess id. -- As previously discussed on the mailing list - we can add convenience here - by default-generating an ID. -
-- If the user selects a screen with an existing presentation showing the - same
-urlunder the samepresentationId, the - opening browsing context is connected to that existing - presentation. If the user selects a screen without an existing - presentation, or a screen presenting a differenturlor -presentationId, the UA connects to the selected screen, - brings up a new presentation window on it, and starts to show the content - denoted by theurlargument. The UA then connects the - opening browsing context to this new presentation and allows - the opening browsing context to exchange messages with it. --
-navigator.presentation.startSession(url, presentationId)- returns aPromiseto the opening browsing - context. When the user selects a screen, the presentation page is - shown and a communication channel has been established the -Promiseresolves to aPresentationSession- object, which acts as a handle to the presentation for communication and - state handling. Initially, the state of the -PresentationSessionis"connected". At this - point, the opening browsing context can communicate with the - presentation page using the session'spostMessage()to send - messages and itsonmessageevent handler to receive - messages. The presentation page will also have access to -PresentationSessionthat it can use to send and receive - messages with the opening browsing context (see Usage on remote screen). -- If the user cancels screen selection, the
-Promisereturned - bystartSession(url, presentationId)remains unresolved. -- ISSUE 20: - Define return value for cancelled/missing session for -
-startSession()/joinSession()-- While there is a pending call to
-startSessionasking the - user to select a screen (that the user has not yet accepted or canceled), - the browser may choose to reject subsequent calls to -startSessionfrom the same page, by returning a -Promisethat never resolves. This will prevent the browser - from needing to 'queue up' requests to present to the user. -- ISSUE 21: - Define whether multiple simultaneous calls are permitted to -
-startSession()-- Automatically reconnecting to existing presentations -
-- The opening browsing context may wish to reconnect to an - existing presentation without prompting the user to select a screen. For - example, the site could allow media items from different pages to be - shown on the same presentation page, and does not want to prompt the user - on each page to reconnect to that presentation. To reconnect - automatically, the page may call
-joinSession(url, - presentationId), which returns aPromisethat - resolves to an existingPresentationSessionif one exists - that is presenting the sameurlwith the same -presentationIdas was passed originally into -startSession. The opening browsing context can - then communicate with the presentation as if the user had manually - connected to it viastartSession. -- At the time
-joinSession(url, presentationId)is called, if - the browser is not aware of anyPresentationSessionwith a - matchingurlandpresentationId, the -Promiseshould remain unresolved. The browser may become - aware of such a session at a later time (for example, by switching to a - WiFi network that has a screen showing that URL). In this case, the - browser may resolve the Promise to allow the page to connect to the - running session. -- If the browser knows of multiple matching sessions, it should connect the - page to the session that was most recently connected to; if that cannot - be determined by the browser (for example, if the matching sessions have - never been connected), then the
-Promiseshould remain - unresolved. -- ISSUE 39: - Resumption of multiple sessions -
-- If the page calls
-startSession(url, presentationId)and - there is a pendingPromisefrom a call to -joinSession(url, presentationId)(with the same -urlandpresentationId, and the user selects a - screen in response tostartSession, then the -PromisefromstartSessionwill be resolved and - thePromisefromjoinSessionwill not. -- Open questions -
-- ISSUE 10: Is - user permission required to prompt for screen availability - information? -
-- ISSUE 12: - Necessity of an additional state to indicate a session was resumed -
-- Usage on remote screen -
-- For addressing the requirement of communication between originating page - and presentation page/screen, the presenting page can now use the same -
-sessionobject. It accesses this object through the -navigator.presentation.sessionproperty, which is only - non-nullfor the page on the presentation screen. -++ We could simplify the example, and perhaps remove UI button state + management for the sake of clarity. +
++ The availability monitoring for secondary screens begins when the page + adds an event listener for the
+availablechangeevent on + thenavigator.presentationobject. If there are already + available screens when the page adds the first event listener for the + event, the UA synthesizes a singleavailablechangeevent + to signal the availability. ++ ISSUE 8: + Timing of availablechange event to signal screen availability +
++ ISSUE 9: How + to filter available screens according to the content being + presented +
++ ++ Starting new presentations or manually connecting to existing + presentations +
++ The "Show" button's state (initially disabled) informs the user of + the availability of secondary screen(s), and the button's state is + updated if the availability changes. (The rationale of putting the + actual boolean information into a property of the event +
+e.availableis to allow the implementation to optimize + power consumption for network discovery of remote wireless screens. + If this information was provided in a globally accessible flag, the + network discovery could never be suspended for keeping the flag up to + date.) ++ Clicking the "Show" button calls +
+navigator.presentation.startSession(), which causes the + user agent to request from the user a screen to show the + presentation. Theurlargument indicates the content to + be presented. ThepresentationIdargument (optional) + allows the page to identify this presentation instance, and control + which other pages may connect to it by setting a hard-to-guess id. ++ As previously discussed on the mailing list - we can add convenience + here by default-generating an ID. +
++ If the user selects a screen with an existing presentation showing + the same
+urlunder the samepresentationId, + the opening browsing context is connected to that + existing presentation. If the user selects a screen without an + existing presentation, or a screen presenting a different +urlorpresentationId, the UA connects to + the selected screen, brings up a new presentation window on it, and + starts to show the content denoted by theurlargument. + The UA then connects the opening browsing context to + this new presentation and allows the opening browsing + context to exchange messages with it. ++
+navigator.presentation.startSession(url, presentationId)+ returns aPromiseto the opening browsing + context. When the user selects a screen, the presentation page + is shown and a communication channel has been established the +Promiseresolves to aPresentationSession+ object, which acts as a handle to the presentation for communication + and state handling. Initially, the state of the +PresentationSessionis"connected". At this + point, the opening browsing context can communicate with + the presentation page using the session'spostMessage()+ to send messages and itsonmessageevent handler to + receive messages. The presentation page will also have access to +PresentationSessionthat it can use to send and receive + messages with the opening browsing context (see Usage on remote screen). ++ If the user cancels screen selection, the
+Promise+ returned bystartSession(url, presentationId)remains + unresolved. ++ ISSUE 20: + Define return value for cancelled/missing session for +
+startSession()/joinSession()++ While there is a pending call to
+startSessionasking the + user to select a screen (that the user has not yet accepted or + canceled), the browser may choose to reject subsequent calls to +startSessionfrom the same page, by returning a +Promisethat never resolves. This will prevent the + browser from needing to 'queue up' requests to present to the user. ++ ISSUE 21: + Define whether multiple simultaneous calls are permitted to +
+startSession()++ ++ Automatically reconnecting to existing presentations +
++ The opening browsing context may wish to reconnect to an + existing presentation without prompting the user to select a screen. + For example, the site could allow media items from different pages to + be shown on the same presentation page, and does not want to prompt + the user on each page to reconnect to that presentation. To reconnect + automatically, the page may call
+joinSession(url, + presentationId), which returns aPromisethat + resolves to an existingPresentationSessionif one + exists that is presenting the sameurlwith the same +presentationIdas was passed originally into +startSession. The opening browsing context + can then communicate with the presentation as if the user had + manually connected to it viastartSession. ++ At the time
+joinSession(url, presentationId)method is + called, if the browser is not aware of any +PresentationSessionwith a matchingurland +presentationId, thePromiseshould remain + unresolved. The browser may become aware of such a session at a later + time (for example, by switching to a WiFi network that has a screen + showing that URL). In this case, the browser may resolve the Promise + to allow the page to connect to the running session. ++ If the browser knows of multiple matching sessions, it should connect + the page to the session that was most recently connected to; if that + cannot be determined by the browser (for example, if the matching + sessions have never been connected), then the
+Promise+ should remain unresolved. ++ ISSUE 39: + Resumption of multiple sessions +
++ If the page calls
+startSession(url, presentationId)and + there is a pendingPromisefrom a call to +joinSession(url, presentationId)(with the same +urlandpresentationId, and the user + selects a screen in response tostartSession, then the +PromisefromstartSessionwill be resolved + and thePromisefromjoinSessionwill not. ++ ++ Open questions +
++ ISSUE 10: + Is user permission required to prompt for screen availability + information? +
++ ISSUE 12: + Necessity of an additional state to indicate a session was + resumed +
++ ++ Usage on remote screen +
++ For addressing the requirement of communication between originating + page and presentation page/screen, the presenting page can now use + the same
+sessionobject. It accesses this object through + thenavigator.presentation.sessionproperty, which is + only non-nullfor the page on the presentation screen. +if (navigator.presentation.session) { var session = navigator.presentation.session; // Communicate with opening browsing context @@ -770,90 +795,104 @@-}; };
- When the content denoted by the
-urlargument in the -startSession()example above is loaded, the page on the - presentation screen will have its -navigator.presentation.sessionproperty set to the session. - This session is a similar object as in the first example. Here, its - initial state is"connected", which means we can use it to - communicate with the opening browsing context using -postMessage()andonmessage. -- The presentation page can also monitor the connection state by listening - for
-statechangeevents. When the state changes to -"disconnected"the page is made aware of the fact that - communication with the opening browsing context was lost, - but it can continue to display the current content. The communication can - be re-established when astatechangeevent fires with a new - state of"connected". -- ISSUE 19: - Specify behavior when multiple controlling pages are connected to the - session -
-- ISSUE 18: - Define reconnection for cross-page navigation on presenting user - agent -
-- ISSUE 14: - Define user agent context for rendering the presentation -
-- API -
-- Common idioms -
-- A presentation display refers to an external screen available - to the user agent via an implementation specific connection technology. -
-- A presentationis an active - connection between a user agent and a presentation display - for displaying web content on the latter at the request of the former. -
-- A presentation session is - an object relating an opening browsing context to its - presentation display and enabling two-way-messaging between - them. Each such object has a presentation session state and a - presentation session identifier to distinguish it from other - presentation sessions. -
-- An opening browsing context is a browsing context that has initiated or resumed a - presentation session by calling startSession or - joinSession. -
-- Common definitions -
-- Let D be the set of presentations that are currently known to - the user agent (regardles of their state). D is represented as a - set of tuples (U, I, S) where U is the - URL that is being presented; - I is an alphanumeric identifier for the presentation; and - S is the user agent's
-PresentationSessionfor the - presentation. U and I together uniquely identify the -PresentationSessionof the corresponding presentation. -- Interface
-PresentationSession-- Each presentation - session is represented by a
-PresentationSession- object. -++ When the content denoted by the
+urlargument in the +startSession()example above is loaded, the page on the + presentation screen will have its +navigator.presentation.sessionproperty set to the + session. This session is a similar object as in the first example. + Here, its initial state is"connected", which means we + can use it to communicate with the opening browsing + context usingpostMessage()and +onmessage. ++ The presentation page can also monitor the connection state by + listening for
+statechangeevents. When the state changes + to"disconnected"the page is made aware of the fact + that communication with the opening browsing context was + lost, but it can continue to display the current content. The + communication can be re-established when astatechange+ event fires with a new state of"connected". ++ ISSUE 19: + Specify behavior when multiple controlling pages are connected to the + session +
++ ISSUE 18: + Define reconnection for cross-page navigation on presenting user + agent +
++ ISSUE 14: + Define user agent context for rendering the presentation +
++ ++ API +
++ ++ Common idioms +
++ A presentation display refers to an external screen + available to the user agent via an implementation specific connection + technology. +
++ A presentation is an active + connection between a user agent and a presentation + display for displaying web content on the latter at the + request of the former. +
++ A presentation + session is an object relating an opening browsing + context to its presentation display and enabling + two-way-messaging between them. Each such object has a + presentation session state and a presentation session + identifier to distinguish it from other presentation sessions. +
++ An opening browsing context is a browsing context that has initiated or resumed a + presentation session by calling +
+startSession()or +joinSession(). ++ ++ Common definitions +
++ Let D be the set of presentations that are currently known + to the user agent (regardles of their state). D is + represented as a set of tuples (U, I, S) where U is + the URL that is being presented; + I is an alphanumeric identifier for the presentation; and + S is the user agent's
+PresentationSessionfor + the presentation. U and I together uniquely + identify thePresentationSessionof the corresponding + presentation. ++ ++ Interface
+PresentationSession++ Each presentation + session is represented by a
+PresentationSession+ object. +enum PresentationSessionState { "connected", "disconnected" /*, "resumed" */ }; interface PresentationSession : EventTarget { @@ -867,140 +906,155 @@-"w3c-html">EventHandler onstatechange; };
- The
-idattribute holds the alphanumeric - presentation session identifier. -- The
-stateattribute represents the - presentation session's current state. It can take one of the - values ofPresentationSessionStatedepending on - connection state. -- When the
-postMessage() method is called on a -PresentationSessionobject with amessage, the - user agent must run the algorithm to post 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. -- Posting a message through
-PresentationSession-- When the user agent is to post a - message through a
-PresentationSessionS, it must run - the following steps: -- ISSUE 46: - Define postMessage behavior -
-- Closing a
-PresentationSession-- When the user agent is to close a - presentation session S, it must run the following steps: -
--
-- If S.state is not
-connected, then: --
-- Abort these steps. -
-- Set S.state to
-disconnected. -- Let D be the set of presentations known by the user agent. -
-- - Queue a task T to run - the following steps in order: -
--
-- For each presentation (U, I, S') in D, -
--
-- Let u equal U, i equal I, - and s equal S'. -
-- If u is equal to S.url and i is - equal to S.id, run the following steps: -
--
-- - Queue a task to - fire an event named -
-statechangeat s.onstatechange. -- ISSUE 35: - Refine how to do session teardown/disconnect/closing -
-- 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
-NavigatorPresentation-++ The
+idattribute holds the alphanumeric + presentation session identifier. ++ The
+stateattribute represents the + presentation session's current state. It can take one of + the values ofPresentationSessionState+ depending on connection state. ++ When the
+postMessage()method is called on a +PresentationSessionobject with amessage, + the user agent must run the algorithm to post 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. ++ ISSUE 34: + Specify the presentation initialization algorithm +
++ ++ Posting a message through
+PresentationSession++ When the user agent is to post + a message through a
+ +PresentationSessionS, it + must run the following steps: ++ ++ Closing a
+PresentationSession++ When the user agent is to close a + presentation session S, it must run the following steps: +
++
+- If S.state is not
+connected, then: ++
+- Abort these steps. +
+- Set S.state to
+disconnected. +- Let D be the set of presentations known by the user + agent. +
+- + Queue a task T + to run the following steps in order: +
++
+- For each presentation (U, I, S') in D, +
++
+- Let u equal U, i equal + I, and s equal S'. +
+- If u is equal to S.url and i + is equal to S.id, run the following steps: +
++
+- + Queue a task + to fire an event named +
+statechangeat s.onstatechange. ++ ISSUE + 35: Refine how to do session teardown/disconnect/closing +
++ ++ 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 +
+PresentationSessioninterface: ++ +
++ + + ++ Event handler + ++ Event handler event type + ++ ++ +onmessage++ +message++ + ++ +onstatechange++ +statechange++ ++ Interface
+NavigatorPresentation+partial interface Navigator { readonly attribute NavigatorPresentation presentation; };-- The
-presentationattribute is used to retrieve an - instance of theNavigatorPresentationinterface, the main - interface of Presentation API. -++ The
+presentationattribute is used to retrieve + an instance of theNavigatorPresentationinterface, the + main interface of Presentation API. +interface NavigatorPresentation : EventTarget { readonly attribute PresentationSession? session; Promise<PresentationSession> startSession(DOMString url, DOMString? presentationId); @@ -1009,104 +1063,201 @@-"w3c-html">EventHandler onavailablechange; };
- Define contents of
-sessionattribute. Clarification: The - purpose of the session attribute is to provide the presented page with - access to the PresentationSession without allowing a potential race - condition between the registration of an event handler and the firing of - an event, or complicating the browser implementation to fix this case. It - should be null in an opening context and non-null in a presented - document. -- Starting a presentation session -
-- When
-startSession(presentationUrl, - presentationId)is called, the user agent must run the following - steps: --
-- - Input -
-- -
-presentationUrl, the URL of the document to be presented -- -
-presentationId, an optional identifier for the - presentation -- - Output -
-- - P, a Promise -
--
- Let P be a new Promise. -
-- Return P. -
-- If the user agent does not monitor presentation display - availability, run the following steps: -
--
-- - Monitor presentation display availability. -
-- Wait until the algorithm completes. -
-- If the availableDisplays list is - empty, then: +
-+ ISSUE 52: + Specify the NavigatorPresentation.session attribute and its related + algorithms +
++ + Starting a presentation session +
++ When the
+startSession(presentationUrl, + presentationId)method is called, the user agent must run the + following steps: ++
- + Input +
+- +
+presentationUrl, the URL of the document to be presented +- +
+presentationId, an optional identifier for the + presentation +- + Output +
+- + P, a Promise +
+-
-- - Reject P with a - "NoScreensAvailable" exception. +
- Let P be a new Promise.
-- Abort all remaining steps. +
- Return P.
-- 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 screen, run the following steps: +
- If the user agent does not monitor presentation display + availability, run the following steps:
+-
+- If
presentationIdis not undefined, - assign I to that thatpresentationId. +- + Monitor presentation display availability.
-- If
presentationIdisundefined, let - I be a random alphanumeric value of at least 16 - characters drawn from the characters[A-Za-z0-9]. +- Wait until the algorithm completes.
-- Create a new
PresentationSessionS. +- If the availableDisplays list is + empty, then: +
++
+- + Reject P with a + "NoScreensAvailable" exception.
-- Set
S.urltopresentationUrl, set -S.idto I, and setS.stateto -disconnected. +- Abort all remaining steps.
-- - Queue a task - C to create a new browsing context on the user-selected - presentation display and - navigate to -
presentationUrlin it. +- 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 screen, run the following steps:
+-
+- If C completes successfully, run the following - steps: +
- If
+presentationIdis not undefined, + assign I to that thatpresentationId. +- If
+presentationIdisundefined, + let I be a random alphanumeric value of at least 16 + characters drawn from the characters +[A-Za-z0-9]. +- Create a new
+PresentationSessionS. +- Set
+S.urltopresentationUrl, + setS.idto I, and set +S.statetodisconnected. +- + Queue a task + C to create a new browsing context on the user-selected + presentation display and + navigate to +
+presentationUrlin it.-
+- Add (S.url, S.id, S) to D. +
- If C completes successfully, run the + following steps: +
++
+- Add (S.url, S.id, S) to D. +
+- + Resolve P with + S. +
+- + Establish a presentation connection + with S. +
+- If C fails, run the following steps: +
++
- + Reject P with a "failed" + exception. +
+- If T completes with the user denying + permission, run the following steps: +
++
+- + Reject P with a + "PermissionDenied" exception. +
++ 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 screen + (granting permission), or cancel the selection (denying permission). +
++ 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
+onavailablechange. ++ ++ Joining a presentation session +
++ When the
+joinSession(presentationUrl, + presentationId)method is called, the user agent must run the + following steps: ++
+- + Input +
+- +
+presentationUrl, the URL of the document being presented +- +
+presentationId, the identifier for the presentation +- + Output +
+- + P, a Promise +
++
- - -- Let P be a new Promise. +
+- Return P. +
+- Let D be the set of presentations known by the user + agent. +
+- + Queue a task T to + run the following steps in order: +
-+
-- For each presentation (U, I, S) in D, +
-+
- Let u equal U, i equal + I, and s equal S. +
+- If u is equal to
-presentationUrl+ and i is equal topresentationId, run + the following steps: +-
- Resolve P with @@ -1116,159 +1267,73 @@
-Establish a presentation connection with S.
- If C fails, run the following steps: -
-
- - Reject P with a "failed" - exception. +
- Abort the remaining steps of T.
- If T completes with the user denying - permission, run the following steps: -
- Reject P with a - "PermissionDenied" exception. + "NoPresentationFound" exception.
- 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 screen (granting permission), or - cancel the selection (denying permission). -
-- Do we want to distinguish the permission-denied outcome from the - no-screens-available outcome? Developers would be able to infer it anyway - from
-onavailablechange. -- Joining a presentation session -
-- When
-joinSession(presentationUrl, presentationId)- is called, the user agent must run the following steps: --
-- - Input -
-- -
-presentationUrl, the URL of the document being presented -- -
-presentationId, the identifier for the presentation -- - Output -
-- - P, a Promise -
--
- Let P be a new Promise. -
-- Return P. -
-- Let D be the set of presentations known by the user agent. -
-- - Queue a task T to run - the following steps in order: +
+ ISSUE: If no matching presentation is found, we could leave the + Promise pending in case a matching presentation is started in the + future. +
++ ++ Establishing a presentation connection +
++ When the user agent is to establish a presentation + connection using a presentation session + S, it must run the following steps: +
-
- - -- For each presentation (U, I, S) in D, +
- If S.state is
connected, then:-
- Let u equal U, i equal I, - and s equal S. -
-- If u is equal to
presentationUrland - i is equal topresentationId, run the - following steps: --
+- - Resolve P with S. -
-- - Establish a presentation connection with - S. -
-- Abort the remaining steps of T. -
-- Abort all remaining steps.
- - Reject P with a - "NoPresentationFound" exception. -
-- If no matching presentation is found, we could leave the Promise pending - in case a matching presentation is started in the future. -
-- Establishing a presentation connection -
-- When the user agent is to establish a presentation connection - using a presentation session S, it must run the - following steps: -
--
- If S.state is
-connected, then: --
-- Abort all remaining steps. -
-- - Queue a task T to - connect S to the document that is presenting S.url. -
-- If T completes successfully, run the following steps: -
-
-- Set S.state to
-connected.-- Let D be the set of presentations known by the user - agent. + Queue a task T to + connect S to the document that is presenting + S.url.
-- Queue a task T to run the following steps in order: +
- If T completes successfully, run the following steps:
--
-- For each presentation (U, I, S') in D, +
- Set S.state to
+connected.+- Let D be the set of presentations known by the user + agent. +
+- Queue a task T to run the following steps in order:
-
- Let u equal U, i equal - I, and s equal S'. -
-- If u is equal to S.url and i - is equal to S.id, run the following steps: +
- For each presentation (U, I, S') in D,
@@ -1277,172 +1342,190 @@-
- - Queue a task - to fire an event named -
statechangeat s.onstatechange. +- Let u equal U, i equal + I, and s equal S'. +
+- If u is equal to S.url and + i is equal to S.id, run the following + steps: +
+
- + Queue a + task to fire an event + named
+statechangeat + s.onstatechange. +
- The mechanism that is used to present on the remote display and connect - the opening 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. -
-- Do we want to notify the caller of a failure to connect, i.e. with an - "error" onstatechange? -
-- Do we want to pass the new state as a property of the statechange event? -
-- The
-onavailablechangeEventHandler -- 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 - -- - -- -onavailablechange-- -availablechange-- In order to satisfy the power - saving non-functionional requirements the user agent must keep - track of the number of
The user agent must keep a list of available presentation - displays. According to the number of event handlers for -EventHandlers registered to the -onavailableevent. Using this information, implementation - specific discovery of presentation - displays can be resumed or suspended, in order to save power. -onavailablechange, the user agent must also keep the list up - to date by running the algorithm for monitoring the list of available presentation - displays. -- Adding an
-EventHandlertoonavailablechange-- When an event handler is added to the list of event handlers registered - for the
-onavailablechangeevent, the user agent must run the - algorithm to monitor the list - of available presentation displays. -- Removing an
-EventHandler-- When an event handler is removed from the list of event handlers - registered to the
-onavailablechangeevent, the user agent - must run the following steps: --
-- If the removed event handler was the last one in the list, - cancel monitoring the list of available presentation - displays. -
-- Monitoring the list of available presentation displays -
-- When the user agent is to monitor the list of available presentation - displays, it must run the following steps: -
-- While there are event handlers - added to NavigatorPresentation.onavailablechange, the user agent must - continuously keep track the list of available presentation - displays and repeat the following steps: -
--
- - Queue a task to retrieve the - the list of curently available presentation displays and let newDisplays be this list. -
-- Wait for the completion of that task. -
-- If availableDisplays is empty and - newDisplays is not empty, then +
+ The mechanism that is used to present on the remote display and + connect the opening 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
+DOMStringpayloads 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? +
++ ++ The
+onavailablechangeEventHandler ++ 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 +
+PresentationSessioninterface: ++ +
++ + + ++ Event handler + ++ Event handler event type + ++ + ++ +onavailablechange++ +availablechange++ In order to satisfy the power saving non-functionional + requirements the user agent must keep track of the number of +
The user agent must keep a list of available presentation + displays. According to the number of event handlers for +EventHandlers registered to theonavailable+ event. Using this information, implementation specific discovery of + presentation displays can + be resumed or suspended, in order to save power. +onavailablechange, the user agent must also keep the list + up to date by running the algorithm for monitoring the list of available + presentation displays. ++ ++ Adding an
+EventHandlertoonavailablechange++ When an event handler is added to the list of event handlers + registered for the
+onavailablechangeevent, the user + agent must run the algorithm to monitor the list of + available presentation displays. ++ ++ Removing an
+EventHandler++ When an event handler is removed from the list of event handlers + registered to the
+onavailablechangeevent, the user + agent must run the following steps: ++
+- If the removed event handler was the last one in the list, + cancel monitoring the list of available presentation + displays. +
++ + ++ Monitoring the list of available presentation displays +
++ When the user agent is to monitor the list of available + presentation displays, it must run the following steps: +
++ While there are event + handlers added to NavigatorPresentation.onavailablechange, the + user agent must continuously keep track the list of available + presentation displays and repeat the following steps: +
- -
- - Queue a task to - fire - an event named
+availablechangeat with the - event'savailableproperty set totrue. + Queue a task to retrieve + the the list of curently available presentation displays and let newDisplays be this list. +- Wait for the completion of that task. +
+- If availableDisplays is empty + and newDisplays is not empty, then +
++
+- + Queue a task to + fire an event named +
+availablechangeat with the event's +availableproperty set totrue. +- If availableDisplays is not + empty and newDisplays is empty, then: +
++
+- + Queue a task to + fire an event named +
+availablechangewith the event's +availableproperty set tofalse. +- Set the list of available presentation displays to + the value of newDisplays.
- If availableDisplays is not empty - and newDisplays is empty, then: +
-+ The mechanism used to monitor presention displays availability is left + to the user agent. The user agent may choose search for screens at + any time, not just when event handlers are added to +
+NavigatorPresentation.onavailablechange. ++ When the user agent is to cancel monitoring the list of + available presentation displays, it must run the following + steps: +
+
-- Cancel any tasks to retrieve the list of available presentation displays. +
+- Set the list of available presentation displays to + empty. +
- Queue a task to fire - an event named
availablechangewith the event's -availableproperty set tofalse. + an event namedavailablechangeat E + (and only E) with the event'savailable+ property set tofalse.- Set the list of available presentation displays to the - value of newDisplays. -
- -- The mechanism used to monitor presention - displays availability is left to the user agent. The user agent may - choose search for screens at any time, not just when event handlers are - added to
-NavigatorPresentation.onavailablechange. -- When the user agent is to cancel monitoring the list of available - presentation displays, it must run the following steps: -
--
-- Cancel any tasks to retrieve the list of available presentation displays. -
-- Set the list of available presentation displays to - empty. -
-- - Queue a task to - fire an - event named
-availablechangeat E (and only - E) with the event'savailableproperty set to -false. -- Interface
-AvailableChangeEvent-++ ++ Interface
+AvailableChangeEvent+[Constructor(DOMString type, optional AvailableChangeEventInit eventInitDict)] interface AvailableChangeEvent : Event { readonly attribute boolean available; @@ -1453,40 +1536,41 @@-};
- An event named
-availablechangeis fired during the execution - of the monitoring presentation display availability - algorithm when the presentation display availability changes. - It is fired at thePresentationSessionobject, - using theAvailableChangeEventinterface, with the -availableattribute set to the boolean value that the - algorithm determined. -- TODO -
-- ISSUE 34: - Flesh out the algorithms -
-- Security and Privacy Considerations -
-- ISSUE 45: - Security and privacy considerations section -
-- References -
- -- Acknowledgments -
-- Thanks to Wayne Carr, Louay Bassbous, Anssi Kostiainen, 闵洪波 (Hongbo Min), - Anton Vayvod, and Mark Foltz for help with editing, reviews and feedback - to this draft. -
++ An event named
+availablechangeis fired during the + execution of the monitoring presentation display + availability algorithm when the presentation display + availability changes. It is fired at the +PresentationSessionobject, using the +AvailableChangeEventinterface, with the +availableattribute set to the boolean value that the + algorithm determined. ++ ++ Security and privacy considerations +
+ ++ ++ References +
+ ++ + Acknowledgments +
++ Thanks to Wayne Carr, Louay Bassbous, Anssi Kostiainen, 闵洪波 (Hongbo + Min), Anton Vayvod, and Mark Foltz for help with editing, reviews and + feedback to this draft. +
+