--- a/discovery-api/Overview.html Tue Sep 25 13:33:45 2012 +0200
+++ b/discovery-api/Overview.html Wed Sep 26 14:47:02 2012 +0200
@@ -204,7 +204,7 @@
</p>
<h1 class="title" id="title">Networked Service Discovery and Messaging</h1>
- <h2 id="w3c-editor-s-draft-25-september-2012"><abbr title="World Wide Web Consortium">W3C</abbr> Editor's Draft 25 September 2012</h2>
+ <h2 id="w3c-editor-s-draft-26-september-2012"><abbr title="World Wide Web Consortium">W3C</abbr> Editor's Draft 26 September 2012</h2>
<dl>
<dt>This version:</dt>
@@ -312,7 +312,7 @@
-</section><section id="toc"><h2 class="introductory">Table of Contents</h2><ul class="toc"><li class="tocline"><a href="#introduction" class="tocxref"><span class="secno">1. </span>Introduction</a></li><li class="tocline"><a href="#conformance" class="tocxref"><span class="secno">2. </span>Conformance</a><ul class="toc"><li class="tocline"><a href="#dependencies" class="tocxref"><span class="secno">2.1 </span>Dependencies</a></li></ul></li><li class="tocline"><a href="#terminology" class="tocxref"><span class="secno">3. </span>Terminology</a></li><li class="tocline"><a href="#requesting-networked-services" class="tocxref"><span class="secno">4. </span>Requesting networked services</a><ul class="toc"><li class="tocline"><a href="#methods" class="tocxref"><span class="secno">4.1 </span>Methods</a></li><li class="tocline"><a href="#error-handling" class="tocxref"><span class="secno">4.2 </span>Error Handling</a></li></ul></li><li class="tocline"><a href="#obtaining-networked-services" class="tocxref"><span class="secno">5. </span>Obtaining networked services</a><ul class="toc"><li class="tocline"><a href="#attributes" class="tocxref"><span class="secno">5.1 </span>Attributes</a></li><li class="tocline"><a href="#methods-1" class="tocxref"><span class="secno">5.2 </span>Methods</a></li><li class="tocline"><a href="#events" class="tocxref"><span class="secno">5.3 </span>Events</a></li></ul></li><li class="tocline"><a href="#communicating-with-a-networked-service" class="tocxref"><span class="secno">6. </span>Communicating with a networked service</a><ul class="toc"><li class="tocline"><a href="#attributes-1" class="tocxref"><span class="secno">6.1 </span>Attributes</a></li><li class="tocline"><a href="#states" class="tocxref"><span class="secno">6.2 </span>States</a></li><li class="tocline"><a href="#events-1" class="tocxref"><span class="secno">6.3 </span>Events</a></li></ul></li><li class="tocline"><a href="#service-discovery" class="tocxref"><span class="secno">7. </span>Service Discovery</a><ul class="toc"><li class="tocline"><a href="#zeroconf-mdns-dns-sd" class="tocxref"><span class="secno">7.1 </span>Zeroconf (<abbr title="Multicast DNS">mDNS</abbr> + <abbr title="Domain Name System">DNS</abbr>-<abbr title="Service Discovery">SD</abbr>)</a></li><li class="tocline"><a href="#universal-plug-and-play-upnp" class="tocxref"><span class="secno">7.2 </span>Universal Plug-and-Play (<abbr title="Universal Plug-and-Play">UPnP</abbr>)</a></li><li class="tocline"><a href="#network-topology-monitoring" class="tocxref"><span class="secno">7.3 </span>Network Topology Monitoring</a></li></ul></li><li class="tocline"><a href="#garbage-collection" class="tocxref"><span class="secno">8. </span>Garbage collection</a></li><li class="tocline"><a href="#use-cases-and-requirements" class="tocxref"><span class="secno">9. </span>Use Cases and Requirements</a></li><li class="tocline"><a href="#examples" class="tocxref"><span class="secno">A. </span>Examples</a></li><li class="tocline"><a href="#acknowledgements" class="tocxref"><span class="secno">B. </span>Acknowledgements</a></li><li class="tocline"><a href="#references" class="tocxref"><span class="secno">C. </span>References</a><ul class="toc"><li class="tocline"><a href="#normative-references" class="tocxref"><span class="secno">C.1 </span>Normative references</a></li></ul></li></ul></section>
+</section><section id="toc"><h2 class="introductory">Table of Contents</h2><ul class="toc"><li class="tocline"><a href="#introduction" class="tocxref"><span class="secno">1. </span>Introduction</a></li><li class="tocline"><a href="#conformance" class="tocxref"><span class="secno">2. </span>Conformance</a><ul class="toc"><li class="tocline"><a href="#dependencies" class="tocxref"><span class="secno">2.1 </span>Dependencies</a></li></ul></li><li class="tocline"><a href="#terminology" class="tocxref"><span class="secno">3. </span>Terminology</a></li><li class="tocline"><a href="#requesting-networked-services" class="tocxref"><span class="secno">4. </span>Requesting networked services</a><ul class="toc"><li class="tocline"><a href="#methods" class="tocxref"><span class="secno">4.1 </span>Methods</a></li><li class="tocline"><a href="#error-handling" class="tocxref"><span class="secno">4.2 </span>Error Handling</a></li></ul></li><li class="tocline"><a href="#obtaining-networked-services" class="tocxref"><span class="secno">5. </span>Obtaining networked services</a><ul class="toc"><li class="tocline"><a href="#attributes" class="tocxref"><span class="secno">5.1 </span>Attributes</a></li><li class="tocline"><a href="#methods-1" class="tocxref"><span class="secno">5.2 </span>Methods</a></li><li class="tocline"><a href="#events" class="tocxref"><span class="secno">5.3 </span>Events</a></li></ul></li><li class="tocline"><a href="#communicating-with-a-networked-service" class="tocxref"><span class="secno">6. </span>Communicating with a networked service</a><ul class="toc"><li class="tocline"><a href="#attributes-1" class="tocxref"><span class="secno">6.1 </span>Attributes</a></li><li class="tocline"><a href="#states" class="tocxref"><span class="secno">6.2 </span>States</a></li><li class="tocline"><a href="#events-1" class="tocxref"><span class="secno">6.3 </span>Events</a></li></ul></li><li class="tocline"><a href="#service-discovery" class="tocxref"><span class="secno">7. </span>Service Discovery</a><ul class="toc"><li class="tocline"><a href="#zeroconf-mdns-dns-sd" class="tocxref"><span class="secno">7.1 </span>Zeroconf (<abbr title="Multicast DNS">mDNS</abbr> + <abbr title="Domain Name System">DNS</abbr>-<abbr title="Service Discovery">SD</abbr>)</a></li><li class="tocline"><a href="#simple-service-discovery-protocol-ssdp" class="tocxref"><span class="secno">7.2 </span>Simple Service Discovery Protocol (<abbr title="Simple Service Discovery Protocol">SSDP</abbr>)</a></li><li class="tocline"><a href="#network-topology-monitoring" class="tocxref"><span class="secno">7.3 </span>Network Topology Monitoring</a></li></ul></li><li class="tocline"><a href="#garbage-collection" class="tocxref"><span class="secno">8. </span>Garbage collection</a></li><li class="tocline"><a href="#use-cases-and-requirements" class="tocxref"><span class="secno">9. </span>Use Cases and Requirements</a></li><li class="tocline"><a href="#examples" class="tocxref"><span class="secno">A. </span>Examples</a></li><li class="tocline"><a href="#acknowledgements" class="tocxref"><span class="secno">B. </span>Acknowledgements</a></li><li class="tocline"><a href="#references" class="tocxref"><span class="secno">C. </span>References</a><ul class="toc"><li class="tocline"><a href="#normative-references" class="tocxref"><span class="secno">C.1 </span>Normative references</a></li></ul></li></ul></section>
@@ -360,7 +360,7 @@
</div>
<div class="example">
- <p>Example of requesting a <abbr title="Universal Plug-and-Play">UPnP</abbr> advertised service, also handling error conditions:</p>
+ <p>Example of requesting a UPnP advertised service, also handling error conditions:</p>
<hr>
<pre class="highlight prettyprint"><span class="kwd">function</span><span class="pln"> showServices</span><span class="pun">(</span><span class="pln"> services </span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
</span><span class="com">// Show a list of all the services provided to the web page</span><span class="pln">
@@ -375,7 +375,7 @@
</div>
<div class="example">
- <p>Example of requesting either a <abbr title="Domain Name System">DNS</abbr>-<abbr title="Service Discovery">SD</abbr> or <abbr title="Universal Plug-and-Play">UPnP</abbr> advertised service:</p>
+ <p>Example of requesting either a <abbr title="Domain Name System">DNS</abbr>-<abbr title="Service Discovery">SD</abbr> or UPnP advertised service:</p>
<hr>
<pre class="highlight prettyprint"><span class="kwd">function</span><span class="pln"> showServices</span><span class="pun">(</span><span class="pln"> services </span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
</span><span class="com">// Show a list of all the services provided to the web page (+ service type)</span><span class="pln">
@@ -472,7 +472,7 @@
</p>
<p>
- A <dfn id="dfn-user-agent-generated-callback-url">user-agent generated callback url</dfn> is a Local-network accessible <abbr title="Uniform Resource Locator">URL</abbr> endpoint that a <a href="#dfn-user-agent" class="internalDFN">user agent</a> must generate and maintain for receiving <abbr title="Hypertext Transfer Protocol">HTTP</abbr> NOTIFY requests from <abbr title="Universal Plug-and-Play">UPnP</abbr> Event sources. It is only required when the user agent implements <abbr title="Universal Plug-and-Play">UPnP</abbr> Service Discovery as defined in
+ A <dfn id="dfn-user-agent-generated-callback-url">user-agent generated callback url</dfn> is a Local-network accessible <abbr title="Uniform Resource Locator">URL</abbr> endpoint that a <a href="#dfn-user-agent" class="internalDFN">user agent</a> must generate and maintain for receiving <abbr title="Hypertext Transfer Protocol">HTTP</abbr> NOTIFY requests from UPnP Event sources. It is only required when the user agent implements UPnP Service Discovery as defined in
this specification.
</p>
@@ -663,7 +663,7 @@
Add the <var>service</var>'s <code>url</code> parameter to the <a href="#dfn-entry-script-origin-s-url-whitelist" class="internalDFN">entry script origin's <abbr title="Uniform Resource Locator">URL</abbr> whitelist</a>.
</li>
<li>
- If <var>service</var>'s <code>type</code> parameter begins with the DOMString "<code>upnp:</code>" and the <var>service</var>'s <code>eventsUrl</code> parameter is not empty then <a href="#dfn-setup-a-upnp-events-subscription" class="internalDFN">setup a <abbr title="Universal Plug-and-Play">UPnP</abbr> Events Subscription</a> for <var>service</var>.
+ If <var>service</var>'s <code>type</code> parameter begins with the DOMString "<code>upnp:</code>" and the <var>service</var>'s <code>eventsUrl</code> parameter is not empty then <a href="#dfn-setup-a-upnp-events-subscription" class="internalDFN">setup a UPnP Events Subscription</a> for <var>service</var>.
</li>
</ol>
</li>
@@ -1143,7 +1143,7 @@
<!--OddPage--><h2><span class="secno">7. </span>Service Discovery</h2>
<p>
- A <a href="#dfn-user-agent" class="internalDFN">user agent</a> conforming to this specification <em class="rfc2119" title="may">may</em> implement <acronym title="Simple Service Discovery Protocol">SSDP</acronym> [<cite><a class="bibref" href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>] and Zeroconf [<cite><a class="bibref" href="#bib-DNS-SD">DNS-SD</a></cite>] + [<cite><a class="bibref" href="#bib-MDNS">MDNS</a></cite>] service discovery mechanisms
+ A <a href="#dfn-user-agent" class="internalDFN">user agent</a> conforming to this specification <em class="rfc2119" title="may">may</em> implement <acronym title="Simple Service Discovery Protocol"><abbr title="Simple Service Discovery Protocol">SSDP</abbr></acronym> [<cite><a class="bibref" href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>] and Zeroconf [<cite><a class="bibref" href="#bib-DNS-SD">DNS-SD</a></cite>] + [<cite><a class="bibref" href="#bib-MDNS">MDNS</a></cite>] service discovery mechanisms
to enable Web pages to request and connect with <abbr title="Hypertext Transfer Protocol">HTTP</abbr> services running on networked devices, discovered via either mechanism, through this <abbr title="Application Programming Interface">API</abbr>. When a <a href="#dfn-user-agent" class="internalDFN">user agent</a> implements either of these service discovery mechanisms, then it <em class="rfc2119" title="must">must</em> conform to the corresponding algorithms provided in this section of the specification.
</p>
<p>
@@ -1255,8 +1255,8 @@
<li>
If the <var>existing service record</var>'s <code>type</code> property begins with the DOMString "<code>upnp:</code>" and
<var>existing service record</var>'s <code>eventsURL</code> property is set then run the rule to
- <a href="#dfn-terminate-an-existing-upnp-events-subscription" class="internalDFN">terminate an existing <abbr title="Universal Plug-and-Play">UPnP</abbr> Events Subscription</a>, if one is currently active (as a result of having previously called
- <a href="#dfn-setup-a-upnp-events-subscription" class="internalDFN">setup a <abbr title="Universal Plug-and-Play">UPnP</abbr> Events Subscription</a> against the current <var>existing service record</var>).
+ <a href="#dfn-terminate-an-existing-upnp-events-subscription" class="internalDFN">terminate an existing UPnP Events Subscription</a>, if one is currently active (as a result of having previously called
+ <a href="#dfn-setup-a-upnp-events-subscription" class="internalDFN">setup a UPnP Events Subscription</a> against the current <var>existing service record</var>).
</li>
<li>
@@ -1334,7 +1334,7 @@
</li>
<li>
- Set <var>network service record</var>'s <code>type</code> property to the concatenation of the string <code>zeroconf:</code> followed by the value of the <abbr title="DNS Pointer Record">PTR</abbr> Service Instance Name's <var>Service</var> component [<cite><a class="bibref" href="#bib-MDNS">MDNS</a></cite>].
+ Set <var>network service record</var>'s <code>type</code> property to the concatenation of the string <code>zeroconf:</code> followed be the value of the <abbr title="DNS Pointer Record">PTR</abbr> Service Instance Name's <var>Service</var> component [<cite><a class="bibref" href="#bib-MDNS">MDNS</a></cite>].
</li>
<li>
@@ -1360,34 +1360,34 @@
</section>
- <section id="universal-plug-and-play-upnp">
- <h3><span class="secno">7.2 </span>Universal Plug-and-Play (<abbr title="Universal Plug-and-Play">UPnP</abbr>)</h3>
+ <section id="simple-service-discovery-protocol-ssdp">
+ <h3><span class="secno">7.2 </span>Simple Service Discovery Protocol (<abbr title="Simple Service Discovery Protocol">SSDP</abbr>)</h3>
<p>
- A user agent that implements <abbr title="Universal Plug-and-Play">UPnP</abbr> service discovery must issue an <dfn id="dfn-advertisement-for-upnp-root-devices">advertisement for <abbr title="Universal Plug-and-Play">UPnP</abbr> root devices</dfn> against the user's
+ A user agent that implements UPnP service discovery must issue an <dfn id="dfn-advertisement-for-upnp-root-devices">advertisement for UPnP root devices</dfn> against the user's
current local network according to the full normative text and timing provided in 'Section 1.3.2: Search request with M-SEARCH' detailed in [<cite><a class="bibref" href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>].
</p>
<p>
- The user agent <em class="ct"><em class="rfc2119" title="must">must</em></em> issue all <a title="advertisement for UPnP root devices" href="#dfn-advertisement-for-upnp-root-devices" class="internalDFN">advertisements for <abbr title="Universal Plug-and-Play">UPnP</abbr> root devices</a> with a <abbr title="Hypertext Transfer Protocol">HTTP</abbr> request line equal to <code>M-SEARCH * <abbr title="Hypertext Transfer Protocol">HTTP</abbr>/1.1</code>, with a HOST header equal to the reserved multicast address and port of <code>239.255.255.250:1900</code>, a MAN header equal to <code>ssdp:discover</code>, an ST header equal to <code>upnp:rootdevice</code> and a user-agent defined MX header equal to a <dfn id="dfn-maximum-upnp-advertisement-response-wait-time">maximum <abbr title="Universal Plug-and-Play">UPnP</abbr> advertisement response wait time</dfn> value between <code>1</code> and <code>5</code> seconds.
+ The user agent <em class="ct"><em class="rfc2119" title="must">must</em></em> issue all <a title="advertisement for UPnP root devices" href="#dfn-advertisement-for-upnp-root-devices" class="internalDFN">advertisements for UPnP root devices</a> with a <abbr title="Hypertext Transfer Protocol">HTTP</abbr> request line equal to <code>M-SEARCH * <abbr title="Hypertext Transfer Protocol">HTTP</abbr>/1.1</code>, with a HOST header equal to the reserved multicast address and port of <code>239.255.255.250:1900</code>, a MAN header equal to <code>ssdp:discover</code>, an ST header equal to <code>upnp:rootdevice</code> and a user-agent defined MX header equal to a <dfn id="dfn-maximum-upnp-advertisement-response-wait-time">maximum UPnP advertisement response wait time</dfn> value between <code>1</code> and <code>5</code> seconds.
</p>
<p>
- The user agent <em class="ct"><em class="rfc2119" title="must">must</em></em> listen for incoming requests and process any incoming responses to any <a href="#dfn-advertisement-for-upnp-root-devices" class="internalDFN">advertisement for <abbr title="Universal Plug-and-Play">UPnP</abbr> root devices</a> on the <dfn id="dfn-standard-upnp-address-and-port">standard <abbr title="Universal Plug-and-Play">UPnP</abbr> address and port</dfn>, on all current local network interface addresses with the port <code>1900</code>, according to the rules defined in this section.
+ The user agent <em class="ct"><em class="rfc2119" title="must">must</em></em> listen for incoming requests and process any incoming responses to any <a href="#dfn-advertisement-for-upnp-root-devices" class="internalDFN">advertisement for UPnP root devices</a> on the <dfn id="dfn-standard-upnp-address-and-port">standard UPnP address and port</dfn>, on all current local network interface addresses with the port <code>1900</code>, according to the rules defined in this section.
</p>
<p>
- For each <dfn id="dfn-http-response"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Response</dfn> following an initial <a href="#dfn-advertisement-for-upnp-root-devices" class="internalDFN">advertisement for <abbr title="Universal Plug-and-Play">UPnP</abbr> root devices</a> sent on a <a href="#dfn-standard-upnp-address-and-port" class="internalDFN">standard <abbr title="Universal Plug-and-Play">UPnP</abbr> address
+ For each <dfn id="dfn-http-response"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Response</dfn> following an initial <a href="#dfn-advertisement-for-upnp-root-devices" class="internalDFN">advertisement for UPnP root devices</a> sent on a <a href="#dfn-standard-upnp-address-and-port" class="internalDFN">standard UPnP address
and port</a> the user agent <em class="ct"><em class="rfc2119" title="must">must</em></em> run the following steps:
</p>
<ol class="rule">
<li>
- If the <a href="#dfn-http-response" class="internalDFN"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Response</a> is not a <abbr title="Hypertext Transfer Protocol">HTTP</abbr> 200 OK response then this response is invalid and the user agent <em class="ct"><em class="rfc2119" title="must">must</em></em> discard this response, abort any remaining steps and return. The user agent <em class="ct"><em class="rfc2119" title="may">may</em></em> issue a new <a href="#dfn-advertisement-for-upnp-root-devices" class="internalDFN">advertisement for <abbr title="Universal Plug-and-Play">UPnP</abbr> root devices</a> as a result of this error occurring.
+ If the <a href="#dfn-http-response" class="internalDFN"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Response</a> is not a <abbr title="Hypertext Transfer Protocol">HTTP</abbr> 200 OK response then this response is invalid and the user agent <em class="ct"><em class="rfc2119" title="must">must</em></em> discard this response, abort any remaining steps and return. The user agent <em class="ct"><em class="rfc2119" title="may">may</em></em> issue a new <a href="#dfn-advertisement-for-upnp-root-devices" class="internalDFN">advertisement for UPnP root devices</a> as a result of this error occurring.
</li>
<li>
- If the <a href="#dfn-maximum-upnp-advertisement-response-wait-time" class="internalDFN">maximum <abbr title="Universal Plug-and-Play">UPnP</abbr> advertisement response wait time</a> has been exceeded since the initial <a href="#dfn-advertisement-for-upnp-root-devices" class="internalDFN">advertisement for <abbr title="Universal Plug-and-Play">UPnP</abbr> root devices</a> was sent then the <a href="#dfn-http-response" class="internalDFN"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Response</a> is invalid and the user agent <em class="ct"><em class="rfc2119" title="must">must</em></em> discard this response, abort any remaining steps and return.
+ If the <a href="#dfn-maximum-upnp-advertisement-response-wait-time" class="internalDFN">maximum UPnP advertisement response wait time</a> has been exceeded since the initial <a href="#dfn-advertisement-for-upnp-root-devices" class="internalDFN">advertisement for UPnP root devices</a> was sent then the <a href="#dfn-http-response" class="internalDFN"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Response</a> is invalid and the user agent <em class="ct"><em class="rfc2119" title="must">must</em></em> discard this response, abort any remaining steps and return.
</li>
<li>
@@ -1399,19 +1399,19 @@
</li>
<li>
- The user agent <em class="ct"><em class="rfc2119" title="must">must</em></em> run the rule for <a href="#dfn-processing-a-upnp-device-description-file" class="internalDFN">processing a <abbr title="Universal Plug-and-Play">UPnP</abbr> Device Description File</a> passing in the first occurrence of <var>LOCATION</var> from <var>ssdp device</var> as the <var>device descriptor</var> argument and the first occurrence of <var>USN</var> from <var>ssdp device</var> as the <var>device identifier</var> argument and the first occurrence of <var>CACHE-CONTROL</var> from <var>ssdp device</var> as the <var>device expiry</var> argument
+ The user agent <em class="ct"><em class="rfc2119" title="must">must</em></em> run the rule for <a href="#dfn-obtaining-a-upnp-device-description-file" class="internalDFN">obtaining a UPnP Device Description File</a> passing in the first occurrence of <var>LOCATION</var> from <var>ssdp device</var> as the <var>device descriptor</var> argument and the first occurrence of <var>USN</var> from <var>ssdp device</var> as the <var>device identifier</var> argument and the first occurrence of <var>CACHE-CONTROL</var> from <var>ssdp device</var> as the <var>device expiry</var> argument.
</li>
</ol>
<p>
- For each <dfn id="dfn-http-request"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Request</dfn> received on a <a href="#dfn-standard-upnp-address-and-port" class="internalDFN">standard <abbr title="Universal Plug-and-Play">UPnP</abbr> address and port</a> the user agent <em class="ct"><em class="rfc2119" title="must">must</em></em> run the following steps:
+ For each <dfn id="dfn-http-request"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Request</dfn> received on a <a href="#dfn-standard-upnp-address-and-port" class="internalDFN">standard UPnP address and port</a> the user agent <em class="ct"><em class="rfc2119" title="must">must</em></em> run the following steps:
</p>
<ol class="rule">
<li>
- If the <a href="#dfn-http-request" class="internalDFN"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Request</a> is not a <abbr title="Hypertext Transfer Protocol">HTTP</abbr> NOTIFY request then it is not a valid <abbr title="Universal Plug-and-Play">UPnP</abbr> Request and the user agent <em class="ct"><em class="rfc2119" title="must">must</em></em> return a <abbr title="Hypertext Transfer Protocol">HTTP</abbr> 200 OK response, discard this request, abort any remaining steps and return.
+ If the <a href="#dfn-http-request" class="internalDFN"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Request</a> is not a <abbr title="Hypertext Transfer Protocol">HTTP</abbr> NOTIFY request then it is not a valid UPnP Request and the user agent <em class="ct"><em class="rfc2119" title="must">must</em></em> return a <abbr title="Hypertext Transfer Protocol">HTTP</abbr> 200 OK response, discard this request, abort any remaining steps and return.
</li>
<li>
@@ -1419,32 +1419,53 @@
</li>
<li>
- If <var>ssdp device</var> does not contain at least one <var>CACHE-CONTROL</var> entry, at least one <var>USN</var> entry, at least one <var>NT</var> entry, at least one <var>NTS</var> entry and at least one <var>LOCATION</var> entry or the value of its <var>NT</var> entry is not <code>upnp:rootdevice</code>, then the <a href="#dfn-http-request" class="internalDFN"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Request</a> is a malformed <abbr title="Universal Plug-and-Play">UPnP</abbr> Request and the <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="rfc2119" title="must">must</em> return a 400 Bad Request response, discard this request, abort any remaining steps and return.
+ If <var>ssdp device</var> does not contain at least one <var>CACHE-CONTROL</var> entry, at least one <var>USN</var> entry, at least one <var>NT</var> entry, at least one <var>NTS</var> entry and at least one <var>LOCATION</var> entry or the value of its <var>NT</var> entry is not <code>upnp:rootdevice</code>, then the <a href="#dfn-http-request" class="internalDFN"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Request</a> is a malformed UPnP Request and the <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="rfc2119" title="must">must</em> return a 400 Bad Request response, discard this request, abort any remaining steps and return.
</li>
<li>
- If <var>ssdp device</var>'s <var>NTS</var> entry is equal to <code>ssdp:alive</code> or <code>ssdp:update</code> then the user agent <em class="ct"><em class="rfc2119" title="must">must</em></em> run the rule for <a href="#dfn-processing-a-upnp-device-description-file" class="internalDFN">processing a <abbr title="Universal Plug-and-Play">UPnP</abbr> Device Description File</a> passing in the first occurrence of <var>LOCATION</var> from <var>ssdp device</var> as the <var>device descriptor</var> argument and the first occurrence of <var>USN</var> from <var>ssdp device</var> as the <var>device identifier</var> argument and the first occurrence of <var>CACHE-CONTROL</var> from <var>ssdp device</var> as the <var>device expiry</var>. <br><br>Otherwise, if <var>ssdp device</var>'s <var>NTS</var> entry is equal to <code>ssdp:byebye</code> then the user agent <em class="ct"><em class="rfc2119" title="must">must</em></em> run the rule for <a href="#dfn-removing-all-services-from-a-registered-upnp-device" class="internalDFN">removing all services from a registered <abbr title="Universal Plug-and-Play">UPnP</abbr> Device</a> passing in the first occurrence of <var>USN</var> from <var>ssdp device</var> as the <var>device identifier</var> argument.
+ If <var>ssdp device</var>'s <var>NTS</var> entry is equal to <code>ssdp:alive</code> or <code>ssdp:update</code> then the user agent <em class="ct"><em class="rfc2119" title="must">must</em></em> run the rule for <a href="#dfn-obtaining-a-upnp-device-description-file" class="internalDFN">obtaining a UPnP Device Description File</a> passing in the first occurrence of <var>LOCATION</var> from <var>ssdp device</var> as the <var>device descriptor</var> argument and the first occurrence of <var>USN</var> from <var>ssdp device</var> as the <var>device identifier</var> argument and the first occurrence of <var>CACHE-CONTROL</var> from <var>ssdp device</var> as the <var>device expiry</var>. <br><br>Otherwise, if <var>ssdp device</var>'s <var>NTS</var> entry is equal to <code>ssdp:byebye</code> then the user agent <em class="ct"><em class="rfc2119" title="must">must</em></em> run the rule for <a href="#dfn-removing-all-services-from-a-registered-upnp-device" class="internalDFN">removing all services from a registered UPnP Device</a> passing in the first occurrence of <var>USN</var> from <var>ssdp device</var> as the <var>device identifier</var> argument.
</li>
</ol>
<p>
- The rule for <dfn id="dfn-processing-a-upnp-device-description-file">processing a <abbr title="Universal Plug-and-Play">UPnP</abbr> Device Description File</dfn> is the process of parsing the contents of a standard <abbr title="Universal Plug-and-Play">UPnP</abbr> Device Description [<cite><a class="bibref" href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>] and
- registering the <abbr title="Universal Plug-and-Play">UPnP</abbr> services contained therein within the <a href="#dfn-list-of-available-service-records" class="internalDFN">list of available service records</a>.
+ The rule for <dfn id="dfn-obtaining-a-upnp-device-description-file">obtaining a UPnP Device Description File</dfn> is the process of obtaining the contents of a standard UPnP Device Description [<cite><a class="bibref" href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>] from a <abbr title="Uniform Resource Locator">URL</abbr>-based resource. This rule takes three arguments - <var>device descriptor <abbr title="Uniform Resource Locator">URL</abbr></var>, <var>device identifier</var> and <var>device expiry</var> - and when called the user agent <em class="ct"><em class="rfc2119" title="must">must</em></em> run the following steps:
</p>
- <p>The rule for <a href="#dfn-processing-a-upnp-device-description-file" class="internalDFN">processing a <abbr title="Universal Plug-and-Play">UPnP</abbr> Device Description File</a> takes three arguments - <var>device descriptor</var>, <var>device identifier</var> and <var>device expiry</var> - and when called the user
+ <ol class="rule">
+
+ <li>
+ Let <var>device descriptor file</var> contain the contents of the file located at the <abbr title="Uniform Resource Locator">URL</abbr> provided in <var>device descriptor <abbr title="Uniform Resource Locator">URL</abbr></var> obtained according to the rules
+ defined in 'Section 2.11: Retrieving a description using <abbr title="Hypertext Transfer Protocol">HTTP</abbr>' in [<cite><a class="bibref" href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>].
+ </li>
+
+ <li>
+ If the value provided in <var>device descriptor <abbr title="Uniform Resource Locator">URL</abbr></var> cannot be resolved as a reachable <abbr title="Uniform Resource Locator">URL</abbr> on the current network or the <var>root device descriptor file</var> remains empty then it is invalid and the <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="rfc2119" title="must">must</em> abort any remaining steps and return.
+ </li>
+
+ <li>
+ Run the rule for <a href="#dfn-processing-a-upnp-device-description-file" class="internalDFN">processing a UPnP Device Description File</a>, passing in the current <var>device descriptor file</var>, <var>device identifier</var> and <var>device expiry</var> arguments.
+ </li>
+
+ <li>
+ If the current <var>device descriptor file</var> contains a <code><deviceList></code> element then for each <code><device></code> element within <code><deviceList></code> - herein known as an <var>embedded device descriptor file</var> - the user agent <em class="rfc2119" title="must">must</em>
+ run the rule for <a href="#dfn-processing-a-upnp-device-description-file" class="internalDFN">processing a UPnP Device Description File</a>, passing in the current <var>embedded device descriptor file</var> as the <var>device descriptor file</var> argument, along with the common <var>device identifier</var> and <var>device expiry</var> arguments.
+ </li>
+
+ </ol>
+
+ <p>
+ The rule for <dfn id="dfn-processing-a-upnp-device-description-file">processing a UPnP Device Description File</dfn> is the process of parsing the contents of a standard UPnP Device Description [<cite><a class="bibref" href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>] and
+ registering the UPnP services contained therein within the <a href="#dfn-list-of-available-service-records" class="internalDFN">list of available service records</a>.
+ </p>
+
+ <p>The rule for <a href="#dfn-processing-a-upnp-device-description-file" class="internalDFN">processing a UPnP Device Description File</a> takes three arguments - <var>device descriptor file</var>, <var>device identifier</var> and <var>device expiry</var> - and when called the user
agent <em class="ct"><em class="rfc2119" title="must">must</em></em> run the following steps:</p>
<ol class="rule">
<li>
- Let <var>root device descriptor file</var> contain the contents of the file located at the <abbr title="Uniform Resource Locator">URL</abbr> provided in <var>device descriptor</var> obtained according to the rules
- defined in 'Section 2.11: Retrieving a description using <abbr title="Hypertext Transfer Protocol">HTTP</abbr>' in [<cite><a class="bibref" href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>]. If the value provided in <var>device descriptor</var> cannot be resolved as a <abbr title="Uniform Resource Locator">URL</abbr> on the current network or the <var>root device descriptor file</var> remains empty then the <a href="#dfn-http-response" class="internalDFN"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Response</a> is invalid and the <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="rfc2119" title="must">must</em> discard this response, abort any remaining steps and return.
- </li>
-
- <li>
- Let <var>advertised services</var> be a <a>list of all advertised services</a> obtained from the <var>root device descriptor file</var> containing the value of the first occurrence of the <code><serviceList></code> element as it is defined in 'Section 2.3: Device Description' in [<cite><a class="bibref" href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>].
+ Let <var>advertised services</var> be a list of all advertised services obtained from the <var>device descriptor file</var> containing the value of the first occurrence of the <code><serviceList></code> element as it is defined in 'Section 2.3: Device Description' in [<cite><a class="bibref" href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>].
</li>
<li>
@@ -1477,7 +1498,7 @@
</li>
<li>
- Set <var>network service record</var>'s <code>config</code> property to the string value of the contents of the first occurrence of the <code><device></code> element in the <var>root device descriptor file</var>.
+ Set <var>network service record</var>'s <code>config</code> property to the string value of the contents of the first occurrence of the <code><device></code> element in the <var>device descriptor file</var>.
</li>
<li>
@@ -1497,7 +1518,7 @@
</li></ol>
<p>
- The rule for <dfn id="dfn-removing-all-services-from-a-registered-upnp-device">removing all services from a registered <abbr title="Universal Plug-and-Play">UPnP</abbr> Device</dfn> is the process of removing all services associated with a
+ The rule for <dfn id="dfn-removing-all-services-from-a-registered-upnp-device">removing all services from a registered UPnP Device</dfn> is the process of removing all services associated with a
device from the <a href="#dfn-list-of-available-service-records" class="internalDFN">list of available service records</a> that has left the user's current network or has otherwise timed out or expired.
This rule takes one argument, <var>device identifier</var>, and consists of running the following steps:
</p>
@@ -1522,7 +1543,7 @@
</ol>
- <p>When the <a href="#dfn-user-agent" class="internalDFN">user agent</a> is to <dfn id="dfn-setup-a-upnp-events-subscription">setup a <abbr title="Universal Plug-and-Play">UPnP</abbr> Events Subscription</dfn>, it is to run the following steps with the current <var>network service record</var> object as defined in 'Section 4.1.2: SUBSCRIBE with NT and CALLBACK' in [<cite><a class="bibref" href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>]:</p>
+ <p>When the <a href="#dfn-user-agent" class="internalDFN">user agent</a> is to <dfn id="dfn-setup-a-upnp-events-subscription">setup a UPnP Events Subscription</dfn>, it is to run the following steps with the current <var>network service record</var> object as defined in 'Section 4.1.2: SUBSCRIBE with NT and CALLBACK' in [<cite><a class="bibref" href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>]:</p>
<ol class="rule">
<li>
@@ -1603,7 +1624,7 @@
</ol>
<p>
- A <a href="#dfn-user-agent" class="internalDFN">user agent</a> can <dfn id="dfn-terminate-an-existing-upnp-events-subscription">terminate an existing <abbr title="Universal Plug-and-Play">UPnP</abbr> Events Subscription</dfn> at any time for any <var>active service</var> in the <a href="#dfn-list-of-authorized-service-records" class="internalDFN">list of authorized service records</a> by sending an <abbr title="Hypertext Transfer Protocol">HTTP</abbr> UNSUBSCRIBE request - as defined in 'Section 4.1.4: Canceling a subscription with UNSUBSCRIBE' in [<cite><a class="bibref" href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>] - with a HOST header set to that <var>active service</var>'s <code>eventsUrl</code> property and a SID header set to the <var>callback ID</var> obtained when the initial <a href="#dfn-setup-a-upnp-events-subscription" class="internalDFN">setup a <abbr title="Universal Plug-and-Play">UPnP</abbr> Events Subscription</a> action occurred.
+ A <a href="#dfn-user-agent" class="internalDFN">user agent</a> can <dfn id="dfn-terminate-an-existing-upnp-events-subscription">terminate an existing UPnP Events Subscription</dfn> at any time for any <var>active service</var> in the <a href="#dfn-list-of-authorized-service-records" class="internalDFN">list of authorized service records</a> by sending an <abbr title="Hypertext Transfer Protocol">HTTP</abbr> UNSUBSCRIBE request - as defined in 'Section 4.1.4: Canceling a subscription with UNSUBSCRIBE' in [<cite><a class="bibref" href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>] - with a HOST header set to that <var>active service</var>'s <code>eventsUrl</code> property and a SID header set to the <var>callback ID</var> obtained when the initial <a href="#dfn-setup-a-upnp-events-subscription" class="internalDFN">setup a UPnP Events Subscription</a> action occurred.
</p>
</section>
@@ -1675,7 +1696,7 @@
<li>
Example: A Web page advertises that it is capable of interacting with and controlling multiple types of Home Media Server. The user can select their Home Media Server type from a drop-down list or known Media Servers, at which point the
Web page sends a request to the user agent to connect with the associated service type (and, optionally, the associated event type) of the Home Media Server. The communiciation protocols supported by Home Media Servers typically vary
- between <abbr title="Universal Plug-and-Play">UPnP</abbr>, JSON-RPC, Protocol Buffers or other messaging formats depending on the Home Media Server requested. The Web page is able to communicate with the user-selected Home Media
+ between UPnP, JSON-RPC, Protocol Buffers or other messaging formats depending on the Home Media Server requested. The Web page is able to communicate with the user-selected Home Media
Server in the messaging format supported by that Device, which, in this example is a simple key/value pair text format.
</li>
</ul>
--- a/discovery-api/Overview.src.html Tue Sep 25 13:33:45 2012 +0200
+++ b/discovery-api/Overview.src.html Wed Sep 26 14:47:02 2012 +0200
@@ -1089,7 +1089,7 @@
</li>
<li>
- Set <var>network service record</var>'s <code>type</code> property to the concatenation of the string <code>zeroconf:</code> followed by the value of the PTR Service Instance Name's <var>Service</var> component [[!MDNS]].
+ Set <var>network service record</var>'s <code>type</code> property to the concatenation of the string <code>zeroconf:</code> followed be the value of the PTR Service Instance Name's <var>Service</var> component [[!MDNS]].
</li>
<li>
@@ -1116,7 +1116,7 @@
</section>
<section>
- <h5>Universal Plug-and-Play (<abbr title="Universal Plug-and-Play">UPnP</abbr>)</h5>
+ <h5>Simple Service Discovery Protocol (<abbr title="Simple Service Discovery Protocol">SSDP</abbr>)</h5>
<p>
A user agent that implements UPnP service discovery must issue an <dfn>advertisement for UPnP root devices</dfn> against the user's
@@ -1154,7 +1154,7 @@
</li>
<li>
- The user agent <em class="ct">MUST</em> run the rule for <a>processing a UPnP Device Description File</a> passing in the first occurrence of <var>LOCATION</var> from <var>ssdp device</var> as the <var>device descriptor</var> argument and the first occurrence of <var>USN</var> from <var>ssdp device</var> as the <var>device identifier</var> argument and the first occurrence of <var>CACHE-CONTROL</var> from <var>ssdp device</var> as the <var>device expiry</var> argument
+ The user agent <em class="ct">MUST</em> run the rule for <a>obtaining a UPnP Device Description File</a> passing in the first occurrence of <var>LOCATION</var> from <var>ssdp device</var> as the <var>device descriptor</var> argument and the first occurrence of <var>USN</var> from <var>ssdp device</var> as the <var>device identifier</var> argument and the first occurrence of <var>CACHE-CONTROL</var> from <var>ssdp device</var> as the <var>device expiry</var> argument.
</li>
</ol>
@@ -1178,28 +1178,49 @@
</li>
<li>
- If <var>ssdp device</var>'s <var>NTS</var> entry is equal to <code>ssdp:alive</code> or <code>ssdp:update</code> then the user agent <em class="ct">MUST</em> run the rule for <a>processing a UPnP Device Description File</a> passing in the first occurrence of <var>LOCATION</var> from <var>ssdp device</var> as the <var>device descriptor</var> argument and the first occurrence of <var>USN</var> from <var>ssdp device</var> as the <var>device identifier</var> argument and the first occurrence of <var>CACHE-CONTROL</var> from <var>ssdp device</var> as the <var>device expiry</var>. <br/><br/>Otherwise, if <var>ssdp device</var>'s <var>NTS</var> entry is equal to <code>ssdp:byebye</code> then the user agent <em class="ct">MUST</em> run the rule for <a>removing all services from a registered UPnP Device</a> passing in the first occurrence of <var>USN</var> from <var>ssdp device</var> as the <var>device identifier</var> argument.
+ If <var>ssdp device</var>'s <var>NTS</var> entry is equal to <code>ssdp:alive</code> or <code>ssdp:update</code> then the user agent <em class="ct">MUST</em> run the rule for <a>obtaining a UPnP Device Description File</a> passing in the first occurrence of <var>LOCATION</var> from <var>ssdp device</var> as the <var>device descriptor</var> argument and the first occurrence of <var>USN</var> from <var>ssdp device</var> as the <var>device identifier</var> argument and the first occurrence of <var>CACHE-CONTROL</var> from <var>ssdp device</var> as the <var>device expiry</var>. <br/><br/>Otherwise, if <var>ssdp device</var>'s <var>NTS</var> entry is equal to <code>ssdp:byebye</code> then the user agent <em class="ct">MUST</em> run the rule for <a>removing all services from a registered UPnP Device</a> passing in the first occurrence of <var>USN</var> from <var>ssdp device</var> as the <var>device identifier</var> argument.
</li>
</ol>
<p>
+ The rule for <dfn>obtaining a UPnP Device Description File</dfn> is the process of obtaining the contents of a standard UPnP Device Description [[!UPNP-DEVICEARCH11]] from a URL-based resource. This rule takes three arguments - <var>device descriptor URL</var>, <var>device identifier</var> and <var>device expiry</var> - and when called the user agent <em class="ct">MUST</em> run the following steps:
+ </p>
+
+ <ol class="rule">
+
+ <li>
+ Let <var>device descriptor file</var> contain the contents of the file located at the URL provided in <var>device descriptor URL</var> obtained according to the rules
+ defined in 'Section 2.11: Retrieving a description using HTTP' in [[!UPNP-DEVICEARCH11]].
+ </li>
+
+ <li>
+ If the value provided in <var>device descriptor URL</var> cannot be resolved as a reachable URL on the current network or the <var>root device descriptor file</var> remains empty then it is invalid and the <a>user agent</a> MUST abort any remaining steps and return.
+ </li>
+
+ <li>
+ Run the rule for <a>processing a UPnP Device Description File</a>, passing in the current <var>device descriptor file</var>, <var>device identifier</var> and <var>device expiry</var> arguments.
+ </li>
+
+ <li>
+ If the current <var>device descriptor file</var> contains a <code><deviceList></code> element then for each <code><device></code> element within <code><deviceList></code> - herein known as an <var>embedded device descriptor file</var> - the user agent MUST
+ run the rule for <a>processing a UPnP Device Description File</a>, passing in the current <var>embedded device descriptor file</var> as the <var>device descriptor file</var> argument, along with the common <var>device identifier</var> and <var>device expiry</var> arguments.
+ </li>
+
+ </ol>
+
+ <p>
The rule for <dfn>processing a UPnP Device Description File</dfn> is the process of parsing the contents of a standard UPnP Device Description [[!UPNP-DEVICEARCH11]] and
registering the UPnP services contained therein within the <a>list of available service records</a>.
</p>
- <p>The rule for <a>processing a UPnP Device Description File</a> takes three arguments - <var>device descriptor</var>, <var>device identifier</var> and <var>device expiry</var> - and when called the user
+ <p>The rule for <a>processing a UPnP Device Description File</a> takes three arguments - <var>device descriptor file</var>, <var>device identifier</var> and <var>device expiry</var> - and when called the user
agent <em class="ct">MUST</em> run the following steps:</p>
<ol class="rule">
<li>
- Let <var>root device descriptor file</var> contain the contents of the file located at the URL provided in <var>device descriptor</var> obtained according to the rules
- defined in 'Section 2.11: Retrieving a description using HTTP' in [[!UPNP-DEVICEARCH11]]. If the value provided in <var>device descriptor</var> cannot be resolved as a URL on the current network or the <var>root device descriptor file</var> remains empty then the <a>HTTP Response</a> is invalid and the <a>user agent</a> MUST discard this response, abort any remaining steps and return.
- </li>
-
- <li>
- Let <var>advertised services</var> be a <a>list of all advertised services</a> obtained from the <var>root device descriptor file</var> containing the value of the first occurrence of the <code><serviceList></code> element as it is defined in 'Section 2.3: Device Description' in [[!UPNP-DEVICEARCH11]].
+ Let <var>advertised services</var> be a list of all advertised services obtained from the <var>device descriptor file</var> containing the value of the first occurrence of the <code><serviceList></code> element as it is defined in 'Section 2.3: Device Description' in [[!UPNP-DEVICEARCH11]].
</li>
<li>
@@ -1232,7 +1253,7 @@
</li>
<li>
- Set <var>network service record</var>'s <code>config</code> property to the string value of the contents of the first occurrence of the <code><device></code> element in the <var>root device descriptor file</var>.
+ Set <var>network service record</var>'s <code>config</code> property to the string value of the contents of the first occurrence of the <code><device></code> element in the <var>device descriptor file</var>.
</li>
<li>