Added DIAL support
authorDaniel Danciu <danieldanciu@google.com>
Thu, 25 Oct 2012 19:49:39 +0200
changeset 33078129450e57a
parent 329 1c5fc74bd529
child 331 43b139afeba9
Added DIAL support
discovery-api/Overview.src.html
     1.1 --- a/discovery-api/Overview.src.html	Thu Jan 10 14:41:23 2013 +0200
     1.2 +++ b/discovery-api/Overview.src.html	Thu Oct 25 19:49:39 2012 +0200
     1.3 @@ -275,9 +275,17 @@
     1.4          is said to be <em>setting</em> when a new value is assigned to it.
     1.5        </p>
     1.6        <p>
     1.7 -        A <dfn>valid service type</dfn> is a string that begins with <code>upnp:</code> or <code>zeroconf:</code>
     1.8 -        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,
     1.9 -        U+0030 to U+0039, U+0041 to U+005A, U+005E to U+007E.
    1.10 +        A <dfn>valid service type</dfn> is any of the following:
    1.11 +        <ul>
    1.12 +           <li>
    1.13 +              a string that begins with <code>upnp:</code> or <code>zeroconf:</code>
    1.14 +              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,
    1.15 +              U+0030 to U+0039, U+0041 to U+005A, U+005E to U+007E.
    1.16 +           </li>
    1.17 +           <li>
    1.18 +              a string that begins with <code>dial:</code> followed by an integer version.
    1.19 +           </li>
    1.20 +        </ul>
    1.21        </p>
    1.22        <p>
    1.23          A <a>valid service type</a> provided in the <code>type</code> attribute of the <a href=
    1.24 @@ -962,7 +970,8 @@
    1.25        </h2>
    1.26        <p>
    1.27          A <a>user agent</a> conforming to this specification MAY implement <abbr title=
    1.28 -        "Simple Service Discovery Protocol">SSDP</abbr> [[!UPNP-DEVICEARCH11]] and Zeroconf [[!DNS-SD]] + [[!MDNS]]
    1.29 +        "Simple Service Discovery Protocol">SSDP</abbr> [[!UPNP-DEVICEARCH11]], Zeroconf [[!DNS-SD]] + [[!MDNS]] or
    1.30 +        <abbr title="Discovery and Launch Protocol">DIAL</abbr> [<a href = "https://sites.google.com/a/dial-multiscreen.org/dial/dial-protocol-specification">DIAL</a>]
    1.31          <dfn>service discovery mechanisms</dfn> - the requirements detailed in this section of the specification - to
    1.32          enable Web pages to request and connect with HTTP services running on networked devices, discovered via either
    1.33          mechanism, through this API. When a <a>user agent</a> implements either of these <a>service discovery
    1.34 @@ -1463,6 +1472,115 @@
    1.35          </p>
    1.36        </section>
    1.37        <section>
    1.38 +        <h5>
    1.39 +          Discovery and Launch Protocol (<abbr title="Discovery and Launch Protocol">DIAL</abbr>)
    1.40 +        </h5>
    1.41 +         <p>
    1.42 +          A user agent that implements DIAL service discovery MUST issue a <dfn>search request for DIAL-enabled
    1.43 +          devices</dfn> against the user's current local network according to the full normative text and timing
    1.44 +          provided in 'Section 1.3.2: Search request with M-SEARCH' detailed in [[!UPNP-DEVICEARCH11]].
    1.45 +        </p>
    1.46 +        <p>
    1.47 +          Let <var>dial version</var> be the version number specified in the <a>valid service type</a> token.
    1.48 +          Let <var>dial search target</var> be the concatentation of the 
    1.49 +          <code>urn:dial-multiscreen-org:service:dial:</code> string constant with the <var>dial version</var>
    1.50 +          (currently, <var>dial version</var> can only be <code>1</code>) 
    1.51 +        </p>
    1.52 +        <p>
    1.53 +          The user agent MUST issue all <a title="search request for DIAL devices">search requests for DIAL
    1.54 +          devices</a> with a HTTP request line equal to <code>M-SEARCH * HTTP/1.1</code>, with a HOST header equal to
    1.55 +          the reserved multicast address and port of <code>239.255.255.250:1900</code>, a MAN header equal to
    1.56 +          <code>ssdp:discover</code>, an ST header equal to <var>dial search target</var>
    1.57 +          and a user-agent defined MX header equal to a <dfn>maximum UPnP advertisement response wait time</dfn>
    1.58 +          value between <code>1</code> and <code>5</code> seconds.
    1.59 +        </p>
    1.60 +        <p>
    1.61 +          The user agent MUST listen for any incoming responses to a <a>search request for DIAL devices</a>.
    1.62 +        </p>
    1.63 +        <p>
    1.64 +          For each <dfn>HTTP Response</dfn> following an initial <a>search request for DIAL devices</a> sent on a
    1.65 +          <a>standard UPnP address and port</a> the user agent MUST run the following steps:
    1.66 +        </p>
    1.67 +        <ol class="rule">
    1.68 +          <li>If the <a>HTTP Response</a> is not a HTTP 200 OK response then this response is invalid and the user
    1.69 +          agent MUST discard this response, abort any remaining steps and return. The user agent MAY issue a new
    1.70 +          <a>search request for DIAL devices</a> as a result of this error occurring.
    1.71 +          </li>
    1.72 +          <li>If the <a>maximum UPnP advertisement response wait time</a> has been exceeded since the initial <a>search
    1.73 +          request for DIAL devices</a> was sent then the <a>HTTP Response</a> is invalid and the user agent MUST
    1.74 +          discard this response, abort any remaining steps and return. The user agent MAY stop listening for responses
    1.75 +          from the current <a>search request for DIAL devices</a> as a result of this error occurring. Equally,
    1.76 +          the user agent MAY issue a new <a>search request for DIAL devices</a> as a result of this error
    1.77 +          occurring.
    1.78 +          </li>
    1.79 +          <li>Let <var>dial device</var> be an Object with a property for each HTTP header received in the <a>HTTP
    1.80 +          Response</a>, with each key being the name of a HTTP response header and each value being that HTTP response
    1.81 +          header's value.
    1.82 +          </li>
    1.83 +          <li>If <var>dial device</var> does not contain at least one <var>CACHE-CONTROL</var> entry, at least one
    1.84 +          <var>USN</var> entry, at least one <var>ST</var> entry and at least one <var>LOCATION</var> entry or the
    1.85 +          value of its <var>ST</var> entry is not <var>dial search target</var>, then the
    1.86 +          <a>HTTP Response</a> is invalid and the <a>user agent</a> MUST discard this response, abort any remaining
    1.87 +          steps and return.
    1.88 +          </li>
    1.89 +          <li>The user agent MUST run the rule for <a>obtaining a UPnP Device Description File</a> passing in the first
    1.90 +          occurrence of <var>LOCATION</var> from <var>dial device</var> as the <var>device descriptor URL</var>
    1.91 +          argument and the first occurrence of <var>USN</var> from <var>dial device</var> as the <var>device
    1.92 +          identifier</var> argument and the first occurrence of <var>CACHE-CONTROL</var> from <var>dial device</var>
    1.93 +          (minus the leading string of <code>max-age=</code>) as the <var>device expiry</var> argument.
    1.94 +          </li>
    1.95 +        </ol>
    1.96 +        <p>
    1.97 +          The rule for <dfn>obtaining a UPnP Device Description File</dfn> is the process of obtaining the contents of
    1.98 +          a standard UPnP Device Description [[!UPNP-DEVICEARCH11]] from a URL-based resource. This rule takes three
    1.99 +          arguments - <var>device descriptor URL</var>, <var>device identifier</var> and <var>device expiry</var> - and
   1.100 +          when called the user agent MUST run the following steps:
   1.101 +        </p>
   1.102 +        <ol class="rule">
   1.103 +          <li>Let <var>device descriptor file</var> contain the contents of the file located at the URL provided in
   1.104 +          <var>device descriptor URL</var> obtained according to the rules defined in 'Section 2.11: Retrieving a
   1.105 +          description using HTTP' in [[!UPNP-DEVICEARCH11]].
   1.106 +          </li>
   1.107 +          <li>Let <var>application url</var> be the value of the first occurrence of the <code>Application-URL</code>
   1.108 +          response header field obtained according to the rules defined in 'Section 5.4: Device Description Response' in
   1.109 +          [<a href = "https://sites.google.com/a/dial-multiscreen.org/dial/dial-protocol-specification">DIAL</a>]
   1.110 +          </li>
   1.111 +          <li>If the value provided in <var>device descriptor URL</var> cannot be resolved as a reachable URL on the
   1.112 +          current network or the <var>device descriptor file</var> remains empty or <var>application url</var> is undefined
   1.113 +          then it is invalid and the <a>user agent</a> MUST abort any remaining steps and return.
   1.114 +          </li>
   1.115 +          <li>Run the following steps to add the newly discovered DIAL service:
   1.116 +            <ol class="rule">
   1.117 +              <li>Let <var>network service record</var> be a new Object consisting of the following empty properties:
   1.118 +              <code>id</code>, <code>deviceId</code>, <code>name</code>, <code>type</code>, <code>url</code>,
   1.119 +              <code>expiryTimestamp</code>.
   1.120 +              </li>
   1.121 +              <li>Set <var>network service record</var>'s <code>id</code> property to the first occurrence of the
   1.122 +              <code>&lt;UDN&gt;</code> element in the <var>descriptor file</var> prefixed with the <code>dial:</code>
   1.123 +              string constant
   1.124 +              </li>
   1.125 +              <li>Set <var>network service record</var>'s <code>deviceId</code> property to the value of <var>device
   1.126 +              identifier</var>.
   1.127 +              </li>
   1.128 +              <li>Set <var>network service record</var>'s <code>name</code> property to the string value of the first
   1.129 +              occurrence of the <code>&lt;friendlyName&gt;</code> element in the <var>descriptor file</var>.
   1.130 +              </li>
   1.131 +              <li>Set <var>network service record</var>'s <code>type</code> property to <var>dial search target</var>.
   1.132 +              </li>
   1.133 +              <li>Set <var>network service record</var>'s <code>url</code> property to the string value of the <var>
   1.134 +              application url</var>.
   1.135 +              </li>
   1.136 +              <li>Set <var>network service record</var>'s <code>expiryTimestamp</code> property to the value of the
   1.137 +              current date, in UTC timestamp format, plus the value of <var>device expiry</var>.
   1.138 +              </li>
   1.139 +              <li>Run the general rule for <a>adding an available service</a>, passing in the current <var>network
   1.140 +              service record</var> as the only argument.
   1.141 +              </li>
   1.142 +            </ol>
   1.143 +          </li>
   1.144 +        </ol>
   1.145 +      </section>
   1.146 +      <section>
   1.147          <h3>
   1.148            Network Topology Monitoring
   1.149          </h3>