Wen Intents Addendum for local Services: Editorial corrections
authorClaes Nilsson <claes1.nilsson@sonymobile.com>
Wed, 15 Aug 2012 16:39:07 +0200
changeset 188 53625f47e1f1
parent 187 5a7c58d2a996
child 189 3fc30ca6364c
Wen Intents Addendum for local Services: Editorial corrections
wi-addendum-local-services/Overview.html
--- a/wi-addendum-local-services/Overview.html	Wed Aug 15 13:28:24 2012 +0900
+++ b/wi-addendum-local-services/Overview.html	Wed Aug 15 16:39:07 2012 +0200
@@ -48,6 +48,8 @@
           editors:  [
               { name: "Claes Nilsson",
                 company: "Sony Mobile", companyURL: "http://www.sonymobile.com/se/" },
+              { name: "Norifumi Kikkawa",
+                company: "Sony Corporation", companyURL: "tbd"},  
           ],
 
           // authors, add as many as you like. 
@@ -149,15 +151,11 @@
           stated in this specification. </li>
           <li><dfn>Web Intents enabled UPnP device</dfn>: A <a>Web Intents enabled UPnP device</a> MUST support [[!UPNP-DEVICEARCH]] and the conformance criteria 
           stated in this specification. </li>
-          <li><dfn>mDNS enabled User Agent</dfn>: A <a>mDNS enabled User Agent</a> MUST support Web Intents [[!WEBINTENTS]] and the conformance criteria 
+          <li><dfn>mDNS enabled User Agent</dfn>: An <a>mDNS enabled User Agent</a> MUST support Web Intents [[!WEBINTENTS]] and the conformance criteria 
           stated in this specification. </li>
-          <li><dfn>Web Intents enabled mDNS device</dfn>: A <a>Web Intents enabled mDNS device</a> MUST support [[!DNS-SD]], [[!MDNS]] the conformance criteria 
+          <li><dfn>Web Intents enabled mDNS device</dfn>: A <a>Web Intents enabled mDNS device</a> MUST support [[!DNS-SD]], [[!MDNS]] and the conformance criteria 
           stated in this specification. </li>
         </ul>
-        
-        <p>
-          TBD definitions of User Agents and devices for other local discovery and communication technologies...
-        </p>
       </p>
       <p>
         Implementations that use ECMAScript to implement the APIs defined in
@@ -209,10 +207,10 @@
       <section> 
         <h3>mDNS related terms</h3>
         <p>
-          The <a>mDNS enabled User Agent</a> has the role of a <dfn id="dfn-registration">DNS client</dfn> with capability of DNS-SD. 
+          The <a>mDNS enabled User Agent</a> has the role of a <dfn id="dfn-registration">DNS client</dfn> with capability of [[!DNS-SD]]. 
         </p>
         <p>
-          The <a>Web Intents enabled mDNS device</a> discovered by the <a>mDNS enabled User Agent</a> has the roles of <dfn id="dfn-registration">service</dfn> according to mDNS and DNS-SD. 
+          The <a>Web Intents enabled mDNS device</a> discovered by the <a>mDNS enabled User Agent</a> has the roles of <dfn id="dfn-registration">service</dfn> according to [[!MDNS]] and [[!DNS-SD]]. 
         </p>        
       </section>     
       
@@ -282,7 +280,7 @@
               comma. Commas included in action strings <em class="rfc2119" title="must">must</em> be percent-encoded as 
               defined in [[!RFC3986]], section-2.1.
               <br />  <br />
-              This header allows the <a>UPnP enabled User Agent</a> to filter received SSDP messages so that the <a>UPnP enabled User Agent</a>s only have to 
+              This header allows the <a>UPnP enabled User Agent</a> to filter received SSDP messages so that the <a>UPnP enabled User Agent</a> only has to 
               retrieve Web Intents documents for matching Web Intents Actions.        
             </li>
           </ul>         
@@ -493,11 +491,11 @@
           <h4>Web Intents service type for DNS-SD</h4>     
           
           <p>
-            The <a>Web Intents enabled mDNS device</a> <em class="rfc2119" title="must">must</em> support DNS-SD with a SRV record of the <code>webintents</code> service type. 
+            The <a>Web Intents enabled mDNS device</a> <em class="rfc2119" title="must">must</em> support [[!DNS-SD]] with a SRV record of the <code>webintents</code> service type. 
           </p>  
           
             <p class="note">
-              A service type <code>webintents</code> should be registered in IANA (http://www.iana.org/form/ports-services).
+              A service type <code>webintents</code> should be registered in [[!IANA-SRVPORT-REG]].
             </p>
 
           <p>          
@@ -506,7 +504,7 @@
           <ul>
             <li>
               <code>location</code>: <em class="rfc2119" title="required">required</em>. States the location to the Web Intents document in the <a class="internalDFN" href="#dfn-web-intents-enabled-mdns-device">Web Intents enabled mDNS device</a>. 
-              The value of this header is path to be concatinated with a host of the <a class="internalDFN" href="#dfn-web-intents-enabled-mdns-device">Web Intents enabled mDNS device</a> to determine the location. The definition of the Web Intents document is same as that for UPnP.
+              The value of this header is path to be concatenated with a host of the <a class="internalDFN" href="#dfn-web-intents-enabled-mdns-device">Web Intents enabled mDNS device</a> to determine the location. The definition of the Web Intents document is the same as for UPnP.
             </li>
             <li>
               <code>action</code>: <em class="rfc2119" title="optional">optional</em>. If supported, states the Web Intents 
@@ -514,9 +512,9 @@
               match the <code>action</code> attributes of the Service registration markup in the Web Intents document. To support more than 
               one Web Intents <code>action</code> the action strings <em class="rfc2119" title="must">must</em> be separated with 
               comma. Commas included in action strings <em class="rfc2119" title="must">must</em> be percent-encoded as 
-              defined in RFC3986, section-2.1.
+              defined in [[!RFC3986]], section-2.1.
               <br>  <br>
-              This allows the <a>mDNS enabled User Agent</a> to filter received mDNS messages so that the <a>mDNS enabled User Agent</a>s only have to 
+              This allows the <a>mDNS enabled User Agent</a> to filter received mDNS messages so that the <a>mDNS enabled User Agent</a> only has to 
               retrieve Web Intents documents for matching Web Intents Actions.        
             </li>
           </ul>         
@@ -531,92 +529,96 @@
           The <a>mDNS enabled User Agent</a> <em class="rfc2119" title="must">must</em> support discovery of <a>Web Intents enabled mDNS device<a>s through mDNS and DNS-SD 
           according to [[!MDNS]], [[!DNS-SD]] and according to the Web Intents specific DNS records defined in this specification, section 5.1. 
         </p>
-
-        <section class="informative">
-            <h4>Sample Records</h4> 
         
+        <section class='informative'>
+          <h4>Dynamic Service registration</h4>   
           <p>
-            See below for the example records for Web Intents. A <a>mDNS enabled User Agent</a> looking for devices supporting http://webintents.org/view Web Intents can understand that 
-            it is possible to get a Web Intents document for "LivingRoomTV" at http://192.168.1.47:3619/webntents.html.
+            When the navigator.startActivity method [[!WEBINTENTS]] is called, the <a>mDNS enabled User Agent</a> typically runs the following steps:
           </p>
-
-          <ul>
+            
+          <ol class="rule">          
             <li>
-              <code>_webintents._tcp.local. 120 IN PTR LivingRoomTV._webintents._tcp.local.</code>: A LivingRoomTV instance serves webintents service.
+               Send a multicast PTR query of the <code>_webintents._tcp.local</code> in the format specified by [[!MDNS]] and [[!DNS-SD]].
+               <br />
             </li>
-            <li>
-              <code>LivingRoomTV._webintents._tcp.local. 120 IN SRV 0 0 3619 TV40EX-W2000.local.</code>: A host "TV40EX-W2000" in the link local network offers the LivingRoomTV webintents service instance in its port 3619.
-            </li>
+            <br />
             <li>
-              <code>LivingRoomTV._webintents._tcp.local. 120 IN TXT location=/webintents.html action=http://webintents.org/view</code>: It offers http://webintents.org/view type of Web Intents. The absolete path for its Web Intents document is "/webintents.html". Note that the actual binary format of the TXT record value is concatinating key-value pairs each of which is a single byte length followed by 0-255 length key=value character string as defined in [DNS-SD].
+               For each response, send a unicast TXT query of the webintents service instance in the PTR answer.
+               <br />
+               <p>This step can be omitted in case that the Web Intents enabled mDNS device attaches a TXT answer with the previous answer.
             </li>
+            <br />
             <li>
-              <code>TV40EX-W2000 120 IN A 192.168.1.47</code>: A host "TV40EX-W2000" is on 192.168.1.47.
+               For each matching response, i.e. the response TXT record does not have an action parameter or does have an <code>action</code> parameter matching the Action of the invoked intent,
+               send a unicast request with a SRV query of the webintens service instance.
+               <br />
+               <p>This step can be omitted in case that the Web Intents enabled mDNS device attaches a SRV answer with the previous answer.
             </li>
-          </ul>
+            <br />
+            <li>
+               For each response, send a unicast A and/or AAAA query of the host name in the SRV answer.
+               <br />
+               <p>This step can be omitted in case that the Web Intents enabled mDNS device attaches an A and/or AAAA answer with the previous answer.
+            </li>
+            <br />
+            <li>
+               The <a>mDNS enabled User Agent</a> attempts to retrieve the Web Intents document from the discovered <a>Web Intents enabled mDNS device</a>.
+               The destination URL consists of an IP address in the A or AAAA answer, a port number in the SRV record and an absolute path in the <code>location</code> parameter of the TXT record.  
+               <br />  <br />
+               If the <a>mDNS enabled User Agent</a> fails to retrieve the Web Intents document it silently disregards the received response.
+               <br />  <br />
+               If the <code>action</code> parameter is present and does not match the <code>action</code> attributes of the Services registered in the retrieved Web Intents 
+               document the <a>mDNS enabled User Agent</a> silently disregards the the received response.
+               <br />  <br />
+               Note that following steps are identical to those of UPnP described in 4.2.
+            </li>
+            <br />          
+            <li>
+               It is expected that the Web Intents document contains registration markup and the <a>mDNS enabled User Agent</a> interprets this
+               registration markup according to the rules for registration defined by [[!WEBINTENTS]] and register the Services accordingly.           
+            </li>
+            <br />          
+            <li>
+               The <a>mDNS enabled User Agent</a> makes each dynamically registered Service, that matches the Action of the invoked intent, available for selection 
+               by the user, typically by making them visible and selectable in a Web Intents Service picker.                          
+            </li>
+            <br />          
+            <li>
+               Based on user selection of a dynamically registered Service the <a>mDNS enabled User Agent</a> loads the 
+               Service handler code as defined by the <code>href</code> attribute in the registration markup for this Service according to the rules for 
+               loading Service pages defined in [[!WEBINTENTS]].                        
+            </li>
+    
+          </ol> 
+                 
+        </section>          
 
-            <p>
-              When the navigator.startActivity method [[!WEBINTENTS]] is called, the <a>mDNS enabled User Agent</a> runs the following steps:
-            </p>
-              
-            <ol class="rule">          
-              <li>
-                 Send a multicast PTR query of the <code>_webintents._tcp.local</code> in the format specified by [[!MDNS]] and [[!DNS-SD]].
-                 <br />
-              </li>
-              <br />
-              <li>
-                 For each response, send a unicast TXT query of the webintents service instance in the PTR answer.
-                 <br />
-                 <p>This step can be omitted in case that the Web Intents enabled mDNS device attaches a TXT answer with the previous answer.
-              </li>
-              <br />
-              <li>
-                 For each matching response, i.e. the response TXT record does not have an action parameter or does have an <code>action</code> parameter matching the Action of the invoked intent,
-                 send a unicast request with a SRV query of the webintens service instance.
-                 <br />
-                 <p>This step can be omitted in case that the Web Intents enabled mDNS device attaches a SRV answer with the previous answer.
-              </li>
-              <br />
-              <li>
-                 For each response, send a unicast A and/or AAAA query of the host name in the SRV answer.
-                 <br />
-                 <p>This step can be omitted in case that the Web Intents enabled mDNS device attaches an A and/or AAAA answer with the previous answer.
-              </li>
-              <br />
-              <li>
-                 The <a>mDNS enabled User Agent</a> attempts to retrieve the Web Intents document from the discovered <a>Web Intents enabled mDNS device</a>.
-                 The destination URL consists of an IP address in the A or AAAA answer, a port number in the SRV record and an absolute path in the <code>location</code> parameter of the TXT record.  
-                 <br />  <br />
-                 If the <a>mDNS enabled User Agent</a> fails to retrieve the Web Intents document it silently disregards the received response.
-                 <br />  <br />
-                 If the <code>action</code> parameter is present and does not match the <code>action</code> attributes of the Services registered in the retrieved Web Intents 
-                 document the <a>mDNS enabled User Agent</a> silently disregards the the received response.
-                 <br />  <br />
-                 Note that following steps are identical to those of UPnP described in 4.2.
-              </li>
-              <br />          
-              <li>
-                 It is expected that the Web Intents document contains registration markup and the <a>mDNS enabled User Agent</a> interprets this
-                 registration markup according to the rules for registration defined by [[!WEBINTENTS]] and register the Services accordingly.           
-              </li>
-              <br />          
-              <li>
-                 The <a>mDNS enabled User Agent</a> makes each dynamically registered Service, that matches the Action of the invoked intent, available for selection 
-                 by the user, typically by making them visible and selectable in a Web Intents Service picker.                          
-              </li>
-              <br />          
-              <li>
-                 Based on user selection of a dynamically registered Service the <a>mDNS enabled User Agent</a> loads the 
-                 Service handler code as defined by the <code>href</code> attribute in the registration markup for this Service according to the rules for 
-                 loading Service pages defined in [[!WEBINTENTS]].                        
-              </li>
-      
-            </ol> 
-     
+      </section>    
+      <section class="informative">
+        <h3>Sample Records</h3> 
+        
+        <p>
+          See below for the example records for Web Intents. An <a>mDNS enabled User Agent</a> looking for devices supporting http://webintents.org/view Web Intents can understand that 
+          it is possible to get a Web Intents document for "LivingRoomTV" at http://192.168.1.47:3619/webintents.html.
+        </p>
 
-        </section>         
-      </section>         
+        <ul>
+          <li>
+            <code>_webintents._tcp.local. 120 IN PTR LivingRoomTV._webintents._tcp.local.</code>: A LivingRoomTV instance serves webintents service.
+          </li>
+          <li>
+            <code>LivingRoomTV._webintents._tcp.local. 120 IN SRV 0 0 3619 TV40EX-W2000.local.</code>: A host "TV40EX-W2000" in the link local network offers the LivingRoomTV webintents service instance in its port 3619.
+          </li>
+          <li>
+            <code>LivingRoomTV._webintents._tcp.local. 120 IN TXT location=/webintents.html action=http://webintents.org/view</code>: It offers http://webintents.org/view type of Web Intents. The absolete path for its Web Intents document is "/webintents.html". Note that the actual binary format of the TXT record value is concatinating key-value pairs each of which is a single byte length followed by 0-255 length key=value character string as defined in [DNS-SD].
+          </li>
+          <li>
+            <code>TV40EX-W2000 120 IN A 192.168.1.47</code>: A host "TV40EX-W2000" is on 192.168.1.47.
+          </li>
+        </ul>
+
+      </section>   
+                 
     </section>         
     
         
@@ -725,8 +727,7 @@
     <section class='appendix'>
       <h3>Acknowledgements</h3>
         <p>         
-          Many thanks to Sony Mobile colleagues Anders Isberg, Anders Edenbrandt and Björn Ekberg
-          for all support.
+          Many thanks to Sony colleagues Anders Isberg, Naoyuki Sato, Tatsuya Igarashi, Anders Edenbrandt and Björn Ekberg for all support.
           <br />  <br />
           Many thanks to Robin Berjon for making our lives so much easier with his cool specification editing tool.
         </p>