discovery-api/Overview.src.html
changeset 191 5e0da09685f7
parent 180 ee3a89da06e1
child 192 3ecf12df315d
--- a/discovery-api/Overview.src.html	Fri Aug 03 12:59:17 2012 +0200
+++ b/discovery-api/Overview.src.html	Wed Aug 22 15:45:40 2012 +0200
@@ -6,27 +6,32 @@
     <!-- This spec has been compiled with ReSpec v2 -->
     <script type="text/javascript" class='remove'>
       var respecConfig = {
-          specStatus: "unofficial",
-          shortName:  "discovery",
-          edDraftURI: "http://dev.w3.org/2009/dap/discovery/",
+          specStatus:   "ED",
+          //publishDate:  "2012-08-22",
+          shortName:    "discovery-api",
+          edDraftURI:   "http://w3c-test.org/dap/discovery-api/",
+          previousMaturity: "WD",
+          previousPublishDate: "2012-08-07",
           editors: [
-                {   name:       "Rich Tibbett",
-                    //url:        "http://richt.me/",
-                    company:    "Opera Software ASA",
-                    companyURL: "http://opera.com/" },
-                {   name:       "Clarke Stevens",
-                    //url:      "",
-                    company:    "CableLabs",
-                    companyURL: "http://cablelabs.com/"
-                }
+            {
+              name:       "Rich Tibbett",
+              //url:        "http://richt.me/",
+              company:    "Opera Software ASA",
+              companyURL: "http://opera.com/"
+            },
+            {
+              name:       "Clarke Stevens",
+              //url:      "",
+              company:    "CableLabs",
+              companyURL: "http://cablelabs.com/"
+            }
           ],
           //extraCSS:             ["./css/respec2.css"],
-          noIDLIn:  true,
-
+          noIDLIn:      true,
           wg:           "Device APIs and Policy Working Group",
           wgURI:        "http://www.w3.org/2009/dap/",
           wgPublicList: "public-device-apis",
-          wgPatentURI:  "http://www.w3.org/2004/01/pp-impl/43696/status",
+          wgPatentURI:  "http://www.w3.org/2004/01/pp-impl/43696/status"
       };
     </script>
 
@@ -659,9 +664,6 @@
           </p>
 
           <ol class="rule">
-            <li>
-               If <var>successCallback</var> is empty or is not an object of type <code>Function</code> then the <a>user agent</a> MUST abort these steps.
-            </li>
 
             <li>
               Let <var>requested control types</var> be initially set to an empty array.
@@ -761,7 +763,7 @@
                      Add the <var>service</var>'s <code>url</code> parameter to the <a>entry script origin's <acronym title="Uniform Resource Locator">URL</acronym> whitelist</a>.
                   </li>
                   <li>
-                    If <var>service</var> was originally created from a UPnP discovery process and the <var>service</var>'s <code>eventsUrl</code> parameter is not empty then <a>setup a UPnP Events Subscription</a> for <var>service</var>.
+                    If <var>service</var>'s <code>type</code> parameter begins with the DOMString &quot;<code>upnp:</code>&quot; and the <var>service</var>'s <code>eventsUrl</code> parameter is not empty then <a>setup a UPnP Events Subscription</a> for <var>service</var>.
                   </li>
                </ol>
             </li>
@@ -771,7 +773,7 @@
             </li>
 
             <li>
-               Set <var>services manager</var>'s <code>servicesAvailable</code> attribute to the length of <var>services</var>.
+               Set <var>services manager</var>'s <a href="#dom-networkservices-servicesavailable"><code>servicesAvailable</code></a> attribute to the length of <var>services</var>.
             </li>
 
             <li>
@@ -917,17 +919,22 @@
            <p>
               The <dfn id="dom-networkservices-servicesavailable"><code>servicesAvailable</code></dfn> attribute MUST return the number of services available in the
               user's network that match the <a>valid service type</a> that was initially used to create the current <a href="#networkservices"><code>NetworkServices</code></a> object.
-              By default, <a href="#dom-networkservices-servicesavailable"><code>servicesAvailable</code></a> MUST be set to <code>1</code>.
            </p>
 
            <p>
-             When a previously unknown instance of a networked service matching one or the requested <a href="#dfn-valid-service-type">valid service types</a> becomes available on the user's current network, the <a>user agent</a> MUST fire a new simple
-             event at the <a href="#dom-networkservices-onserviceavailable"><code>onserviceavailable</code></a> event handler.
+             When a previously unknown instance of a networked service matching one of the requested <a href="#dfn-valid-service-type">valid service types</a> becomes available on the user's current network, the <a>user agent</a> MUST increment the <a href="#dom-networkservices-servicesavailable"><code>servicesAvailable</code></a> attribute by <code>1</code> and then
+             <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a>
+             to dispatch a newly created event with the name <code>serviceavailable</code> that uses the <code>Event</code> interface, which does
+             not bubble, is not cancellable, and has no default action, at the current <a href="#networkservices"><code>NetworkServices</code></a>
+             object.
            </p>
 
            <p>
-             When a previously known instance of a networked service matching one or the requested <a href="#dfn-valid-service-type">valid service types</a> becomes unavailable on the user's current network, the <a>user agent</a> MUST fire a new simple
-             event at the <a href="#dom-networkservices-onserviceunavailable"><code>onserviceunavailable</code></a> event handler.
+             When a previously known instance of a networked service matching one of the requested <a href="#dfn-valid-service-type">valid service types</a> becomes unavailable on the user's current network, the <a>user agent</a> MUST decrement the <a href="#dom-networkservices-servicesavailable"><code>servicesAvailable</code></a> attribute by <code>1</code> and then
+             <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a>
+              to dispatch a newly created event with the name <code>serviceunavailable</code> that uses the <code>Event</code> interface, which does
+              not bubble, is not cancellable, and has no default action, at the current <a href="#networkservices"><code>NetworkServices</code></a>
+              object.
            </p>
         </div>
 
@@ -970,7 +977,7 @@
       </dl>
 
       <p>
-        A <a href="#networkservices"><code>NetworkServices</code></a> object represents the current list of zero or more <a>current authorized services</a>, of which zero or more can be available at a time. Each item in <a>current authorized services</a> is represented by a <a href="#networkservice"><code>NetworkService</code></a> object.
+        A <a href="#networkservices"><code>NetworkServices</code></a> object represents the current list of zero or more <a>current authorized services</a>, of which zero or more can be available at a time. Each item in <a>current authorized services</a> is represented by a <a href="#networkservice"><code>NetworkService</code></a> object. The list of <a>current authorized services</a> is <span>immutable</span> meaning that it cannot be modified for the lifetime of a <a href="#networkservices"><code>NetworkServices</code></a> object.
       </p>
 
       <p class="note">
@@ -1063,13 +1070,13 @@
   readonly attribute DOMString        <a href="#dom-networkservice-url">url</a>;
   readonly attribute DOMString        <a href="#dom-networkservice-config">config</a>;
 
-  const unsigned short <a href="#dom-networkservice-AVAILABLE">AVAILABLE</a>      = 1;
-  const unsigned short <a href="#dom-networkservice-UNAVAILABLE">UNAVAILABLE</a>    = 2;
-  readonly attribute unsigned short   <a href="#dom-networkservice-readystate">readyState</a>;
+  readonly attribute boolean          <a href="#dom-networkservice-online">online</a>;
 
   // event handler attributes
-           attribute <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler" class="externalDFN">EventHandler</a>     <a href="#dom-networkservice-onreadystatechange">onreadystatechange</a>;
-           attribute <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler" class="externalDFN">EventHandler</a>     <a href="#dom-networkservice-onmessage">onmessage</a>;
+           attribute <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler" class="externalDFN">EventHandler</a>     <a href="#dom-networkservice-onserviceonline">onserviceonline</a>;
+           attribute <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler" class="externalDFN">EventHandler</a>     <a href="#dom-networkservice-onserviceoffline">onserviceoffline</a>;
+
+           attribute <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler" class="externalDFN">EventHandler</a>     <a href="#dom-networkservice-onnotify">onnotify</a>;
 };
 
 <a href="#networkservice">NetworkService</a> implements <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#interface-eventtarget" class="externalDFN">EventTarget</a>;
@@ -1171,47 +1178,21 @@
         <dt>
           <var title="">service</var>
            .
-          <code title="dom-networkservice-readystate">
-            <a href="#dom-networkservice-readystate">readyState</a>
+          <code title="dom-networkservice-online">
+            <a href="#dom-networkservice-online">online</a>
           </code>
         </dt>
         <dd>
           <p>
-            Returns the current state.
+            Returns <code>true</code> if the service is reporting that it is accessible on the local network or <code>false</code> if the service is reporting that it is no longer accessible (temporarily or permanently) on the local network.
           </p>
         </dd>
       </dl>
 
-         A <a href="#networkservice"><code>NetworkService</code></a> object can be in several states. The <dfn id="dom-networkservice-readystate"><code>readyState</code></dfn> attribute MUST return the current state of the networked service,
-         which MUST be one of the following values:
-
-         <dl>
-           <dt>
-             <dfn id="dom-networkservice-AVAILABLE" title="dom-networkservice-AVAILABLE">
-               <code>AVAILABLE</code>
-             </dfn>
-              (numeric value
-             1)
-
-
-           </dt>
-           <dd>
-             <p>The object is connected to its service endpoint.
-
-            </p>
-           </dd>
-           <dt>
-             <dfn id="dom-networkservice-UNAVAILABLE" title="dom-networkservice-UNAVAILABLE">
-               <code>UNAVAILABLE</code>
-             </dfn>
-              (numeric value
-             2)
-           </dt>
-           <dd>
-             <p>The object is not connected to its service endpoint.
-            </p>
-           </dd>
-         </dl>
+      <p>
+        The <dfn id="dom-networkservice-config"><code>online</code></dfn> attribute indicates whether the service is reporting itself as being
+        either <var>online</var>, and therefore accessible on the local network, in which case this attribute will return <code>true</code> or, <var>offline</var>, and therefore not accessible on the local network, either temporarily or permanently, in which case this attribute will return <code>false</code>. This attribute MUST default to <code>true</code>.
+      </p>
 
       </section>
 
@@ -1237,33 +1218,39 @@
         <tbody>
           <tr>
             <td>
-              <dfn id="dom-networkservice-onmessage" title="dom-NetworkService-onmessage">
-                <code>onmessage</code>
+              <dfn id="dom-networkservice-onnotify" title="dom-NetworkService-onnotify">
+                <code>onnotify</code>
               </dfn>
             </td>
             <td>
-              <code title="event-message">message</code>
+              <code title="event-notify">notify</code>
             </td>
           </tr>
           <tr>
             <td>
-              <dfn id="dom-networkservice-onreadystatechange" title="dom-NetworkService-onreadystatechange">
-                <code>onreadystatechange</code>
+              <dfn id="dom-networkservice-onserviceonline" title="dom-NetworkService-onserviceonline">
+                <code>onserviceonline</code>
               </dfn>
             </td>
             <td>
-              <code title="event-onreadystatechange">readystatechange</code>
+              <code title="event-onserviceonline">serviceonline</code>
+            </td>
+          </tr>
+          <tr>
+            <td>
+              <dfn id="dom-networkservice-offserviceoffline" title="dom-NetworkService-onserviceoffline">
+                <code>onserviceoffline</code>
+              </dfn>
+            </td>
+            <td>
+              <code title="event-onserviceoffline">serviceoffline</code>
             </td>
           </tr>
         </tbody>
       </table>
 
       <p>
-         Events with an event type of <code>message</code> defined in this specification are <a href="http://dev.w3.org/html5/postmsg/#messageevent" class="externalDFN"><code>MessageEvent</code></a> objects as defined in [[!WEBMESSAGING]].
-      </p>
-
-      <p>
-         Events with an event type of <code>readystatechange</code> defined in this specification are simple <code>Event</code> objects.
+         Events with an event type of <code>notify</code>, <code>serviceonline</code> or <code>serviceoffline</code> defined in this specification are simple <code>Event</code> objects.
       </p>
 
       </section>
@@ -1273,7 +1260,7 @@
             <h2>Service Discovery</h2>
 
       <p>
-         A <a>user agent</a> conforming to this specification MAY implement <acronym title="Simple Service Discovery Protocol">SSDP</acronym> [[!UPNP]] and Zeroconf [[!ZEROCONF]] service discovery mechanisms
+         A <a>user agent</a> conforming to this specification MAY implement <acronym title="Simple Service Discovery Protocol">SSDP</acronym> [[!UPNP]] and Zeroconf [[!DNS-SD]] + [[!MDNS]] service discovery mechanisms
          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 service discovery mechanisms, then it MUST conform to the corresponding algorithms provided in this section of the specification.
       </p>
       <p>
@@ -1358,7 +1345,17 @@
                            <a href="#networkservice"><code>NetworkService</code></a> object.
                         </li>
                         <li>
-                           Increment the <code>servicesAvailable</code> attribute of the <a href="#networkservices"><code>NetworkServices</code></a> object by <code>1</code>.
+                           Increment the <a href="#dom-networkservices-servicesavailable"><code>servicesAvailable</code></a> attribute of the <a href="#networkservices"><code>NetworkServices</code></a> object by <code>1</code>.
+                        </li>
+                        <li>
+                          <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">Queue a task</a>
+                           to dispatch a newly created event with the name <code>serviceavailable</code> that uses the <code>Event</code> interface, which does not bubble, is not cancellable, and has no default action, at the current
+                            <a href="#networkservices"><code>NetworkServices</code></a> object.
+                        </li>
+                        <li>
+                          <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">Queue a task</a>
+                           to dispatch a newly created event with the name <code>serviceonline</code> that uses the <code>Event</code> interface, which does not bubble, is not cancellable, and has no default action, at the current
+                           <a href="#networkservice"><code>NetworkService</code></a> object.
                         </li>
                      </ol>
                   </li>
@@ -1468,9 +1465,13 @@
                      <a href="#networkservice"><code>NetworkService</code></a> object.
                   </li>
                   <li>
-                     If the <var>announcement type</var> equals <code>ssdp:alive</code> then Increment the <code>servicesAvailable</code> attribute of the <a href="#networkservices"><code>NetworkServices</code></a>
-                     object by <code>1</code>. Otherwise, decrement the <code>servicesAvailable</code> attribute of the <a href="#networkservices"><code>NetworkServices</code></a>
-                     object by <code>1</code>.
+                     If the <var>announcement type</var> equals <code>ssdp:alive</code> then Increment the <a href="#dom-networkservices-servicesavailable"><code>servicesAvailable</code></a> attribute of the <a href="#networkservices"><code>NetworkServices</code></a>
+                     object by <code>1</code> and then <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a>
+                      to dispatch a newly created event with the name <code>serviceonline</code> that uses the <code>Event</code> interface, which does not bubble, is not cancellable, and has no default action, at the current
+                      <a href="#networkservice"><code>NetworkService</code></a> object. Otherwise, decrement the <a href="#dom-networkservices-servicesavailable"><code>servicesAvailable</code></a> attribute of the <a href="#networkservices"><code>NetworkServices</code></a>
+                     object by <code>1</code> and then  <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a>
+                       to dispatch a newly created event with the name <code>serviceoffline</code> that uses the <code>Event</code> interface, which does not bubble, is not cancellable, and has no default action, at the current
+                       <a href="#networkservice"><code>NetworkService</code></a> object..
                   </li>
                </ol>
             </li>
@@ -1492,7 +1493,7 @@
             </li>
 
             <li>
-               Send a HTTP SUBSCRIBE request with a <em>NT</em> header with a string value of <code>upnp:event</code>, a <em>TIMEOUT</em> header with an integer value of
+               Send a HTTP SUBSCRIBE request with a <em>NT</em> header with a string value of <code>upnp:event</code>, a <em>TIMEOUT</em> header with an integer value ofÆ’
                <code>86400</code> and a <em>CALLBACK</em> header
                with a string value of <var>callback URL</var> towards the <var>network service record</var>'s <code>eventsUrl</code> property.
             </li>
@@ -1544,15 +1545,15 @@
                            Let <var>content clone</var> be the result of obtaining the message body of the HTTP NOTIFY request. If <var>content clone</var> is empty, then the <a>user agent</a> MUST abort these steps.
                         </li>
                         <li>
-                          Create a new <code>message</code> event that uses the <a href="http://dev.w3.org/html5/postmsg/#messageevent" class="externalDFN"><code>MessageEvent</code></a> interface [[!WEBMESSAGING]], with the name <code>message</code>,
-                           which does not bubble, is not cancelable, and has no default action.
+                          Let <var>notification event</var> be a new simple event that uses the <code>Event</code> interface with the name <code>notify</code>,
+                           which does not bubble, is not cancellable, and has no default action.
                         </li>
                         <li>
-                           Let the <code>data</code> attribute of the event have the DOMString value of <var>content clone</var>.
+                           Let the <code>data</code> attribute of <var>notification event</var> have the DOMString value of <var>content clone</var>.
                         </li>
                         <li>
                            <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">Queue a task</a> to
-                            dispatch the newly created event at the current <a><code>NetworkService</code></a> object.
+                            dispatch <var>notification event</var> at the current <a><code>NetworkService</code></a> object.
                         </li>
                      </ol>
                   </li>
@@ -1581,17 +1582,30 @@
 
                            <ol class="rule">
                               <li>
-                                 Set the <a href="#dom-networkservice-readystate"><code>readyState</code></a> attribute to <code>2</code> (<a href="#dom-networkservice-UNAVAILABLE"><code>UNAVAILABLE</code></a>).
+                                 Set the <a href="#dom-networkservice-online"><code>online</code></a> attribute to <code>false</code>.
                               </li>
                               <li>
-                                 Create a new <code>readystatechange</code> event that uses the <code>Event</code> interface which does not bubble, is not cancelable, and has no default action.
-                              </li>
-                              <li>
-                                 <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">Queue a task</a> to
-                                        dispatch the newly created event at the <a href="#networkservice"><code>NetworkService</code></a> object.
-                              </li>
+                                 <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">Queue a task</a>
+                                                      to dispatch a newly created event with the name <code>serviceoffline</code> that uses the <code>Event</code> interface, which does not bubble, is not cancellable, and has no default action, at the current
+                                                      <a href="#networkservice"><code>NetworkService</code></a> object.
                            </ol>
                         </li>
+                        <li>
+                          For each <a href="#networkservices"><code>NetworkServices</code></a> object currently active in the <a>user agent</a> perform the following steps:
+
+                          <ol class="rule">
+                            <li>
+                              Let <var>number of available services</var> equal the value of <a href="#networkservices"><code>NetworkServices</code></a>'s <a href="#dom-networkservices-servicesavailable"><code>servicesAvailable</code></a> attribute.
+                            </li>
+                            <li>
+                              Set the <a href="#networkservices"><code>NetworkServices</code></a>'s <a href="#dom-networkservices-servicesavailable"><code>servicesAvailable</code></a> attribute to zero (<code>0</code>).
+                            </li>
+                            <li>
+                              For each <var>available service</var> in <var>number of available services</var> the <a>user agent</a> MUST fire a new simple event with the name <code>serviceunavailable</code> that has no default action, does not bubble and is not cancellable, at the current <a href="#networkservices"><code>NetworkServices</code></a> object.
+                            </li>
+                          </ol>
+                        </li>
+
                      </ol>
 
                      <p>
@@ -1600,7 +1614,7 @@
 
                      <ol class="rule">
                         <li>
-                           Re-issue an mDNS search and SSDP discovery search and handle the responses according to the processing defined in <a href="#service-discovery">Section 6: Service Discovery</a>.
+                           Re-issue an mDNS search and SSDP discovery search using all of the <a>valid service type</a> tokens initially provided to all active <a href="#networkservices"><code>NetworkServices</code></a> objects and handle all discovery responses according to the processing defined in <a href="#service-discovery">Section 7: Service Discovery</a>.
                         </li>
                      </ol>
                   </div>
@@ -1712,7 +1726,7 @@
       navigator.getNetworkServices('zeroconf:_xbmc-jsonrpc._tcp', gotXBMCService, error);
       startBtn.disabled = true;
    } else {
-      debug.innerHTML += "&lt;br&gt;Service Discovery API not supported!";
+      debug.innerHTML += "&lt;br&gt;Service Discovery not supported!";
    }
  }
 
@@ -1720,11 +1734,9 @@
 
 // Listen for service disconnect messages
 
-   services[0].addEventListener('readystatechange', function ( e ) {
-     if(services[0].readyState === services[0].UNAVAILABLE) {
+   services[0].addEventListener('serviceoffline', function ( e ) {
        debug.innerHTML += "&lt;br>" + services[0].name + " disconnected.";
        startBtn.disabled = false;
-     }
    }, false);
 
 // Send a service message to get albums list (and process the service response)
@@ -1825,9 +1837,9 @@
 &lt;script&gt;
   function successCallback( services ) {
 
-  // Listen for service push messages
+  // Listen for service push notification messages
 
-    services[0].addEventListener('message', function ( msg ) {
+    services[0].addEventListener('notify', function ( msg ) {
          debug.innerHTML += "&lt;br>" + services[0].name + " event received: ";
          debug.textContent += msg.data;
     }, false);
@@ -1881,7 +1893,7 @@
 
       <p>Thanks are expressed by the editor to the following individuals for their feedback on this specification to date (in alphabetical order):
       <br /><br />
-      Gar Bergstedt, Lars-Erik Bolstad, Hari G Kumar, Bob Lund, Giuseppe Pascale, Marcin Simonides, Clarke Stevens, Christian S&ouml;derstr&ouml;m, Mark Vickers, ...</p>
+      Gar Bergstedt, Lars-Erik Bolstad, Cathy Chan, Hari G Kumar, Bob Lund, Giuseppe Pascale, Marcin Simonides, Clarke Stevens, Christian S&ouml;derstr&ouml;m, Mark Vickers, ...</p>
 
       <p>Thanks are also expressed by the editor to the following organizations and groups for their support in producing this specification to date (in alphabetical order):
       <br /></br />