Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Adds steps for initiating presentation from default presentation request. #369

Merged
merged 5 commits into from Nov 23, 2016
Merged

Adds steps for initiating presentation from default presentation request. #369

Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6467f94
Draft changes to refactor start presentation
mfoltzgoogle Nov 18, 2016
ad41edf
Finish drafting. Tidy
mfoltzgoogle Nov 18, 2016
7ae6314
Respond to tidoust@ comments
mfoltzgoogle Nov 21, 2016
e898fca
Merge branch 'gh-pages' into issue-359-default-request
mfoltzgoogle Nov 23, 2016
822cd22
Respond to schien@ comments
mfoltzgoogle Nov 23, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
226 changes: 154 additions & 72 deletions index.html
View file
Open in desktop
Expand Up @@ -886,7 +886,7 @@ <h3>
In a <a>controlling browsing context</a>, the <dfn>default
presentation request</dfn>, which is initially set to
<code>null</code>, represents the request to use when the user wishes
to initiate a <a>presentation connection</a> from the browser.
to initiate a <a>presentation connection</a> from the browser chrome.
</p>
</section>
<section>
Expand Down Expand Up @@ -932,43 +932,22 @@ <h4>
The <a>controlling user agent</a> SHOULD initiate presentation
using the <a>default presentation request</a> only when the user
has expressed an intention to do so via a user gesture, for example
by clicking a button in the browser.
by clicking a button in the browser chrome.
</p>
<p>
To initiate presentation using the <a>default presentation
request</a>, the <a>controlling user agent</a> MUST <a>start a
presentation</a> using the <a>default presentation request</a> (as
if the controller had called <code>defaultRequest.start()</code>),
skipping the first step of that algorithm.
request</a>, the <a>controlling user agent</a> MUST follow the
steps to <a>start a presentation from a default presentation
request</a>.
</p>
<div class="note">
Subsequent security steps of the <a>start a presentation</a>
algorithm apply. For instance, the request will fail if the
document object's <a>active sandboxing flag set</a> has the
<a>sandboxed presentation browsing context flag</a> set.
</div>
<p>
Support for the initiation of a <a>presentation connection</a> from
the browser is OPTIONAL.
Support initating presentation using the <a>default presentation
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/initating/initiating
Also, shouldn't that be "Support for initiating"?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

request</a> is OPTIONAL.
</p>
<div class="note">
If a <a>controlling user agent</a> does not support initiation of a
<a>presentation connection</a> from the browser, setting
<code>defaultRequest</code> will have no effect.
</div>
<div class="note">
Some <a data-lt="controlling user agent">controlling user
agents</a> may allow the user to initiate a default <a>presentation
connection</a> and select a <a>presentation display</a> 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 an
<a href="https://nfc-forum.org/">Near Field Communications
(NFC)</a> enabled display. In this case, when the <a>controlling
user agent</a> asks for permission while <a data-lt=
"start a presentation">starting a presentation</a>, the browser
could offer that display as the default choice, or consider the
gesture as granting permission for the display and bypass display
selection entirely.
If a <a>controlling user agent</a> does not support <a>starting a
presentation from a default presentation request</a>, that user
agent should ignore any value set for <code>defaultRequest</code>.
</div>
</section>
<section>
Expand Down Expand Up @@ -1082,23 +1061,22 @@ <h4>
</section>
<section>
<h4>
Starting a presentation
Selecting a presentation display
</h4>
<p>
When the <code><dfn for="PresentationRequest">start</dfn></code>
method is called, the <a>user agent</a> MUST run the following
steps to <dfn>start a presentation</dfn>:
steps to <dfn>select a presentation display</dfn>, and then
<a>start a presentation connection</a> with the selected display.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Although I don't see anyone could mis-interpret this and run the second algorithm twice, I would drop the end of the sentence.

In practice, the user agent will not run "select a presentation display", and then "start a presentation connection". It will rather run "select a presentation display" which includes a call to "start a presentation connection".

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

</p>
<dl>
<dt>
Input
</dt>
<dd>
<var>presentationRequest</var>, the
<code>PresentationRequest</code> object
</dd>
<dd>
<var>presentationUrls</var>, the <a>presentation request URLs</a>
<code>PresentationRequest</code> object that received the call to
<code>start</code>
</dd>
<dt>
Output
Expand All @@ -1112,6 +1090,9 @@ <h4>
<a>Promise</a> rejected with an <a>InvalidAccessError</a> exception
and abort these steps.
</li>
<li>Let <var>presentationUrls</var> be the <a>presentation request
URLs</a> of <var>presentationRequest</var>.
</li>
<li>Using the document's <a>relevant settings object</a>, run the
<a>prohibits mixed security contexts algorithm</a>.
</li>
Expand Down Expand Up @@ -1170,9 +1151,123 @@ <h4>
all remaining steps.
</li>
<li>Otherwise, the user <em>granted permission</em> to use a
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure why we use past tense here, "user grants permission" should be enough. Same thing in "user denied permission" few lines before.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Both done.

display; let <var>D</var> be that display and <var>U</var> the user
agent connected to <var>D</var>.
display; let <var>D</var> be that display.
</li>
<li>Run the steps to <a>start a presentation connection</a> with
<var>presentationRequest</var>, <var>D</var>, and <var>P</var>.
</li>
</ol>
<div class="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.
</div>
<div class="note">
Receiving user agents are encouraged to advertise a user friendly
name for the presentation display, e.g. &quot;Living Room TV&quot;,
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.
</div>
</section>
<section>
<h4>
Starting a presentation from a default presentation request
</h4>
<p>
When the user expresses an intent to start presentation of a
document on a presentation display using the browser chrome (via a
dedicated button, user gesture, or other signal), that user agent
MUST run the following steps to <dfn data-lt=
"starting a presentation from a default presentation request">start
a presentation from a default presentation request</dfn>. If no
<a>default presentation request</a> is set on the document, these
steps MUST not be run.
</p>
<dl>
<dt>
Input
</dt>
<dd>
<var>W</var>, the document that the user intends to present
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I may be reading that incorrectly but, for me, the document that the user intends to present is the document that will be created on the receiving side when the presentation gets started. Use "the document on which the user expresses an intent to start presentation", instead?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, that's what I meant to say :) Updated text per your suggestion.

</dd>
<dd>
<var>presentationRequest</var>, the non-<code>null</code> value
of <code>navigator.presentation.defaultRequest</code> set on
<var>W</var>
</dd>
<dd>
<var>D</var>, the <a>presentation display</a> that is the target
for presentation
</dd>
</dl>
<ol>
<li>Let <var>presentationUrls</var> be the <a>presentation request
URLs</a> of <var>presentationRequest</var>.
</li>
<li>Using the <a>relevant settings object</a> for <var>W</var>, run
the <a>prohibits mixed security contexts algorithm</a>.
</li>
<li>If the result of the algorithm is <code>"Prohibits Mixed
Security Contexts"</code> and any member of
<var>presentationUrls</var> is an <a>a priori unauthenticated
URL</a>, then abort these steps.
</li>
<li>If the <a>active sandboxing flag set</a> for <var>W</var> has
the <a>sandboxed presentation browsing context flag</a> set, then
abort these steps.
</li>
<li>If there is no <a>presentation request URL</a> for
<var>presentationRequest</var> for which <var>D</var> is an
<a>available presentation display</a>, then abort these steps.
</li>
<li>Run the steps to <a>start a presentation connection</a> with
<var>presentationRequest</var> and <var>D</var>.
</li>
</ol>
<div class="note">
When <a>starting a presentation from a default presentation
request</a>, a <a>controlling user agent</a> may allow the user to
request presentation and choose the intended <a>presentation
display</a> 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 an <a href="https://nfc-forum.org/">Near Field
Communications (NFC)</a> enabled display.
</div>
</section>
<section>
<h4>
Starting a presentation connection
</h4>
<p>
When the <a>user agent</a> is to <dfn>start a presentation
connection</dfn>, it MUST run the following steps:
</p>
<dl>
<dt>
Input
</dt>
<dd>
<var>presentationRequest</var>, the
<code>PresentationRequest</code> that is used to start the
presentation connection.
</dd>
<dd>
<var>D</var>, the selected <a>presentation display</a>.
</dd>
<dd>
<var>P</var>, an optional <a>Promise</a> that will be resolved
with a new <a>presentation connection</a>.
</dd>
</dl>
<ol>
<li>Let <var>I</var> be a new <a>valid presentation identifier</a>
unique among all <a>presentation identifiers</a> for known
<a>presentation connections</a> in the <a>set of controlled
Expand All @@ -1185,6 +1280,9 @@ <h4>
<li>Set the <a>presentation identifier</a> of <var>S</var> to <var>
I</var>.
</li>
<li>Let <var>presentationUrls</var> be the <a>presentation request
URLs</a> of <var>presentationRequest</var>.
</li>
<li>Set the <a>presentation URL</a> for <var>S</var> to the first
<var>presentationUrl</var> in <var>presentationUrls</var> for which
there exists an entry <var>(presentationUrl, D)</var> in the
Expand All @@ -1195,8 +1293,8 @@ <h4>
</li>
<li>Add <var>S</var> to the <a>set of controlled presentations</a>.
</li>
<li>
<a>Resolve</a> <var>P</var> with <var>S</var>.
<li>If <var>P</var> was provided, <a>resolve</a> <var>P</var> with
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Use "If P is provided"?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

<var>S</var>.
</li>
<li>
<a>Queue a task</a> to <a>fire</a> a <a>trusted event</a> with
Expand All @@ -1208,6 +1306,8 @@ <h4>
The event must not bubble, must not be cancelable, and has no
default action.
</li>
<li>Let <var>U</var> be the the user agent connected to D.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/the the/the/

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

</li>
<li>If the next step fails, abort all remaining steps and <a>close
the presentation connection</a> <var>S</var> with <a for=
"PresentationConnectionClosedReason">error</a> as
Expand All @@ -1222,25 +1322,6 @@ <h4>
<a>Establish a presentation connection</a> with <var>S</var>.
</li>
</ol>
<div class="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.
</div>
<div class="note">
Receiving user agents are encouraged to advertise a user friendly
name for the presentation display, e.g. &quot;Living Room TV&quot;,
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.
</div>
<div class="note">
The <var>presentationUrl</var> should name a resource accessible to
the local or a remote user agent. This specification defines
Expand Down Expand Up @@ -1507,7 +1588,7 @@ <h4>
"PresentationRequest">getAvailability</a>()</code> MUST be
<a data-lt="reject">rejected</a> and the algorithm to <a>monitor
the list of available presentation displays</a> will only run as
part of the <a>start a presentation</a> algorithm.
part of the <a>select a presentation display</a> algorithm.
</p>
<p>
When there are no live <a>PresentationAvailability</a> objects
Expand Down Expand Up @@ -1649,9 +1730,9 @@ <h4>
<p>
If the <a>set of availability objects</a> is non-empty, or there is
a pending request to <a for="PresentationRequest" data-lt=
"start">start a presentation</a>, the <a>user agent</a> MUST
<dfn>monitor the list of available presentation displays</dfn> by
running the following steps.
"start">select a presentation display</a>, the <a>user agent</a>
MUST <dfn>monitor the list of available presentation displays</dfn>
by running the following steps.
</p>
<ol link-for="PresentationAvailability">
<li>Set the <a>list of available presentation displays</a> to the
Expand Down Expand Up @@ -1718,10 +1799,10 @@ <h4>
</li>
<li>If the <a>set of availability objects</a> is now empty and
there is no pending request to <a for="PresentationRequest"
data-lt="start">start a presentation</a>, cancel any pending task
to <a>monitor the list of available presentation displays</a> for
power saving purposes, and set the <a>list of available
presentation displays</a> to the empty list.
data-lt="start">select a presentation display</a>, cancel any
pending task to <a>monitor the list of available presentation
displays</a> for power saving purposes, and set the <a>list of
available presentation displays</a> to the empty list.
</li>
</ol>
<div class="note">
Expand Down Expand Up @@ -2920,9 +3001,10 @@ <h3>
<dd>
<p>
When the user is asked permission to use a <a>presentation
display</a> during the steps to <a>start a presentation</a>, the
<a>controlling user agent</a> should make it clear what origin is
requesting presentation <i>and</i> what origin will be presented.
display</a> during the steps to <a>select a presentation
display</a>, the <a>controlling user agent</a> should make it
clear what origin is requesting presentation <i>and</i> what
origin will be presented.
</p>
<p>
Display of the origin requesting presentation will help the user
Expand All @@ -2946,7 +3028,7 @@ <h3>
</dt>
<dd>
<p>
When a user <a data-lt="start a presentation">starts a
When a user <a data-lt="start a presentation connection">starts a
presentation</a>, 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
Expand Down