- From: Mercurial notifier <cvsmail@w3.org>
- Date: Tue, 02 Oct 2012 12:51:49 +0000
- To: public-dap-commits@w3.org
changeset: 238:65e14f8dc95d
tag: tip
user: Rich Tibbett <richt@opera.com>
date: Tue Oct 02 14:51:33 2012 +0200
files: discovery-api/Overview.html discovery-api/Overview.src.html
description:
Editorial changes to Service Discovery spec
diff -r 7729986a7295 -r 65e14f8dc95d discovery-api/Overview.html
--- a/discovery-api/Overview.html Mon Oct 01 15:26:54 2012 -0400
+++ b/discovery-api/Overview.html Tue Oct 02 14:51:33 2012 +0200
@@ -32,6 +32,11 @@
dl.domintro dd p { margin: 0.5em 0; }
dl.domintro code {font-size: inherit; font-style: italic; }
dl.domintro:before { display: table; margin: -1em -0.5em 0.5em auto; width: auto; content: 'This box is non-normative. Implementation requirements are given below this box.'; color: red; border: solid 2px; background: white; padding: 0 0.25em; }
+
+ table { border-collapse:collapse; border-style:hidden hidden none hidden }
+ table thead { border-bottom:solid }
+ table tbody th:first-child { border-left:solid }
+ table td, table th { border-left:solid; border-right:solid; border-bottom:solid thin; vertical-align:top; padding:0.2em }
</style>
<style>/*****************************************************************
* ReSpec 3 CSS
@@ -204,7 +209,7 @@
</p>
<h1 class="title" id="title">Networked Service Discovery and Messaging</h1>
- <h2 id="w3c-editor-s-draft-26-september-2012"><abbr title="World Wide Web Consortium">W3C</abbr> Editor's Draft 26 September 2012</h2>
+ <h2 id="w3c-editor-s-draft-02-october-2012"><abbr title="World Wide Web Consortium">W3C</abbr> Editor's Draft 02 October 2012</h2>
<dl>
<dt>This version:</dt>
@@ -312,7 +317,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 clss="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"><liclass="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="#acknowledgemnts" 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 clss="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"><liclass="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="#events-summary" class="tocxref"><span class="secno">8. </span>Events Summary</a></li><li class="tocline"><a href="#garbage-collection" class="tocxref"><span class="secno">9. </span>Garbage collection</a></li><li class="tocline"><a href="#use-cases-and-requirements" class="tocxref"><span class="secno">10. </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>
@@ -412,7 +417,7 @@
</p>
<p>
- Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in
+ Conformance requirements phrased as algorithms or specific steps <em class="ct"><em class="rfc2119" title="may">may</em></em> be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in
this specification are intended to be easy to follow, and not intended to be performant.)
</p>
@@ -421,12 +426,12 @@
</p>
<p>
- User agents may impose implementation-specific limits on otherwise unconstrained inputs, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work
+ User agents <em class="ct"><em class="rfc2119" title="may">may</em></em> impose implementation-specific limits on otherwise unconstrained inputs, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work
around platform-specific limitations.
</p>
<p>
- When support for a feature is disabled (e.g. as an emergency measure to mitigate a security problem, or to aid in development, or for performance reasons), user agents must act as if
+ When support for a feature is disabled (e.g. as an emergency measure to mitigate a security problem, or to aid in development, or for performance reasons), user agents <em class="ct"><em class="rfc2119" title="must">must</em></em> act as if
they had no support for the feature whatsoever, and as if the feature was not mentioned in this specification. For example, if a particular feature is accessed via an attribute in a Web
IDL interface, the attribute itself would be omitted from the objects that implement that interface - leaving the attribute on the object but making it return null or throw an exception
is insufficient.
@@ -472,7 +477,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 UPnP Event sources. It is only required when the user agent implements UPnP 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> generates and maintains 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>
@@ -560,7 +565,7 @@
<div>
<p>
- When the <dfn id="dom-navigator-getnetworkservices" title="dom-navigator-getnetworkservices"><code>getNetworkServices(type, successCallback[, errorCallback])</code></dfn> method is called, the <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="rfc2119" title="must">must</em> run the following steps:
+ When the <dfn id="dom-navigator-getnetworkservices" title="dom-navigator-getnetworkservices"><code>getNetworkServices(type, successCallback[, errorCallback])</code></dfn> method is called, the <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="ct"><em class="rfc2119" title="must">must</em></em> run the following steps:
</p>
<ol class="rule">
@@ -578,7 +583,7 @@
</li>
<li>
- If <var>requested control types</var> is an array that contains at least one or more <a title="valid service type" href="#dfn-valid-service-type" class="internalDFN">valid service type</a> tokens then continue to the step labeled <em>process</em> below. Otherwise, the <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="rfc2119" title="must">must</em> <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an object of type <code>Function</code>, with a new <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose
+ If <var>requested control types</var> is an array that contains at least one or more <a title="valid service type" href="#dfn-valid-service-type" class="internalDFN">valid service type</a> tokens then continue to the step labeled <em>process</em> below. Otherwise, the <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="ct"><em class="rfc2119" title="must">must</em></em> <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an object of type <code>Function</code>, with a new <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose
<a href="#dom-navigatornetworkserviceerror-code"><code>code</code></a> attribute has the numeric value 2
(<a href="#dom-navigatornetworkserviceerror-unknown_type_prefix"><code>UNKNOWN_TYPE_PREFIX_ERR</code></a>) as its argument,
abort any remaining steps and return.
@@ -614,7 +619,7 @@
</li>
<li>
- If <var>services found</var> is an empty array, then the <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="rfc2119" title="must">must</em> <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an object of type <code>Function</code>, with a new <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose
+ If <var>services found</var> is an empty array, then the <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="ct"><em class="rfc2119" title="must">must</em></em> <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an object of type <code>Function</code>, with a new <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose
<a href="#dom-navigatornetworkserviceerror-code"><code>code</code></a> attribute has the numeric value 1
(<a href="#dom-navigatornetworkserviceerror-permission_denied"><code>PERMISSION_DENIED_ERR</code></a>) as its argument, abort any remaining steps and return.
</li>
@@ -624,13 +629,13 @@
</li>
<li>
- Optionally, e.g. based on a previously-established user preference, for security reasons, or due to platform limitations, the <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="rfc2119" title="may">may</em> <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an object of type <code>Function</code>, with a new <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose
+ Optionally, e.g. based on a previously-established user preference, for security reasons, or due to platform limitations, the <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="ct"><em class="rfc2119" title="may">may</em></em> <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an object of type <code>Function</code>, with a new <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose
<a href="#dom-navigatornetworkserviceerror-code"><code>code</code></a> attribute has the numeric value 1
(<a href="#dom-navigatornetworkserviceerror-permission_denied"><code>PERMISSION_DENIED_ERR</code></a>) as its argument, abort any remaining steps and return.
</li>
<li>
- The <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="rfc2119" title="must">must</em> prompt the user in a user-agent-specific manner for permission to provide the
+ The <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="ct"><em class="rfc2119" title="must">must</em></em> prompt the user in a user-agent-specific manner for permission to provide the
<a href="http://www.whatwg.org/specs/web-apps/current-work/complete/browsers.html#entry-script" class="externalDFN">entry script</a>'s
<a href="http://www.whatwg.org/specs/web-apps/current-work/complete/origin-0.html#origin" class="externalDFN">origin</a> with an array of
<a href="#networkservice"><code>NetworkService</code></a> objects representing the user-authorized subset of <var>services found</var>.
@@ -640,7 +645,7 @@
"ongoing local-network communication" indicator.
</p>
- <p>If the user denies permission, then the <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="rfc2119" title="must">must</em> <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an object of type <code>Function</code>, with a new <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose
+ <p>If the user denies permission, then the <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="ct"><em class="rfc2119" title="must">must</em></em> <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an object of type <code>Function</code>, with a new <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose
<a href="#dom-navigatornetworkserviceerror-code"><code>code</code></a> attribute has the numeric value 1
(<a href="#dom-navigatornetworkserviceerror-permission_denied"><code>PERMISSION_DENIED_ERR</code></a>) as its argument, abort any remaining steps and return.
</p>
@@ -681,7 +686,7 @@
</li>
<li>
- The <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="rfc2119" title="must">must</em> <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>successCallback</var> with
+ The <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="ct"><em class="rfc2119" title="must">must</em></em> <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>successCallback</var> with
<var>services manager</var> as its argument.
</li>
@@ -694,7 +699,7 @@
</p>
<p>
- When a <a href="#networkservice"><code>NetworkService</code></a> object is provided to a Web page, the <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="rfc2119" title="must">must</em> add the <code>url</code> property
+ When a <a href="#networkservice"><code>NetworkService</code></a> object is provided to a Web page, the <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="ct"><em class="rfc2119" title="must">must</em></em> add the <code>url</code> property
to the <dfn id="dfn-entry-script-origin-s-url-whitelist">entry script origin's <abbr title="Uniform Resource Locator">URL</abbr> whitelist</dfn>. This list enables the
Web page to override and initiate cross-site resource requests towards these URLs, and any sub-resources of these URLs, within the current
<a href="http://www.whatwg.org/specs/web-apps/current-work/complete/browsers.html#entry-script" class="externalDFN">entry script</a>'s
@@ -703,7 +708,7 @@
</p>
<p>
- If the user navigates away from the current browsing context, the <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="rfc2119" title="must">must</em> remove all previously whitelisted urls from 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>.
+ If the user navigates away from the current browsing context, the <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="ct"><em class="rfc2119" title="must">must</em></em> remove all previously whitelisted urls from 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>.
There is no persistence to network service selections provided to a web page. It is not possible to access a previously white-listed networked service without the necessary user authorization in all of the following cases:
</p><ul>
<li>If the current script is reloaded at any point in the same or different window.</li>
@@ -729,7 +734,7 @@
</dt>
<dd>
<p>
- Returns the current error's error code. At the current time, this may be <code>1</code> or <code>2</code>, for which the
+ Returns the current error's error code. At the current time, this will be <code>1</code> or <code>2</code>, for which the
corresponding error constants
<a href="#dom-navigatornetworkserviceerror-permission_denied"><code>PERMISSION_DENIED_ERR</code></a> and
<a href="#dom-navigatornetworkserviceerror-unknown_type_prefix"><code>UNKNOWN_TYPE_PREFIX_ERR</code></a> are defined.
@@ -739,7 +744,7 @@
<p>
The <dfn id="dom-navigatornetworkserviceerror-code" title="dom-navigatornetworkserviceerror-code"><code>code</code></dfn> attribute of a
- <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object <em class="rfc2119" title="must">must</em> return the code for the error, which will be one of the following:
+ <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object <em class="ct"><em class="rfc2119" title="must">must</em></em> return the code for the error, which will be one of the following:
</p>
<dl>
@@ -813,11 +818,11 @@
<div>
<p>
- The <dfn id="dom-networkservices-length"><code>length</code></dfn> attribute <em class="rfc2119" title="must">must</em> return the number of services represented in the object's corresponding <a href="#dfn-list-of-authorized-service-records" class="internalDFN">list of authorized service records</a> at the time of getting.
+ The <dfn id="dom-networkservices-length"><code>length</code></dfn> attribute <em class="ct"><em class="rfc2119" title="must">must</em></em> return the number of services represented in the object's corresponding <a href="#dfn-list-of-authorized-service-records" class="internalDFN">list of authorized service records</a> at the time of getting.
</p>
<p>
- The <dfn id="dom-networkservices-servicesavailable"><code>servicesAvailable</code></dfn> attribute <em class="rfc2119" title="must">must</em> return the number of services in the <a href="#dfn-list-of-available-service-records" class="internalDFN">list of available service records</a> whose <code>type</code> attribute matches any of the <a href="#dfn-valid-service-type" class="internalDFN">valid service type</a> tokens that was initially used to create the current <a href="#networkservices"><code>NetworkServices</code></a> object.
+ The <dfn id="dom-networkservices-servicesavailable"><code>servicesAvailable</code></dfn> attribute <em class="ct"><em class="rfc2119" title="must">must</em></em> return the number of services in the <a href="#dfn-list-of-available-service-records" class="internalDFN">list of available service records</a> whose <code>type</code> attribute matches any of the <a href="#dfn-valid-service-type" class="internalDFN">valid service type</a> tokens that was initially used to create the current <a href="#networkservices"><code>NetworkServices</code></a> object.
</p>
</div>
@@ -873,12 +878,12 @@
</p>
<p>
- To <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#determine-the-value-of-an-indexed-property" class="externalDFN">determine the value of an indexed property</a> for a given index <var>index</var> in a <a href="#networkservices"><code>NetworkServices</code></a> object's <a href="#dfn-list-of-authorized-service-records" class="internalDFN">list of authorized service records</a>, the user agent <em class="rfc2119" title="must">must</em> return the <a href="#networkservice"><code>NetworkService</code></a> object that represents the <var>index</var>th service in the <a href="#dfn-list-of-authorized-service-records" class="internalDFN">list of authorized service records</a>.
+ To <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#determine-the-value-of-an-indexed-property" class="externalDFN">determine the value of an indexed property</a> for a given index <var>index</var> in a <a href="#networkservices"><code>NetworkServices</code></a> object's <a href="#dfn-list-of-authorized-service-records" class="internalDFN">list of authorized service records</a>, the user agent <em class="ct"><em class="rfc2119" title="must">must</em></em> return the <a href="#networkservice"><code>NetworkService</code></a> object that represents the <var>index</var>th service in the <a href="#dfn-list-of-authorized-service-records" class="internalDFN">list of authorized service records</a>.
</p>
<p>
- The <dfn id="dom-networkservices-getservicebyid"><code>getServiceById(id)</code></dfn> method <em class="rfc2119" title="must">must</em> return the first <a href="#networkservice"><code>NetworkService</code></a> object in the <a href="#dfn-list-of-authorized-service-records" class="internalDFN">list of authorized service records</a> represented by the respective object whose <a href="#dom-networkservice-id"><code>id</code></a> attribute is equal to the value of the <var>id</var> argument.
- When no services in the <a href="#dfn-list-of-authorized-service-records" class="internalDFN">list of authorized service records</a> match the given argument, the method <em class="rfc2119" title="must">must</em> return null.
+ The <dfn id="dom-networkservices-getservicebyid"><code>getServiceById(id)</code></dfn> method <em class="ct"><em class="rfc2119" title="must">must</em></em> return the first <a href="#networkservice"><code>NetworkService</code></a> object in the <a href="#dfn-list-of-authorized-service-records" class="internalDFN">list of authorized service records</a> represented by the respective object whose <a href="#dom-networkservice-id"><code>id</code></a> attribute is equal to the value of the <var>id</var> argument.
+ When no services in the <a href="#dfn-list-of-authorized-service-records" class="internalDFN">list of authorized service records</a> match the given argument, the method <em class="ct"><em class="rfc2119" title="must">must</em></em> return null.
</p>
<p>
@@ -893,7 +898,7 @@
<h3><span class="secno">5.3 </span>Events</h3>
<p>
- The following are the event handlers (and their corresponding event handler event types) that must be supported, as IDL attributes, by all objects implementing the <a href="#networkservices"><code>NetworkServices</code></a> interface:
+ The following are the event handlers (and their corresponding event handler event types) that <em class="ct"><em class="rfc2119" title="must">must</em></em> be supported, as IDL attributes, by all objects implementing the <a href="#networkservices"><code>NetworkServices</code></a> interface:
</p>
<table border="1">
@@ -915,8 +920,8 @@
</dfn>
</td>
<td>
- <code title="event-serviceavailable">serviceavailable</code>
- </td>
+ <a href="#event-serviceavailable"><code>serviceavailable</code>
+ </a></td>
</tr>
<tr>
<td>
@@ -925,16 +930,12 @@
</dfn>
</td>
<td>
- <code title="event-serviceunavailable">serviceunavailable</code>
+ <a href="#event-serviceunavailable"><code>serviceunavailable</code></a>
</td>
</tr>
</tbody>
</table>
- <p>
- Events with an event type of <code>serviceavailable</code> or <code>serviceunavailable</code> defined in this specification are simple <code>Event</code> objects.
- </p>
-
</section>
</section>
@@ -1032,7 +1033,7 @@
</dl>
<p>
- The <dfn id="dom-networkservice-id"><code>id</code></dfn> attribute is a unique identifier for the service. The same service provided at different times or on different objects <em class="rfc2119" title="must">must</em> have the same <a href="#dom-networkservice-id"><code>id</code></a> value.
+ The <dfn id="dom-networkservice-id"><code>id</code></dfn> attribute is a unique identifier for the service. The same service provided at different times or on different objects <em class="ct"><em class="rfc2119" title="must">must</em></em> have the same <a href="#dom-networkservice-id"><code>id</code></a> value.
</p>
<p>
@@ -1074,7 +1075,7 @@
<p>
The <dfn id="dom-networkservice-online"><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 <em class="rfc2119" title="must">must</em> default to <code>true</code>.
+ 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 <em class="ct"><em class="rfc2119" title="must">must</em></em> default to <code>true</code>.
</p>
</section>
@@ -1083,7 +1084,7 @@
<h3><span class="secno">6.3 </span>Events</h3>
<p>
- The following are the event handlers (and their corresponding event handler event types) that must be supported, as IDL attributes, by all objects implementing the
+ The following are the event handlers (and their corresponding event handler event types) that <em class="ct"><em class="rfc2119" title="must">must</em></em> be supported, as IDL attributes, by all objects implementing the
<a href="#networkservice"><code>NetworkService</code></a> interface:
</p>
@@ -1106,7 +1107,7 @@
</dfn>
</td>
<td>
- <code title="event-notify">notify</code>
+ <a href="#event-notify"><code>notify</code></a>
</td>
</tr>
<tr>
@@ -1116,7 +1117,7 @@
</dfn>
</td>
<td>
- <code title="event-onserviceonline">serviceonline</code>
+ <a href="#event-serviceonline"><code>serviceonline</code></a>
</td>
</tr>
<tr>
@@ -1126,16 +1127,12 @@
</dfn>
</td>
<td>
- <code title="event-onserviceoffline">serviceoffline</code>
+ <a href="#event-serviceoffline"><code>serviceoffline</code></a>
</td>
</tr>
</tbody>
</table>
- <p>
- 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>
</section>
@@ -1143,8 +1140,8 @@
<!--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"><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.
+ A <a href="#dfn-user-agent" class="internalDFN">user agent</a> conforming to this specification <em class="ct"><em class="rfc2119" title="may">may</em></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="ct"><em class="rfc2119" title="must">must</em></em> conform to the corresponding algorithms provided in this section of the specification.
</p>
<p>
This section presents how the results of these two service discovery
@@ -1160,7 +1157,7 @@
<p>
The <dfn id="dfn-list-of-available-service-records">list of available service records</dfn> is a single dynamic internal lookup table within user agents that is used to track all the services that have been discovered and are available in the current network at any given time.
At any point during the running of either of the two service discovery mechanisms then existing entries within this table can be updated, entries can be added and entries can be removed as the status of networked
- services changes according to the rules defined in this specification. <!--Each record contained within this table contains the attributes: <code>id</code>, <code>deviceId</code>, <code>name</code>, <code>type</code>, <code>url</code>, <code>config</code> and <code>expiryTimestamp</code>.-->
+ services changes according to the rules defined in this specification.
</p>
<p>
@@ -1218,14 +1215,16 @@
If the <var>new service registration flag</var> is set to <code>true</code> then increment the <a href="#dom-networkservices-servicesavailable"><code>servicesAvailable</code></a> attribute of the <var>services manager</var> associated with
the current <var>active service</var>
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 <a href="#dom-networkservices-onserviceavailable"><code>serviceavailable</code></a> that uses the <code>Event</code> interface,
+ to dispatch a newly created event with the name <a href="#event-serviceavailable"><code>serviceavailable</code></a> that uses the <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event" class="externalDFN"><code>Event</code></a> interface,
which does not bubble, is not cancellable, and has no default action, at the <var>services manager</var> associated with
the current <var>active service</var> 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 <a href="#dom-networkservice-onserviceonline"><code>serviceonline</code></a> that uses the <code>Event</code> interface, which
+ Set <var>active service</var>'s <a href="#dom-networkservice-online"><code>online</code></a> attribute to <code>true</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 <a href="#event-serviceonline"><code>serviceonline</code></a> that uses the
+ <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event" class="externalDFN"><code>Event</code></a> interface, which
does not bubble, is not cancellable, and has no default action, at the current
<var>active service</var> object.
</li>
@@ -1273,14 +1272,17 @@
Decrement the <a href="#dom-networkservices-servicesavailable"><code>servicesAvailable</code></a> attribute of the
<var>services manager</var> associated with the current <var>active service</var>
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 <a href="#dom-networkservices-onserviceunavailable"><code>serviceunavailable</code></a> that uses the <code>Event</code> interface,
+ to dispatch a newly created event with the name <a href="#event-serviceunavailable"><code>serviceunavailable</code></a> that uses the
+ <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event" class="externalDFN"><code>Event</code></a> interface,
which does not bubble, is not cancellable, and has no default action, at the <var>services manager</var> associated with
the current <var>active service</var> 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 <a href="#dom-networkservice-onserviceoffline"><code>serviceoffline</code></a> that uses the <code>Event</code> interface, which
+ Set <var>active service</var>'s <a href="#dom-networkservice-online"><code>online</code></a> attribute to <code>false</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 <a href="#event-serviceoffline"><code>serviceoffline</code></a> that uses the
+ <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event" class="externalDFN"><code>Event</code></a> interface, which
does not bubble, is not cancellable, and has no default action, at the current
<var>active service</var> object.
</li>
@@ -1311,7 +1313,7 @@
<p>
For each <abbr title="Domain Name System">DNS</abbr> response received from a user-agent-initiated Multicast <abbr title="Domain Name System">DNS</abbr> Browse for <abbr title="DNS Pointer Record">PTR</abbr> records with the name <code>_services._dns-sd._udp</code> on the resolved recommended automatic browsing
- domain [<cite><a class="bibref" href="#bib-MDNS">MDNS</a></cite>], the <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="rfc2119" title="must">must</em> run the following steps:
+ domain [<cite><a class="bibref" href="#bib-MDNS">MDNS</a></cite>], the <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="ct"><em class="rfc2119" title="must">must</em></em> run the following steps:
</p>
<ol class="rule">
@@ -1364,7 +1366,7 @@
<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 UPnP service discovery must issue an <dfn id="dfn-advertisement-for-upnp-root-devices">advertisement for UPnP root devices</dfn> against the user's
+ A user agent that implements UPnP service discovery <em class="ct"><em class="rfc2119" title="must">must</em></em> 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>
@@ -1395,11 +1397,11 @@
</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>ST</var> entry and at least one <var>LOCATION</var> entry or the value of its <var>ST</var> entry is not <code>upnp:rootdevice</code>, 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.
+ 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>ST</var> entry and at least one <var>LOCATION</var> entry or the value of its <var>ST</var> entry is not <code>upnp:rootdevice</code>, 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="ct"><em class="rfc2119" title="must">must</em></em> discard this response, abort any remaining steps and return.
</li>
<li>
- 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.
+ 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 <abbr title="Uniform Resource Locator">URL</abbr></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>
@@ -1419,11 +1421,11 @@
</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 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.
+ 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="ct"><em class="rfc2119" title="must">must</em></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-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 fro 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"><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 <abbr title="Uniform Resource Locator">URL</abbr></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-devce" 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>
@@ -1440,7 +1442,7 @@
</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.
+ 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="ct"><em class="rfc2119" title="must">must</em></em> abort any remaining steps and return.
</li>
<li>
@@ -1448,7 +1450,7 @@
</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>
+ 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="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 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>
@@ -1547,7 +1549,7 @@
<ol class="rule">
<li>
- If <var>network service record</var>'s <code>eventsUrl</code> property is empty then the <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="rfc2119" title="must">must</em> abort these steps.
+ If <var>network service record</var>'s <code>eventsUrl</code> property is empty then the <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="ct"><em class="rfc2119" title="must">must</em></em> abort these steps.
</li>
<li>
@@ -1560,7 +1562,7 @@
</li>
<li>
- If a non-200 OK response is received from the <abbr title="Hypertext Transfer Protocol">HTTP</abbr> SUBSCRIBE request then the <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="rfc2119" title="must">must</em> abort these steps.
+ If a non-200 OK response is received from the <abbr title="Hypertext Transfer Protocol">HTTP</abbr> SUBSCRIBE request then the <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="ct"><em class="rfc2119" title="must">must</em></em> abort these steps.
</li>
<li>
@@ -1602,10 +1604,12 @@
<ol class="rule">
<li>
- Let <var>content clone</var> be the result of obtaining the message body of the <abbr title="Hypertext Transfer Protocol">HTTP</abbr> NOTIFY request. If <var>content clone</var> is empty, then the <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="rfc2119" title="must">must</em> abort these steps.
+ Let <var>content clone</var> be the result of obtaining the message body of the <abbr title="Hypertext Transfer Protocol">HTTP</abbr> NOTIFY request. If <var>content clone</var> is empty, then the <a href="#dfn-user-agent" class="internalDFN">user agent</a> <em class="ct"><em class="rfc2119" title="must">must</em></em> abort these steps.
</li>
<li>
- Let <var>notification event</var> be a new simple event that uses the <code>Event</code> interface with the name <code>notify</code>,
+ Let <var>notification event</var> be a new simple event that uses the
+ <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event" class="externalDFN"><code>Event</code></a>
+ interface with the name <a href="#event-notify"><code>notify</code></a>,
which does not bubble, is not cancellable, and has no default action.
</li>
<li>
@@ -1650,18 +1654,108 @@
</section>
</section>
+ <section id="events-summary">
+ <!--OddPage--><h2><span class="secno">8. </span>Events Summary</h2>
+
+ <p>The following events are dispatched on the <a href="#networkservices"><code>NetworkServices</code></a> and/or <a href="#networkservice"><code>NetworkService</code></a> objects:</p>
+
+ <table border="1">
+ <thead>
+ <tr>
+ <th>
+ <span title="event handlers">Event name</span>
+ </th>
+ <th>
+ <span>Interface</span>
+ </th>
+ <th>
+ <span>Dispatched when...</span>
+ </th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>
+ <dfn id="event-serviceavailable">
+ <code>serviceavailable</code>
+ </dfn>
+ </td>
+ <td>
+ <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event" class="externalDFN"><code>Event</code></a>
+ </td>
+ <td>
+ When a new service that matches one of the <a>requested type tokens</a> is found in the current network.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <dfn id="event-serviceunavailable">
+ <code>serviceunavailable</code>
+ </dfn>
+ </td>
+ <td>
+ <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event" class="externalDFN"><code>Event</code></a>
+ </td>
+ <td>
+ When an existing service that matches one of the <a>requested type tokens</a> gracefully leaves or expires from the current network.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <dfn id="event-serviceonline">
+ <code>serviceonline</code>
+ </dfn>
+ </td>
+ <td>
+ <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event" class="externalDFN"><code>Event</code></a>
+ </td>
+ <td>
+ When a current service renews its service registration within the current network.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <dfn id="event-serviceoffline">
+ <code>serviceoffline</code>
+ </dfn>
+ </td>
+ <td>
+ <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event" class="externalDFN"><code>Event</code></a>
+ </td>
+ <td>
+ When a current service gracefully leaves or otherwise expires from the current network.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <dfn id="event-notify">
+ <code>notify</code>
+ </dfn>
+ </td>
+ <td>
+ <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event" class="externalDFN"><code>Event</code></a>
+ </td>
+ <td>
+ When a valid UPnP Events Subscription Message is received on a <a href="#dfn-user-agent-generated-callback-url" class="internalDFN">user-agent generated callback url</a> for a current service. This event never fires for Zeroconf-based services.
+ </td>
+ </tr>
+ </tbody>
+ </table>
+
+ </section>
+
<section id="garbage-collection">
- <!--OddPage--><h2><span class="secno">8. </span>Garbage collection</h2>
+ <!--OddPage--><h2><span class="secno">9. </span>Garbage collection</h2>
<p>
- Only when the user navigates away from the current browsing context can <a href="#networkservice" class="internalDFN"><code>NetworkService</code></a> objects be garbage-collected, its records in 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> be removed and its corresponding entry in the <a href="#dfn-list-of-authorized-service-records" class="internalDFN">list of authorized service records</a> be removed.
+ Only when the user navigates away from the current browsing context can <a href="#networkservice" class="internalDFN"><code>NetworkService</code></a> objects be garbage-collected, its records in 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> be removed and its corresponding entry in the <a href="#dfn-list-of-authorized-service-records" class="internalDFN">list of authorized service records</a> be removed according to passing each expired object identifier through the rule for <a href="#dfn-removing-an-available-service" class="internalDFN">removing an available service</a>.
</p>
</section>
<section id="use-cases-and-requirements">
- <!--OddPage--><h2><span class="secno">9. </span>Use Cases and Requirements</h2>
+ <!--OddPage--><h2><span class="secno">10. </span>Use Cases and Requirements</h2>
<p>This section covers what the requirements are for this <abbr title="Application Programming Interface">API</abbr>, as well as illustrates some use cases.</p>
diff -r 7729986a7295 -r 65e14f8dc95d discovery-api/Overview.src.html
--- a/discovery-api/Overview.src.html Mon Oct 01 15:26:54 2012 -0400
+++ b/discovery-api/Overview.src.html Tue Oct 02 14:51:33 2012 +0200
@@ -60,6 +60,11 @@
dl.domintro dd p { margin: 0.5em 0; }
dl.domintro code {font-size: inherit; font-style: italic; }
dl.domintro:before { display: table; margin: -1em -0.5em 0.5em auto; width: auto; content: 'This box is non-normative. Implementation requirements are given below this box.'; color: red; border: solid 2px; background: white; padding: 0 0.25em; }
+
+ table { border-collapse:collapse; border-style:hidden hidden none hidden }
+ table thead { border-bottom:solid }
+ table tbody th:first-child { border-left:solid }
+ table td, table th { border-left:solid; border-right:solid; border-bottom:solid thin; vertical-align:top; padding:0.2em }
</style>
</head>
@@ -165,7 +170,7 @@
</p>
<p>
- Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in
+ Conformance requirements phrased as algorithms or specific steps <em class="ct">MAY</em> be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in
this specification are intended to be easy to follow, and not intended to be performant.)
</p>
@@ -174,12 +179,12 @@
</p>
<p>
- User agents may impose implementation-specific limits on otherwise unconstrained inputs, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work
+ User agents <em class="ct">MAY</em> impose implementation-specific limits on otherwise unconstrained inputs, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work
around platform-specific limitations.
</p>
<p>
- When support for a feature is disabled (e.g. as an emergency measure to mitigate a security problem, or to aid in development, or for performance reasons), user agents must act as if
+ When support for a feature is disabled (e.g. as an emergency measure to mitigate a security problem, or to aid in development, or for performance reasons), user agents <em class="ct">MUST</em> act as if
they had no support for the feature whatsoever, and as if the feature was not mentioned in this specification. For example, if a particular feature is accessed via an attribute in a Web
IDL interface, the attribute itself would be omitted from the objects that implement that interface - leaving the attribute on the object but making it return null or throw an exception
is insufficient.
@@ -225,7 +230,7 @@
</p>
<p>
- A <dfn>user-agent generated callback url</dfn> is a Local-network accessible URL endpoint that a <a>user agent</a> must generate and maintain for receiving HTTP NOTIFY requests from UPnP Event sources. It is only required when the user agent implements UPnP Service Discovery as defined in
+ A <dfn>user-agent generated callback url</dfn> is a Local-network accessible URL endpoint that a <a>user agent</a> generates and maintains for receiving HTTP NOTIFY requests from UPnP Event sources. It is only required when the user agent implements UPnP Service Discovery as defined in
this specification.
</p>
@@ -313,7 +318,7 @@
<div>
<p>
- When the <dfn id="dom-navigator-getnetworkservices" title="dom-navigator-getnetworkservices"><code>getNetworkServices(type, successCallback[, errorCallback])</code></dfn> method is called, the <a>user agent</a> MUST run the following steps:
+ When the <dfn id="dom-navigator-getnetworkservices" title="dom-navigator-getnetworkservices"><code>getNetworkServices(type, successCallback[, errorCallback])</code></dfn> method is called, the <a>user agent</a> <em class="ct">MUST</em> run the following steps:
</p>
<ol class="rule">
@@ -331,7 +336,7 @@
</li>
<li>
- If <var>requested control types</var> is an array that contains at least one or more <a title="valid service type">valid service type</a> tokens then continue to the step labeled <em>process</em> below. Otherwise, the <a>user agent</a> MUST <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an object of type <code>Function</code>, with a new <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose
+ If <var>requested control types</var> is an array that contains at least one or more <a title="valid service type">valid service type</a> tokens then continue to the step labeled <em>process</em> below. Otherwise, the <a>user agent</a> <em class="ct">MUST</em> <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an object of type <code>Function</code>, with a new <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose
<a href="#dom-navigatornetworkserviceerror-code"><code>code</code></a> attribute has the numeric value 2
(<a href="#dom-navigatornetworkserviceerror-unknown_type_prefix"><code>UNKNOWN_TYPE_PREFIX_ERR</code></a>) as its argument,
abort any remaining steps and return.
@@ -367,7 +372,7 @@
</li>
<li>
- If <var>services found</var> is an empty array, then the <a>user agent</a> MUST <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an object of type <code>Function</code>, with a new <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose
+ If <var>services found</var> is an empty array, then the <a>user agent</a> <em class="ct">MUST</em> <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an object of type <code>Function</code>, with a new <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose
<a href="#dom-navigatornetworkserviceerror-code"><code>code</code></a> attribute has the numeric value 1
(<a href="#dom-navigatornetworkserviceerror-permission_denied"><code>PERMISSION_DENIED_ERR</code></a>) as its argument, abort any remaining steps and return.
</li>
@@ -377,13 +382,13 @@
</li>
<li>
- Optionally, e.g. based on a previously-established user preference, for security reasons, or due to platform limitations, the <a>user agent</a> MAY <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an object of type <code>Function</code>, with a new <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose
+ Optionally, e.g. based on a previously-established user preference, for security reasons, or due to platform limitations, the <a>user agent</a> <em class="ct">MAY</em> <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an object of type <code>Function</code>, with a new <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose
<a href="#dom-navigatornetworkserviceerror-code"><code>code</code></a> attribute has the numeric value 1
(<a href="#dom-navigatornetworkserviceerror-permission_denied"><code>PERMISSION_DENIED_ERR</code></a>) as its argument, abort any remaining steps and return.
</li>
<li>
- The <a>user agent</a> MUST prompt the user in a user-agent-specific manner for permission to provide the
+ The <a>user agent</a> <em class="ct">MUST</em> prompt the user in a user-agent-specific manner for permission to provide the
<a href="http://www.whatwg.org/specs/web-apps/current-work/complete/browsers.html#entry-script" class="externalDFN">entry script</a>'s
<a href="http://www.whatwg.org/specs/web-apps/current-work/complete/origin-0.html#origin" class="externalDFN">origin</a> with an array of
<a href="#networkservice"><code>NetworkService</code></a> objects representing the user-authorized subset of <var>services found</var>.
@@ -393,7 +398,7 @@
"ongoing local-network communication" indicator.
</p>
- <p>If the user denies permission, then the <a>user agent</a> MUST <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an object of type <code>Function</code>, with a new <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose
+ <p>If the user denies permission, then the <a>user agent</a> <em class="ct">MUST</em> <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an object of type <code>Function</code>, with a new <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose
<a href="#dom-navigatornetworkserviceerror-code"><code>code</code></a> attribute has the numeric value 1
(<a href="#dom-navigatornetworkserviceerror-permission_denied"><code>PERMISSION_DENIED_ERR</code></a>) as its argument, abort any remaining steps and return.
</p>
@@ -434,7 +439,7 @@
</li>
<li>
- The <a>user agent</a> MUST <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>successCallback</var> with
+ The <a>user agent</a> <em class="ct">MUST</em> <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>successCallback</var> with
<var>services manager</var> as its argument.
</li>
@@ -447,7 +452,7 @@
</p>
<p>
- When a <a href="#networkservice"><code>NetworkService</code></a> object is provided to a Web page, the <a>user agent</a> MUST add the <code>url</code> property
+ When a <a href="#networkservice"><code>NetworkService</code></a> object is provided to a Web page, the <a>user agent</a> <em class="ct">MUST</em> add the <code>url</code> property
to the <dfn>entry script origin's URL whitelist</dfn>. This list enables the
Web page to override and initiate cross-site resource requests towards these URLs, and any sub-resources of these URLs, within the current
<a href="http://www.whatwg.org/specs/web-apps/current-work/complete/browsers.html#entry-script" class="externalDFN">entry script</a>'s
@@ -456,7 +461,7 @@
</p>
<p>
- If the user navigates away from the current browsing context, the <a>user agent</a> MUST remove all previously whitelisted urls from the <a>entry script origin's URL whitelist</a>.
+ If the user navigates away from the current browsing context, the <a>user agent</a> <em class="ct">MUST</em> remove all previously whitelisted urls from the <a>entry script origin's URL whitelist</a>.
There is no persistence to network service selections provided to a web page. It is not possible to access a previously white-listed networked service without the necessary user authorization in all of the following cases:
<ul>
<li>If the current script is reloaded at any point in the same or different window.</li>
@@ -482,7 +487,7 @@
</dt>
<dd>
<p>
- Returns the current error's error code. At the current time, this may be <code>1</code> or <code>2</code>, for which the
+ Returns the current error's error code. At the current time, this will be <code>1</code> or <code>2</code>, for which the
corresponding error constants
<a href="#dom-navigatornetworkserviceerror-permission_denied"><code>PERMISSION_DENIED_ERR</code></a> and
<a href="#dom-navigatornetworkserviceerror-unknown_type_prefix"><code>UNKNOWN_TYPE_PREFIX_ERR</code></a> are defined.
@@ -492,7 +497,7 @@
<p>
The <dfn id="dom-navigatornetworkserviceerror-code" title="dom-navigatornetworkserviceerror-code"><code>code</code></dfn> attribute of a
- <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object MUST return the code for the error, which will be one of the following:
+ <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object <em class="ct">MUST</em> return the code for the error, which will be one of the following:
</p>
<dl>
@@ -567,11 +572,11 @@
<div>
<p>
- The <dfn id="dom-networkservices-length"><code>length</code></dfn> attribute MUST return the number of services represented in the object's corresponding <a>list of authorized service records</a> at the time of getting.
+ The <dfn id="dom-networkservices-length"><code>length</code></dfn> attribute <em class="ct">MUST</em> return the number of services represented in the object's corresponding <a>list of authorized service records</a> at the time of getting.
</p>
<p>
- The <dfn id="dom-networkservices-servicesavailable"><code>servicesAvailable</code></dfn> attribute MUST return the number of services in the <a>list of available service records</a> whose <code>type</code> attribute matches any of the <a>valid service type</a> tokens that was initially used to create the current <a href="#networkservices"><code>NetworkServices</code></a> object.
+ The <dfn id="dom-networkservices-servicesavailable"><code>servicesAvailable</code></dfn> attribute <em class="ct">MUST</em> return the number of services in the <a>list of available service records</a> whose <code>type</code> attribute matches any of the <a>valid service type</a> tokens that was initially used to create the current <a href="#networkservices"><code>NetworkServices</code></a> object.
</p>
</div>
@@ -627,12 +632,12 @@
</p>
<p>
- To <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#determine-the-value-of-an-indexed-property" class="externalDFN">determine the value of an indexed property</a> for a given index <var>index</var> in a <a href="#networkservices"><code>NetworkServices</code></a> object's <a>list of authorized service records</a>, the user agent MUST return the <a href="#networkservice"><code>NetworkService</code></a> object that represents the <var>index</var>th service in the <a>list of authorized service records</a>.
+ To <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#determine-the-value-of-an-indexed-property" class="externalDFN">determine the value of an indexed property</a> for a given index <var>index</var> in a <a href="#networkservices"><code>NetworkServices</code></a> object's <a>list of authorized service records</a>, the user agent <em class="ct">MUST</em> return the <a href="#networkservice"><code>NetworkService</code></a> object that represents the <var>index</var>th service in the <a>list of authorized service records</a>.
</p>
<p>
- The <dfn id="dom-networkservices-getservicebyid"><code>getServiceById(id)</code></dfn> method MUST return the first <a href="#networkservice"><code>NetworkService</code></a> object in the <a>list of authorized service records</a> represented by the respective object whose <a href="#dom-networkservice-id"><code>id</code></a> attribute is equal to the value of the <var>id</var> argument.
- When no services in the <a>list of authorized service records</a> match the given argument, the method MUST return null.
+ The <dfn id="dom-networkservices-getservicebyid"><code>getServiceById(id)</code></dfn> method <em class="ct">MUST</em> return the first <a href="#networkservice"><code>NetworkService</code></a> object in the <a>list of authorized service records</a> represented by the respective object whose <a href="#dom-networkservice-id"><code>id</code></a> attribute is equal to the value of the <var>id</var> argument.
+ When no services in the <a>list of authorized service records</a> match the given argument, the method <em class="ct">MUST</em> return null.
</p>
<p>
@@ -647,7 +652,7 @@
<h2>Events</h2>
<p>
- The following are the event handlers (and their corresponding event handler event types) that must be supported, as IDL attributes, by all objects implementing the <a href="#networkservices"><code>NetworkServices</code></a> interface:
+ The following are the event handlers (and their corresponding event handler event types) that <em class="ct">MUST</em> be supported, as IDL attributes, by all objects implementing the <a href="#networkservices"><code>NetworkServices</code></a> interface:
</p>
<table border="1">
@@ -669,7 +674,7 @@
</dfn>
</td>
<td>
- <code title="event-serviceavailable">serviceavailable</code>
+ <a href="#event-serviceavailable"><code>serviceavailable</code>
</td>
</tr>
<tr>
@@ -679,16 +684,12 @@
</dfn>
</td>
<td>
- <code title="event-serviceunavailable">serviceunavailable</code>
+ <a href="#event-serviceunavailable"><code>serviceunavailable</code></a>
</td>
</tr>
</tbody>
</table>
- <p>
- Events with an event type of <code>serviceavailable</code> or <code>serviceunavailable</code> defined in this specification are simple <code>Event</code> objects.
- </p>
-
</section>
</section>
@@ -787,7 +788,7 @@
</dl>
<p>
- The <dfn id="dom-networkservice-id"><code>id</code></dfn> attribute is a unique identifier for the service. The same service provided at different times or on different objects MUST have the same <a href="#dom-networkservice-id"><code>id</code></a> value.
+ The <dfn id="dom-networkservice-id"><code>id</code></dfn> attribute is a unique identifier for the service. The same service provided at different times or on different objects <em class="ct">MUST</em> have the same <a href="#dom-networkservice-id"><code>id</code></a> value.
</p>
<p>
@@ -829,7 +830,7 @@
<p>
The <dfn id="dom-networkservice-online"><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>.
+ 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 <em class="ct">MUST</em> default to <code>true</code>.
</p>
</section>
@@ -838,7 +839,7 @@
<h3>Events</h3>
<p>
- The following are the event handlers (and their corresponding event handler event types) that must be supported, as IDL attributes, by all objects implementing the
+ The following are the event handlers (and their corresponding event handler event types) that <em class="ct">MUST</em> be supported, as IDL attributes, by all objects implementing the
<a href="#networkservice"><code>NetworkService</code></a> interface:
</p>
@@ -861,7 +862,7 @@
</dfn>
</td>
<td>
- <code title="event-notify">notify</code>
+ <a href="#event-notify"><code>notify</code></a>
</td>
</tr>
<tr>
@@ -871,7 +872,7 @@
</dfn>
</td>
<td>
- <code title="event-onserviceonline">serviceonline</code>
+ <a href="#event-serviceonline"><code>serviceonline</code></a>
</td>
</tr>
<tr>
@@ -881,16 +882,12 @@
</dfn>
</td>
<td>
- <code title="event-onserviceoffline">serviceoffline</code>
+ <a href="#event-serviceoffline"><code>serviceoffline</code></a>
</td>
</tr>
</tbody>
</table>
- <p>
- 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>
</section>
@@ -898,8 +895,8 @@
<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-DEVICEARCH11]] 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.
+ A <a>user agent</a> conforming to this specification <em class="ct">MAY</em> implement <acronym title="Simple Service Discovery Protocol">SSDP</acronym> [[!UPNP-DEVICEARCH11]] 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 <em class="ct">MUST</em> conform to the corresponding algorithms provided in this section of the specification.
</p>
<p>
This section presents how the results of these two service discovery
@@ -915,7 +912,7 @@
<p>
The <dfn>list of available service records</dfn> is a single dynamic internal lookup table within user agents that is used to track all the services that have been discovered and are available in the current network at any given time.
At any point during the running of either of the two service discovery mechanisms then existing entries within this table can be updated, entries can be added and entries can be removed as the status of networked
- services changes according to the rules defined in this specification. <!--Each record contained within this table contains the attributes: <code>id</code>, <code>deviceId</code>, <code>name</code>, <code>type</code>, <code>url</code>, <code>config</code> and <code>expiryTimestamp</code>.-->
+ services changes according to the rules defined in this specification.
</p>
<p>
@@ -973,14 +970,16 @@
If the <var>new service registration flag</var> is set to <code>true</code> then increment the <a href="#dom-networkservices-servicesavailable"><code>servicesAvailable</code></a> attribute of the <var>services manager</var> associated with
the current <var>active service</var>
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 <a href="#dom-networkservices-onserviceavailable"><code>serviceavailable</code></a> that uses the <code>Event</code> interface,
+ to dispatch a newly created event with the name <a href="#event-serviceavailable"><code>serviceavailable</code></a> that uses the <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event" class="externalDFN"><code>Event</code></a> interface,
which does not bubble, is not cancellable, and has no default action, at the <var>services manager</var> associated with
the current <var>active service</var> 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 <a href="#dom-networkservice-onserviceonline"><code>serviceonline</code></a> that uses the <code>Event</code> interface, which
+ Set <var>active service</var>'s <a href="#dom-networkservice-online"><code>online</code></a> attribute to <code>true</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 <a href="#event-serviceonline"><code>serviceonline</code></a> that uses the
+ <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event" class="externalDFN"><code>Event</code></a> interface, which
does not bubble, is not cancellable, and has no default action, at the current
<var>active service</var> object.
</li>
@@ -1028,14 +1027,17 @@
Decrement the <a href="#dom-networkservices-servicesavailable"><code>servicesAvailable</code></a> attribute of the
<var>services manager</var> associated with the current <var>active service</var>
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 <a href="#dom-networkservices-onserviceunavailable"><code>serviceunavailable</code></a> that uses the <code>Event</code> interface,
+ to dispatch a newly created event with the name <a href="#event-serviceunavailable"><code>serviceunavailable</code></a> that uses the
+ <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event" class="externalDFN"><code>Event</code></a> interface,
which does not bubble, is not cancellable, and has no default action, at the <var>services manager</var> associated with
the current <var>active service</var> 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 <a href="#dom-networkservice-onserviceoffline"><code>serviceoffline</code></a> that uses the <code>Event</code> interface, which
+ Set <var>active service</var>'s <a href="#dom-networkservice-online"><code>online</code></a> attribute to <code>false</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 <a href="#event-serviceoffline"><code>serviceoffline</code></a> that uses the
+ <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event" class="externalDFN"><code>Event</code></a> interface, which
does not bubble, is not cancellable, and has no default action, at the current
<var>active service</var> object.
</li>
@@ -1066,7 +1068,7 @@
<p>
For each DNS response received from a user-agent-initiated Multicast DNS Browse for <abbr title="DNS Pointer Record">PTR</abbr> records with the name <code>_services._dns-sd._udp</code> on the resolved recommended automatic browsing
- domain [[!MDNS]], the <a>user agent</a> MUST run the following steps:
+ domain [[!MDNS]], the <a>user agent</a> <em class="ct">MUST</em> run the following steps:
</p>
<ol class="rule">
@@ -1119,7 +1121,7 @@
<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
+ A user agent that implements UPnP service discovery <em class="ct">MUST</em> issue an <dfn>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 [[!UPNP-DEVICEARCH11]].
</p>
@@ -1150,11 +1152,11 @@
</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>ST</var> entry and at least one <var>LOCATION</var> entry or the value of its <var>ST</var> entry is not <code>upnp:rootdevice</code>, then the <a>HTTP Response</a> is invalid and the <a>user agent</a> MUST discard this response, 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>ST</var> entry and at least one <var>LOCATION</var> entry or the value of its <var>ST</var> entry is not <code>upnp:rootdevice</code>, then the <a>HTTP Response</a> is invalid and the <a>user agent</a> <em class="ct">MUST</em> discard this response, abort any remaining steps and return.
</li>
<li>
- 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.
+ 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 URL</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>
@@ -1174,11 +1176,11 @@
</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>HTTP Request</a> is a malformed UPnP Request and the <a>user agent</a> MUST 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>HTTP Request</a> is a malformed UPnP Request and the <a>user agent</a> <em class="ct">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">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.
+ 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 URL</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>
@@ -1195,7 +1197,7 @@
</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.
+ 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> <em class="ct">MUST</em> abort any remaining steps and return.
</li>
<li>
@@ -1203,7 +1205,7 @@
</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
+ 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="ct">MUST</em>
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>
@@ -1302,7 +1304,7 @@
<ol class="rule">
<li>
- If <var>network service record</var>'s <code>eventsUrl</code> property is empty then the <a>user agent</a> MUST abort these steps.
+ If <var>network service record</var>'s <code>eventsUrl</code> property is empty then the <a>user agent</a> <em class="ct">MUST</em> abort these steps.
</li>
<li>
@@ -1315,7 +1317,7 @@
</li>
<li>
- If a non-200 OK response is received from the HTTP SUBSCRIBE request then the <a>user agent</a> MUST abort these steps.
+ If a non-200 OK response is received from the HTTP SUBSCRIBE request then the <a>user agent</a> <em class="ct">MUST</em> abort these steps.
</li>
<li>
@@ -1357,10 +1359,12 @@
<ol class="rule">
<li>
- 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.
+ 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> <em class="ct">MUST</em> abort these steps.
</li>
<li>
- Let <var>notification event</var> be a new simple event that uses the <code>Event</code> interface with the name <code>notify</code>,
+ Let <var>notification event</var> be a new simple event that uses the
+ <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event" class="externalDFN"><code>Event</code></a>
+ interface with the name <a href="#event-notify"><code>notify</code></a>,
which does not bubble, is not cancellable, and has no default action.
</li>
<li>
@@ -1405,11 +1409,101 @@
</section>
</section>
+ <section>
+ <h3>Events Summary</h3>
+
+ <p>The following events are dispatched on the <a href="#networkservices"><code>NetworkServices</code></a> and/or <a href="#networkservice"><code>NetworkService</code></a> objects:</p>
+
+ <table border="1">
+ <thead>
+ <tr>
+ <th>
+ <span title="event handlers">Event name</span>
+ </th>
+ <th>
+ <span>Interface</span>
+ </th>
+ <th>
+ <span>Dispatched when...</span>
+ </th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>
+ <dfn id="event-serviceavailable">
+ <code>serviceavailable</code>
+ </dfn>
+ </td>
+ <td>
+ <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event" class="externalDFN"><code>Event</code></a>
+ </td>
+ <td>
+ When a new service that matches one of the <a>requested type tokens</a> is found in the current network.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <dfn id="event-serviceunavailable">
+ <code>serviceunavailable</code>
+ </dfn>
+ </td>
+ <td>
+ <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event" class="externalDFN"><code>Event</code></a>
+ </td>
+ <td>
+ When an existing service that matches one of the <a>requested type tokens</a> gracefully leaves or expires from the current network.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <dfn id="event-serviceonline">
+ <code>serviceonline</code>
+ </dfn>
+ </td>
+ <td>
+ <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event" class="externalDFN"><code>Event</code></a>
+ </td>
+ <td>
+ When a current service renews its service registration within the current network.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <dfn id="event-serviceoffline">
+ <code>serviceoffline</code>
+ </dfn>
+ </td>
+ <td>
+ <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event" class="externalDFN"><code>Event</code></a>
+ </td>
+ <td>
+ When a current service gracefully leaves or otherwise expires from the current network.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <dfn id="event-notify">
+ <code>notify</code>
+ </dfn>
+ </td>
+ <td>
+ <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event" class="externalDFN"><code>Event</code></a>
+ </td>
+ <td>
+ When a valid UPnP Events Subscription Message is received on a <a>user-agent generated callback url</a> for a current service. This event never fires for Zeroconf-based services.
+ </td>
+ </tr>
+ </tbody>
+ </table>
+
+ </section>
+
<section>
<h3>Garbage collection</h3>
<p>
- Only when the user navigates away from the current browsing context can <a><code>NetworkService</code></a> objects be garbage-collected, its records in the <a>entry script origin's URL whitelist</a> be removed and its corresponding entry in the <a>list of authorized service records</a> be removed.
+ Only when the user navigates away from the current browsing context can <a><code>NetworkService</code></a> objects be garbage-collected, its records in the <a>entry script origin's URL whitelist</a> be removed and its corresponding entry in the <a>list of authorized service records</a> be removed according to passing each expired object identifier through the rule for <a>removing an available service</a>.
</p>
</section>
Received on Tuesday, 2 October 2012 12:51:58 UTC