Movatterモバイル変換


[0]ホーム

URL:


W3C

Presentation API

W3C Editor's Draft

This version:
https://w3c.github.io/presentation-api/
Latest published version:
https://www.w3.org/TR/presentation-api/
Latest editor's draft:
https://w3c.github.io/presentation-api/
Implementation report:
https://www.w3.org/wiki/Second_Screen/Implementation_Status#Tests
Editors:
Mark Foltz, Google,mfoltz@google.com
Dominik Röttsches, Intel (until April 2015)
Version history:
GitHub w3c/presentation-api/commits
Test suite:
GitHub web-platform-tests/presentation-api
w3c-test.org/presentation-api/
Participate:
GitHub w3c/presentation-api
File an issue
Open issues
Mailing-list (public-secondscreen@w3.org)

Copyright © 2017W3C® (MIT,ERCIM,Keio,Beihang).W3Cliability,trademark andpermissive document license rules apply.


Abstract

This specification defines an API to enable Web content to access presentation displays and use them for presenting Web content.

Status of This Document

This is a preview

Do not attempt to implement this version of the specification. Do not reference this version as authoritative in any way. Instead, seehttps://w3c.github.io/presentation-api/ for the Editor's draft.

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of currentW3C publications and the latest revision of this technical report can be found in theW3C technical reports index at https://www.w3.org/TR/.

This document was published by theSecond Screen Working Group as an Editor's Draft. Comments regarding this document are welcome. Please send them topublic-secondscreen@w3.org (subscribe,archives).

Please see the Working Group'simplementation report.

Since publication as Candidate Recommendation on14 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, exceptPresentationConnectionClosedReason andPresentationConnectionClosedEvent, which were renamed to improve consistency with the rest of the Web platform. The API was also restricted to secure contexts. See thelist of changes for details.

No feature has been identified as beingat risk.

The Second Screen Working Group will refine thetest suite for the Presentation API during the Candidate Recommendation period and update thepreliminary implementation report. For this specification to advance to Proposed Recommendation, two independent, interoperable implementations of each feature must be demonstrated, as detailed in theCandidate Recommendation exit criteria section.

Publication as an Editor's Draft does not imply endorsement by theW3C 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 theW3C Patent Policy.W3C maintains apublic 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 containsEssential Claim(s) must disclose the information in accordance withsection 6 of theW3C Patent Policy.

This document is governed by the1 March 2017W3C Process Document.

1. Introduction

This section is non-normative.

The Presentation API aims to makepresentation 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 largerpresentation display has greater perceived quality, legibility, and impact.

At its core, the Presentation API enables acontroller page to show apresentation page on apresentation 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 thepresentation display is connected by HDMI or Miracast, which only allow audio and video to be transmitted, the user agent (UA) hosting thecontroller will also render thepresentation. It then uses the operating system to send the resulting graphical and audio output to the presentation display. We refer to this situation as the1-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 thepresentation display is able to render HTML natively and communicate with thecontroller via a network, the user agent hosting the controller does not need to render thepresentation. 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 the2-UA mode implementation of the Presentation API.

The Presentation API is intended to be used with user agents that attach topresentation displays in1-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 theSecond Screen Community Group.

2. Use cases and requirements

This section is non-normative.

Use cases and requirements are captured in a separatePresentation API Use Cases and Requirements document.

3.Conformance

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 wordsMAY,MUST,MUST NOT,OPTIONAL,SHOULD, andSHOULD 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.)

3.1 Conformance classes

This specification describes the conformance criteria for two classes ofuser agents.

Controlling user agent

Web browsers that conform to the specifications of acontrolling user agent must be able to start and control presentations by providing acontrolling browsing context as described in this specification. This context implements thePresentation,PresentationAvailability,PresentationConnection,PresentationConnectionAvailableEvent,PresentationConnectionCloseEvent, andPresentationRequest interfaces.

Receiving user agent

Web browsers that conform to the specifications of areceiving user agent must be able to render presentations by providing areceiving browsing context as described in this specification. This context implements thePresentation,PresentationConnection,PresentationConnectionAvailableEvent,PresentationConnectionCloseEvent,PresentationConnectionList, andPresentationReceiver interfaces.

One user agent may act both as acontrolling user agent and as areceiving 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 thecontrolling browsing context and thereceiving browsing context for a presentation, as in the1-UA mode implementation of the API.

Conformance requirements phrased against auser agent apply either to acontrolling user agent, areceiving user agent or to both classes, depending on the context.

4. Terminology

The following terms are defined in [HTML51]:

The termJavaScript realm is defined in [ECMASCRIPT].

The termsEventTarget,Event,EventInit are defined in [DOM].

The termMessageEvent is defined in [WEBMESSAGING].

This document provides interface definitions using the Web IDL standard [WEBIDL-2].

The termsthrow,Promise,ArrayBuffer,ArrayBufferView, and the following exception names are defined in [WEBIDL-2]:

The termsresolving a Promise andrejecting a Promise are used as explained in [PROMGUIDE].

The termURL is defined in the WHATWG URL standard [URL].

The termBlob is defined in the File API specification [FILEAPI].

The headerAccept-Language is defined in HTTP/1.1 [rfc7231].

HTTP authentication is defined in HTTP/1.1: Authentication [rfc7235].

The termRTCDataChannel is defined in the WebRTC API specification [WEBRTC].

The termcookie store is defined in RFC 6265 [COOKIES].

The termUUID is defined in RFC 4122 [rfc4122].

The termspermission descriptor type andpermission state are defined in [PERMISSIONS].

The termdatabase is defined in [INDEXEDDB].

The termslocal storage areas andsession storage areas are defined in [WEBSTORAGE].

The term a priori authenticated URL is defined in [MIXED-CONTENT].

The termsservice worker, a list of registered service worker registrations,caches,window client andworker client are defined in [SERVICE-WORKERS].

The termDIAL is defined in [DIAL].

5. Examples

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 andpresentation.html implements the presentation. Both pages are served from the domainhttps://example.org (https://example.org/controller.html andhttps://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.

5.1 Monitor availability of presentation displays example

Example 1
<!-- controller.html --><buttonid="presentBtn"style="display: none;">Present</button><script>// The Present button is visible if at least one presentation display is availablevar 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 availabilityvar 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>

5.2 Starting a new presentation example

Example 2
<!-- 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>

5.3 Reconnect to a presentation example

Example 3
<!-- controller.html --><buttonid="reconnectBtn"style="display: none;">Reconnect</button><script>var reconnect =function (){// read presId from localStorage if existsvar 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>

5.4 Presentation initiation by the controlling UA example

Example 4
<!-- 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>

5.5 Monitor connection's state and exchange data example

Example 5
<!-- controller.html --><buttonid="disconnectBtn"style="display: none;">Disconnect</button><buttonid="stopBtn"style="display: none;">Stop</button><script>let connection;// The Disconnect and Stop buttons are visible if there is a connected presentationconst stopBtn =document.querySelector("#stopBtn");const disconnectBtn =document.querySelector("#disconnectBtn");  stopBtn.onclick =_ => {    connection && connection.terminate();  };  disconnectBtn.onclick =_ => {    connection && connection.close();  };functionsetConnection(newConnection){// Disconnect from existing presentation, if not attempting to reconnectif (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;functionshowConnectedUI(){// Allow the user to disconnect from or terminate the presentation      stopBtn.style.display ="inline";      disconnectBtn.style.display ="inline";      reconnectBtn.style.display ="none";    }functionshowDisconnectedUI(){      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 existsdelete localStorage["presId"];      connection =null;      showDisconnectedUI();    };  };</script>

5.6 Monitor available connection(s) and say hello

Example 6
<!-- 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>

5.7 Passing locale information with a message

Example 7
<!-- 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>

6. API

6.1 Common idioms

Apresentation display refers to a graphical and/or audio output device available to the user agent via an implementation specific connection technology.

Apresentation connection is an object relating acontrolling browsing context to itsreceiving browsing context and enables two-way-messaging between them. Eachpresentation connection has apresentation connection state, a uniquepresentation identifier to distinguish it from otherpresentations, and apresentation URL that is aURL used to create or reconnect to thepresentation. Avalid presentation identifier consists of alphanumeric ASCII characters only and is at least 16 characters long.

Somepresentation 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 anavailable presentation display for apresentation URL if thecontrolling user agent can reasonably guarantee that presentation of the URL on that display will succeed.

A controlling browsing context (orcontroller for short) is abrowsing context that has connected to apresentation by callingstart orreconnect, or received apresentation connection via aconnectionavailable event. In algorithms forPresentationRequest, thecontrolling browsing context is theresponsible browsing context whoseJavaScript realm was used to construct thePresentationRequest.

The receiving browsing context (orpresentation for short) is the browsing context responsible for rendering to apresentation display. Areceiving browsing context can reside in the same user agent as thecontrolling browsing context or a different one. Areceiving browsing context is created by following the steps tocreate a receiving browsing context.

In a procedure, thedestination browsing context is thereceiving browsing context when the procedure is initiated at thecontrolling browsing context, or thecontrolling browsing context if it is initiated at thereceiving browsing context.

Theset of controlled presentations, initially empty, contains thepresentation connections created by thecontrolling browsing contexts for thecontrolling user agent (or a specific user profile within that user agent). Theset of controlled presentations is represented by a list ofPresentationConnection objects that represent the underlyingpresentation connections. SeveralPresentationConnection objects may share the samepresentation URL andpresentation identifier in that set, but there can be only onePresentationConnection with a specificpresentation URL andpresentation identifier for a givencontrolling browsing context.

Theset of presentation controllers, initially empty, contains thepresentation connections created by areceiving browsing context for thereceiving user agent. Theset of presentation controllers is represented by a list ofPresentationConnection objects that represent the underlyingpresentation connections. Allpresentation connections in this set share the samepresentation URL andpresentation identifier.

In areceiving browsing context, thepresentation controllers monitor, initially set tonull, exposes the currentset of presentation controllers to the receiving application. Thepresentation controllers monitor is represented by aPresentationConnectionList.

In areceiving browsing context, thepresentation controllers promise, which is initially set tonull, provides thepresentation controllers monitor once the initialpresentation connection is established. Thepresentation controllers promise is represented by aPromise that resolves with thepresentation controllers monitor.

In acontrolling browsing context, thedefault presentation request, which is initially set tonull, represents the request to use when the user wishes to initiate apresentation connection from the browser chrome.

Thetask source for the tasks mentioned in this specification is thepresentation task source.

Unless otherwise specified, theJavaScript realm for script objects constructed by algorithm steps is thecurrent realm.

6.2 InterfacePresentation

partial interfaceNavigator {    [SecureContext,SameObject]    readonly attributePresentationpresentation;};[SecureContext,Exposed=Window]interfacePresentation {};

Thepresentation attribute is used to retrieve an instance of thePresentation interface. ItMUST return thePresentation instance.

6.2.1 Controlling user agent

Controlling user agentsMUST implement the following partial interface:

partial interfacePresentation {    attributePresentationRequest?defaultRequest;};

ThedefaultRequest attributeMUST return thedefault presentation request if any,null otherwise. On setting, thedefault presentation requestMUST be set to the new value.

Thecontrolling user agentSHOULD initiate presentation using thedefault 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 thedefault presentation request, thecontrolling user agentMUST follow the steps tostart a presentation from a default presentation request.

Support for initiating a presentation using thedefault presentation request isOPTIONAL.

Note
If acontrolling user agent does not supportstarting a presentation from a default presentation request, that user agent should ignore any value set fordefaultRequest.

6.2.2 Receiving user agent

Receiving user agentsMUST implement the following partial interface:

partial interfacePresentation {    readonly attributePresentationReceiver?receiver;};

Thereceiver attributeMUST return thePresentationReceiver instance associated with thereceiving browsing context and created by thereceiving user agent when thereceiving browsing context iscreated. In any otherbrowsing context (includingnested browsing contexts of thereceiving browsing context) itMUST returnnull.

Note

Web developers can usenavigator.presentation.receiver to detect when a document is loaded as a presentation.

6.3 InterfacePresentationRequest

[Constructor(USVStringurl),Constructor(sequence<USVString>urls),SecureContext,Exposed=Window]interfacePresentationRequest :EventTarget {Promise<PresentationConnection>start();Promise<PresentationConnection>reconnect(USVStringpresentationId);Promise<PresentationAvailability>getAvailability();    attributeEventHandleronconnectionavailable;};

APresentationRequest object is associated with a request to initiate or reconnect to a presentation made by acontrolling browsing context. ThePresentationRequest objectMUST be implemented in acontrolling browsing context provided by acontrolling user agent.

When aPresentationRequest is constructed, the givenurlsMUST be used as the list ofpresentation request URLs which are each a possiblepresentation URL for thePresentationRequest instance.

6.3.1 Constructing aPresentationRequest

When thePresentationRequest constructor is called, thecontrolling user agentMUST run these steps:

Input
url orurls, thepresentation request URLs
Output
APresentationRequest object
  1. If the document object'sactive sandboxing flag set has thesandboxed presentation browsing context flag set, then throw aSecurityError and abort these steps.
  2. Ifurls is an empty sequence, thenthrow aNotSupportedError and abort all remaining steps.
  3. If a singleurl was provided, leturls be a one item array containingurl.
  4. LetpresentationUrls be an empty list of URLs.
  5. For each URLU inurls:
    1. ResolveU relative to the API base URL specified by thecurrent settings object, and add the resulting absolute URL (if any) topresentationUrls.
    2. If the resolve a URL algorithm failed, thenthrow aSyntaxError exception and abort all remaining steps.
  6. If any member ofpresentationUrls is not ana priori authenticated URL, then throw aSecurityError and abort these steps.
  7. Construct a newPresentationRequest object withpresentationUrls as itspresentation request URLs and return it.

6.3.2 Selecting a presentation display

When thestart method is called, theuser agentMUST run the following steps toselect a presentation display.

Input
presentationRequest, thePresentationRequest object that received the call tostart
Output
APromise
  1. If the algorithm isn'tallowed to show a popup, return aPromise rejected with anInvalidAccessError exception and abort these steps.
  2. LettopContext be thetop-level browsing context of thecontrolling browsing context.
  3. If there is already an unsettledPromise from a previous call tostart intopContext or anybrowsing context in thelist of descendant browsing contexts oftopContext, return a newPromise rejected with anOperationError exception and abort all remaining steps.
  4. LetP be a newPromise.
  5. ReturnP, but continue running these stepsin parallel.
  6. If theuser agent is notmonitoring the list of available presentation displays, run the steps tomonitor the list of available presentation displaysin parallel.
  7. LetpresentationUrls be thepresentation request URLs ofpresentationRequest.
  8. Request user permission for the use of apresentation display and selection of one presentation display.
  9. If either of the following is true:
    1. Thelist of available presentation displays is empty and will remain so before the request for user permission is completed.
    2. No member in thelist of available presentation displays is anavailable presentation display for any member ofpresentationUrls.
    Then run the following steps:
    1. RejectP with aNotFoundError exception.
    2. Abort all remaining steps.
  10. If the userdenies permission to use a display, rejectP with anNotAllowedError exception, and abort all remaining steps.
  11. Otherwise, the usergrants permission to use a display; letD be that display.
  12. Run the steps tostart a presentation connection withpresentationRequest,D, andP.
Note
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). Implementers are encouraged to show the user whether an available display is currently in use, to facilitate presentations that can make use of multiple displays.
Note
Receiving user agents are encouraged to advertise a user friendly name for the presentation display, e.g. "Living Room TV", to assist the user in selecting the intended display. Implementers of receiving user agents are also encouraged to advertise the locale and intended text direction of the user friendly name. Implementers of controlling user agents are encouraged to render a user friendly name using its locale and text direction when they are known.

6.3.3 Starting a presentation from a default presentation request

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 agentMUST run the following steps tostart a presentation from a default presentation request. If nodefault presentation request is set on the document, these stepsMUST not be run.

Input
W, the document on which the user has expressed an intent to start presentation
presentationRequest, the non-null value ofnavigator.presentation.defaultRequest set onW
D, thepresentation display that is the target for presentation
  1. LetpresentationUrls be thepresentation request URLs ofpresentationRequest.
  2. If there is nopresentation request URL forpresentationRequest for whichD is anavailable presentation display, then abort these steps.
  3. Run the steps tostart a presentation connection withpresentationRequest andD.
Note
Whenstarting a presentation from a default presentation request, acontrolling user agent may allow the user to request presentation and choose the intendedpresentation display with the same user gesture. For example, the browser chrome could allow the user to pick a display from a menu, or allow the user to tap on anNear Field Communications (NFC) enabled display.

6.3.4 Starting a presentation connection

When theuser agent is tostart a presentation connection, itMUST run the following steps:

Input
presentationRequest, thePresentationRequest that is used to start the presentation connection
D, the selectedpresentation display
P, an optionalPromise that will be resolved with a newpresentation connection
  1. LetI be a newvalid presentation identifier unique among allpresentation identifiers for knownpresentation connections in theset of controlled presentations. To avoid fingerprinting, implementationsSHOULD set thepresentation identifier to aUUID generated by following forms 4.4 or 4.5 of [rfc4122].
  2. Create a newPresentationConnectionS.
  3. Set thepresentation identifier ofS to I.
  4. LetpresentationUrls be thepresentation request URLs ofpresentationRequest.
  5. Set thepresentation URL forS to the firstpresentationUrl inpresentationUrls for which there exists an entry(presentationUrl, D) in thelist of available presentation displays.
  6. Set thepresentation connection state ofS toconnecting.
  7. AddS to theset of controlled presentations.
  8. IfP is provided,resolveP withS.
  9. Queue a task tofire atrusted event with the nameconnectionavailable, that uses thePresentationConnectionAvailableEvent interface, with theconnection attribute initialized toS, atpresentationRequest. The event must not bubble, must not be cancelable, and has no default action.
  10. LetU be the user agent connected to D.
  11. If the next step fails, abort all remaining steps andclose the presentation connectionS witherror ascloseReason, and a human readable message describing the failure ascloseMessage.
  12. Using an implementation specific mechanism, tellU tocreate a receiving browsing context withD,presentationUrl, andI as parameters.
  13. Establish a presentation connection withS.
Note
ThepresentationUrl should name a resource accessible to the local or a remote user agent. This specification defines behavior forpresentationUrl using thehttp orhttps schemes; behavior for other schemes is not defined by this specification.

6.3.5 Reconnecting to a presentation

When thereconnect method is called, theuser agentMUST run the following steps toreconnect to a presentation:

Input
presentationRequest, thePresentationRequest object thatreconnect was called on
presentationId, a validpresentation identifier
Output
P, aPromise
  1. LetP be a newPromise.
  2. ReturnP, but continue running these steps in parallel.
  3. Search theset of controlled presentations for aPresentationConnection that meets the following criteria:
  4. If such aPresentationConnection exists, run the following steps:
    1. LetexistingConnection be thatPresentationConnection.
    2. ResolveP withexistingConnection.
    3. If thepresentation connection state ofexistingConnection isconnecting orconnected, then abort all remaining steps.
    4. Set thepresentation connection state ofexistingConnection toconnecting.
    5. Establish a presentation connection withexistingConnection.
    6. Abort all remaining steps.
  5. Search theset of controlled presentations for the firstPresentationConnection that meets the following criteria:
  6. If such aPresentationConnection exists, run the following steps:
    1. LetexistingConnection be thatPresentationConnection.
    2. Create a newPresentationConnectionnewConnection.
    3. Set thepresentation identifier ofnewConnection topresentationId.
    4. Set thepresentation URL ofnewConnection to thepresentation URL ofexistingConnection.
    5. Set thepresentation connection state ofnewConnection toconnecting.
    6. AddnewConnection to theset of controlled presentations.
    7. ResolveP withnewConnection.
    8. Queue a task tofire atrusted event with the nameconnectionavailable, that uses thePresentationConnectionAvailableEvent interface, with theconnection attribute initialized tonewConnection, atpresentationRequest. The event must not bubble, must not be cancelable, and has no default action.
    9. Establish a presentation connection withnewConnection.
    10. Abort all remaining steps.
  7. RejectP with aNotFoundError exception.

6.3.6 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 thePresentationRequest interface:

Event handler Event handler event type
onconnectionavailableconnectionavailable

6.4 InterfacePresentationAvailability

[SecureContext,Exposed=Window]interfacePresentationAvailability :EventTarget {    readonly attributebooleanvalue;             attributeEventHandleronchange;};

APresentationAvailability object exposes thepresentation display availability for a presentation request. Thepresentation display availability for aPresentationRequest stores whether there is currently anyavailable presentation display for at least one of thepresentation request URLs of the request.

Thepresentation display availability for a presentation request is eligible for garbage collection when no ECMASCript code can observe thePresentationAvailability object.

If thecontrolling user agent canmonitor the list of available presentation displays in the background (without a pending request tostart), thePresentationAvailability objectMUST be implemented in acontrolling browsing context.

Thevalue attributeMUST return the last value it was set to. The value is initialized and updated by themonitor the list of available presentation displays algorithm.

Theonchange attribute is anevent handler whose correspondingevent handler event type ischange.

6.4.1 The set of presentation availability objects

Theuser agentMUST keep track of theset of presentation availability objects created by thegetAvailability method. Theset of presentation availability objects is represented as a set of tuples(A,availabilityUrls), initially empty, where:

  1. A is a livePresentationAvailability object.
  2. availabilityUrls is the list ofpresentation request URLs for thePresentationRequest whengetAvailability was called on it to createA.

6.4.2 The list of available presentation displays

Theuser agentMUST keep alist of available presentation displays. Thelist of available presentation displays is represented by a list of tuples(availabilityUrl, display). An entry in this list means thatdisplay is currently anavailable presentation display foravailabilityUrl. This list ofpresentation displays may be used for starting new presentations, and is populated based on an implementation specific discovery mechanism. It is set to the most recent result of the algorithm tomonitor the list of available presentation displays.

While theset of presentation availability objects is not empty, theuser agentMAYmonitor the list of available presentation displays continuously, so that pages can use thevalue property of aPresentationAvailability object to offer presentation only when there are available displays. However, theuser agent may not support continuous availability monitoring in the background; for example, because of platform or power consumption restrictions. In this case thePromise returned bygetAvailability isrejected, and the algorithm tomonitor the list of available presentation displays will only run as part of theselect a presentation display algorithm.

When theset of presentation availability objects is empty (that is, there are noavailabilityUrls being monitored), user agentsSHOULD NOTmonitor the list of available presentation displays to satisfy the power saving non-functional requirement. To further save power, theuser agentMAY also keep track of whether a page holding aPresentationAvailability object is in the foreground. Using this information, implementation specific discovery ofpresentation displays can be resumed or suspended.

6.4.3 Getting thepresentation displays availability information

When thegetAvailability method is called, the user agentMUST run the following steps:

Input
presentationRequest, thePresentationRequest object that received the call togetAvailability
Output
APromise
  1. If there is an unsettledPromise from a previous call togetAvailability on presentationRequest, return thatPromise and abort these steps.
  2. Otherwise, letP be a newPromise constructed in theJavaScript realm ofpresentationRequest.
  3. ReturnP, but continue running these stepsin parallel.
  4. If the user agent is unable to continuouslymonitor the list of available presentation displays in the background, but can later find presentation displays in order to start a connection, then:
    1. RejectP with aNotSupportedError exception.
    2. Abort all the remaining steps.
  5. If thepresentation display availability forpresentationRequest is notnull, then:
    1. ResolveP with the request'spresentation display availability.
    2. Abort all the remaining steps.
  6. Set thepresentation display availability forpresentationRequest to a newly createdPresentationAvailability object constructed in theJavaScript realm ofpresentationRequest, and letA be that object.
  7. Create a tuple(A,presentationUrls) and add it to theset of presentation availability objects.
  8. Run the algorithm tomonitor the list of available presentation displays.
    Note
    The monitoring algorithm must be run at least one more time after the previous step to pick up the tuple that was added to theset of presentation availability objects.
  9. ResolveP withA.

6.4.4 Monitoring the list of available presentation displays

If theset of presentation availability objects is non-empty, or there is a pending request toselect a presentation display, theuser agentMUSTmonitor the list of available presentation displays by running the following steps:

  1. LetavailabilitySet be a shallow copy of theset of presentation availability objects.
  2. If there is a pending request toselect a presentation display for aPresentationRequest and if thePresentationRequest'spresentation display availability isnull, then run the following substeps:
    1. LetA be a newly createdPresentationAvailability object.
    2. Create a tuple(A,presentationUrls) wherepresentationUrls is thePresentationRequest'spresentation request URLs and add it toavailabilitySet.
  3. LetnewDisplays be an empty list.
  4. If theuser agent is unable to retrievepresentation displays (e.g., because the user has disabled this capability), then skip the following step.
  5. Retrievepresentation displays (using an implementation specific mechanism) and setnewDisplays to this list.
  6. Set thelist of available presentation displays to the empty list.
  7. For each member(A,availabilityUrls) ofavailabilitySet, run the following steps:
    1. SetpreviousAvailability to the value ofA'svalue property.
    2. LetnewAvailability befalse.
    3. For eachavailabilityUrl inavailabilityUrls, run the following step:
      1. For eachdisplay innewDisplays, ifdisplay is anavailable presentation display foravailabilityUrl, then run the following steps:
        1. Insert a tuple(availabilityUrl, display) into thelist of available presentation displays, if no identical tuple already exists.
        2. SetnewAvailability totrue.
    4. IfA'svalue property has not yet been initialized, then setA'svalue property tonewAvailability and skip the following step.
    5. IfpreviousAvailability is not equal tonewAvailability, thenqueue a task to run the following steps:
      1. SetA'svalue property tonewAvailability.
      2. Fire a simple event namedchange atA.
Note
Thecontrolling user agent may choose how often tomonitor the list of available presentation displays, including grouping requests fromstart andgetAvailability, and aggregating them acrossbrowsing contexts.

When apresentation display availability object is eligible for garbage collection, theuser agentSHOULD run the following steps:

  1. LetA be the newly deceasedPresentationAvailability object
  2. Find and remove any entry(A,availabilityUrl) in theset of presentation availability objects.
  3. If theset of presentation availability objects is now empty and there is no pending request toselect a presentation display, cancel any pending task tomonitor the list of available presentation displays for power saving purposes, and set thelist of available presentation displays to the empty list.
Note
The mechanism used to monitorpresentation displays availability and determine the compatibility of apresentation display with a given URL is left to the user agent.

6.4.5 InterfacePresentationConnectionAvailableEvent

[Constructor(DOMStringtype,PresentationConnectionAvailableEventIniteventInitDict),SecureContext,Exposed=Window]interfacePresentationConnectionAvailableEvent :Event {    [SameObject]    readonly attributePresentationConnectionconnection;};dictionaryPresentationConnectionAvailableEventInit :EventInit {    requiredPresentationConnectionconnection;};

Acontrolling user agentfires atrusted event namedconnectionavailable on aPresentationRequest when a connection associated with the object is created. It is fired at thePresentationRequest instance, using thePresentationConnectionAvailableEvent interface, with theconnection attribute set to thePresentationConnection object that was created. The event is fired for each connection that is created for thecontroller, either by thecontroller callingstart orreconnect, or by thecontrolling user agent creating a connection on the controller's behalf viadefaultRequest.

Areceiving user agentfires atrusted event namedconnectionavailable on aPresentationReceiver when an incoming connection is created. It is fired at thepresentation controllers monitor, using thePresentationConnectionAvailableEvent interface, with theconnection attribute set to thePresentationConnection object that was created. The event is fired for all connections that are created whenmonitoring incoming presentation connections.

Theconnection attributeMUST return the value it was set to when thePresentationConnection object was created.

When thePresentationConnectionAvailableEvent constructor is called, theuser agentMUST construct a newPresentationConnectionAvailableEvent object with itsconnection attribute set to theconnection member of thePresentationConnectionAvailableEventInit object passed to the constructor.

6.5 InterfacePresentationConnection

Eachpresentation connection is represented by aPresentationConnection object. Both thecontrolling user agent andreceiving user agentMUST implementPresentationConnection.

enumPresentationConnectionState {"connecting","connected","closed","terminated"};enumBinaryType {"blob","arraybuffer"};[SecureContext,Exposed=Window]interfacePresentationConnection :EventTarget {    readonly attributeUSVStringid;    readonly attributeUSVStringurl;    readonly attributePresentationConnectionStatestate;voidclose();voidterminate();             attributeEventHandleronconnect;             attributeEventHandleronclose;             attributeEventHandleronterminate;    // Communication             attributeBinaryTypebinaryType;             attributeEventHandleronmessage;voidsend(DOMStringmessage);voidsend(Blobdata);voidsend(ArrayBufferdata);voidsend(ArrayBufferViewdata);};

Theid attribute specifies thepresentation connection'spresentation identifier.

Theurl attribute specifies thepresentation connection'spresentation URL.

Thestate attribute represents thepresentation connection's current state. It can take one of the values ofPresentationConnectionState depending on the connection state:

When theclose method is called on aPresentationConnectionS, theuser agentMUSTstart closing the presentation connectionS withclosed ascloseReason and an empty message ascloseMessage.

When theterminate method is called on aPresentationConnectionS in acontrolling browsing context, theuser agentMUST run the algorithm toterminate a presentation in a controlling browsing context usingS.

When theterminate method is called on aPresentationConnectionS in areceiving browsing context, theuser agentMUST run the algorithm toterminate a presentation in a receiving browsing context usingS.

ThebinaryType attribute can take one of the values ofBinaryType. When aPresentationConnection object is created, itsbinaryType attributeMUST be set to the string "arraybuffer". On getting, itMUST return the last value it was set to. On setting, the user agentMUST set the attribute to the new value.

Note
ThebinaryType attribute allows authors to control how binary data is exposed to scripts. By setting the attribute to "blob", binary data is returned inBlob form; by setting it to "arraybuffer", it is returned inArrayBuffer form. The attribute defaults to "arraybuffer". This attribute has no effect on data sent in a string form.

When thesend method is called on aPresentationConnectionS, theuser agentMUST run the algorithm tosend a message throughS.

When aPresentationConnection objectS is discarded (because the document owning it is navigating or is closed) while thepresentation connection state ofS isconnecting orconnected, theuser agentMUSTstart closing the presentation connectionS withwentaway ascloseReason and an emptycloseMessage.

If theuser agent receives a signal from thedestination browsing context that aPresentationConnectionS is to be closed, itMUSTclose the presentation connectionS withclosed orwentaway ascloseReason and an emptycloseMessage.

6.5.1 Establishing a presentation connection

When theuser agent is toestablish a presentation connection using apresentation connection, itMUST run the following steps:

Input
presentationConnection, thePresentationConnection object that is to be connected
  1. If thepresentation connection state ofpresentationConnection is notconnecting, then abort all remaining steps.
  2. Request connection ofpresentationConnection to thereceiving browsing context. Thepresentation identifier ofpresentationConnectionMUST be sent with this request.
  3. If connection completes successfully,queue a task to run the following steps:
    1. Set thepresentation connection state ofpresentationConnection toconnected.
    2. Fire a simple event namedconnect atpresentationConnection.
  4. If the connection cannot be completed,close the presentation connectionS witherror ascloseReason, and a human readable message describing the failure ascloseMessage.
Note
The mechanism that is used to present on the remote display and connect thecontrolling 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 carryingDOMString and binary payloads in a reliable and in-order fashion as described in theSend a Message andReceive a Message steps below.

6.5.2 Sending a message throughPresentationConnection

Note
No specific transport for the connection between thecontrolling browsing context and thereceiving browsing context is mandated, except that for multiple calls tosend it has to be ensured that messages are delivered to the other end reliably and in sequence. The transport should function equivalently to anRTCDataChannel in reliable mode.

Letpresentation message data be the payload data to be transmitted between two browsing contexts. Letpresentation message type be the type of that data, one oftext orbinary.

When theuser agent is tosend a message through apresentation connection, itMUST run the following steps:

Input
presentationConnection, thepresentation connection connected to the other browsing context
messageOrData, thepresentation message data to send to the other browsing context
  1. If thestate property ofpresentationConnection is notconnected,throw an InvalidStateError exception.
  2. If theclosing procedure ofpresentationConnection has started, then abort these steps.
  3. Letpresentation message typemessageType bebinary ifmessageOrData is of typeArrayBuffer,ArrayBufferView, orBlob. LetmessageType betext ifmessageOrData is of typeDOMString.
  4. Using an implementation specific mechanism, transmit the contents ofmessageOrData as thepresentation message data andmessageType as thepresentation message type to thedestination browsing context.
  5. If the previous step encounters an unrecoverable error, then abruptlyclose the presentation connectionpresentationConnection witherror ascloseReason, and acloseMessage describing the error encountered.
Note

To assist applications in recovery from an error sending a message through apresentation connection, the user agent should include details of which attempt failed incloseMessage, along with a human readable string explaining the failure reason. Example renditions ofcloseMessage:

  • Unable to send text message (network_error): "hello" forDOMString messages, where"hello" is the first 256 characters of the failed message.
  • Unable to send binary message (invalid_message) forArrayBuffer,ArrayBufferView andBlob messages.
Note
When sending a user-visible string via apresentation connection, the page author should take care to ensure that locale information is also propagated so that the destination user agent can know how to best render the string. Seethe examples for one solution.

6.5.3 Receiving a message throughPresentationConnection

When theuser agent has received a transmission from the remote side consisting ofpresentation message data andpresentation message type, itMUST run the following steps toreceive a message through aPresentationConnection:

Input
presentationConnection, thepresentation connection receiving the message
messageType, thepresentation message type of the message
messageData, thepresentation message data of the message
  1. If thestate property ofpresentationConnection is notconnected, abort these steps.
  2. Letevent be a newly createdtrusted event that uses theMessageEvent interface, with the event typemessage, which does not bubble, is not cancelable, and has no default action.
  3. Initialize theevent's data attribute as follows:
    1. IfmessageType istext, then initializeevent'sdata attribute tomessageData with typeDOMString.
    2. IfmessageType isbinary, andbinaryType attribute is set to "blob", then initializeevent'sdata attribute to a newBlob object withmessageData as its raw data.
    3. IfmessageType isbinary, andbinaryType attribute is set to "arraybuffer", then initializeevent'sdata attribute to a newArrayBuffer object whose contents aremessageData.
  4. Queue a task tofireevent atpresentationConnection.

If theuser agent encounters an unrecoverable error whilereceiving a message throughpresentationConnection, itMUST abruptlyclose the presentation connectionpresentationConnection witherror ascloseReason. ItSHOULD use a human readable description of the error encountered ascloseMessage.

6.5.4 InterfacePresentationConnectionCloseEvent

enumPresentationConnectionCloseReason {"error","closed","wentaway"};[Constructor(DOMStringtype,PresentationConnectionCloseEventIniteventInitDict),SecureContext,Exposed=Window]interfacePresentationConnectionCloseEvent :Event {    readonly attributePresentationConnectionCloseReasonreason;    readonly attributeDOMStringmessage;};dictionaryPresentationConnectionCloseEventInit :EventInit {    requiredPresentationConnectionCloseReasonreason;DOMStringmessage ="";};

APresentationConnectionCloseEvent is fired when apresentation connection enters aclosed state. Thereason attribute provides the reason why the connection was closed. It can take one of the values ofPresentationConnectionCloseReason:

  • error means that the mechanism for connecting or communicating with a presentation entered an unrecoverable error.
  • closed means that either thecontrolling browsing context or thereceiving browsing context that were connected by thePresentationConnection calledclose.
  • wentaway means that the browser closed the connection, for example, because the browsing context that owned the connection navigated or was discarded.

When thereason attribute iserror, the user agentSHOULD set themessage attribute to a human readable description of how the communication channel encountered an error.

When thePresentationConnectionCloseEvent constructor is called, theuser agentMUST construct a newPresentationConnectionCloseEvent object, with itsreason attribute set to thereason member of thePresentationConnectionCloseEventInit object passed to the constructor, and itsmessage attribute set to themessage member of thisPresentationConnectionCloseEventInit object if set, to an empty string otherwise.

6.5.5 Closing aPresentationConnection

When theuser agent is tostart closing a presentation connection, itMUST do the following:

Input
presentationConnection, thepresentation connection to be closed
closeReason, thePresentationConnectionCloseReason describing why the connection is to be closed
closeMessage, a human-readable message with details of why the connection was closed
  1. If thepresentation connection state ofpresentationConnection is notconnecting orconnected then abort the remaining steps.
  2. Set thepresentation connection state ofpresentationConnection toclosed.
  3. Start to signal to thedestination browsing context the intention to close the correspondingPresentationConnection, passing thecloseReason to that context. The user agent does not need to wait for acknowledgement that the correspondingPresentationConnection was actually closed before proceeding to the next step.
  4. IfcloseReason is notwentaway, then locally run the steps toclose the presentation connection withpresentationConnection,closeReason, andcloseMessage.

When theuser agent is toclose a presentation connection, itMUST do the following:

Input
presentationConnection, thepresentation connection to be closed
closeReason, thePresentationConnectionCloseReason describing why the connection is to be closed
closeMessage, a human-readable message with details of why the connection was closed.
  1. If there is a pendingclose the presentation connection task forpresentationConnection, or aclose the presentation connection task has already run forpresentationConnection, then abort the remaining steps.
  2. Queue a task to run the following steps:
    1. If thepresentation connection state ofpresentationConnection is notconnecting,connected, orclosed, then abort the remaining steps.
    2. If thepresentation connection state ofpresentationConnection is notclosed, set it toclosed.
    3. If thepresentationConnection was created as a result ofmonitoring incoming presentation connections in areceiving browsing context, run the following sub-steps.
      1. RemovepresentationConnection from theset of presentation controllers.
      2. Populate thepresentation controllers monitor with theset of presentation controllers.
    4. Fire atrusted event with the nameclose, that uses thePresentationConnectionCloseEvent interface, with thereason attribute initialized tocloseReason and themessage attribute initialized tocloseMessage, atpresentationConnection. The event must not bubble, must not be cancelable, and has no default action.

6.5.6 Terminating a presentation in a controlling browsing context

When acontrolling user agent is toterminate a presentation in a controlling browsing context usingconnection, itMUST run the following steps:

  1. If thepresentation connection state ofconnection is notconnected orconnecting, then abort these steps.
  2. Otherwise, for eachknown connection in theset of controlled presentations in thecontrolling user agent:
    1. If thepresentation identifier ofknown connection andconnection are equal, and thepresentation connection state ofknown connection isconnected orconnecting, thenqueue a task to run the following steps:
      1. Set thepresentation connection state ofknown connection toterminated.
      2. Fire a simple event namedterminate atknown connection.
  3. Send a termination request for the presentation to itsreceiving user agent using an implementation specific mechanism.

6.5.7 Terminating a presentation in a receiving browsing context

When any of the following occur, thereceiving user agentMUSTterminate a presentation in a receiving browsing context:

  1. Thereceiving user agent is tounload a document corresponding to thereceiving browsing context, e.g. in response to a request tonavigate that context to a new resource.
  2. The user requests to terminate the presentation via thereceiving user agent.
    Note

    This could happen by an explicit user action, or as a policy of the user agent. For example, thereceiving user agent could be configured to terminate presentations whosePresentationConnection objects are all closed for 30 minutes.

  3. Acontrolling user agentsends a termination request to thereceiving user agent for that presentation.

When areceiving user agent is toterminate a presentation in a receiving browsing context, itMUST run the following steps:

  1. LetP be the presentation to be terminated, letallControllers be theset of presentation controllers that were created forP, andconnectedControllers an empty list.
  2. For eachconnection inallControllers, run the following steps:
    1. If thepresentation connection state ofconnection isconnected, then addconnection toconnectedControllers.
    2. Set thepresentation connection state ofconnection toterminated.
  3. If there is areceiving browsing context forP, and it has a document forP that is not unloaded,unload a document corresponding to thatbrowsing context, remove thatbrowsing context from the user interface anddiscard it.
  4. For eachconnection inconnectedControllers,queue a task to send a termination confirmation forP using an implementation specific mechanism to thecontrolling user agent that owns thedestination browsing context forconnection.
    Note

    Only one termination confirmation needs to be sent percontrolling user agent.

6.5.8 Handling a termination confirmation in a controlling user agent

When areceiving user agent is tosend a termination confirmation for a presentationP, and that confirmation was received by acontrolling user agent, thecontrolling user agentMUST run the following steps:

  1. For eachconnection in theset of controlled presentations that was connected toP,queue a task to run the following steps:
    1. If thepresentation connection state ofconnection is notconnected orconnecting, then abort the following steps.
    2. Set thepresentation connection state ofconnection toterminated.
    3. Fire a simple event namedterminate atconnection.

6.5.9 Event Handlers

The following are the event handlers (and their corresponding event handler event types) that must be supported, as event handler IDL attributes, by objects implementing thePresentationConnection interface:

Event handler Event handler event type
onmessagemessage
onconnectconnect
oncloseclose
onterminateterminate

6.6 InterfacePresentationReceiver

[SecureContext,Exposed=Window]interfacePresentationReceiver {    readonly attributePromise<PresentationConnectionList>connectionList;};

ThePresentationReceiver interface allows areceiving browsing context to access thecontrolling browsing contexts and communicate with them. ThePresentationReceiver interfaceMUST be implemented in areceiving browsing context provided by areceiving user agent.

On getting, theconnectionList attributeMUST return the result of running the following steps:

  1. If thepresentation controllers promise is notnull, return thepresentation controllers promise and abort all remaining steps.
  2. Otherwise, let thepresentation controllers promise be a newPromise constructed in theJavaScript realm of thisPresentationReceiver object.
  3. Return thepresentation controllers promise.
  4. If thepresentation controllers monitor is notnull,resolve thepresentation controllers promise with thepresentation controllers monitor.

6.6.1 Creating a receiving browsing context

When theuser agent is tocreate a receiving browsing context, itMUST run the following steps:

Input
D, apresentation display chosen by the user
presentationUrl, thepresentation request URL
presentationId, thepresentation identifier
  1. Create a newtop-level browsing contextC, set to display content onD.
  2. Set thesession history ofC to be the empty list.
  3. Set thesandboxed modals flag and thesandboxed auxiliary navigation browsing context flag onC.
  4. If thereceiving user agent implements [PERMISSIONS], set thepermission state of allpermission descriptor types forC to"denied".
  5. Create a new emptycookie store forC.
  6. Create a new empty store forC to holdHTTP authentication states.
  7. Create a new emptyapplication cache storage forC.
  8. If thereceiving user agent implements [INDEXEDDB], create a new empty storage for IndexedDBdatabases for C.
  9. If thereceiving user agent implements [WEBSTORAGE], create a new empty storage forsession storage areas and local storage areas forC.
  10. If thereceiving user agent implements [SERVICE-WORKERS], create a new emptylist of registered service worker registrations and a new emptycaches forC.
  11. NavigateC topresentationUrl.
  12. Startmonitoring incoming presentation connections forC withpresentationId andpresentationUrl.

Allnested browsing contextscreated by the presented document, i.e. that have thereceiving browsing context as theirtop-level browsing context,MUST also have restrictions 2-4 above. In addition, theyMUST have thesandboxed top-level navigation browsing context flag set. All of thesebrowsing contextsMUST also share the same browsing state (storage) for features 5-10 listed above.

Thetop-level browsing contextMUST NOT be allowed to navigate itself, except bynavigating to a fragment identifier. This allows the user to grant permission based on the presentation URL shown whenselecting a presentation display.

Window clients andworker clients associated with thereceiving browsing context and itslist of descendant browsing contexts must not be exposed toservice workers associated with each other.

When thereceiving browsing context is terminated, anyservice workers associated with it and thebrowsing contexts in itslist of descendant browsing contextsMUST be unregistered and terminated. Any browsing state associated with thereceiving browsing context and thebrowsing contexts in itslist of descendant browsing contexts, includingsession history, thecookie store, anyHTTP authentication state, theapplication cache, anydatabases, thesession storage areas, thelocal storage areas, thelist of registered service worker registrations and thecachesMUST be discarded and not used for any otherbrowsing context.

Note

This algorithm is intended to create a well defined environment to allow interoperable behavior for1-UA and2-UA presentations, and to minimize the amount of state remaining on apresentation display used for a2-UA presentation.

Thereceiving user agentSHOULD fetch resources in areceiving browsing context with an HTTPAccept-Language header that reflects the language preferences of thecontrolling user agent (i.e., with the sameAccept-Language that the controlling user agent would have sent). This will help thereceiving user agent render the presentation with fonts and locale-specific attributes that reflect the user's preferences.

Note

Given the operating context of thepresentation 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); thereceiving user agent should be aware of this. Furthermore, any modal user interface will need to be handled carefully. Thesandboxed modals flag is set on thereceiving browsing context to prevent most of these operations.

6.7 InterfacePresentationConnectionList

[SecureContext,Exposed=Window]interfacePresentationConnectionList :EventTarget {    readonly attributeFrozenArray<PresentationConnection>connections;             attributeEventHandleronconnectionavailable;};

Theconnections attributeMUST return the non-terminated set ofpresentation connections in theset of presentation controllers.

6.7.1 Monitoring incoming presentation connections

When thereceiving user agent is to startmonitoring incoming presentation connections in areceiving browsing context fromcontrolling browsing contexts, itMUST listen to and accept incoming connection requests from acontrolling browsing context using an implementation specific mechanism. When a new connection request is received from acontrolling browsing context, thereceiving user agentMUST run the following steps:

Input
I, thepresentation identifier passed by thecontrolling browsing context with the incoming connection request
presentationId, thepresentation identifier used tocreate the receiving browsing context
presentationUrl, thepresentation request URL used tocreate the receiving browsing context
  1. IfpresentationId andI are not equal, refuse the connection and abort all remaining steps.
  2. Create a newPresentationConnectionS.
  3. Set thepresentation identifier ofS to I.
  4. Set thepresentation URL ofS topresentationUrl.
  5. Establish the connection between the controlling andreceiving browsing contexts using an implementation specific mechanism.
  6. If connection establishment completes successfully, set the presentation connection state ofS toconnected. Otherwise, set thepresentation connection state ofS toclosed and abort all remaining steps.
  7. AddS to theset of presentation controllers.
  8. If thepresentation controllers monitor isnull, run the following stepsin parallel.
    1. Let thepresentation controllers monitor be a newPresentationConnectionList constructed in theJavaScript realm of thePresentationReceiver object of thereceiving browsing context.
    2. Populate thepresentation controllers monitor with theset of presentation controllers.
    3. If thepresentation controllers promise is notnull,resolve thepresentation controllers promise with thepresentation controllers monitor.
    4. Abort all remaining steps.
  9. Otherwise, run the following stepsin parallel.
    1. Populate thepresentation controllers monitor with theset of presentation controllers.
    2. Queue a task tofire atrusted event with the nameconnectionavailable, that uses thePresentationConnectionAvailableEvent interface, with theconnection attribute initialized toS, at thepresentation controllers monitor. The event must not bubble, must not be cancelable, and has no default action.

6.7.2 Event Handlers

The following are the event handlers (and their corresponding event handler event types) that must be supported, as event handler IDL attributes, by objects implementing thePresentationConnectionList interface:

Event handler Event handler event type
onconnectionavailableconnectionavailable

7. Security and privacy considerations

This section is non-normative.

7.1 Personally identifiable information

Thechange event fired on thePresentationAvailability object reveals one bit of information about the presence or absence of apresentation 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 enablesmonitoring the list of available presentation displays. How the user agent determines the compatibility and availability of apresentation display with a given URL is an implementation detail. If acontrolling user agent matches apresentation request URL to aDIAL application to determine its availability, this feature can be used to probe information about whichDIAL applications the user has installed on thepresentation display without user consent.

7.2 Cross-origin access

Apresentation is allowed to be accessed across origins; thepresentation URL andpresentation 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 areceiving user agent to publish information about itsset of controlled presentations, and acontrolling user agent to reconnect to presentations started from other devices. This is possible when thecontrolling browsing context obtains thepresentation URL andpresentation identifier of a running presentation from the user, local storage, or a server, and then connects to the presentation viareconnect.

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 viasend that the presentation uses to verify identity and authorization.

7.3 User interface guidelines

Origin display

When the user is asked permission to use apresentation display during the steps toselect a presentation display, thecontrolling user agent should make it clear what origin is requesting presentationand 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 anested browsing context. For example, embedded content may try to convince the user to click to trigger a request to start an unwanted presentation.

Thesandboxed top-level navigation browsing context flag is set on thereceiving browsing context to enforce that the top-level origin of the presentation remains the same during the lifetime of the presentation.

Cross-device access

When a userstarts 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 connectedcontrolling 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 thereceiving user agent is capable of receiving user input, as well as acting as apresentation display. In this case, thereceiving user agent should notify its user via browser chrome when areceiving browsing context is under the control of a remote party (i.e., it has one or more connected controllers).

7.4 Device Access

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.

7.5 Temporary identifiers and browser state

Thepresentation URL andpresentation 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.

7.6 Private browsing 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 thecontrolling browsing context, she will not be automatically logged out from thereceiving 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 initialset of controlled presentations in that browsing session must be empty. Anypresentation connections added to it must be discarded when the session terminates.

7.7 Messaging between presentation connections

This spec will not mandate communication protocols between thecontrolling browsing context and thereceiving browsing context, but it should set some guarantees of message confidentiality and authenticity between correspondingpresentation connections.

A. Acknowledgments

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 andMiracast 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.

B. Candidate Recommendation exit criteria

For this specification to be advanced to Proposed Recommendation, there must be, for each of the conformance classes it defines (controlling user agent andreceiving 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 thecontrolling user agent conformance class must include at least one implementation of the1-UA mode, and one implementation of the2-UA mode.2-UA mode implementations may only support non http/https presentation URLs. Implementations of thereceiving user agent conformance class may not include implementations of the2-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:

Independent
Each implementation must be developed by a different party, and cannot share, reuse, or derive from code used by another qualifying implementation. Sections of code that have no bearing on the implementation of this specification are exempt from this requirement.
Interoperable
Passing the respective test case(s) in the official test suite.
Implementation
A user agent which:
  1. implements one of the conformance classes of the specification.
  2. is available to the general public. The implementation may be a shipping product or other publicly available version (i.e., beta version, preview release, or "nightly build"). Non-shipping product releases must have implemented the feature(s) for a period of at least one month in order to demonstrate stability.
  3. is not experimental (i.e. a version specifically designed to pass the test suite and not intended for normal usage going forward).

C. Change log

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.

C.1 Changes since 14 July 2016

D.References

D.1Normative references

[COOKIES]
HTTP State Management Mechanism. A. Barth. IETF. April 2011. Proposed Standard. URL:https://tools.ietf.org/html/rfc6265
[DOM]
DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL:https://dom.spec.whatwg.org/
[ECMASCRIPT]
ECMAScript Language Specification. Ecma International. URL:https://tc39.github.io/ecma262/
[FILEAPI]
File API. Arun Ranganathan; Jonas Sicking. W3C. 21 April 2015. W3C Working Draft. URL:https://www.w3.org/TR/FileAPI/
[HTML51]
HTML 5.1 2nd Edition. Steve Faulkner; Arron Eicholz; Travis Leithead; Alex Danilo. W3C. 3 October 2017. W3C Recommendation. URL:https://www.w3.org/TR/html51/
[HTML52]
HTML 5.2. Steve Faulkner; Arron Eicholz; Travis Leithead; Alex Danilo; Sangwhan Moon. W3C. 8 August 2017. W3C Candidate Recommendation. URL:https://www.w3.org/TR/html52/
[INDEXEDDB]
Indexed Database API. Nikunj Mehta; Jonas Sicking; Eliot Graff; Andrei Popescu; Jeremy Orlow; Joshua Bell. W3C. 8 January 2015. W3C Recommendation. URL:https://www.w3.org/TR/IndexedDB/
[MIXED-CONTENT]
Mixed Content. Mike West. W3C. 2 August 2016. W3C Candidate Recommendation. URL:https://www.w3.org/TR/mixed-content/
[PERMISSIONS]
Permissions. Mounir Lamouri; Marcos Caceres; Jeffrey Yasskin. W3C. 25 September 2017. W3C Working Draft. URL:https://www.w3.org/TR/permissions/
[PROMGUIDE]
Writing Promise-Using Specifications. Domenic Denicola. W3C. finding. URL:http://www.w3.org/2001/tag/doc/promises-guide
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL:https://tools.ietf.org/html/rfc2119
[rfc4122]
A Universally Unique IDentifier (UUID) URN Namespace. P. Leach; M. Mealling; R. Salz. IETF. July 2005. Proposed Standard. URL:https://tools.ietf.org/html/rfc4122
[rfc7231]
Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL:https://tools.ietf.org/html/rfc7231
[rfc7235]
Hypertext Transfer Protocol (HTTP/1.1): Authentication. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL:https://tools.ietf.org/html/rfc7235
[SERVICE-WORKERS]
Service Workers 1. Alex Russell; Jungkee Song; Jake Archibald; Marijn Kruisselbrink. W3C. 11 October 2016. W3C Working Draft. URL:https://www.w3.org/TR/service-workers-1/
[URL]
URL Standard. Anne van Kesteren. WHATWG. Living Standard. URL:https://url.spec.whatwg.org/
[WEBIDL-2]
Web IDL. Cameron McCormack; Boris Zbarsky; Tobie Langel. W3C. 15 December 2016. W3C Editor's Draft. URL:https://heycam.github.io/webidl/
[WEBMESSAGING]
HTML5 Web Messaging. Ian Hickson. W3C. 19 May 2015. W3C Recommendation. URL:https://www.w3.org/TR/webmessaging/
[WEBSTORAGE]
Web Storage (Second Edition). Ian Hickson. W3C. 19 April 2016. W3C Recommendation. URL:https://www.w3.org/TR/webstorage/

D.2Informative references

[DIAL]
DIscovery And Launch Protocol Specification. Netflix; YouTube. Netflix. URL:http://www.dial-multiscreen.org/dial-protocol-specification
[HTML]
HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL:https://html.spec.whatwg.org/multipage/
[WEBIDL]
Web IDL. Cameron McCormack; Boris Zbarsky; Tobie Langel. W3C. 15 December 2016. W3C Editor's Draft. URL:https://heycam.github.io/webidl/
[WEBRTC]
WebRTC 1.0: Real-time Communication Between Browsers. Adam Bergkvist; Daniel Burnett; Cullen Jennings; Anant Narayanan; Bernard Aboba; Taylor Brandstetter. W3C. 22 August 2017. W3C Working Draft. URL:https://www.w3.org/TR/webrtc/


[8]ページ先頭

©2009-2025 Movatter.jp