discovery-api/Overview.src.html
changeset 330 78129450e57a
parent 288 ec6f8e4f894e
child 331 43b139afeba9
--- 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>&lt;UDN&gt;</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>&lt;friendlyName&gt;</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>