discovery-api/Overview.src.html
changeset 254 f29ec967fb3b
parent 250 8b912f2bb9c7
child 288 ec6f8e4f894e
--- a/discovery-api/Overview.src.html	Tue Oct 02 18:07:01 2012 -0700
+++ b/discovery-api/Overview.src.html	Wed Oct 03 14:47:11 2012 +0200
@@ -35,7 +35,7 @@
           class='remove'>
 var respecConfig = {
           specStatus:   "ED",
-          //publishDate:  "2012-10-09",
+          //publishDate:  "2012-10-04",
           shortName:    "discovery-api",
           edDraftURI:   "http://dvcs.w3.org/hg/dap/raw-file/tip/discovery-api/Overview.html",
           previousMaturity: "FPWD",
@@ -124,7 +124,7 @@
       <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 one or more discovered services, is expected before the web page is able to interact
+        connects the web page to discovered services, is expected before the web page is able to interact
         with any Local-networked Services.
       </p>
       <p>
@@ -336,7 +336,7 @@
           </dt>
           <dd>
             <p>
-              Prompts the user to select one or more discovered network services that have advertised support for the
+              Prompts the user to select discovered network services that have advertised support for the
               requested service type.
             </p>
             <p>
@@ -344,7 +344,7 @@
               page would like to interact with.
             </p>
             <p>
-              If the user accepts, the <var title="">successCallback</var> is invoked, with one or more <a href=
+              If the user accepts, the <var title="">successCallback</var> is invoked, with zero or more <a href=
               "#networkservice"><code>NetworkService</code></a> objects as its argument.
             </p>
             <p>
@@ -406,16 +406,6 @@
                 </li>
               </ol>
             </li>
-            <li>If <var>services found</var> is an empty array, 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=
-                  "#dom-navigatornetworkserviceerror-code"><code>code</code></a> attribute has the numeric value 1
-                  (<a href=
-                  "#dom-navigatornetworkserviceerror-permission_denied"><code>PERMISSION_DENIED_ERR</code></a>) as its
-                  argument, abort any remaining steps and return.
-            </li>
             <li>Return, and run the remaining steps asynchronously.
             </li>
             <li>Optionally, e.g. based on a previously-established user preference, for security reasons, or due to
@@ -429,13 +419,14 @@
                   "#dom-navigatornetworkserviceerror-permission_denied"><code>PERMISSION_DENIED_ERR</code></a>) as its
                   argument, abort any remaining steps and return.
             </li>
-            <li>The <a>user agent</a> MUST prompt the user in a user-agent-specific manner for permission to provide
+            <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 user-authorized subset of
-                  <var>services found</var>.
+                  "#networkservice"><code>NetworkService</code></a> objects representing the <a>user-authorized</a> subset
+                  of <var>services found</var>.
               <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.
@@ -455,10 +446,14 @@
                 If the user never responds, this algorithm stalls on this step.
               </p>
             </li>
-            <li>Let <var>services</var> be the array of one or more <a href=
-            "#networkservice"><code>NetworkService</code></a> objects for which the user granted permission.
+            <li>Let <var>services</var> be an empty array.
             </li>
-            <li>For each Object <var>service</var> in <var>services</var>, run the following sub-steps:
+            <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">
                 <li>Add the <var>service</var>'s <code>url</code> parameter to the <a>entry script origin's
                   <abbr title="Uniform Resource Locator">URL</abbr> whitelist</a>.
@@ -477,8 +472,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> to the <var>services manager</var> object as its collection of <a>indexed
-            properties</a>.
+            <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>.
@@ -511,7 +507,11 @@
                Web Messaging, XMLHttpRequest).
           </p>
           <p>
-            If the user navigates away from the current browsing context, the <a>user agent</a> <em class=
+            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
@@ -581,10 +581,14 @@
         Obtaining networked services
       </h2>
       <p>
-        The <a href="#networkservices"><code>NetworkServices</code></a> interface is the top-level response object from
-        a call to <a href="#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a> and provides access
-        to a set of user-authorized <a href="#networkservice"><code>NetworkService</code></a> objects for the given
-        request.
+        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>.
       </p>
       <pre class="widl">
 [NoInterfaceObject]
@@ -674,10 +678,11 @@
           </dd>
         </dl>
         <p>
-          A <a href="#networkservices"><code>NetworkServices</code></a> object represents the current collection of one
-          or more <a href="#networkservice"><code>NetworkService</code></a> objects. A <a href=
-          "#networkservices"><code>NetworkServices</code></a> object is <span>immutable</span> meaning that it cannot
-          be modified.
+          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
@@ -961,7 +966,7 @@
       </p>
       <p>
         This section presents how the results of these two <a>service discovery mechanisms</a> will be matched to
-        requested service types, how the user agent stores available and active services, how their properties are
+        requested service types, how the user agent stores available and active services and how their properties are
         applied to any resulting <a href="#networkservice"><code>NetworkService</code></a> objects.
       </p>
       <p>
@@ -980,8 +985,9 @@
       <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. Each <a href="#networkservices"><code>NetworkServices</code></a> object in the <a>list of
-        active service managers</a> represents a collection of one 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=
@@ -1565,8 +1571,12 @@
       </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 browsing context in which
-        that <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