discovery-api/Overview.src.html
changeset 371 8b03e17da083
parent 332 e19dc529aacc
child 372 7639401e21f4
--- 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