- From: Mercurial notifier <cvsmail@w3.org>
- Date: Thu, 17 Jan 2013 14:08:46 +0000
- To: public-dap-commits@w3.org
changeset: 330:78129450e57a
user: Daniel Danciu <danieldanciu@google.com>
date: Thu Oct 25 19:49:39 2012 +0200
files: discovery-api/Overview.src.html
description:
Added DIAL support
diff -r 1c5fc74bd529 -r 78129450e57a discovery-api/Overview.src.html
--- a/discovery-api/Overview.src.html Thu Jan 10 14:41:23 2013 +0200
+++ b/discovery-api/Overview.src.html Thu Oct 25 19:49:39 2012 +0200
@@ -275,9 +275,17 @@
is said to be <em>setting</em> when a new value is assigned to it.
</p>
<p>
- A <dfn>valid service type</dfn> is a string that begins with <code>upnp:</code> or <code>zeroconf:</code>
- followed by one or more characters in the ranges U+0021, U+0023 to U+0027, U+002A to U+002B, U+002D to U+002E,
- U+0030 to U+0039, U+0041 to U+005A, U+005E to U+007E.
+ A <dfn>valid service type</dfn> is any of the following:
+ <ul>
+ <li>
+ a string that begins with <code>upnp:</code> or <code>zeroconf:</code>
+ followed by one or more characters in the ranges U+0021, U+0023 to U+0027, U+002A to U+002B, U+002D to U+002E,
+ U+0030 to U+0039, U+0041 to U+005A, U+005E to U+007E.
+ </li>
+ <li>
+ a string that begins with <code>dial:</code> followed by an integer version.
+ </li>
+ </ul>
</p>
<p>
A <a>valid service type</a> provided in the <code>type</code> attribute of the <a href=
@@ -962,7 +970,8 @@
</h2>
<p>
A <a>user agent</a> conforming to this specification MAY implement <abbr title=
- "Simple Service Discovery Protocol">SSDP</abbr> [[!UPNP-DEVICEARCH11]] and Zeroconf [[!DNS-SD]] + [[!MDNS]]
+ "Simple Service Discovery Protocol">SSDP</abbr> [[!UPNP-DEVICEARCH11]], Zeroconf [[!DNS-SD]] + [[!MDNS]] or
+ <abbr title="Discovery and Launch Protocol">DIAL</abbr> [<a href = "https://sites.google.com/a/dial-multiscreen.org/dial/dial-protocol-specification">DIAL</a>]
<dfn>service discovery mechanisms</dfn> - the requirements detailed in this section of the specification - 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 <a>service discovery
@@ -1463,6 +1472,115 @@
</p>
</section>
<section>
+ <h5>
+ Discovery and Launch Protocol (<abbr title="Discovery and Launch Protocol">DIAL</abbr>)
+ </h5>
+ <p>
+ A user agent that implements DIAL service discovery MUST issue a <dfn>search request for DIAL-enabled
+ 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>
+ <p>
+ Let <var>dial version</var> be the version number specified in the <a>valid service type</a> token.
+ Let <var>dial search target</var> be the concatentation of the
+ <code>urn:dial-multiscreen-org:service:dial:</code> string constant with the <var>dial version</var>
+ (currently, <var>dial version</var> can only be <code>1</code>)
+ </p>
+ <p>
+ The user agent MUST issue all <a title="search request for DIAL devices">search requests for DIAL
+ devices</a> with a HTTP request line equal to <code>M-SEARCH * HTTP/1.1</code>, with a HOST header equal to
+ the reserved multicast address and port of <code>239.255.255.250:1900</code>, a MAN header equal to
+ <code>ssdp:discover</code>, an ST header equal to <var>dial search target</var>
+ and a user-agent defined MX header equal to a <dfn>maximum UPnP advertisement response wait time</dfn>
+ value between <code>1</code> and <code>5</code> seconds.
+ </p>
+ <p>
+ The user agent MUST listen for any incoming responses to a <a>search request for DIAL devices</a>.
+ </p>
+ <p>
+ For each <dfn>HTTP Response</dfn> following an initial <a>search request for DIAL devices</a> sent on a
+ <a>standard UPnP address and port</a> the user agent MUST run the following steps:
+ </p>
+ <ol class="rule">
+ <li>If the <a>HTTP Response</a> is not a HTTP 200 OK response then this response is invalid and the user
+ agent MUST discard this response, abort any remaining steps and return. The user agent MAY issue a new
+ <a>search request for DIAL devices</a> as a result of this error occurring.
+ </li>
+ <li>If the <a>maximum UPnP advertisement response wait time</a> has been exceeded since the initial <a>search
+ request for DIAL devices</a> was sent then the <a>HTTP Response</a> is invalid and the user agent MUST
+ discard this response, abort any remaining steps and return. The user agent MAY stop listening for responses
+ from the current <a>search request for DIAL devices</a> as a result of this error occurring. Equally,
+ the user agent MAY issue a new <a>search request for DIAL devices</a> as a result of this error
+ occurring.
+ </li>
+ <li>Let <var>dial device</var> be an Object with a property for each HTTP header received in the <a>HTTP
+ Response</a>, with each key being the name of a HTTP response header and each value being that HTTP response
+ header's value.
+ </li>
+ <li>If <var>dial 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 <var>dial search target</var>, then the
+ <a>HTTP Response</a> is invalid and the <a>user agent</a> MUST discard this response, abort any remaining
+ steps and return.
+ </li>
+ <li>The user agent MUST run the rule for <a>obtaining a UPnP Device Description File</a> passing in the first
+ occurrence of <var>LOCATION</var> from <var>dial device</var> as the <var>device descriptor URL</var>
+ argument and the first occurrence of <var>USN</var> from <var>dial device</var> as the <var>device
+ identifier</var> argument and the first occurrence of <var>CACHE-CONTROL</var> from <var>dial device</var>
+ (minus the leading string of <code>max-age=</code>) as the <var>device expiry</var> argument.
+ </li>
+ </ol>
+ <p>
+ The rule for <dfn>obtaining a UPnP Device Description File</dfn> is the process of obtaining the contents of
+ a standard UPnP Device Description [[!UPNP-DEVICEARCH11]] from a URL-based resource. This rule takes three
+ arguments - <var>device descriptor URL</var>, <var>device identifier</var> and <var>device expiry</var> - and
+ when called the user agent MUST run the following steps:
+ </p>
+ <ol class="rule">
+ <li>Let <var>device descriptor file</var> contain the contents of the file located at the URL provided in
+ <var>device descriptor URL</var> obtained according to the rules defined in 'Section 2.11: Retrieving a
+ description using HTTP' in [[!UPNP-DEVICEARCH11]].
+ </li>
+ <li>Let <var>application url</var> be the value of the first occurrence of the <code>Application-URL</code>
+ response header field obtained according to the rules defined in 'Section 5.4: Device Description Response' in
+ [<a href = "https://sites.google.com/a/dial-multiscreen.org/dial/dial-protocol-specification">DIAL</a>]
+ </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>device descriptor file</var> remains empty or <var>application url</var> is undefined
+ then it is invalid and the <a>user agent</a> MUST abort any remaining steps and return.
+ </li>
+ <li>Run the following steps to add the newly discovered DIAL service:
+ <ol class="rule">
+ <li>Let <var>network service record</var> be a new Object consisting of the following empty properties:
+ <code>id</code>, <code>deviceId</code>, <code>name</code>, <code>type</code>, <code>url</code>,
+ <code>expiryTimestamp</code>.
+ </li>
+ <li>Set <var>network service record</var>'s <code>id</code> property to the first occurrence of the
+ <code><UDN></code> element in the <var>descriptor file</var> prefixed with the <code>dial:</code>
+ string constant
+ </li>
+ <li>Set <var>network service record</var>'s <code>deviceId</code> property to the value of <var>device
+ identifier</var>.
+ </li>
+ <li>Set <var>network service record</var>'s <code>name</code> property to the string value of the first
+ occurrence of the <code><friendlyName></code> element in the <var>descriptor file</var>.
+ </li>
+ <li>Set <var>network service record</var>'s <code>type</code> property to <var>dial search target</var>.
+ </li>
+ <li>Set <var>network service record</var>'s <code>url</code> property to the string value of the <var>
+ application url</var>.
+ </li>
+ <li>Set <var>network service record</var>'s <code>expiryTimestamp</code> property to the value of the
+ current date, in UTC timestamp format, plus the value of <var>device expiry</var>.
+ </li>
+ <li>Run the general rule for <a>adding an available service</a>, passing in the current <var>network
+ service record</var> as the only argument.
+ </li>
+ </ol>
+ </li>
+ </ol>
+ </section>
+ <section>
<h3>
Network Topology Monitoring
</h3>
Received on Thursday, 17 January 2013 14:08:48 UTC