Skip to content

Commit a2698c2

Browse files
markafoltzmarkafoltz
authored
Adds steps for initiating presentation from default presentation request. (#369)
1 parent 064f74a commit a2698c2

File tree

1 file changed

+156
-74
lines changed

1 file changed

+156
-74
lines changed

‎index.html

+156-74
Original file line numberDiff line numberDiff line change
@@ -886,7 +886,7 @@ <h3>
886886
In a <a>controlling browsing context</a>, the <dfn>default
887887
presentation request</dfn>, which is initially set to
888888
<code>null</code>, represents the request to use when the user wishes
889-
to initiate a <a>presentation connection</a> from the browser.
889+
to initiate a <a>presentation connection</a> from the browser chrome.
890890
</p>
891891
</section>
892892
<section>
@@ -932,43 +932,22 @@ <h4>
932932
The <a>controlling user agent</a> SHOULD initiate presentation
933933
using the <a>default presentation request</a> only when the user
934934
has expressed an intention to do so via a user gesture, for example
935-
by clicking a button in the browser.
935+
by clicking a button in the browser chrome.
936936
</p>
937937
<p>
938938
To initiate presentation using the <a>default presentation
939-
request</a>, the <a>controlling user agent</a> MUST <a>start a
940-
presentation</a> using the <a>default presentation request</a> (as
941-
if the controller had called <code>defaultRequest.start()</code>),
942-
skipping the first step of that algorithm.
939+
request</a>, the <a>controlling user agent</a> MUST follow the
940+
steps to <a>start a presentation from a default presentation
941+
request</a>.
943942
</p>
944-
<div class="note">
945-
Subsequent security steps of the <a>start a presentation</a>
946-
algorithm apply. For instance, the request will fail if the
947-
document object's <a>active sandboxing flag set</a> has the
948-
<a>sandboxed presentation browsing context flag</a> set.
949-
</div>
950943
<p>
951-
Support for the initiation of a <a>presentation connection</a> from
952-
the browser is OPTIONAL.
944+
Support for initiating a presentation using the <a>default
945+
presentation request</a> is OPTIONAL.
953946
</p>
954947
<div class="note">
955-
If a <a>controlling user agent</a> does not support initiation of a
956-
<a>presentation connection</a> from the browser, setting
957-
<code>defaultRequest</code> will have no effect.
958-
</div>
959-
<div class="note">
960-
Some <a data-lt="controlling user agent">controlling user
961-
agents</a> may allow the user to initiate a default <a>presentation
962-
connection</a> and select a <a>presentation display</a> with the
963-
same user gesture. For example, the browser chrome could allow the
964-
user to pick a display from a menu, or allow the user to tap on an
965-
<a href="https://nfc-forum.org/">Near Field Communications
966-
(NFC)</a> enabled display. In this case, when the <a>controlling
967-
user agent</a> asks for permission while <a data-lt=
968-
"start a presentation">starting a presentation</a>, the browser
969-
could offer that display as the default choice, or consider the
970-
gesture as granting permission for the display and bypass display
971-
selection entirely.
948+
If a <a>controlling user agent</a> does not support <a>starting a
949+
presentation from a default presentation request</a>, that user
950+
agent should ignore any value set for <code>defaultRequest</code>.
972951
</div>
973952
</section>
974953
<section>
@@ -1082,23 +1061,21 @@ <h4>
10821061
</section>
10831062
<section>
10841063
<h4>
1085-
Starting a presentation
1064+
Selecting a presentation display
10861065
</h4>
10871066
<p>
10881067
When the <code><dfn for="PresentationRequest">start</dfn></code>
10891068
method is called, the <a>user agent</a> MUST run the following
1090-
steps to <dfn>start a presentation</dfn>:
1069+
steps to <dfn>select a presentation display</dfn>.
10911070
</p>
10921071
<dl>
10931072
<dt>
10941073
Input
10951074
</dt>
10961075
<dd>
10971076
<var>presentationRequest</var>, the
1098-
<code>PresentationRequest</code> object
1099-
</dd>
1100-
<dd>
1101-
<var>presentationUrls</var>, the <a>presentation request URLs</a>
1077+
<code>PresentationRequest</code> object that received the call to
1078+
<code>start</code>
11021079
</dd>
11031080
<dt>
11041081
Output
@@ -1112,6 +1089,9 @@ <h4>
11121089
<a>Promise</a> rejected with an <a>InvalidAccessError</a> exception
11131090
and abort these steps.
11141091
</li>
1092+
<li>Let <var>presentationUrls</var> be the <a>presentation request
1093+
URLs</a> of <var>presentationRequest</var>.
1094+
</li>
11151095
<li>Using the document's <a>relevant settings object</a>, run the
11161096
<a>prohibits mixed security contexts algorithm</a>.
11171097
</li>
@@ -1165,14 +1145,129 @@ <h4>
11651145
</li>
11661146
</ol>
11671147
</li>
1168-
<li>If the user <em>denied permission</em> to use a display, reject
1148+
<li>If the user <em>denies permission</em> to use a display, reject
11691149
<var>P</var> with an <a>NotAllowedError</a> exception, and abort
11701150
all remaining steps.
11711151
</li>
1172-
<li>Otherwise, the user <em>granted permission</em> to use a
1173-
display; let <var>D</var> be that display and <var>U</var> the user
1174-
agent connected to <var>D</var>.
1152+
<li>Otherwise, the user <em>grants permission</em> to use a
1153+
display; let <var>D</var> be that display.
1154+
</li>
1155+
<li>Run the steps to <a>start a presentation connection</a> with
1156+
<var>presentationRequest</var>, <var>D</var>, and <var>P</var>.
1157+
</li>
1158+
</ol>
1159+
<div class="note">
1160+
The details of implementing the permission request and display
1161+
selection are left to the user agent; for example it may show the
1162+
user a dialog and allow the user to select an available display
1163+
(granting permission), or cancel the selection (denying
1164+
permission). Implementers are encouraged to show the user whether
1165+
an available display is currently in use, to facilitate
1166+
presentations that can make use of multiple displays.
1167+
</div>
1168+
<div class="note">
1169+
Receiving user agents are encouraged to advertise a user friendly
1170+
name for the presentation display, e.g. &quot;Living Room TV&quot;,
1171+
to assist the user in selecting the intended display. Implementers
1172+
of receiving user agents are also encouraged to advertise the
1173+
locale and intended text direction of the user friendly name.
1174+
Implementers of controlling user agents are encouraged to render a
1175+
user friendly name using its locale and text direction when they
1176+
are known.
1177+
</div>
1178+
</section>
1179+
<section>
1180+
<h4>
1181+
Starting a presentation from a default presentation request
1182+
</h4>
1183+
<p>
1184+
When the user expresses an intent to start presentation of a
1185+
document on a presentation display using the browser chrome (via a
1186+
dedicated button, user gesture, or other signal), that user agent
1187+
MUST run the following steps to <dfn data-lt=
1188+
"starting a presentation from a default presentation request">start
1189+
a presentation from a default presentation request</dfn>. If no
1190+
<a>default presentation request</a> is set on the document, these
1191+
steps MUST not be run.
1192+
</p>
1193+
<dl>
1194+
<dt>
1195+
Input
1196+
</dt>
1197+
<dd>
1198+
<var>W</var>, the document on which the user has expressed an
1199+
intent to start presentation
1200+
</dd>
1201+
<dd>
1202+
<var>presentationRequest</var>, the non-<code>null</code> value
1203+
of <code>navigator.presentation.defaultRequest</code> set on
1204+
<var>W</var>
1205+
</dd>
1206+
<dd>
1207+
<var>D</var>, the <a>presentation display</a> that is the target
1208+
for presentation
1209+
</dd>
1210+
</dl>
1211+
<ol>
1212+
<li>Let <var>presentationUrls</var> be the <a>presentation request
1213+
URLs</a> of <var>presentationRequest</var>.
1214+
</li>
1215+
<li>Using the <a>relevant settings object</a> for <var>W</var>, run
1216+
the <a>prohibits mixed security contexts algorithm</a>.
1217+
</li>
1218+
<li>If the result of the algorithm is <code>"Prohibits Mixed
1219+
Security Contexts"</code> and any member of
1220+
<var>presentationUrls</var> is an <a>a priori unauthenticated
1221+
URL</a>, then abort these steps.
1222+
</li>
1223+
<li>If the <a>active sandboxing flag set</a> for <var>W</var> has
1224+
the <a>sandboxed presentation browsing context flag</a> set, then
1225+
abort these steps.
11751226
</li>
1227+
<li>If there is no <a>presentation request URL</a> for
1228+
<var>presentationRequest</var> for which <var>D</var> is an
1229+
<a>available presentation display</a>, then abort these steps.
1230+
</li>
1231+
<li>Run the steps to <a>start a presentation connection</a> with
1232+
<var>presentationRequest</var> and <var>D</var>.
1233+
</li>
1234+
</ol>
1235+
<div class="note">
1236+
When <a>starting a presentation from a default presentation
1237+
request</a>, a <a>controlling user agent</a> may allow the user to
1238+
request presentation and choose the intended <a>presentation
1239+
display</a> with the same user gesture. For example, the browser
1240+
chrome could allow the user to pick a display from a menu, or allow
1241+
the user to tap on an <a href="https://nfc-forum.org/">Near Field
1242+
Communications (NFC)</a> enabled display.
1243+
</div>
1244+
</section>
1245+
<section>
1246+
<h4>
1247+
Starting a presentation connection
1248+
</h4>
1249+
<p>
1250+
When the <a>user agent</a> is to <dfn>start a presentation
1251+
connection</dfn>, it MUST run the following steps:
1252+
</p>
1253+
<dl>
1254+
<dt>
1255+
Input
1256+
</dt>
1257+
<dd>
1258+
<var>presentationRequest</var>, the
1259+
<code>PresentationRequest</code> that is used to start the
1260+
presentation connection.
1261+
</dd>
1262+
<dd>
1263+
<var>D</var>, the selected <a>presentation display</a>.
1264+
</dd>
1265+
<dd>
1266+
<var>P</var>, an optional <a>Promise</a> that will be resolved
1267+
with a new <a>presentation connection</a>.
1268+
</dd>
1269+
</dl>
1270+
<ol>
11761271
<li>Let <var>I</var> be a new <a>valid presentation identifier</a>
11771272
unique among all <a>presentation identifiers</a> for known
11781273
<a>presentation connections</a> in the <a>set of controlled
@@ -1185,6 +1280,9 @@ <h4>
11851280
<li>Set the <a>presentation identifier</a> of <var>S</var> to <var>
11861281
I</var>.
11871282
</li>
1283+
<li>Let <var>presentationUrls</var> be the <a>presentation request
1284+
URLs</a> of <var>presentationRequest</var>.
1285+
</li>
11881286
<li>Set the <a>presentation URL</a> for <var>S</var> to the first
11891287
<var>presentationUrl</var> in <var>presentationUrls</var> for which
11901288
there exists an entry <var>(presentationUrl, D)</var> in the
@@ -1195,8 +1293,8 @@ <h4>
11951293
</li>
11961294
<li>Add <var>S</var> to the <a>set of controlled presentations</a>.
11971295
</li>
1198-
<li>
1199-
<a>Resolve</a> <var>P</var> with <var>S</var>.
1296+
<li>If <var>P</var> is provided, <a>resolve</a> <var>P</var> with
1297+
<var>S</var>.
12001298
</li>
12011299
<li>
12021300
<a>Queue a task</a> to <a>fire</a> a <a>trusted event</a> with
@@ -1208,6 +1306,8 @@ <h4>
12081306
The event must not bubble, must not be cancelable, and has no
12091307
default action.
12101308
</li>
1309+
<li>Let <var>U</var> be the user agent connected to D.
1310+
</li>
12111311
<li>If the next step fails, abort all remaining steps and <a>close
12121312
the presentation connection</a> <var>S</var> with <a for=
12131313
"PresentationConnectionClosedReason">error</a> as
@@ -1222,25 +1322,6 @@ <h4>
12221322
<a>Establish a presentation connection</a> with <var>S</var>.
12231323
</li>
12241324
</ol>
1225-
<div class="note">
1226-
The details of implementing the permission request and display
1227-
selection are left to the user agent; for example it may show the
1228-
user a dialog and allow the user to select an available display
1229-
(granting permission), or cancel the selection (denying
1230-
permission). Implementers are encouraged to show the user whether
1231-
an available display is currently in use, to facilitate
1232-
presentations that can make use of multiple displays.
1233-
</div>
1234-
<div class="note">
1235-
Receiving user agents are encouraged to advertise a user friendly
1236-
name for the presentation display, e.g. &quot;Living Room TV&quot;,
1237-
to assist the user in selecting the intended display. Implementers
1238-
of receiving user agents are also encouraged to advertise the
1239-
locale and intended text direction of the user friendly name.
1240-
Implementers of controlling user agents are encouraged to render a
1241-
user friendly name using its locale and text direction when they
1242-
are known.
1243-
</div>
12441325
<div class="note">
12451326
The <var>presentationUrl</var> should name a resource accessible to
12461327
the local or a remote user agent. This specification defines
@@ -1534,7 +1615,7 @@ <h4>
15341615
"PresentationRequest">getAvailability</a>()</code> MUST be
15351616
<a data-lt="reject">rejected</a> and the algorithm to <a>monitor
15361617
the list of available presentation displays</a> will only run as
1537-
part of the <a>start a presentation</a> algorithm.
1618+
part of the <a>select a presentation display</a> algorithm.
15381619
</p>
15391620
<p>
15401621
When there are no live <a>PresentationAvailability</a> objects
@@ -1676,9 +1757,9 @@ <h4>
16761757
<p>
16771758
If the <a>set of availability objects</a> is non-empty, or there is
16781759
a pending request to <a for="PresentationRequest" data-lt=
1679-
"start">start a presentation</a>, the <a>user agent</a> MUST
1680-
<dfn>monitor the list of available presentation displays</dfn> by
1681-
running the following steps.
1760+
"start">select a presentation display</a>, the <a>user agent</a>
1761+
MUST <dfn>monitor the list of available presentation displays</dfn>
1762+
by running the following steps.
16821763
</p>
16831764
<ol link-for="PresentationAvailability">
16841765
<li>Set the <a>list of available presentation displays</a> to the
@@ -1745,10 +1826,10 @@ <h4>
17451826
</li>
17461827
<li>If the <a>set of availability objects</a> is now empty and
17471828
there is no pending request to <a for="PresentationRequest"
1748-
data-lt="start">start a presentation</a>, cancel any pending task
1749-
to <a>monitor the list of available presentation displays</a> for
1750-
power saving purposes, and set the <a>list of available
1751-
presentation displays</a> to the empty list.
1829+
data-lt="start">select a presentation display</a>, cancel any
1830+
pending task to <a>monitor the list of available presentation
1831+
displays</a> for power saving purposes, and set the <a>list of
1832+
available presentation displays</a> to the empty list.
17521833
</li>
17531834
</ol>
17541835
<div class="note">
@@ -2947,9 +3028,10 @@ <h3>
29473028
<dd>
29483029
<p>
29493030
When the user is asked permission to use a <a>presentation
2950-
display</a> during the steps to <a>start a presentation</a>, the
2951-
<a>controlling user agent</a> should make it clear what origin is
2952-
requesting presentation <i>and</i> what origin will be presented.
3031+
display</a> during the steps to <a>select a presentation
3032+
display</a>, the <a>controlling user agent</a> should make it
3033+
clear what origin is requesting presentation <i>and</i> what
3034+
origin will be presented.
29533035
</p>
29543036
<p>
29553037
Display of the origin requesting presentation will help the user
@@ -2973,7 +3055,7 @@ <h3>
29733055
</dt>
29743056
<dd>
29753057
<p>
2976-
When a user <a data-lt="start a presentation">starts a
3058+
When a user <a data-lt="start a presentation connection">starts a
29773059
presentation</a>, the user will begin with exclusive control of
29783060
the presentation. However, the Presentation API allows additional
29793061
devices (likely belonging to distinct users) to connect and

0 commit comments

Comments
 (0)