discovery-api/Overview.src.html
changeset 437 d25229263a68
parent 402 a3626e492d27
child 438 d66ca00fe7d9
     1.1 --- a/discovery-api/Overview.src.html	Tue Jul 16 18:23:28 2013 -0400
     1.2 +++ b/discovery-api/Overview.src.html	Tue Jul 23 18:33:30 2013 +1000
     1.3 @@ -46,12 +46,6 @@
     1.4                //url:        "http://richt.me/",
     1.5                company:    "Opera Software ASA",
     1.6                companyURL: "http://opera.com/"
     1.7 -            },
     1.8 -            {
     1.9 -              name:       "Clarke Stevens",
    1.10 -              //url:      "",
    1.11 -              company:    "CableLabs",
    1.12 -              companyURL: "http://cablelabs.com/"
    1.13              }
    1.14            ],
    1.15  
    1.16 @@ -60,8 +54,8 @@
    1.17            wgPublicList: "public-device-apis",
    1.18            wgPatentURI:  "http://www.w3.org/2004/01/pp-impl/43696/status",
    1.19  
    1.20 -//          extraCSS:     ["http://dvcs.w3.org/hg/dap/raw-file/tip/discovery-api/css/respec.nsd.css"],
    1.21 -//          inlineCSS:    true,
    1.22 +    //          extraCSS:     ["http://dvcs.w3.org/hg/dap/raw-file/tip/discovery-api/css/respec.nsd.css"],
    1.23 +    //          inlineCSS:    true,
    1.24            noIDLIn:      true
    1.25  
    1.26        };
    1.27 @@ -69,9 +63,10 @@
    1.28      <script src='http://www.w3.org/Tools/respec/respec-w3c-common'
    1.29            type="text/javascript"
    1.30            class='remove'
    1.31 -          async=""></script>
    1.32 +          async="">
    1.33 +</script>
    1.34      <style>
    1.35 -     /* Custom ReSpec CSS (by Rich Tibbett) */
    1.36 +/* Custom ReSpec CSS (by Rich Tibbett) */
    1.37  
    1.38       /* Add better spacing to sections */
    1.39       section, .section { margin-bottom: 2em; }
    1.40 @@ -101,7 +96,17 @@
    1.41       table thead { border-bottom:solid }
    1.42       table tbody th:first-child { border-left:solid }
    1.43       table td, table th { border-left:solid; border-right:solid; border-bottom:solid thin; vertical-align:top; padding:0.2em }
    1.44 -     </style>
    1.45 +    </style>
    1.46 +    <script type="text/javascript"
    1.47 +          class="remove">
    1.48 +// RESPEC DEFINITIONS STYLE OVERLOAD
    1.49 +        window.addEventListener('load', function() {
    1.50 +          var overrideStyleEl = document.createElement('style');
    1.51 +          overrideStyleEl.textContent += "\n  a.externalDFN { color: #00C; border-bottom: 1px dashed #00C; }";
    1.52 +          overrideStyleEl.textContent += "\n  a.internalDFN { color: #00C; text-decoration: solid; }";
    1.53 +          document.querySelector('body').appendChild(overrideStyleEl);
    1.54 +        }, false);
    1.55 +    </script>
    1.56    </head>
    1.57    <body>
    1.58      <section id='abstract'>
    1.59 @@ -141,9 +146,10 @@
    1.60          service according to the processing described herein.
    1.61        </p>
    1.62        <p>
    1.63 -        If a service connectivity request is successful then the Web page is provided with the necessary information to
    1.64 -        communicate with the authorized Local-networked Service. If the request fails then the Web page will receive an
    1.65 -        error callback containing an error code describing the cause of Local-networked Service connectivity failure.
    1.66 +        If a service connectivity request is successful then the Web page is provided with a promise-based success
    1.67 +        callback with the all necessary information to communicate with the authorized Local-networked Service. If the
    1.68 +        request fails then the Web page will receive a promise-based error callback containing an error code describing
    1.69 +        the cause of Local-networked Service connectivity failure.
    1.70        </p>
    1.71        <p>
    1.72          Once connected to a Local-networked Service the Web page can send requests and receive responses to the
    1.73 @@ -153,7 +159,11 @@
    1.74          by the connected Local-networked Service.
    1.75        </p>
    1.76        <p>
    1.77 -        Services available within the local network can connect and disconnect at different times during the execution of a web page. The user agent can inform a web page when the state of networked services matching any of the requested valid service types change. Web pages can use this information to enable in-page experiences for communicating the state of networked services with the ability to change the particular service or set of services the page is connected to (by re-invoking the <a href=
    1.78 +        Services available within the local network can connect and disconnect at different times during the execution
    1.79 +        of a web page. The user agent can inform a web page when the state of networked services matching any of the
    1.80 +        requested valid service types change. Web pages can use this information to enable in-page experiences for
    1.81 +        communicating the state of networked services with the ability to change the particular service or set of
    1.82 +        services the page is connected to (by re-invoking the <a href=
    1.83          "#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a> method defined herein).
    1.84        </p>
    1.85        <div class="example">
    1.86 @@ -167,7 +177,7 @@
    1.87    for(var i = 0, l = services.length; i &lt; l; i++) console.log( services[i].name );
    1.88  }
    1.89  
    1.90 -navigator.getNetworkServices('zeroconf:_boxee-jsonrpc._tcp', showServices);
    1.91 +navigator.getNetworkServices('zeroconf:_boxee-jsonrpc._tcp').then(showServices);
    1.92  </pre>
    1.93        </div>
    1.94        <div class="example">
    1.95 @@ -185,7 +195,7 @@
    1.96    console.log( "Error occurred: " + e.code );
    1.97  }
    1.98  
    1.99 -navigator.getNetworkServices('upnp:urn:schemas-upnp-org:service:ContentDirectory:1', showServices, error);
   1.100 +navigator.getNetworkServices('upnp:urn:schemas-upnp-org:service:ContentDirectory:1').then(showServices, error);
   1.101  </pre>
   1.102        </div>
   1.103        <div class="example">
   1.104 @@ -203,7 +213,7 @@
   1.105  navigator.getNetworkServices([
   1.106    'zeroconf:_boxee-jsonrpc._tcp',
   1.107    'upnp:urn:schemas-upnp-org:service:ContentDirectory:1'
   1.108 -], showServices);
   1.109 +]).then(showServices);
   1.110  </pre>
   1.111        </div>
   1.112        <p>
   1.113 @@ -324,34 +334,21 @@
   1.114        <pre class="widl">
   1.115  [Supplemental, NoInterfaceObject]
   1.116  interface <dfn id="navigatornetworkservice">NavigatorNetworkService</dfn> {
   1.117 -  // Obtain a Local-networked Service
   1.118 -  void <a href="#dom-navigator-getnetworkservices">getNetworkServices</a>( in any type,
   1.119 -                           in <a href=
   1.120 -"#navigatornetworkservicesuccesscallback">NavigatorNetworkServiceSuccessCallback</a> successCallback,
   1.121 -                           in optional <a href=
   1.122 -"#navigatornetworkserviceerrorcallback">NavigatorNetworkServiceErrorCallback</a> errorCallback );
   1.123 +  <a class="externalDFN"
   1.124 +     href="http://dom.spec.whatwg.org/#promise">Promise</a> <a href=
   1.125 +     "#dom-navigator-getnetworkservices">getNetworkServices</a>( in any type );
   1.126  };
   1.127  <a class="externalDFN"
   1.128       href=
   1.129       "http://www.whatwg.org/specs/web-apps/current-work/complete/timers.html#navigator">Navigator</a> implements <a href=
   1.130       "#navigatornetworkservice">NavigatorNetworkService</a>;
   1.131  
   1.132 -[Callback=FunctionOnly, NoInterfaceObject]
   1.133 -interface <dfn id="navigatornetworkservicesuccesscallback">NavigatorNetworkServiceSuccessCallback</dfn> {
   1.134 -  void handleEvent( in <a href="#networkservices">NetworkServices</a> services );
   1.135 -};
   1.136 -
   1.137  [NoInterfaceObject]
   1.138  interface <dfn id="navigatornetworkserviceerror">NavigatorNetworkServiceError</dfn> {
   1.139    const unsigned short <a href="#dom-navigatornetworkserviceerror-permission_denied">PERMISSION_DENIED_ERR</a> = 1;
   1.140    const unsigned short <a href="#dom-navigatornetworkserviceerror-unknown_type_prefix">UNKNOWN_TYPE_PREFIX_ERR</a> = 2;
   1.141    readonly attribute unsigned short <a href="#dom-navigatornetworkserviceerror-code">code</a>;
   1.142  };
   1.143 -
   1.144 -[Callback=FunctionOnly, NoInterfaceObject]
   1.145 -interface <dfn id="navigatornetworkserviceerrorcallback">NavigatorNetworkServiceErrorCallback</dfn> {
   1.146 -  void handleEvent( in <a href="#navigatornetworkserviceerror">NavigatorNetworkServiceError</a> error );
   1.147 -};
   1.148  </pre>
   1.149        <section>
   1.150          <h2>
   1.151 @@ -359,37 +356,49 @@
   1.152          </h2>
   1.153          <dl class="domintro">
   1.154            <dt>
   1.155 -            <var title="">window</var> . <code title="dom-navigator"><a href=
   1.156 +            <var title="">promise</var> = <var title="">window</var> . <code title="dom-navigator"><a href=
   1.157              "http://www.whatwg.org/specs/web-apps/current-work/complete/timers.html#navigator">navigator</a></code> .
   1.158              <code title="dom-navigator-getNetworkServices"><a href=
   1.159 -            "#dom-navigator-getnetworkservices">getNetworkServices</a></code> ( <var title="">type</var> , <var title=
   1.160 -            "">successCallback</var> [, <var title="">errorCallback</var> ] )
   1.161 +            "#dom-navigator-getnetworkservices">getNetworkServices</a></code> ( <var title="">type</var> )
   1.162            </dt>
   1.163            <dd>
   1.164              <p>
   1.165 -              Prompts the user to select discovered network services that have advertised support for the requested
   1.166 -              service type.
   1.167 +              Immediately returns a new <a href="http://dom.spec.whatwg.org/#promise"
   1.168 +                 class="externalDFN">Promise</a> object and then the user is prompted to select discovered network
   1.169 +                 services that have advertised support for the requested service type(s).
   1.170              </p>
   1.171              <p>
   1.172                The <var title="">type</var> argument contains one or more <a>valid service type</a> tokens that the web
   1.173                page would like to interact with.
   1.174              </p>
   1.175              <p>
   1.176 -              If the user accepts, the <var title="">successCallback</var> is invoked, with zero or more <a href=
   1.177 -              "#networkservice"><code>NetworkService</code></a> objects as its argument.
   1.178 +              If the user accepts, the <var title="">promise</var> object is <a class="externalDFN"
   1.179 +                 href="http://dom.spec.whatwg.org/#concept-resolver-resolve">resolved</a>, with a <a href=
   1.180 +                 "#networkservices"><code>NetworkServices</code></a> object as its argument.
   1.181              </p>
   1.182              <p>
   1.183 -              If the user declines, the <var title="">errorCallback</var> (if any) is invoked.
   1.184 +              If the user declines, or an error occurs, the <var title="">promise</var> object is <a class=
   1.185 +              "externalDFN"
   1.186 +                 href="http://dom.spec.whatwg.org/#concept-resolver-reject">rejected</a>.
   1.187              </p>
   1.188            </dd>
   1.189          </dl>
   1.190          <div>
   1.191            <p>
   1.192              When the <dfn id="dom-navigator-getnetworkservices"
   1.193 -               title="dom-navigator-getnetworkservices"><code>getNetworkServices(type, successCallback[,
   1.194 -               errorCallback])</code></dfn> method is called, the <a>user agent</a> MUST run the following steps:
   1.195 +               title="dom-navigator-getnetworkservices"><code>getNetworkServices(type)</code></dfn> method is called,
   1.196 +               the <a>user agent</a> MUST run the following steps:
   1.197            </p>
   1.198            <ol class="rule">
   1.199 +            <li>Let <var>Network Service Promise</var> be a new <a href="http://dom.spec.whatwg.org/#promise"
   1.200 +                  class="externalDFN"><code>Promise</code></a> object.
   1.201 +            </li>
   1.202 +            <li>Let <var>Network Service Promise's Resolver</var> be the default <a href=
   1.203 +            "http://dom.spec.whatwg.org/#concept-resolver"
   1.204 +                  class="externalDFN">resolver</a> of <var>Network Service Promise</var>.
   1.205 +            </li>
   1.206 +            <li>Return <var>Network Service Promise</var>, and run the remaining steps asynchronously.
   1.207 +            </li>
   1.208              <li>Let <var>requested control types</var> be initially set to an empty array.
   1.209              </li>
   1.210              <li>If <var>type</var> is an array consisting of one or more <a>valid service type</a> tokens, then let
   1.211 @@ -401,10 +410,10 @@
   1.212              </li>
   1.213              <li>If <var>requested control types</var> is an array that contains at least one or more <a title=
   1.214              "valid service type">valid service type</a> tokens then continue to the step labeled <em>process</em>
   1.215 -            below. Otherwise, the <a>user agent</a> MUST <a href=
   1.216 -            "http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task"
   1.217 -                  class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an
   1.218 -                  object of type <code>Function</code>, with a new <a href=
   1.219 +            below. Otherwise, reject <var>Network Service Promise</var> by running the <a href=
   1.220 +            "http://dom.spec.whatwg.org/#concept-resolver-reject"
   1.221 +                  class="externalDFN">resolver reject algorithm</a> against the <var>Network Service Promise's
   1.222 +                  Resolver</var>, passing in a new <a href=
   1.223                    "#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose <a href=
   1.224                    "#dom-navigatornetworkserviceerror-code"><code>code</code></a> attribute has the numeric value 2
   1.225                    (<a href=
   1.226 @@ -437,13 +446,11 @@
   1.227                  </li>
   1.228                </ol>
   1.229              </li>
   1.230 -            <li>Return, and run the remaining steps asynchronously.
   1.231 -            </li>
   1.232              <li>Optionally, e.g. based on a previously-established user preference, for security reasons, or due to
   1.233 -            platform limitations, the <a>user agent</a> MAY <a href=
   1.234 -            "http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task"
   1.235 -                  class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an
   1.236 -                  object of type <code>Function</code>, with a new <a href=
   1.237 +            platform limitations, the <a>user agent</a> MAY reject <var>Network Service Promise</var> by running the
   1.238 +            <a href="http://dom.spec.whatwg.org/#concept-resolver-reject"
   1.239 +                  class="externalDFN">resolver reject algorithm</a> against the <var>Network Service Promise's
   1.240 +                  Resolver</var>, passing in a new <a href=
   1.241                    "#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose <a href=
   1.242                    "#dom-navigatornetworkserviceerror-code"><code>code</code></a> attribute has the numeric value 1
   1.243                    (<a href=
   1.244 @@ -462,11 +469,11 @@
   1.245                     object representing the <a>user-authorized</a> subset of <var>services found</var>.
   1.246                </p>
   1.247                <p>
   1.248 -                Alternatively, the user agent MAY choose to queue a task to invoke <var>successCallback</var> or
   1.249 -                <var>errorCallback</var> immediately based on a previously-established user previously, for security
   1.250 -                reasons, or due to platform limitations. In such an implementation, if <var>successCallback</var> is to
   1.251 -                be fired as a result of a previously-established user preference then the <a>user agent</a> MUST
   1.252 -                continue at the next step of this algorithm.
   1.253 +                Alternatively, the user agent MAY wish to skip this user opt-in step and choose to fulfill <var>Network
   1.254 +                Service Promise</var> immediately based on a previously-established user preference, for security
   1.255 +                reasons, or due to platform limitations. In such an implementation, if <var>Network Service
   1.256 +                Promise</var> is to be fulfilled as a result of a previously-established user preference then the
   1.257 +                <a>user agent</a> MUST continue at the next step of this algorithm.
   1.258                </p>
   1.259                <p>
   1.260                  If permission has been granted by the user to access one or more networked services then the <a>user
   1.261 @@ -474,9 +481,10 @@
   1.262                </p>
   1.263                <p>
   1.264                  If permission has been denied by the user, <a>user agent</a> or platform, then the <a>user agent</a>
   1.265 -                MUST <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task"
   1.266 -                   class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an
   1.267 -                   object of type <code>Function</code>, with a new <a href=
   1.268 +                MUST reject <var>Network Service Promise</var> by running the <a href=
   1.269 +                "http://dom.spec.whatwg.org/#concept-resolver-reject"
   1.270 +                   class="externalDFN">resolver reject algorithm</a> against the <var>Network Service Promise's
   1.271 +                   Resolver</var>, passing in a new <a href=
   1.272                     "#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose <a href=
   1.273                     "#dom-navigatornetworkserviceerror-code"><code>code</code></a> attribute has the numeric value 1
   1.274                     (<a href=
   1.275 @@ -530,10 +538,10 @@
   1.276              </li>
   1.277              <li>Add <var>services manager</var> to the <a>list of active service managers</a>.
   1.278              </li>
   1.279 -            <li>The <a>user agent</a> MUST <a href=
   1.280 -            "http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task"
   1.281 -                  class="externalDFN">queue a task</a> to invoke <var>successCallback</var> with <var>services
   1.282 -                  manager</var> as its argument.
   1.283 +            <li>The <a>user agent</a> MUST fulfill <var>Network Service Promise</var> by running the <a href=
   1.284 +            "http://dom.spec.whatwg.org/#concept-resolver-fulfill"
   1.285 +                  class="externalDFN">resolver fulfill algorithm</a> against the <var>Network Service Promise's
   1.286 +                  Resolver</var>, passing in <var>services manager</var> as its argument.
   1.287              </li>
   1.288            </ol>
   1.289            <p>
   1.290 @@ -634,8 +642,10 @@
   1.291          "#networkservice"><code>NetworkService</code></a> object.
   1.292        </p>
   1.293        <p>
   1.294 -        A <a href="#networkservices"><code>NetworkServices</code></a> object is the top level success callback
   1.295 -        parameter from a call to <a href="#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a>.
   1.296 +        A <a href="#networkservices"><code>NetworkServices</code></a> object is the <a href=
   1.297 +        "http://dom.spec.whatwg.org/#concept-promise-result"
   1.298 +           class="externalDFN">promise result</a> from a call to <a href=
   1.299 +           "#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a>.
   1.300        </p>
   1.301        <pre class="widl">
   1.302  [NoInterfaceObject]
   1.303 @@ -660,7 +670,6 @@
   1.304  "http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#interface-eventtarget"
   1.305       class="externalDFN">EventTarget</a>;
   1.306  </pre>
   1.307 -
   1.308        <section>
   1.309          <h2>
   1.310            Attributes
   1.311 @@ -693,8 +702,8 @@
   1.312            <p>
   1.313              The <dfn id="dom-networkservices-servicesavailable"><code>servicesAvailable</code></dfn> attribute MUST
   1.314              return the number of services in the <a>list of available service records</a> whose <code>type</code>
   1.315 -            attribute matches any of the <a>valid service type</a> tokens that were initially used to create the current
   1.316 -            <a href="#networkservices"><code>NetworkServices</code></a> object.
   1.317 +            attribute matches any of the <a>valid service type</a> tokens that were initially used to create the
   1.318 +            current <a href="#networkservices"><code>NetworkServices</code></a> object.
   1.319            </p>
   1.320          </div>
   1.321        </section>
   1.322 @@ -1747,8 +1756,8 @@
   1.323        <p>
   1.324          A user agent MUST garbage collect the <a><code>NetworkService</code></a> <a>indexed properties</a> of a
   1.325          <a><code>NetworkServices</code></a> object, passing each indexed property's <code>id</code> attribute as the
   1.326 -        only argument to the rule for <a>removing an available service<a>, when that <a><code>NetworkServices</code></a> object itself has been
   1.327 -        garbage-collected.
   1.328 +        only argument to the rule for <a>removing an available service</a>, when that
   1.329 +        <a><code>NetworkServices</code></a> object itself has been garbage-collected.
   1.330        </p>
   1.331      </section>
   1.332      <section>
   1.333 @@ -1857,7 +1866,7 @@
   1.334  
   1.335   function start() {
   1.336     if(navigator.getNetworkServices) {
   1.337 -      navigator.getNetworkServices('zeroconf:_xbmc-jsonrpc._tcp', gotXBMCService, error);
   1.338 +      navigator.getNetworkServices('zeroconf:_xbmc-jsonrpc._tcp'.then(gotXBMCService).catch(error);
   1.339        startBtn.disabled = true;
   1.340     } else {
   1.341        debug.innerHTML += "&lt;br&gt;Service Discovery not supported!";
   1.342 @@ -1964,7 +1973,7 @@
   1.343    modelEl.addEventListener('change', function() {
   1.344      if(navigator.getNetworkServices &amp;&amp;
   1.345           modelEl.value == "upnp:urn:schemas-upnp-org:service:RenderingControl:1") {
   1.346 -      navigator.getNetworkServices(modelEl.value, successCallback, errorCallback);
   1.347 +      var servicesPromise = navigator.getNetworkServices(modelEl.value).then(successCallback, errorCallback);
   1.348      } else if (modelEl.value == "zeroconf:_mediarenderer._http._tcp") {
   1.349        debug.innerHTML += "&lt;br&gt;Service type is not implemented by this application.";
   1.350      } else {