discovery-api/Overview.src.html
changeset 437 d25229263a68
parent 402 a3626e492d27
child 438 d66ca00fe7d9
--- a/discovery-api/Overview.src.html	Tue Jul 16 18:23:28 2013 -0400
+++ b/discovery-api/Overview.src.html	Tue Jul 23 18:33:30 2013 +1000
@@ -46,12 +46,6 @@
               //url:        "http://richt.me/",
               company:    "Opera Software ASA",
               companyURL: "http://opera.com/"
-            },
-            {
-              name:       "Clarke Stevens",
-              //url:      "",
-              company:    "CableLabs",
-              companyURL: "http://cablelabs.com/"
             }
           ],
 
@@ -60,8 +54,8 @@
           wgPublicList: "public-device-apis",
           wgPatentURI:  "http://www.w3.org/2004/01/pp-impl/43696/status",
 
-//          extraCSS:     ["http://dvcs.w3.org/hg/dap/raw-file/tip/discovery-api/css/respec.nsd.css"],
-//          inlineCSS:    true,
+    //          extraCSS:     ["http://dvcs.w3.org/hg/dap/raw-file/tip/discovery-api/css/respec.nsd.css"],
+    //          inlineCSS:    true,
           noIDLIn:      true
 
       };
@@ -69,9 +63,10 @@
     <script src='http://www.w3.org/Tools/respec/respec-w3c-common'
           type="text/javascript"
           class='remove'
-          async=""></script>
+          async="">
+</script>
     <style>
-     /* Custom ReSpec CSS (by Rich Tibbett) */
+/* Custom ReSpec CSS (by Rich Tibbett) */
 
      /* Add better spacing to sections */
      section, .section { margin-bottom: 2em; }
@@ -101,7 +96,17 @@
      table thead { border-bottom:solid }
      table tbody th:first-child { border-left:solid }
      table td, table th { border-left:solid; border-right:solid; border-bottom:solid thin; vertical-align:top; padding:0.2em }
-     </style>
+    </style>
+    <script type="text/javascript"
+          class="remove">
+// RESPEC DEFINITIONS STYLE OVERLOAD
+        window.addEventListener('load', function() {
+          var overrideStyleEl = document.createElement('style');
+          overrideStyleEl.textContent += "\n  a.externalDFN { color: #00C; border-bottom: 1px dashed #00C; }";
+          overrideStyleEl.textContent += "\n  a.internalDFN { color: #00C; text-decoration: solid; }";
+          document.querySelector('body').appendChild(overrideStyleEl);
+        }, false);
+    </script>
   </head>
   <body>
     <section id='abstract'>
@@ -141,9 +146,10 @@
         service according to the processing described herein.
       </p>
       <p>
-        If a service connectivity request is successful then the Web page is provided with the necessary information to
-        communicate with the authorized Local-networked Service. If the request fails then the Web page will receive an
-        error callback containing an error code describing the cause of Local-networked Service connectivity failure.
+        If a service connectivity request is successful then the Web page is provided with a promise-based success
+        callback with the all necessary information to communicate with the authorized Local-networked Service. If the
+        request fails then the Web page will receive a promise-based error callback containing an error code describing
+        the cause of Local-networked Service connectivity failure.
       </p>
       <p>
         Once connected to a Local-networked Service the Web page can send requests and receive responses to the
@@ -153,7 +159,11 @@
         by the connected Local-networked Service.
       </p>
       <p>
-        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=
+        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=
         "#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a> method defined herein).
       </p>
       <div class="example">
@@ -167,7 +177,7 @@
   for(var i = 0, l = services.length; i &lt; l; i++) console.log( services[i].name );
 }
 
-navigator.getNetworkServices('zeroconf:_boxee-jsonrpc._tcp', showServices);
+navigator.getNetworkServices('zeroconf:_boxee-jsonrpc._tcp').then(showServices);
 </pre>
       </div>
       <div class="example">
@@ -185,7 +195,7 @@
   console.log( "Error occurred: " + e.code );
 }
 
-navigator.getNetworkServices('upnp:urn:schemas-upnp-org:service:ContentDirectory:1', showServices, error);
+navigator.getNetworkServices('upnp:urn:schemas-upnp-org:service:ContentDirectory:1').then(showServices, error);
 </pre>
       </div>
       <div class="example">
@@ -203,7 +213,7 @@
 navigator.getNetworkServices([
   'zeroconf:_boxee-jsonrpc._tcp',
   'upnp:urn:schemas-upnp-org:service:ContentDirectory:1'
-], showServices);
+]).then(showServices);
 </pre>
       </div>
       <p>
@@ -324,34 +334,21 @@
       <pre class="widl">
 [Supplemental, NoInterfaceObject]
 interface <dfn id="navigatornetworkservice">NavigatorNetworkService</dfn> {
-  // Obtain a Local-networked Service
-  void <a href="#dom-navigator-getnetworkservices">getNetworkServices</a>( in any type,
-                           in <a href=
-"#navigatornetworkservicesuccesscallback">NavigatorNetworkServiceSuccessCallback</a> successCallback,
-                           in optional <a href=
-"#navigatornetworkserviceerrorcallback">NavigatorNetworkServiceErrorCallback</a> errorCallback );
+  <a class="externalDFN"
+     href="http://dom.spec.whatwg.org/#promise">Promise</a> <a href=
+     "#dom-navigator-getnetworkservices">getNetworkServices</a>( in any type );
 };
 <a class="externalDFN"
      href=
      "http://www.whatwg.org/specs/web-apps/current-work/complete/timers.html#navigator">Navigator</a> implements <a href=
      "#navigatornetworkservice">NavigatorNetworkService</a>;
 
-[Callback=FunctionOnly, NoInterfaceObject]
-interface <dfn id="navigatornetworkservicesuccesscallback">NavigatorNetworkServiceSuccessCallback</dfn> {
-  void handleEvent( in <a href="#networkservices">NetworkServices</a> services );
-};
-
 [NoInterfaceObject]
 interface <dfn id="navigatornetworkserviceerror">NavigatorNetworkServiceError</dfn> {
   const unsigned short <a href="#dom-navigatornetworkserviceerror-permission_denied">PERMISSION_DENIED_ERR</a> = 1;
   const unsigned short <a href="#dom-navigatornetworkserviceerror-unknown_type_prefix">UNKNOWN_TYPE_PREFIX_ERR</a> = 2;
   readonly attribute unsigned short <a href="#dom-navigatornetworkserviceerror-code">code</a>;
 };
-
-[Callback=FunctionOnly, NoInterfaceObject]
-interface <dfn id="navigatornetworkserviceerrorcallback">NavigatorNetworkServiceErrorCallback</dfn> {
-  void handleEvent( in <a href="#navigatornetworkserviceerror">NavigatorNetworkServiceError</a> error );
-};
 </pre>
       <section>
         <h2>
@@ -359,37 +356,49 @@
         </h2>
         <dl class="domintro">
           <dt>
-            <var title="">window</var> . <code title="dom-navigator"><a href=
+            <var title="">promise</var> = <var title="">window</var> . <code title="dom-navigator"><a href=
             "http://www.whatwg.org/specs/web-apps/current-work/complete/timers.html#navigator">navigator</a></code> .
             <code title="dom-navigator-getNetworkServices"><a href=
-            "#dom-navigator-getnetworkservices">getNetworkServices</a></code> ( <var title="">type</var> , <var title=
-            "">successCallback</var> [, <var title="">errorCallback</var> ] )
+            "#dom-navigator-getnetworkservices">getNetworkServices</a></code> ( <var title="">type</var> )
           </dt>
           <dd>
             <p>
-              Prompts the user to select discovered network services that have advertised support for the requested
-              service type.
+              Immediately returns a new <a href="http://dom.spec.whatwg.org/#promise"
+                 class="externalDFN">Promise</a> object and then the user is prompted to select discovered network
+                 services that have advertised support for the requested service type(s).
             </p>
             <p>
               The <var title="">type</var> argument contains one or more <a>valid service type</a> tokens that the web
               page would like to interact with.
             </p>
             <p>
-              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.
+              If the user accepts, the <var title="">promise</var> object is <a class="externalDFN"
+                 href="http://dom.spec.whatwg.org/#concept-resolver-resolve">resolved</a>, with a <a href=
+                 "#networkservices"><code>NetworkServices</code></a> object as its argument.
             </p>
             <p>
-              If the user declines, the <var title="">errorCallback</var> (if any) is invoked.
+              If the user declines, or an error occurs, the <var title="">promise</var> object is <a class=
+              "externalDFN"
+                 href="http://dom.spec.whatwg.org/#concept-resolver-reject">rejected</a>.
             </p>
           </dd>
         </dl>
         <div>
           <p>
             When the <dfn id="dom-navigator-getnetworkservices"
-               title="dom-navigator-getnetworkservices"><code>getNetworkServices(type, successCallback[,
-               errorCallback])</code></dfn> method is called, the <a>user agent</a> MUST run the following steps:
+               title="dom-navigator-getnetworkservices"><code>getNetworkServices(type)</code></dfn> method is called,
+               the <a>user agent</a> MUST run the following steps:
           </p>
           <ol class="rule">
+            <li>Let <var>Network Service Promise</var> be a new <a href="http://dom.spec.whatwg.org/#promise"
+                  class="externalDFN"><code>Promise</code></a> object.
+            </li>
+            <li>Let <var>Network Service Promise's Resolver</var> be the default <a href=
+            "http://dom.spec.whatwg.org/#concept-resolver"
+                  class="externalDFN">resolver</a> of <var>Network Service Promise</var>.
+            </li>
+            <li>Return <var>Network Service Promise</var>, and run the remaining steps asynchronously.
+            </li>
             <li>Let <var>requested control types</var> be initially set to an empty array.
             </li>
             <li>If <var>type</var> is an array consisting of one or more <a>valid service type</a> tokens, then let
@@ -401,10 +410,10 @@
             </li>
             <li>If <var>requested control types</var> is an array that contains at least one or more <a title=
             "valid service type">valid service type</a> tokens then continue to the step labeled <em>process</em>
-            below. Otherwise, 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=
+            below. Otherwise, reject <var>Network Service Promise</var> by running the <a href=
+            "http://dom.spec.whatwg.org/#concept-resolver-reject"
+                  class="externalDFN">resolver reject algorithm</a> against the <var>Network Service Promise's
+                  Resolver</var>, passing in 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 2
                   (<a href=
@@ -437,13 +446,11 @@
                 </li>
               </ol>
             </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
-            platform limitations, the <a>user agent</a> MAY <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=
+            platform limitations, the <a>user agent</a> MAY reject <var>Network Service Promise</var> by running the
+            <a href="http://dom.spec.whatwg.org/#concept-resolver-reject"
+                  class="externalDFN">resolver reject algorithm</a> against the <var>Network Service Promise's
+                  Resolver</var>, passing in 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=
@@ -462,11 +469,11 @@
                    object representing the <a>user-authorized</a> subset of <var>services found</var>.
               </p>
               <p>
-                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 previously, 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.
+                Alternatively, the user agent MAY wish to skip this user opt-in step and choose to fulfill <var>Network
+                Service Promise</var> immediately based on a previously-established user preference, for security
+                reasons, or due to platform limitations. In such an implementation, if <var>Network Service
+                Promise</var> is to be fulfilled 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
@@ -474,9 +481,10 @@
               </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=
+                MUST reject <var>Network Service Promise</var> by running the <a href=
+                "http://dom.spec.whatwg.org/#concept-resolver-reject"
+                   class="externalDFN">resolver reject algorithm</a> against the <var>Network Service Promise's
+                   Resolver</var>, passing in 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=
@@ -530,10 +538,10 @@
             </li>
             <li>Add <var>services manager</var> to the <a>list of active service managers</a>.
             </li>
-            <li>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>successCallback</var> with <var>services
-                  manager</var> as its argument.
+            <li>The <a>user agent</a> MUST fulfill <var>Network Service Promise</var> by running the <a href=
+            "http://dom.spec.whatwg.org/#concept-resolver-fulfill"
+                  class="externalDFN">resolver fulfill algorithm</a> against the <var>Network Service Promise's
+                  Resolver</var>, passing in <var>services manager</var> as its argument.
             </li>
           </ol>
           <p>
@@ -634,8 +642,10 @@
         "#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>.
+        A <a href="#networkservices"><code>NetworkServices</code></a> object is the <a href=
+        "http://dom.spec.whatwg.org/#concept-promise-result"
+           class="externalDFN">promise result</a> from a call to <a href=
+           "#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a>.
       </p>
       <pre class="widl">
 [NoInterfaceObject]
@@ -660,7 +670,6 @@
 "http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#interface-eventtarget"
      class="externalDFN">EventTarget</a>;
 </pre>
-
       <section>
         <h2>
           Attributes
@@ -693,8 +702,8 @@
           <p>
             The <dfn id="dom-networkservices-servicesavailable"><code>servicesAvailable</code></dfn> attribute MUST
             return the number of services in the <a>list of available service records</a> whose <code>type</code>
-            attribute matches any of the <a>valid service type</a> tokens that were initially used to create the current
-            <a href="#networkservices"><code>NetworkServices</code></a> object.
+            attribute matches any of the <a>valid service type</a> tokens that were initially used to create the
+            current <a href="#networkservices"><code>NetworkServices</code></a> object.
           </p>
         </div>
       </section>
@@ -1747,8 +1756,8 @@
       <p>
         A user agent MUST garbage collect the <a><code>NetworkService</code></a> <a>indexed properties</a> of a
         <a><code>NetworkServices</code></a> object, passing each indexed property's <code>id</code> attribute as the
-        only argument to the rule for <a>removing an available service<a>, when that <a><code>NetworkServices</code></a> object itself has been
-        garbage-collected.
+        only argument to the rule for <a>removing an available service</a>, when that
+        <a><code>NetworkServices</code></a> object itself has been garbage-collected.
       </p>
     </section>
     <section>
@@ -1857,7 +1866,7 @@
 
  function start() {
    if(navigator.getNetworkServices) {
-      navigator.getNetworkServices('zeroconf:_xbmc-jsonrpc._tcp', gotXBMCService, error);
+      navigator.getNetworkServices('zeroconf:_xbmc-jsonrpc._tcp'.then(gotXBMCService).catch(error);
       startBtn.disabled = true;
    } else {
       debug.innerHTML += "&lt;br&gt;Service Discovery not supported!";
@@ -1964,7 +1973,7 @@
   modelEl.addEventListener('change', function() {
     if(navigator.getNetworkServices &amp;&amp;
          modelEl.value == "upnp:urn:schemas-upnp-org:service:RenderingControl:1") {
-      navigator.getNetworkServices(modelEl.value, successCallback, errorCallback);
+      var servicesPromise = navigator.getNetworkServices(modelEl.value).then(successCallback, errorCallback);
     } else if (modelEl.value == "zeroconf:_mediarenderer._http._tcp") {
       debug.innerHTML += "&lt;br&gt;Service type is not implemented by this application.";
     } else {