discovery-api/Overview.src.html
changeset 254 f29ec967fb3b
parent 250 8b912f2bb9c7
child 288 ec6f8e4f894e
     1.1 --- a/discovery-api/Overview.src.html	Tue Oct 02 18:07:01 2012 -0700
     1.2 +++ b/discovery-api/Overview.src.html	Wed Oct 03 14:47:11 2012 +0200
     1.3 @@ -35,7 +35,7 @@
     1.4            class='remove'>
     1.5  var respecConfig = {
     1.6            specStatus:   "ED",
     1.7 -          //publishDate:  "2012-10-09",
     1.8 +          //publishDate:  "2012-10-04",
     1.9            shortName:    "discovery-api",
    1.10            edDraftURI:   "http://dvcs.w3.org/hg/dap/raw-file/tip/discovery-api/Overview.html",
    1.11            previousMaturity: "FPWD",
    1.12 @@ -124,7 +124,7 @@
    1.13        <p>
    1.14          Using this <abbr title="Application Programming Interface">API</abbr> consists of requesting a well-known
    1.15          service type, known by developers and advertised by Local-networked Devices. User authorization, where the user
    1.16 -        connects the web page to one or more discovered services, is expected before the web page is able to interact
    1.17 +        connects the web page to discovered services, is expected before the web page is able to interact
    1.18          with any Local-networked Services.
    1.19        </p>
    1.20        <p>
    1.21 @@ -336,7 +336,7 @@
    1.22            </dt>
    1.23            <dd>
    1.24              <p>
    1.25 -              Prompts the user to select one or more discovered network services that have advertised support for the
    1.26 +              Prompts the user to select discovered network services that have advertised support for the
    1.27                requested service type.
    1.28              </p>
    1.29              <p>
    1.30 @@ -344,7 +344,7 @@
    1.31                page would like to interact with.
    1.32              </p>
    1.33              <p>
    1.34 -              If the user accepts, the <var title="">successCallback</var> is invoked, with one or more <a href=
    1.35 +              If the user accepts, the <var title="">successCallback</var> is invoked, with zero or more <a href=
    1.36                "#networkservice"><code>NetworkService</code></a> objects as its argument.
    1.37              </p>
    1.38              <p>
    1.39 @@ -406,16 +406,6 @@
    1.40                  </li>
    1.41                </ol>
    1.42              </li>
    1.43 -            <li>If <var>services found</var> is an empty array, then the <a>user agent</a> MUST <a href=
    1.44 -            "http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task"
    1.45 -                  class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an
    1.46 -                  object of type <code>Function</code>, with a new <a href=
    1.47 -                  "#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose <a href=
    1.48 -                  "#dom-navigatornetworkserviceerror-code"><code>code</code></a> attribute has the numeric value 1
    1.49 -                  (<a href=
    1.50 -                  "#dom-navigatornetworkserviceerror-permission_denied"><code>PERMISSION_DENIED_ERR</code></a>) as its
    1.51 -                  argument, abort any remaining steps and return.
    1.52 -            </li>
    1.53              <li>Return, and run the remaining steps asynchronously.
    1.54              </li>
    1.55              <li>Optionally, e.g. based on a previously-established user preference, for security reasons, or due to
    1.56 @@ -429,13 +419,14 @@
    1.57                    "#dom-navigatornetworkserviceerror-permission_denied"><code>PERMISSION_DENIED_ERR</code></a>) as its
    1.58                    argument, abort any remaining steps and return.
    1.59              </li>
    1.60 -            <li>The <a>user agent</a> MUST prompt the user in a user-agent-specific manner for permission to provide
    1.61 +            <li>If <var>services found</var> is not an empty array then the <a>user agent</a> MUST prompt the user in a
    1.62 +              user-agent-specific manner for permission to provide
    1.63              the <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/browsers.html#entry-script"
    1.64                    class="externalDFN">entry script</a>'s <a href=
    1.65                    "http://www.whatwg.org/specs/web-apps/current-work/complete/origin-0.html#origin"
    1.66                    class="externalDFN">origin</a> with an array of <a href=
    1.67 -                  "#networkservice"><code>NetworkService</code></a> objects representing the user-authorized subset of
    1.68 -                  <var>services found</var>.
    1.69 +                  "#networkservice"><code>NetworkService</code></a> objects representing the <a>user-authorized</a> subset
    1.70 +                  of <var>services found</var>.
    1.71                <p>
    1.72                  If the user grants permission to access one or more networked services then the <a>user agent</a>
    1.73                  SHOULD include an "ongoing local-network communication" indicator.
    1.74 @@ -455,10 +446,14 @@
    1.75                  If the user never responds, this algorithm stalls on this step.
    1.76                </p>
    1.77              </li>
    1.78 -            <li>Let <var>services</var> be the array of one or more <a href=
    1.79 -            "#networkservice"><code>NetworkService</code></a> objects for which the user granted permission.
    1.80 +            <li>Let <var>services</var> be an empty array.
    1.81              </li>
    1.82 -            <li>For each Object <var>service</var> in <var>services</var>, run the following sub-steps:
    1.83 +            <li>
    1.84 +               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=
    1.85 +            "#networkservice"><code>NetworkService</code></a> objects for which the user granted permission above - known as the
    1.86 +            current objects <dfn>user-authorized</dfn> services.
    1.87 +            </li>
    1.88 +            <li>For each Object <var>service</var> in <var>services</var>, if any, run the following sub-steps:
    1.89                <ol class="rule">
    1.90                  <li>Add the <var>service</var>'s <code>url</code> parameter to the <a>entry script origin's
    1.91                    <abbr title="Uniform Resource Locator">URL</abbr> whitelist</a>.
    1.92 @@ -477,8 +472,9 @@
    1.93              items currently found in the <a>list of available service records</a> whose <code>type</code> property
    1.94              matches any of the tokens requested in <var>requested control types</var>.
    1.95              </li>
    1.96 -            <li>Add <var>services</var> to the <var>services manager</var> object as its collection of <a>indexed
    1.97 -            properties</a>.
    1.98 +            <li>Add <var>services</var>, if any, to the <var>services manager</var> object as its collection of <a>indexed
    1.99 +            properties</a>. If <var>services</var> is an empty array then the <var>services manager</var> does not have any
   1.100 +            <var>indexed properties</var>.
   1.101              </li>
   1.102              <li>Set <var>services manager</var>'s <a href="#dom-networkservices-length"><code>length</code></a>
   1.103              attribute to the number of items in <var>services</var>.
   1.104 @@ -511,7 +507,11 @@
   1.105                 Web Messaging, XMLHttpRequest).
   1.106            </p>
   1.107            <p>
   1.108 -            If the user navigates away from the current browsing context, the <a>user agent</a> <em class=
   1.109 +            If the user navigates away from the
   1.110 +            <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/browsers.html#entry-script"
   1.111 +                  class="externalDFN">entry script</a>'s <a href=
   1.112 +                  "http://www.whatwg.org/specs/web-apps/current-work/complete/origin-0.html#origin"
   1.113 +                  class="externalDFN">origin</a> then the <a>user agent</a> <em class=
   1.114              "ct">MUST</em> remove all previously whitelisted urls from the <a>entry script origin's URL whitelist</a>.
   1.115              There is no persistence to network service selections provided to a web page. It is not possible to access
   1.116              a previously white-listed networked service without the necessary user authorization in all of the
   1.117 @@ -581,10 +581,14 @@
   1.118          Obtaining networked services
   1.119        </h2>
   1.120        <p>
   1.121 -        The <a href="#networkservices"><code>NetworkServices</code></a> interface is the top-level response object from
   1.122 -        a call to <a href="#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a> and provides access
   1.123 -        to a set of user-authorized <a href="#networkservice"><code>NetworkService</code></a> objects for the given
   1.124 -        request.
   1.125 +        The <a href="#networkservices"><code>NetworkServices</code></a> interface represents a collection of zero
   1.126 +        or more <dfn>indexed properties</dfn> that are
   1.127 +        each a <a>user-authorized</a> <a href="#networkservice"><code>NetworkService</code></a> object.
   1.128 +      </p>
   1.129 +      <p>
   1.130 +        A <a href="#networkservices"><code>NetworkServices</code></a> object is the top level success callback
   1.131 +        parameter from a call to
   1.132 +        <a href="#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a>.
   1.133        </p>
   1.134        <pre class="widl">
   1.135  [NoInterfaceObject]
   1.136 @@ -674,10 +678,11 @@
   1.137            </dd>
   1.138          </dl>
   1.139          <p>
   1.140 -          A <a href="#networkservices"><code>NetworkServices</code></a> object represents the current collection of one
   1.141 -          or more <a href="#networkservice"><code>NetworkService</code></a> objects. A <a href=
   1.142 -          "#networkservices"><code>NetworkServices</code></a> object is <span>immutable</span> meaning that it cannot
   1.143 -          be modified.
   1.144 +          A <a href="#networkservices"><code>NetworkServices</code></a> object represents the current collection of zero
   1.145 +          or more <a href="#networkservice"><code>NetworkService</code></a> objects - its <a>indexed properties</a>. A <a href=
   1.146 +          "#networkservices"><code>NetworkServices</code></a> object is <span>immutable</span> meaning that
   1.147 +          <a>indexed properties</a> cannot be added and <a>indexed properties</a> cannot be removed for the lifetime of
   1.148 +          a <a href="#networkservices"><code>NetworkServices</code></a> object.
   1.149          </p>
   1.150          <p class="note">
   1.151            Each service in a <a href="#networkservices"><code>NetworkServices</code></a> object thus has an index; the
   1.152 @@ -961,7 +966,7 @@
   1.153        </p>
   1.154        <p>
   1.155          This section presents how the results of these two <a>service discovery mechanisms</a> will be matched to
   1.156 -        requested service types, how the user agent stores available and active services, how their properties are
   1.157 +        requested service types, how the user agent stores available and active services and how their properties are
   1.158          applied to any resulting <a href="#networkservice"><code>NetworkService</code></a> objects.
   1.159        </p>
   1.160        <p>
   1.161 @@ -980,8 +985,9 @@
   1.162        <p>
   1.163          The <dfn>list of active service managers</dfn> is an internal list within user agents that is used to track all
   1.164          <a href="#networkservices"><code>NetworkServices</code></a> objects currently being shared with any web pages
   1.165 -        at the current time. Each <a href="#networkservices"><code>NetworkServices</code></a> object in the <a>list of
   1.166 -        active service managers</a> represents a collection of one or more <a href=
   1.167 +        at the current time within the user agent. Each <a href="#networkservices"><code>NetworkServices</code></a> object
   1.168 +        in the <a>list of
   1.169 +        active service managers</a> represents a collection of zero or more <a href=
   1.170          "#networkservice"><code>NetworkService</code></a> objects - known as its <dfn>indexed properties</dfn>.
   1.171          <a href="#networkservice"><code>NetworkService</code></a> objects are attached as the <a>indexed properties</a>
   1.172          of a <a href="#networkservices"><code>NetworkServices</code></a> object as part of the <a href=
   1.173 @@ -1565,8 +1571,12 @@
   1.174        </h3>
   1.175        <p>
   1.176          A user agent MUST only garbage collect a <a><code>NetworkServices</code></a> object and remove its entry from
   1.177 -        the <a>list of active service managers</a> when the user has navigated away from the browsing context in which
   1.178 -        that <a><code>NetworkServices</code></a> object was provided.
   1.179 +        the <a>list of active service managers</a> when the user has navigated away from the
   1.180 +        <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/browsers.html#entry-script"
   1.181 +              class="externalDFN">entry script</a>'s <a href=
   1.182 +              "http://www.whatwg.org/specs/web-apps/current-work/complete/origin-0.html#origin"
   1.183 +              class="externalDFN">origin</a> in which
   1.184 +        the current <a><code>NetworkServices</code></a> object was provided.
   1.185        </p>
   1.186        <p>
   1.187          A user agent MUST NOT garbage collect individual <a><code>NetworkService</code></a> objects until their parent