- From: Mercurial notifier <cvsmail@w3.org>
- Date: Tue, 05 Feb 2013 14:22:44 +0000
- To: public-dap-commits@w3.org
changeset: 371:8b03e17da083
user: Rich Tibbett <richt@opera.com>
date: Mon Feb 04 13:47:41 2013 +0100
files: discovery-api/Overview.src.html
description:
Rewrite Step 9 of getNetworkService algorithm following feedback @ http://lists.w3.org/Archives/Public/public-device-apis/2012Sep/0141.html
diff -r ffdaef94ac31 -r 8b03e17da083 discovery-api/Overview.src.html
--- a/discovery-api/Overview.src.html Fri Feb 01 10:43:20 2013 +0200
+++ b/discovery-api/Overview.src.html Mon Feb 04 13:47:41 2013 +0100
@@ -124,8 +124,8 @@
<p>
Using this <abbr title="Application Programming Interface">API</abbr> consists of requesting a well-known
service type, known by developers and advertised by Local-networked Devices. User authorization, where the user
- connects the web page to discovered services, is expected before the web page is able to interact
- with any Local-networked Services.
+ connects the web page to discovered services, is expected before the web page is able to interact with any
+ Local-networked Services.
</p>
<p>
A web page creates a request to obtain connectivity to services running in the network by specifying a
@@ -271,17 +271,15 @@
</p>
<p>
A <dfn>valid service type</dfn> is any of the following:
- <ul>
- <li>
- a string that begins with <code>upnp:</code> or <code>zeroconf:</code>
- followed by one or more characters in the ranges U+0021, U+0023 to U+0027, U+002A to U+002B, U+002D to U+002E,
- U+0030 to U+0039, U+0041 to U+005A, U+005E to U+007E.
- </li>
- <li>
- a string that begins with <code>dial:</code> followed by an integer version.
- </li>
- </ul>
</p>
+ <ul>
+ <li>a string that begins with <code>upnp:</code> or <code>zeroconf:</code> followed by one or more characters
+ in the ranges U+0021, U+0023 to U+0027, U+002A to U+002B, U+002D to U+002E, U+0030 to U+0039, U+0041 to U+005A,
+ U+005E to U+007E.
+ </li>
+ <li>a string that begins with <code>dial:</code> followed by an integer version.
+ </li>
+ </ul>
<p>
A <a>valid service type</a> provided in the <code>type</code> attribute of the <a href=
"#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a> method will be matched against the
@@ -344,8 +342,8 @@
</dt>
<dd>
<p>
- Prompts the user to select discovered network services that have advertised support for the
- requested service type.
+ Prompts the user to select discovered network services that have advertised support for the requested
+ service type.
</p>
<p>
The <var title="">type</var> argument contains one or more <a>valid service type</a> tokens that the web
@@ -427,21 +425,31 @@
"#dom-navigatornetworkserviceerror-permission_denied"><code>PERMISSION_DENIED_ERR</code></a>) as its
argument, abort any remaining steps and return.
</li>
- <li>If <var>services found</var> is not an empty array then the <a>user agent</a> MUST prompt the user in a
- user-agent-specific manner for permission to provide
- the <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/browsers.html#entry-script"
- class="externalDFN">entry script</a>'s <a href=
- "http://www.whatwg.org/specs/web-apps/current-work/complete/origin-0.html#origin"
- class="externalDFN">origin</a> with an array of <a href=
- "#networkservice"><code>NetworkService</code></a> objects representing the <a>user-authorized</a> subset
- of <var>services found</var>.
+ <li>The user agent MUST NOT provide the entry script's origin with a <a href=
+ "#networkservices"><code>NetworkServices</code></a> object without prior permission given by the user.
<p>
- If the user grants permission to access one or more networked services then the <a>user agent</a>
- SHOULD include an "ongoing local-network communication" indicator.
+ If <var>services found</var> is not an empty array then the <a>user agent</a> MAY choose to prompt the
+ user in a user-agent-specific manner for permission to provide the <a href=
+ "http://www.whatwg.org/specs/web-apps/current-work/complete/browsers.html#entry-script"
+ class="externalDFN">entry script</a>'s <a href=
+ "http://www.whatwg.org/specs/web-apps/current-work/complete/origin-0.html#origin"
+ class="externalDFN">origin</a> with a <a href="#networkservices"><code>NetworkServices</code></a>
+ object representing the <a>user-authorized</a> subset of <var>services found</var>.
</p>
<p>
- If the user denies permission, then the <a>user agent</a> MUST <a href=
- "http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task"
+ Alternatively, the user agent MAY choose to queue a task to invoke <var>successCallback</var> or
+ <var>errorCallback</var> immediately based on a previously-established user preference, for security
+ reasons, or due to platform limitations. In such an implementation, if <var>successCallback</var> is to
+ be fired as a result of a previously-established user preference then the <a>user agent</a> MUST
+ continue at the next step of this algorithm.
+ </p>
+ <p>
+ If permission has been granted by the user to access one or more networked services then the <a>user
+ agent</a> SHOULD include an "ongoing local-network communication" indicator.
+ </p>
+ <p>
+ If permission has been denied by the user, <a>user agent</a> or platform, then the <a>user agent</a>
+ MUST <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task"
class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an
object of type <code>Function</code>, with a new <a href=
"#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose <a href=
@@ -451,15 +459,15 @@
argument, abort any remaining steps and return.
</p>
<p>
- If the user never responds, this algorithm stalls on this step.
+ If the user never responds or no previously-established user preference has been met, this algorithm
+ stalls on this step.
</p>
</li>
<li>Let <var>services</var> be an empty array.
</li>
- <li>
- If <var>services found</var> is not an empty array then set <var>services</var> to be an array of one or more <a href=
- "#networkservice"><code>NetworkService</code></a> objects for which the user granted permission above - known as the
- current objects <dfn>user-authorized</dfn> services.
+ <li>If <var>services found</var> is not an empty array then set <var>services</var> to be an array of one
+ or more <a href="#networkservice"><code>NetworkService</code></a> objects for which the user granted
+ permission above - known as the current objects <dfn>user-authorized</dfn> services.
</li>
<li>For each Object <var>service</var> in <var>services</var>, if any, run the following sub-steps:
<ol class="rule">
@@ -480,9 +488,9 @@
items currently found in the <a>list of available service records</a> whose <code>type</code> property
matches any of the tokens requested in <var>requested control types</var>.
</li>
- <li>Add <var>services</var>, if any, to the <var>services manager</var> object as its collection of <a>indexed
- properties</a>. If <var>services</var> is an empty array then the <var>services manager</var> does not have any
- <var>indexed properties</var>.
+ <li>Add <var>services</var>, if any, to the <var>services manager</var> object as its collection of
+ <a>indexed properties</a>. If <var>services</var> is an empty array then the <var>services manager</var>
+ does not have any <var>indexed properties</var>.
</li>
<li>Set <var>services manager</var>'s <a href="#dom-networkservices-length"><code>length</code></a>
attribute to the number of items in <var>services</var>.
@@ -515,15 +523,14 @@
Web Messaging, XMLHttpRequest).
</p>
<p>
- If the user navigates away from the
- <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/browsers.html#entry-script"
- class="externalDFN">entry script</a>'s <a href=
- "http://www.whatwg.org/specs/web-apps/current-work/complete/origin-0.html#origin"
- class="externalDFN">origin</a> then the <a>user agent</a> <em class=
- "ct">MUST</em> remove all previously whitelisted urls from the <a>entry script origin's URL whitelist</a>.
- There is no persistence to network service selections provided to a web page. It is not possible to access
- a previously white-listed networked service without the necessary user authorization in all of the
- following cases:
+ If the user navigates away from the <a href=
+ "http://www.whatwg.org/specs/web-apps/current-work/complete/browsers.html#entry-script"
+ class="externalDFN">entry script</a>'s <a href=
+ "http://www.whatwg.org/specs/web-apps/current-work/complete/origin-0.html#origin"
+ class="externalDFN">origin</a> then the <a>user agent</a> <em class="ct">MUST</em> remove all previously
+ whitelisted urls from the <a>entry script origin's URL whitelist</a>. There is no persistence to network
+ service selections provided to a web page. It is not possible to access a previously white-listed
+ networked service without the necessary user authorization in all of the following cases:
</p>
<ul>
<li>If the current script is reloaded at any point in the same or different window.
@@ -589,14 +596,13 @@
Obtaining networked services
</h2>
<p>
- The <a href="#networkservices"><code>NetworkServices</code></a> interface represents a collection of zero
- or more <dfn>indexed properties</dfn> that are
- each a <a>user-authorized</a> <a href="#networkservice"><code>NetworkService</code></a> object.
+ The <a href="#networkservices"><code>NetworkServices</code></a> interface represents a collection of zero or
+ more <dfn>indexed properties</dfn> that are each a <a>user-authorized</a> <a href=
+ "#networkservice"><code>NetworkService</code></a> object.
</p>
<p>
A <a href="#networkservices"><code>NetworkServices</code></a> object is the top level success callback
- parameter from a call to
- <a href="#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a>.
+ parameter from a call to <a href="#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a>.
</p>
<pre class="widl">
[NoInterfaceObject]
@@ -686,11 +692,11 @@
</dd>
</dl>
<p>
- A <a href="#networkservices"><code>NetworkServices</code></a> object represents the current collection of zero
- or more <a href="#networkservice"><code>NetworkService</code></a> objects - its <a>indexed properties</a>. A <a href=
- "#networkservices"><code>NetworkServices</code></a> object is <span>immutable</span> meaning that
- <a>indexed properties</a> cannot be added and <a>indexed properties</a> cannot be removed for the lifetime of
- a <a href="#networkservices"><code>NetworkServices</code></a> object.
+ A <a href="#networkservices"><code>NetworkServices</code></a> object represents the current collection of
+ zero or more <a href="#networkservice"><code>NetworkService</code></a> objects - its <a>indexed
+ properties</a>. A <a href="#networkservices"><code>NetworkServices</code></a> object is
+ <span>immutable</span> meaning that <a>indexed properties</a> cannot be added and <a>indexed properties</a>
+ cannot be removed for the lifetime of a <a href="#networkservices"><code>NetworkServices</code></a> object.
</p>
<p class="note">
Each service in a <a href="#networkservices"><code>NetworkServices</code></a> object thus has an index; the
@@ -966,12 +972,12 @@
<p>
A <a>user agent</a> conforming to this specification MAY implement <abbr title=
"Simple Service Discovery Protocol">SSDP</abbr> [[!UPNP-DEVICEARCH11]], Zeroconf [[!DNS-SD]] + [[!MDNS]] or
- <abbr title="Discovery and Launch Protocol">DIAL</abbr> [<a href = "https://sites.google.com/a/dial-multiscreen.org/dial/dial-protocol-specification">DIAL</a>]
- <dfn>service discovery mechanisms</dfn> - the requirements detailed in this section of the specification - to
- enable Web pages to request and connect with HTTP services running on networked devices, discovered via either
- mechanism, through this API. When a <a>user agent</a> implements either of these <a>service discovery
- mechanisms</a>, then it MUST conform to the corresponding algorithms provided in this section of the
- specification.
+ <abbr title="Discovery and Launch Protocol">DIAL</abbr> [<a href=
+ "https://sites.google.com/a/dial-multiscreen.org/dial/dial-protocol-specification">DIAL</a>] <dfn>service
+ discovery mechanisms</dfn> - the requirements detailed in this section of the specification - to enable Web
+ pages to request and connect with HTTP services running on networked devices, discovered via either mechanism,
+ through this API. When a <a>user agent</a> implements either of these <a>service discovery mechanisms</a>, then
+ it MUST conform to the corresponding algorithms provided in this section of the specification.
</p>
<p>
This section presents how the results of these two <a>service discovery mechanisms</a> will be matched to
@@ -994,9 +1000,8 @@
<p>
The <dfn>list of active service managers</dfn> is an internal list within user agents that is used to track all
<a href="#networkservices"><code>NetworkServices</code></a> objects currently being shared with any web pages
- at the current time within the user agent. Each <a href="#networkservices"><code>NetworkServices</code></a> object
- in the <a>list of
- active service managers</a> represents a collection of zero or more <a href=
+ at the current time within the user agent. Each <a href="#networkservices"><code>NetworkServices</code></a>
+ object in the <a>list of active service managers</a> represents a collection of zero or more <a href=
"#networkservice"><code>NetworkService</code></a> objects - known as its <dfn>indexed properties</dfn>.
<a href="#networkservice"><code>NetworkService</code></a> objects are attached as the <a>indexed properties</a>
of a <a href="#networkservices"><code>NetworkServices</code></a> object as part of the <a href=
@@ -1470,43 +1475,42 @@
<h5>
Discovery and Launch Protocol (<abbr title="Discovery and Launch Protocol">DIAL</abbr>)
</h5>
- <p>
+ <p>
A user agent that implements DIAL service discovery MUST issue a <dfn>search request for DIAL-enabled
devices</dfn> against the user's current local network according to the full normative text and timing
provided in 'Section 1.3.2: Search request with M-SEARCH' detailed in [[!UPNP-DEVICEARCH11]].
</p>
<p>
- Let <var>dial version</var> be the version number specified in the <a>valid service type</a> token.
- Let <var>dial search target</var> be the concatentation of the
+ Let <var>dial version</var> be the version number specified in the <a>valid service type</a> token. Let
+ <var>dial search target</var> be the concatentation of the
<code>urn:dial-multiscreen-org:service:dial:</code> string constant with the <var>dial version</var>
(currently, <var>dial version</var> can only be <code>1</code>)
</p>
<p>
- The user agent MUST issue all <a title="search request for DIAL devices">search requests for DIAL
- devices</a> with a HTTP request line equal to <code>M-SEARCH * HTTP/1.1</code>, with a HOST header equal to
- the reserved multicast address and port of <code>239.255.255.250:1900</code>, a MAN header equal to
- <code>ssdp:discover</code>, an ST header equal to <var>dial search target</var>
- and a user-agent defined MX header equal to a <dfn>maximum DIAL advertisement response wait time</dfn>
- value between <code>1</code> and <code>5</code> seconds.
+ The user agent MUST issue all <a title="search request for DIAL devices">search requests for DIAL devices</a>
+ with a HTTP request line equal to <code>M-SEARCH * HTTP/1.1</code>, with a HOST header equal to the reserved
+ multicast address and port of <code>239.255.255.250:1900</code>, a MAN header equal to
+ <code>ssdp:discover</code>, an ST header equal to <var>dial search target</var> and a user-agent defined MX
+ header equal to a <dfn>maximum DIAL advertisement response wait time</dfn> value between <code>1</code> and
+ <code>5</code> seconds.
</p>
<p>
The user agent MUST listen for any incoming responses to a <a>search request for DIAL devices</a>.
</p>
<p>
- For each HTTP Response following an initial <a>search request for DIAL devices</a> sent on a
- <a>standard UPnP address and port</a> the user agent MUST run the following steps:
+ For each HTTP Response following an initial <a>search request for DIAL devices</a> sent on a <a>standard UPnP
+ address and port</a> the user agent MUST run the following steps:
</p>
<ol class="rule">
- <li>If the HTTP Response is not a HTTP 200 OK response then this response is invalid and the user
- agent MUST discard this response, abort any remaining steps and return. The user agent MAY issue a new
- <a>search request for DIAL devices</a> as a result of this error occurring.
+ <li>If the HTTP Response is not a HTTP 200 OK response then this response is invalid and the user agent MUST
+ discard this response, abort any remaining steps and return. The user agent MAY issue a new <a>search request
+ for DIAL devices</a> as a result of this error occurring.
</li>
<li>If the <a>maximum DIAL advertisement response wait time</a> has been exceeded since the initial <a>search
request for DIAL devices</a> was sent then the <a>HTTP Response</a> is invalid and the user agent MUST
discard this response, abort any remaining steps and return. The user agent MAY stop listening for responses
- from the current <a>search request for DIAL devices</a> as a result of this error occurring. Equally,
- the user agent MAY issue a new <a>search request for DIAL devices</a> as a result of this error
- occurring.
+ from the current <a>search request for DIAL devices</a> as a result of this error occurring. Equally, the
+ user agent MAY issue a new <a>search request for DIAL devices</a> as a result of this error occurring.
</li>
<li>Let <var>dial device</var> be an Object with a property for each HTTP header received in the <a>HTTP
Response</a>, with each key being the name of a HTTP response header and each value being that HTTP response
@@ -1514,9 +1518,8 @@
</li>
<li>If <var>dial device</var> does not contain at least one <var>CACHE-CONTROL</var> entry, at least one
<var>USN</var> entry, at least one <var>ST</var> entry and at least one <var>LOCATION</var> entry or the
- value of its <var>ST</var> entry is not <var>dial search target</var>, then the
- <a>HTTP Response</a> is invalid and the <a>user agent</a> MUST discard this response, abort any remaining
- steps and return.
+ value of its <var>ST</var> entry is not <var>dial search target</var>, then the <a>HTTP Response</a> is
+ invalid and the <a>user agent</a> MUST discard this response, abort any remaining steps and return.
</li>
<li>The user agent MUST run the rule for <a>obtaining a UPnP Device Description File</a> passing in the first
occurrence of <var>LOCATION</var> from <var>dial device</var> as the <var>device descriptor URL</var>
@@ -1537,12 +1540,12 @@
description using HTTP' in [[!UPNP-DEVICEARCH11]].
</li>
<li>Let <var>application url</var> be the value of the first occurrence of the <code>Application-URL</code>
- response header field obtained according to the rules defined in 'Section 5.4: Device Description Response' in
- [<a href = "https://sites.google.com/a/dial-multiscreen.org/dial/dial-protocol-specification">DIAL</a>]
+ response header field obtained according to the rules defined in 'Section 5.4: Device Description Response'
+ in [<a href="https://sites.google.com/a/dial-multiscreen.org/dial/dial-protocol-specification">DIAL</a>]
</li>
<li>If the value provided in <var>device descriptor URL</var> cannot be resolved as a reachable URL on the
- current network or the <var>device descriptor file</var> remains empty or <var>application url</var> is undefined
- then it is invalid and the <a>user agent</a> MUST abort any remaining steps and return.
+ current network or the <var>device descriptor file</var> remains empty or <var>application url</var> is
+ undefined then it is invalid and the <a>user agent</a> MUST abort any remaining steps and return.
</li>
<li>Run the following steps to add the newly discovered DIAL service:
<ol class="rule">
@@ -1562,8 +1565,8 @@
</li>
<li>Set <var>network service record</var>'s <code>type</code> property to <var>dial search target</var>.
</li>
- <li>Set <var>network service record</var>'s <code>url</code> property to the string value of the <var>
- application url</var>.
+ <li>Set <var>network service record</var>'s <code>url</code> property to the string value of the
+ <var>application url</var>.
</li>
<li>Set <var>network service record</var>'s <code>expiryTimestamp</code> property to the value of the
current date, in UTC timestamp format, plus the value of <var>device expiry</var>.
@@ -1689,12 +1692,11 @@
</h3>
<p>
A user agent MUST only garbage collect a <a><code>NetworkServices</code></a> object and remove its entry from
- the <a>list of active service managers</a> when the user has navigated away from the
- <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/browsers.html#entry-script"
- class="externalDFN">entry script</a>'s <a href=
- "http://www.whatwg.org/specs/web-apps/current-work/complete/origin-0.html#origin"
- class="externalDFN">origin</a> in which
- the current <a><code>NetworkServices</code></a> object was provided.
+ the <a>list of active service managers</a> when the user has navigated away from the <a href=
+ "http://www.whatwg.org/specs/web-apps/current-work/complete/browsers.html#entry-script"
+ class="externalDFN">entry script</a>'s <a href=
+ "http://www.whatwg.org/specs/web-apps/current-work/complete/origin-0.html#origin"
+ class="externalDFN">origin</a> in which the current <a><code>NetworkServices</code></a> object was provided.
</p>
<p>
A user agent MUST NOT garbage collect individual <a><code>NetworkService</code></a> objects until their parent
Received on Tuesday, 5 February 2013 14:22:46 UTC