discovery-api/Overview.html
author Rich Tibbett <richt@opera.com>
Thu, 05 Sep 2013 15:53:34 +0200
changeset 453 07345c55f11f
parent 448 865b6f93faac
child 480 f3ea6558ffe1
permissions -rw-r--r--
Fix [DAP-ISSUE-147]: Reference 'Requirements for Home Networking Scenarios' in Introduction
     1 <!DOCTYPE html>
     2 <html lang="en"
     3       dir="ltr"
     4       typeof="bibo:Document"
     5       about=""
     6       property="dcterms:language"
     7       content="en">
     8   <head>
     9     <title>
    10       Network Service Discovery
    11     </title>
    12     <meta http-equiv="Content-Type"
    13           content="text/html; charset=utf-8">
    14     <style>
    15 /* Custom ReSpec CSS (by Rich Tibbett) */
    16 
    17      /* Add better spacing to sections */
    18      section, .section { margin-bottom: 2em; }
    19 
    20      /* Add addition spacing to <ol> and <ul> for rule definition */
    21      ol.rule li, ul.rule li { padding:0.6em; }
    22 
    23      pre.widl { border: solid thin; background: #EEEEEE; color: black; padding: 0.5em 1em; position: relative; }
    24      pre.widl :link, pre.widl :visited { color: #000; background: transparent; }
    25      pre.widl:before { content: "IDL"; font: bold small sans-serif; padding: 0.5em; background: white; position: absolute; top: 0; margin: -1px 0 0 -4em; width: 1.5em; border: thin solid; border-radius: 0 0 0 0.5em }
    26 
    27      div.example { border: solid thin black; background: #FFFFF0; color: black; padding: 0.5em 1em; position: relative; margin: 1em 0 1em 4.6em; width: auto; }
    28      div.example:before { content: "EXAMPLE"; font: bold small sans-serif; padding: 0.5em; background: white; color: black; position: absolute; top: 0; margin: -1px 0 0 -7.6em; width: 5em; border: thin solid black; border-radius: 0 0 0 0.5em }
    29 
    30      dl.domintro { color: green; margin: 2em 0 2em 2em; padding: 0.5em 1em; border: none; background: #DDFFDD; }
    31      hr + dl.domintro, div.impl + dl.domintro { margin-top: 2.5em; margin-bottom: 1.5em; }
    32      dl.domintro dt, dl.domintro dt * { color: black; text-decoration: none; }
    33      dl.domintro dd { margin: 0.5em 0 1em 2em; padding: 0; }
    34      dl.domintro dd p { margin: 0.5em 0; }
    35      dl.domintro code {font-size: inherit; font-style: italic; }
    36      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; font-size:0.8em; }
    37 
    38      table { border-collapse:collapse; border-style:hidden hidden none hidden }
    39      table thead { border-bottom:solid }
    40      table tbody th:first-child { border-left:solid }
    41      table td, table th { border-left:solid; border-right:solid; border-bottom:solid thin; vertical-align:top; padding:0.2em }
    42     </style>
    43     <style>
    44 /*****************************************************************
    45     * ReSpec 3 CSS
    46     * Robin Berjon - http://berjon.com/
    47     *****************************************************************/
    48 
    49     /* --- INLINES --- */
    50     em.rfc2119 {
    51     text-transform:     lowercase;
    52     font-variant:       small-caps;
    53     font-style:         normal;
    54     color:              #900;
    55     }
    56 
    57     h1 acronym, h2 acronym, h3 acronym, h4 acronym, h5 acronym, h6 acronym, a acronym,
    58     h1 abbr, h2 abbr, h3 abbr, h4 abbr, h5 abbr, h6 abbr, a abbr {
    59     border: none;
    60     }
    61 
    62     dfn {
    63     font-weight:    bold;
    64     }
    65 
    66     a.internalDFN {
    67     color:  inherit;
    68     border-bottom:  1px solid #99c;
    69     text-decoration:    none;
    70     }
    71 
    72     a.externalDFN {
    73     color:  inherit;
    74     border-bottom:  1px dotted #ccc;
    75     text-decoration:    none;
    76     }
    77 
    78     a.bibref {
    79     text-decoration:    none;
    80     }
    81 
    82     cite .bibref {
    83     font-style: normal;
    84     }
    85 
    86     code {
    87     color:  #ff4500;
    88     }
    89 
    90     /* --- TOC --- */
    91     .toc a, .tof a {
    92     text-decoration:    none;
    93     }
    94 
    95     a .secno, a .figno {
    96     color:  #000;
    97     }
    98 
    99     ul.tof, ol.tof {
   100     list-style: none outside none;
   101     }
   102 
   103     .caption {
   104     margin-top: 0.5em;
   105     font-style:   italic;
   106     }
   107 
   108     /* --- TABLE --- */
   109     table.simple {
   110     border-spacing: 0;
   111     border-collapse:    collapse;
   112     border-bottom:  3px solid #005a9c;
   113     }
   114 
   115     .simple th {
   116     background: #005a9c;
   117     color:  #fff;
   118     padding:    3px 5px;
   119     text-align: left;
   120     }
   121 
   122     .simple th[scope="row"] {
   123     background: inherit;
   124     color:  inherit;
   125     border-top: 1px solid #ddd;
   126     }
   127 
   128     .simple td {
   129     padding:    3px 10px;
   130     border-top: 1px solid #ddd;
   131     }
   132 
   133     .simple tr:nth-child(even) {
   134     background: #f0f6ff;
   135     }
   136 
   137     /* --- DL --- */
   138     .section dd > p:first-child {
   139     margin-top: 0;
   140     }
   141 
   142     .section dd > p:last-child {
   143     margin-bottom: 0;
   144     }
   145 
   146     .section dd {
   147     margin-bottom:  1em;
   148     }
   149 
   150     .section dl.attrs dd, .section dl.eldef dd {
   151     margin-bottom:  0;
   152     }
   153     </style>
   154     <style>
   155 /* --- ISSUES/NOTES --- */
   156     div.issue-title, div.note-title {
   157     padding-right:  1em;
   158     min-width: 7.5em;
   159     color: #b9ab2d;
   160     }
   161     div.issue-title { color: #e05252; }
   162     div.note-title { color: #2b2; }
   163     div.issue-title span, div.note-title span {
   164     text-transform: uppercase;
   165     }
   166     div.note, div.issue {
   167     margin-top: 1em;
   168     margin-bottom: 1em;
   169     }
   170     .note > p:first-child, .issue > p:first-child { margin-top: 0 }
   171     .issue, .note {
   172     padding: .5em;
   173     border-left-width: .5em;
   174     border-left-style: solid;
   175     }
   176     div.issue, div.note {
   177     padding: 1em 1.2em 0.5em;
   178     margin: 1em 0;
   179     position: relative;
   180     clear: both;
   181     }
   182     span.note, span.issue { padding: .1em .5em .15em; }
   183 
   184     .issue {
   185     border-color: #e05252;
   186     background: #fbe9e9;
   187     }
   188     .note {
   189     border-color: #52e052;
   190     background: #e9fbe9;
   191     }
   192 
   193 
   194     </style>
   195     <style>
   196 /* HIGHLIGHTS */
   197     code.prettyprint {
   198     color:  inherit;
   199     }
   200 
   201     /* this from google-code-prettify */
   202     .pln{color:#000}@media screen{.str{color:#080}.kwd{color:#008}.com{color:#800}.typ{color:#606}.lit{color:#066}.pun,.opn,.clo{color:#660}.tag{color:#008}.atn{color:#606}.atv{color:#080}.dec,.var{color:#606}.fun{color:red}}@media print,projection{.str{color:#060}.kwd{color:#006;font-weight:bold}.com{color:#600;font-style:italic}.typ{color:#404;font-weight:bold}.lit{color:#044}.pun,.opn,.clo{color:#440}.tag{color:#006;font-weight:bold}.atn{color:#404}.atv{color:#060}}ol.linenums{margin-top:0;margin-bottom:0}li.L0,li.L1,li.L2,li.L3,li.L5,li.L6,li.L7,li.L8{list-style-type:none}li.L1,li.L3,li.L5,li.L7,li.L9{background:#eee}
   203     </style>
   204     <link rel="stylesheet"
   205           href="https://www.w3.org/StyleSheets/TR/W3C-ED">
   206   </head>
   207   <body class="h-entry"
   208         role="document"
   209         id="respecDocument">
   210     <div class="head"
   211          role="contentinfo"
   212          id="respecHeader">
   213       <p>
   214         <a href="http://www.w3.org/"><img width="72"
   215              height="48"
   216              src="https://www.w3.org/Icons/w3c_home"
   217              alt="W3C"></a>
   218       </p>
   219       <h1 class="title p-name"
   220           id="title"
   221           property="dcterms:title">
   222         Network Service Discovery
   223       </h1>
   224       <h2 property="dcterms:issued"
   225           datatype="xsd:dateTime"
   226           content="2013-09-05T11:58:47.000Z"
   227           id="w3c-editor-s-draft-05-september-2013">
   228         <abbr title="World Wide Web Consortium">W3C</abbr> Editor's Draft <time class="dt-published"
   229             datetime="2013-09-05">05 September 2013</time>
   230       </h2>
   231       <dl>
   232         <dt>
   233           This version:
   234         </dt>
   235         <dd>
   236           <a class="u-url"
   237               href=
   238               "http://dvcs.w3.org/hg/dap/raw-file/tip/discovery-api/Overview.html">http://dvcs.w3.org/hg/dap/raw-file/tip/discovery-api/Overview.html</a>
   239         </dd>
   240         <dt>
   241           Latest published version:
   242         </dt>
   243         <dd>
   244           <a href="http://www.w3.org/TR/discovery-api/">http://www.w3.org/TR/discovery-api/</a>
   245         </dd>
   246         <dt>
   247           Latest editor's draft:
   248         </dt>
   249         <dd>
   250           <a href=
   251           "http://dvcs.w3.org/hg/dap/raw-file/tip/discovery-api/Overview.html">http://dvcs.w3.org/hg/dap/raw-file/tip/discovery-api/Overview.html</a>
   252         </dd>
   253         <dt>
   254           Editor:
   255         </dt>
   256         <dd class="p-author h-card vcard"
   257             rel="bibo:editor"
   258             inlist="">
   259           <span typeof="foaf:Person"><span property="foaf:name"
   260                 class="p-name fn">Rich Tibbett</span>, <a rel="foaf:workplaceHomepage"
   261              class="p-org org h-org h-card"
   262              href="http://opera.com/">Opera Software ASA</a></span>
   263         </dd>
   264       </dl>
   265       <p class="copyright">
   266         <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © 2013 <a href=
   267         "http://www.w3.org/"><abbr title="World Wide Web Consortium">W3C</abbr></a><sup>®</sup> (<a href=
   268         "http://www.csail.mit.edu/"><abbr title="Massachusetts Institute of Technology">MIT</abbr></a>, <a href=
   269         "http://www.ercim.eu/"><abbr title=
   270         "European Research Consortium for Informatics and Mathematics">ERCIM</abbr></a>, <a href=
   271         "http://www.keio.ac.jp/">Keio</a>, <a href="http://ev.buaa.edu.cn/">Beihang</a>), All Rights Reserved.
   272         <abbr title="World Wide Web Consortium">W3C</abbr> <a href=
   273         "http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href=
   274         "http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href=
   275         "http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.
   276       </p>
   277       <hr>
   278     </div>
   279     <section id="abstract"
   280              class="introductory"
   281              property="dcterms:abstract"
   282              datatype=""
   283              typeof="bibo:Chapter"
   284              resource="#abstract"
   285              rel="bibo:chapter">
   286       <h2 aria-level="1"
   287           role="heading"
   288           id="h2_abstract">
   289         Abstract
   290       </h2>
   291       <p>
   292         This specification defines a mechanism for an HTML document to discover and subsequently communicate with
   293         <abbr title="Hypertext Transfer Protocol">HTTP</abbr>-based services advertised via common discovery protocols
   294         within the current network.
   295       </p>
   296     </section>
   297     <section id="toc">
   298       <h2 class="introductory"
   299           aria-level="1"
   300           role="heading"
   301           id="h2_toc">
   302         Table of Contents
   303       </h2>
   304       <ul class="toc"
   305           role="directory"
   306           id="respecContents">
   307         <li class="tocline">
   308           <a href="#introduction"
   309               class="tocxref"><span class="secno">1.</span> Introduction</a>
   310         </li>
   311         <li class="tocline">
   312           <a href="#conformance"
   313               class="tocxref"><span class="secno">2.</span> Conformance</a>
   314           <ul class="toc">
   315             <li class="tocline">
   316               <a href="#dependencies"
   317                   class="tocxref"><span class="secno">2.1</span> Dependencies</a>
   318             </li>
   319           </ul>
   320         </li>
   321         <li class="tocline">
   322           <a href="#terminology"
   323               class="tocxref"><span class="secno">3.</span> Terminology</a>
   324         </li>
   325         <li class="tocline">
   326           <a href="#security-and-privacy-considerations"
   327               class="tocxref"><span class="secno">4.</span> Security and privacy considerations</a>
   328           <ul class="toc">
   329             <li class="tocline">
   330               <a href="#privacy-considerations-for-api-implementations"
   331                   class="tocxref"><span class="secno">4.1</span> Privacy considerations for <abbr title=
   332                   "Application Programming Interface">API</abbr> implementations</a>
   333             </li>
   334             <li class="tocline">
   335               <a href="#additional-api-implementation-considerations"
   336                   class="tocxref"><span class="secno">4.2</span> Additional <abbr title=
   337                   "Application Programming Interface">API</abbr> implementation considerations</a>
   338             </li>
   339           </ul>
   340         </li>
   341         <li class="tocline">
   342           <a href="#requesting-networked-services"
   343               class="tocxref"><span class="secno">5.</span> Requesting networked services</a>
   344           <ul class="toc">
   345             <li class="tocline">
   346               <a href="#methods"
   347                   class="tocxref"><span class="secno">5.1</span> Methods</a>
   348             </li>
   349             <li class="tocline">
   350               <a href="#error-handling"
   351                   class="tocxref"><span class="secno">5.2</span> Error Handling</a>
   352             </li>
   353           </ul>
   354         </li>
   355         <li class="tocline">
   356           <a href="#obtaining-networked-services"
   357               class="tocxref"><span class="secno">6.</span> Obtaining networked services</a>
   358           <ul class="toc">
   359             <li class="tocline">
   360               <a href="#attributes"
   361                   class="tocxref"><span class="secno">6.1</span> Attributes</a>
   362             </li>
   363             <li class="tocline">
   364               <a href="#methods-1"
   365                   class="tocxref"><span class="secno">6.2</span> Methods</a>
   366             </li>
   367             <li class="tocline">
   368               <a href="#events"
   369                   class="tocxref"><span class="secno">6.3</span> Events</a>
   370             </li>
   371           </ul>
   372         </li>
   373         <li class="tocline">
   374           <a href="#communicating-with-a-networked-service"
   375               class="tocxref"><span class="secno">7.</span> Communicating with a networked service</a>
   376           <ul class="toc">
   377             <li class="tocline">
   378               <a href="#attributes-1"
   379                   class="tocxref"><span class="secno">7.1</span> Attributes</a>
   380             </li>
   381             <li class="tocline">
   382               <a href="#states"
   383                   class="tocxref"><span class="secno">7.2</span> States</a>
   384             </li>
   385             <li class="tocline">
   386               <a href="#events-1"
   387                   class="tocxref"><span class="secno">7.3</span> Events</a>
   388             </li>
   389           </ul>
   390         </li>
   391         <li class="tocline">
   392           <a href="#service-discovery"
   393               class="tocxref"><span class="secno">8.</span> Service Discovery</a>
   394           <ul class="toc">
   395             <li class="tocline">
   396               <a href="#zeroconf-mdns-dns-sd"
   397                   class="tocxref"><span class="secno">8.1</span> Zeroconf (<abbr title="Multicast DNS">mDNS</abbr> +
   398                   <abbr title="Domain Name System">DNS</abbr>-<abbr title="Service Discovery">SD</abbr>)</a>
   399             </li>
   400             <li class="tocline">
   401               <a href="#simple-service-discovery-protocol-ssdp"
   402                   class="tocxref"><span class="secno">8.2</span> Simple Service Discovery Protocol (<abbr title=
   403                   "Simple Service Discovery Protocol">SSDP</abbr>)</a>
   404             </li>
   405             <li class="tocline">
   406               <a href="#discovery-and-launch-protocol-dial"
   407                   class="tocxref"><span class="secno">8.3</span> Discovery and Launch Protocol (<abbr title=
   408                   "Discovery and Launch Protocol">DIAL</abbr>)</a>
   409             </li>
   410             <li class="tocline">
   411               <a href="#network-topology-monitoring"
   412                   class="tocxref"><span class="secno">8.4</span> Network Topology Monitoring</a>
   413             </li>
   414           </ul>
   415         </li>
   416         <li class="tocline">
   417           <a href="#events-summary"
   418               class="tocxref"><span class="secno">9.</span> Events Summary</a>
   419         </li>
   420         <li class="tocline">
   421           <a href="#garbage-collection"
   422               class="tocxref"><span class="secno">10.</span> Garbage collection</a>
   423         </li>
   424         <li class="tocline">
   425           <a href="#use-cases-and-requirements"
   426               class="tocxref"><span class="secno">11.</span> Use Cases and Requirements</a>
   427         </li>
   428         <li class="tocline">
   429           <a href="#examples"
   430               class="tocxref"><span class="secno">A.</span> Examples</a>
   431         </li>
   432         <li class="tocline">
   433           <a href="#acknowledgements"
   434               class="tocxref"><span class="secno">B.</span> Acknowledgements</a>
   435         </li>
   436         <li class="tocline">
   437           <a href="#references"
   438               class="tocxref"><span class="secno">C.</span> References</a>
   439           <ul class="toc">
   440             <li class="tocline">
   441               <a href="#normative-references"
   442                   class="tocxref"><span class="secno">C.1</span> Normative references</a>
   443             </li>
   444             <li class="tocline">
   445               <a href="#informative-references"
   446                   class="tocxref"><span class="secno">C.2</span> Informative references</a>
   447             </li>
   448           </ul>
   449         </li>
   450       </ul>
   451     </section>
   452     <section class="informative"
   453              id="introduction">
   454       <h2 aria-level="1"
   455           role="heading"
   456           id="h2_introduction">
   457         <span class="secno">1.</span> Introduction
   458       </h2>
   459       <p>
   460         <em>This section is non-normative.</em>
   461       </p>
   462       <p>
   463         This specification defines the <a href="#navigatornetworkservice"><code>NavigatorNetworkService</code></a>
   464         interface to enable Web pages to connect and communicate with Local-networked Services provided over
   465         <abbr title="Hypertext Transfer Protocol">HTTP</abbr>. This enables access to services and content provided by
   466         home network devices, including the discovery and playback of content available to those devices, both from
   467         services such as traditional broadcast media and internet based services as well as local services. Initial
   468         design goals and requirements provided by the <a href="http://www.w3.org/2011/webtv/"><abbr title=
   469         "World Wide Web Consortium">W3C</abbr> Web &amp; TV interest group</a> are documented in [<cite><a class=
   470         "bibref"
   471            href="#bib-hnreq">hnreq</a></cite>].
   472       </p>
   473       <p>
   474         Using this <abbr title="Application Programming Interface">API</abbr> consists of requesting a well-known
   475         service type, known by developers and advertised by Local-networked Devices. User authorization, where the user
   476         connects the web page to discovered services, is expected before the web page is able to interact with any
   477         Local-networked Services.
   478       </p>
   479       <p>
   480         A web page creates a request to obtain connectivity to services running in the network by specifying a
   481         well-known discovery service type that it wishes to interact with.
   482       </p>
   483       <p>
   484         The user agent, having captured all advertised services on the network from the <a href=
   485         "#dfn-service-discovery-mechanisms"
   486            class="internalDFN">service discovery mechanisms</a> included in this recommendation, attempts to match the
   487            requested service type to a discovered service according to the processing described herein.
   488       </p>
   489       <p>
   490         If a service connectivity request is successful then the Web page is provided with a promise-based success
   491         callback with the all necessary information to communicate with the authorized Local-networked Service. If the
   492         request fails then the Web page will receive a promise-based error callback containing an error string
   493         describing the cause of Local-networked Service connectivity failure.
   494       </p>
   495       <p>
   496         Once connected to a Local-networked Service the Web page can send requests and receive responses to the
   497         Local-networked Service via the messaging format and appropriate channel inferred from the service type
   498         authorized via the provided <abbr title="Application Programming Interface">API</abbr>. The Web page, once
   499         connected, can also receive service-pushed events, in the messaging format supported by the Local-networked
   500         Device, if such event subscription functionality is provided by the connected Local-networked Service.
   501       </p>
   502       <p>
   503         Services available within the local network can connect and disconnect at different times during the execution
   504         of a web page. The user agent can inform a web page when the state of networked services matching any of the
   505         requested valid service types change. Web pages can use this information to enable in-page experiences for
   506         communicating the state of networked services with the ability to change the particular service or set of
   507         services the page is connected to (by re-invoking the <a href=
   508         "#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a> method defined herein).
   509       </p>
   510       <div class="example">
   511         <p>
   512           Example of requesting a <abbr title="Domain Name System">DNS</abbr>-<abbr title="Service Discovery">SD</abbr>
   513           advertised service:
   514         </p>
   515         <hr>
   516         <pre class="highlight prettyprint">
   517 <span class="kwd">function</span><span class="pln"> showServices</span><span class="pun">(</span><span class=
   518 "pln"> services </span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
   519   </span><span class="com">// Show a list of all the services provided to the web page</span><span class="pln">
   520   </span><span class="kwd">for</span><span class="pun">(</span><span class="kwd">var</span><span class=
   521 "pln"> i </span><span class="pun">=</span><span class="pln"> </span><span class="lit">0</span><span class=
   522 "pun">,</span><span class="pln"> l </span><span class="pun">=</span><span class="pln"> services</span><span class=
   523 "pun">.</span><span class="pln">length</span><span class="pun">;</span><span class="pln"> i </span><span class=
   524 "pun">&lt;</span><span class="pln"> l</span><span class="pun">;</span><span class="pln"> i</span><span class=
   525 "pun">++)</span><span class="pln"> console</span><span class="pun">.</span><span class="pln">log</span><span class=
   526 "pun">(</span><span class="pln"> services</span><span class="pun">[</span><span class="pln">i</span><span class=
   527 "pun">].</span><span class="pln">name </span><span class="pun">);</span><span class="pln">
   528 </span><span class="pun">}</span><span class="pln">
   529 
   530 navigator</span><span class="pun">.</span><span class="pln">getNetworkServices</span><span class=
   531 "pun">(</span><span class="str">'zeroconf:_boxee-jsonrpc._tcp'</span><span class="pun">).</span><span class=
   532 "kwd">then</span><span class="pun">(</span><span class="pln">showServices</span><span class="pun">);</span>
   533 </pre>
   534       </div>
   535       <div class="example">
   536         <p>
   537           Example of requesting a UPnP advertised service, also handling error conditions:
   538         </p>
   539         <hr>
   540         <pre class="highlight prettyprint">
   541 <span class="kwd">function</span><span class="pln"> showServices</span><span class="pun">(</span><span class=
   542 "pln"> services </span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
   543   </span><span class="com">// Show a list of all the services provided to the web page</span><span class="pln">
   544   </span><span class="kwd">for</span><span class="pun">(</span><span class="kwd">var</span><span class=
   545 "pln"> i </span><span class="pun">=</span><span class="pln"> </span><span class="lit">0</span><span class=
   546 "pun">,</span><span class="pln"> l </span><span class="pun">=</span><span class="pln"> services</span><span class=
   547 "pun">.</span><span class="pln">length</span><span class="pun">;</span><span class="pln"> i </span><span class=
   548 "pun">&lt;</span><span class="pln"> l</span><span class="pun">;</span><span class="pln"> i</span><span class=
   549 "pun">++)</span><span class="pln"> console</span><span class="pun">.</span><span class="pln">log</span><span class=
   550 "pun">(</span><span class="pln"> services</span><span class="pun">[</span><span class="pln">i</span><span class=
   551 "pun">].</span><span class="pln">name </span><span class="pun">);</span><span class="pln">
   552 </span><span class="pun">}</span><span class="pln">
   553 
   554 </span><span class="kwd">function</span><span class="pln"> error</span><span class="pun">(</span><span class=
   555 "pln"> e </span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
   556   console</span><span class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class=
   557 "pln"> </span><span class="str">"Error occurred: "</span><span class="pln"> </span><span class=
   558 "pun">+</span><span class="pln"> e</span><span class="pun">.</span><span class="pln">name </span><span class=
   559 "pun">);</span><span class="pln">
   560 </span><span class="pun">}</span><span class="pln">
   561 
   562 navigator</span><span class="pun">.</span><span class="pln">getNetworkServices</span><span class=
   563 "pun">(</span><span class="str">'upnp:urn:schemas-upnp-org:service:ContentDirectory:1'</span><span class=
   564 "pun">).</span><span class="kwd">then</span><span class="pun">(</span><span class="pln">showServices</span><span class=
   565 "pun">,</span><span class="pln"> error</span><span class="pun">);</span>
   566 </pre>
   567       </div>
   568       <div class="example">
   569         <p>
   570           Example of requesting either a <abbr title="Domain Name System">DNS</abbr>-<abbr title=
   571           "Service Discovery">SD</abbr> or UPnP advertised service:
   572         </p>
   573         <hr>
   574         <pre class="highlight prettyprint">
   575 <span class="kwd">function</span><span class="pln"> showServices</span><span class="pun">(</span><span class=
   576 "pln"> services </span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
   577   </span><span class=
   578 "com">// Show a list of all the services provided to the web page (+ service type)</span><span class="pln">
   579   </span><span class="kwd">for</span><span class="pun">(</span><span class="kwd">var</span><span class=
   580 "pln"> i </span><span class="pun">=</span><span class="pln"> </span><span class="lit">0</span><span class=
   581 "pun">,</span><span class="pln"> l </span><span class="pun">=</span><span class="pln"> services</span><span class=
   582 "pun">.</span><span class="pln">length</span><span class="pun">;</span><span class="pln"> i </span><span class=
   583 "pun">&lt;</span><span class="pln"> l</span><span class="pun">;</span><span class="pln"> i</span><span class=
   584 "pun">++)</span><span class="pln">
   585      console</span><span class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class=
   586 "pln"> services</span><span class="pun">[</span><span class="pln">i</span><span class="pun">].</span><span class=
   587 "pln">name </span><span class="pun">+</span><span class="pln"> </span><span class="str">'('</span><span class=
   588 "pln"> </span><span class="pun">+</span><span class="pln"> services</span><span class="pun">[</span><span class=
   589 "pln">i</span><span class="pun">].</span><span class="pln">type </span><span class="pun">+</span><span class=
   590 "pln"> </span><span class="str">')'</span><span class="pln"> </span><span class="pun">);</span><span class="pln">
   591 </span><span class="pun">}</span><span class="pln">
   592 
   593 navigator</span><span class="pun">.</span><span class="pln">getNetworkServices</span><span class=
   594 "pun">([</span><span class="pln">
   595   </span><span class="str">'zeroconf:_boxee-jsonrpc._tcp'</span><span class="pun">,</span><span class="pln">
   596   </span><span class="str">'upnp:urn:schemas-upnp-org:service:ContentDirectory:1'</span><span class="pln">
   597 </span><span class="pun">]).</span><span class="kwd">then</span><span class="pun">(</span><span class=
   598 "pln">showServices</span><span class="pun">);</span>
   599 </pre>
   600       </div>
   601       <p>
   602         For more detailed examples, including examples of communicating with obtained networked services, see the
   603         <a href="#examples">Examples</a> section.
   604       </p>
   605     </section>
   606     <section id="conformance"
   607              typeof="bibo:Chapter"
   608              resource="#conformance"
   609              rel="bibo:chapter">
   610       <h2 aria-level="1"
   611           role="heading"
   612           id="h2_conformance">
   613         <span class="secno">2.</span> Conformance
   614       </h2>
   615       <p>
   616         As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this
   617         specification are non-normative. Everything else in this specification is normative.
   618       </p>
   619       <p>
   620         The key words <em class="rfc2119"
   621            title="MUST">MUST</em>, <em class="rfc2119"
   622            title="MUST NOT">MUST NOT</em>, <em class="rfc2119"
   623            title="REQUIRED">REQUIRED</em>, <em class="rfc2119"
   624            title="SHOULD">SHOULD</em>, <em class="rfc2119"
   625            title="SHOULD NOT">SHOULD NOT</em>, <em class="rfc2119"
   626            title="RECOMMENDED">RECOMMENDED</em>, <em class="rfc2119"
   627            title="MAY">MAY</em>, and <em class="rfc2119"
   628            title="OPTIONAL">OPTIONAL</em> in this specification are to be interpreted as described in [<cite><a class=
   629            "bibref"
   630            href="#bib-RFC2119">RFC2119</a></cite>].
   631       </p>
   632       <p>
   633         Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or
   634         "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should",
   635         "may", etc) used in introducing the algorithm.
   636       </p>
   637       <p>
   638         Some conformance requirements are phrased as requirements on attributes, methods or objects. Such requirements
   639         are to be interpreted as requirements on user agents.
   640       </p>
   641       <p>
   642         Conformance requirements phrased as algorithms or specific steps <em class="rfc2119"
   643            title="MAY">MAY</em> be implemented in any manner, so long as the end result is equivalent. (In particular,
   644            the algorithms defined in this specification are intended to be easy to follow, and not intended to be
   645            performant.)
   646       </p>
   647       <p>
   648         The only conformance class defined by this specification is a <dfn id="dfn-user-agent">user agent</dfn>.
   649       </p>
   650       <p>
   651         User agents <em class="rfc2119"
   652            title="MAY">MAY</em> impose implementation-specific limits on otherwise unconstrained inputs, e.g. to
   653            prevent denial of service attacks, to guard against running out of memory, or to work around
   654            platform-specific limitations.
   655       </p>
   656       <p>
   657         When support for a feature is disabled (e.g. as an emergency measure to mitigate a security problem, or to aid
   658         in development, or for performance reasons), user agents <em class="rfc2119"
   659            title="MUST">MUST</em> act as if they had no support for the feature whatsoever, and as if the feature was
   660            not mentioned in this specification. For example, if a particular feature is accessed via an attribute in a
   661            Web IDL interface, the attribute itself would be omitted from the objects that implement that interface -
   662            leaving the attribute on the object but making it return null or throw an exception is insufficient.
   663       </p>
   664       <section id="dependencies">
   665         <h3 aria-level="2"
   666             role="heading"
   667             id="h3_dependencies">
   668           <span class="secno">2.1</span> Dependencies
   669         </h3>This specification relies on several other underlying specifications.
   670         <dl>
   671           <dt>
   672             HTML
   673           </dt>
   674           <dd>
   675             Many fundamental concepts from HTML are used by this specification. [<cite><a class="bibref"
   676                href="#bib-HTML5">HTML5</a></cite>]
   677           </dd>
   678           <dt>
   679             WebIDL
   680           </dt>
   681           <dd>
   682             The IDL blocks in this specification use the semantics of the WebIDL specification. [<cite><a class=
   683             "bibref"
   684                href="#bib-WEBIDL">WEBIDL</a></cite>]
   685           </dd>
   686         </dl>
   687       </section>
   688     </section>
   689     <section id="terminology">
   690       <h2 aria-level="1"
   691           role="heading"
   692           id="h2_terminology">
   693         <span class="secno">3.</span> Terminology
   694       </h2>
   695       <p>
   696         The construction "a <code>Foo</code> object", where <code>Foo</code> is actually an interface, is sometimes
   697         used instead of the more accurate "an object implementing the interface <code>Foo</code>".
   698       </p>
   699       <p>
   700         The term DOM is used to refer to the <abbr title="Application Programming Interface">API</abbr> set made
   701         available to scripts in Web applications, and does not necessarily imply the existence of an actual
   702         <code>Document</code> object or of any other <code>Node</code> objects as defined in the DOM Core
   703         specifications. [<cite><a class="bibref"
   704            href="#bib-DOM4">DOM4</a></cite>]
   705       </p>
   706       <p>
   707         An IDL attribute is said to be <em>getting</em> when its value is being retrieved (e.g. by author script), and
   708         is said to be <em>setting</em> when a new value is assigned to it.
   709       </p>
   710       <p>
   711         A <dfn id="dfn-valid-service-type">valid service type</dfn> is any of the following:
   712       </p>
   713       <ul>
   714         <li>a string that begins with <code>upnp:</code> or <code>zeroconf:</code> followed by one or more characters
   715         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,
   716         U+005E to U+007E.
   717         </li>
   718         <li>a string that begins with <code>dial:</code> followed by an integer version.
   719         </li>
   720       </ul>
   721       <p>
   722         A <a href="#dfn-valid-service-type"
   723            class="internalDFN">valid service type</a> provided in the <code>type</code> attribute of the <a href=
   724            "#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a> method will be matched against the
   725            services currently contained in the <a href="#dfn-list-of-available-service-records"
   726            class="internalDFN">list of available service records</a> according to the algorithms defined in this
   727            specification.
   728       </p>
   729       <p>
   730         A <dfn id="dfn-user-agent-generated-callback-url">user-agent generated callback url</dfn> is a Local-network
   731         accessible <abbr title="Uniform Resource Locator">URL</abbr> endpoint that a <a href="#dfn-user-agent"
   732            class="internalDFN">user agent</a> generates and maintains for receiving <abbr title=
   733            "Hypertext Transfer Protocol">HTTP</abbr> NOTIFY requests from UPnP Event sources. It is only required when
   734            the user agent implements UPnP Service Discovery as defined in this specification.
   735       </p>
   736       <p>
   737         In this specification we use the following terms to describe the processes required for Local-networked
   738         Services management:
   739       </p>
   740       <ul>
   741         <li>A <dfn id="dfn-new-service">new service</dfn> is a Local-networked Service that has not previously been
   742         discovered or registered in the <a href="#dfn-list-of-available-service-records"
   743               class="internalDFN">list of available service records</a>.
   744         </li>
   745         <li>An <dfn id="dfn-existing-service">existing service</dfn> is a Local-networked Service that has previously
   746         been discovered and is registered in the <a href="#dfn-list-of-available-service-records"
   747               class="internalDFN">list of available service records</a>.
   748         </li>
   749         <li>A <dfn id="dfn-current-service">current service</dfn> is a Local-networked Service, represented by a
   750         <a href="#networkservice"><code>NetworkService</code></a> object, that is currently being shared with a web
   751         page via a <a href="#networkservices"><code>NetworkServices</code></a> object registered in the <a href=
   752         "#dfn-list-of-active-service-managers"
   753               class="internalDFN">list of active service managers</a>.
   754         </li>
   755       </ul>
   756     </section>
   757     <section id="security-and-privacy-considerations">
   758       <h2 aria-level="1"
   759           role="heading"
   760           id="h2_security-and-privacy-considerations">
   761         <span class="secno">4.</span> Security and privacy considerations
   762       </h2>
   763       <p>
   764         The <abbr title="Application Programming Interface">API</abbr> defined in this specification can be used to
   765         find and connect to devices and services within a user's current network. This discloses information related to
   766         a user's network: devices available on their network and the publicly-accessible services ("networked
   767         services") currently running and available on those devices. The distribution of this information could
   768         potentially compromise the user's privacy. A conforming implementation of this specification <em class=
   769         "rfc2119"
   770            title="MUST">MUST</em> provide a mechanism that protects the user's privacy. This mechanism <em class=
   771            "rfc2119"
   772            title="MUST">MUST</em> ensure that no networked service information is retrievable without the user's
   773            express permission.
   774       </p>
   775       <section id="privacy-considerations-for-api-implementations">
   776         <h3 aria-level="2"
   777             role="heading"
   778             id="h3_privacy-considerations-for-api-implementations">
   779           <span class="secno">4.1</span> Privacy considerations for <abbr title=
   780           "Application Programming Interface">API</abbr> implementations
   781         </h3>
   782         <p>
   783           A <a href="#dfn-user-agent"
   784              class="internalDFN">user agent</a> <em class="rfc2119"
   785              title="MUST NOT">MUST NOT</em> provide networked service information to web sites without the express
   786              permission of the user. A user agent <em class="rfc2119"
   787              title="MUST">MUST</em> acquire permission through a user interface, unless they have prearranged trust
   788              relationships with users, as described below. The user interface <em class="rfc2119"
   789              title="MUST">MUST</em> include the document base <abbr title="Uniform Resource Locator">URL</abbr>. Those
   790              permissions that are acquired through the user interface and that are preserved beyond the current
   791              browsing session (i.e. beyond the time when the browsing context is navigated to another <abbr title=
   792              "Uniform Resource Locator">URL</abbr>) <em class="rfc2119"
   793              title="MUST">MUST</em> be revocable and a user agent <em class="rfc2119"
   794              title="MUST">MUST</em> respect revoked permissions.
   795         </p>
   796         <p>
   797           Obtaining the user's express permission to access one <abbr title=
   798           "Application Programming Interface">API</abbr> method does not imply the user has granted permission for the
   799           same web site to access any other methods that may be provided by this <abbr title=
   800           "Application Programming Interface">API</abbr>, or to access the same method with a different set of
   801           arguments, as part of the same permission context. If a user has expressed permission for an implementation
   802           to, e.g. find a set of existing networked services, the implementation <em class="rfc2119"
   803              title="MUST">MUST</em> seek the user's express permission if and when any subsequent functions are called
   804              on this <abbr title="Application Programming Interface">API</abbr>.
   805         </p>
   806         <p>
   807           A user agent <em class="rfc2119"
   808              title="MAY">MAY</em> have prearranged trust relationships that do not require such user interfaces. For
   809              example, while a web browser will present a user interface when a web site performs a networked service
   810              lookup, a different runtime may have a prearranged, delegated security relationship with the user and, as
   811              such, a suitable alternative security and privacy mechanism with which to authorise the retrieval of
   812              networked service information.
   813         </p>
   814       </section>
   815       <section class="informative"
   816                id="additional-api-implementation-considerations">
   817         <h3 aria-level="2"
   818             role="heading"
   819             id="h3_additional-api-implementation-considerations">
   820           <span class="secno">4.2</span> Additional <abbr title="Application Programming Interface">API</abbr>
   821           implementation considerations
   822         </h3>
   823         <p>
   824           <em>This section is non-normative.</em>
   825         </p>
   826         <p>
   827           Further to the requirements listed in the previous section, implementors of the Network Service Discovery
   828           <abbr title="Application Programming Interface">API</abbr> are also advised to consider the following aspects
   829           that can negatively affect the privacy of their users: in certain cases, users can inadvertently grant
   830           permission to the user agent to disclose networked services to Web sites. In other cases, the content hosted
   831           at a certain <abbr title="Uniform Resource Locator">URL</abbr> changes in such a way that previously granted
   832           networked service permissions no longer apply as far as the user is concerned. Or the users might simply
   833           change their minds.
   834         </p>
   835         <p>
   836           Predicting or preventing these situations is inherently difficult. Mitigation and in-depth defensive measures
   837           are an implementation responsibility and not prescribed by this specification. However, in designing these
   838           measures, implementers are advised to enable user awareness of networked service sharing, and to provide easy
   839           access to interfaces that enable revocation of permissions that web applications have for accessing networked
   840           services via this <abbr title="Application Programming Interface">API</abbr>.
   841         </p>
   842       </section>
   843     </section>
   844     <section id="requesting-networked-services">
   845       <h2 aria-level="1"
   846           role="heading"
   847           id="h2_requesting-networked-services">
   848         <span class="secno">5.</span> Requesting networked services
   849       </h2>
   850       <pre class="widl">
   851 [Supplemental, NoInterfaceObject]
   852 interface <dfn id="navigatornetworkservice">NavigatorNetworkService</dfn> {
   853   <a class="externalDFN"
   854      href="http://dom.spec.whatwg.org/#promise">Promise</a> <a href=
   855      "#dom-navigator-getnetworkservices">getNetworkServices</a>( in any type );
   856 };
   857 
   858 <a class="externalDFN"
   859      href=
   860      "http://www.whatwg.org/specs/web-apps/current-work/complete/timers.html#navigator">Navigator</a> implements <a href=
   861      "#navigatornetworkservice">NavigatorNetworkService</a>;
   862 </pre>
   863       <section id="methods">
   864         <h3 aria-level="2"
   865             role="heading"
   866             id="h3_methods">
   867           <span class="secno">5.1</span> Methods
   868         </h3>
   869         <dl class="domintro">
   870           <dt>
   871             <var title="">promise</var> = <var title="">window</var> . <code title="dom-navigator"><a href=
   872             "http://www.whatwg.org/specs/web-apps/current-work/complete/timers.html#navigator">navigator</a></code> .
   873             <code title="dom-navigator-getNetworkServices"><a href=
   874             "#dom-navigator-getnetworkservices">getNetworkServices</a></code> ( <var title="">type</var> )
   875           </dt>
   876           <dd>
   877             <p>
   878               Immediately returns a new <a href="http://dom.spec.whatwg.org/#promise"
   879                  class="externalDFN">Promise</a> object and then the user is prompted to select discovered network
   880                  services that have advertised support for the requested service type(s).
   881             </p>
   882             <p>
   883               The <var title="">type</var> argument contains one or more <a href="#dfn-valid-service-type"
   884                  class="internalDFN">valid service type</a> tokens that the web page would like to interact with.
   885             </p>
   886             <p>
   887               If the user accepts, the <var title="">promise</var> object is <a class="externalDFN"
   888                  href="http://dom.spec.whatwg.org/#concept-resolver-resolve">resolved</a>, with a <a href=
   889                  "#networkservices"><code>NetworkServices</code></a> object as its argument.
   890             </p>
   891             <p>
   892               If the user declines, or an error occurs, the <var title="">promise</var> object is <a class=
   893               "externalDFN"
   894                  href="http://dom.spec.whatwg.org/#concept-resolver-reject">rejected</a>.
   895             </p>
   896           </dd>
   897         </dl>
   898         <div>
   899           <p>
   900             When the <dfn id="dom-navigator-getnetworkservices"
   901                title="dom-navigator-getnetworkservices"><code>getNetworkServices(type)</code></dfn> method is called,
   902                the <a href="#dfn-user-agent"
   903                class="internalDFN">user agent</a> <em class="rfc2119"
   904                title="MUST">MUST</em> run the following steps:
   905           </p>
   906           <ol class="rule">
   907             <li>Let <var>Network Service Promise</var> be a new <a href="http://dom.spec.whatwg.org/#promise"
   908                   class="externalDFN"><code>Promise</code></a> object.
   909             </li>
   910             <li>Let <var>Network Service Promise's Resolver</var> be the default <a href=
   911             "http://dom.spec.whatwg.org/#concept-resolver"
   912                   class="externalDFN">resolver</a> of <var>Network Service Promise</var>.
   913             </li>
   914             <li>Return <var>Network Service Promise</var>, and run the remaining steps asynchronously.
   915             </li>
   916             <li>Let <var>requested control types</var> be initially set to an empty array.
   917             </li>
   918             <li>If <var>type</var> is an array consisting of one or more <a href="#dfn-valid-service-type"
   919                   class="internalDFN">valid service type</a> tokens, then let <var>requested control types</var> by the
   920                   value of <var>type</var>, removing any non-<a href="#dfn-valid-service-type"
   921                   class="internalDFN">valid service type</a> tokens from the resulting array.
   922             </li>
   923             <li>If <var>type</var> is a string consisting of one <a href="#dfn-valid-service-type"
   924                   class="internalDFN">valid service type</a> token, then let <var>requested control types</var> be an
   925                   array containing one item with a value of <var>type</var>.
   926             </li>
   927             <li>If <var>requested control types</var> is an array that contains at least one or more <a title=
   928             "valid service type"
   929                   href="#dfn-valid-service-type"
   930                   class="internalDFN">valid service type</a> tokens then continue to the step labeled <em>process</em>
   931                   below. Otherwise, reject <var>Network Service Promise</var> by running the <a href=
   932                   "http://dom.spec.whatwg.org/#concept-resolver-reject"
   933                   class="externalDFN">resolver reject algorithm</a> against the <var>Network Service Promise's
   934                   Resolver</var>, passing in a newly constructed <a href="http://dom.spec.whatwg.org/#domerror"
   935                   class="externalDFN"><code>DOMError</code></a> object whose <code>name</code> attribute has the string
   936                   value "UnknownTypePrefixError" (<a href=
   937                   "#dom-domerror-extensions-unknown_type_prefix"><code>UNKNOWN_TYPE_PREFIX_ERR</code></a>) and whose
   938                   <code>message</code> attribute has a helpful implementation-dependent message that explains this
   939                   error, abort any remaining steps and return.
   940             </li>
   941             <li>
   942               <em>Process</em>: Let <var>services found</var> be an empty array.
   943             </li>
   944             <li>For each <var>available service</var> in the <a href="#dfn-list-of-available-service-records"
   945                   class="internalDFN">list of available service records</a> run the following steps:
   946               <ol class="rule">
   947                 <li>For each <var>requested control type</var> in <var>requested control types</var>: If <var>available
   948                 service</var>'s <code>type</code> attribute equals the <var>requested control type</var> then let <var>
   949                   matched service</var> equal the value of <var>available service</var> and continue at the step
   950                   labeled <var>attach</var> below.
   951                 </li>
   952                 <li>Continue at the next <var>available service</var>.
   953                 </li>
   954                 <li>
   955                   <em>Attach</em>: If <var>matched service</var> is not empty then run the following steps:
   956                   <ol class="rule">
   957                     <li>Let <var>new service object</var> be a new <a href=
   958                     "#networkservice"><code>NetworkService</code></a> object, mapping the parameters of <var>matched
   959                     service</var> to this new object where possible.
   960                     </li>
   961                     <li>Append <var>new service object</var> to the <var>services found</var> array.
   962                     </li>
   963                   </ol>
   964                 </li>
   965               </ol>
   966             </li>
   967             <li>Optionally, e.g. based on a previously-established user preference, for security reasons, or due to
   968             platform limitations, the <a href="#dfn-user-agent"
   969                   class="internalDFN">user agent</a> <em class="rfc2119"
   970                   title="MAY">MAY</em> reject <var>Network Service Promise</var> by running the <a href=
   971                   "http://dom.spec.whatwg.org/#concept-resolver-reject"
   972                   class="externalDFN">resolver reject algorithm</a> against the <var>Network Service Promise's
   973                   Resolver</var>, passing in a newly constructed <a href="http://dom.spec.whatwg.org/#domerror"
   974                   class="externalDFN"><code>DOMError</code></a> object whose <code>name</code> attribute has the string
   975                   value "PermissionDeniedError" (<a href=
   976                   "#dom-domerror-extensions-permission_denied"><code>PERMISSION_DENIED_ERR</code></a>) and whose
   977                   <code>message</code> attribute has a helpful implementation-dependent message that explains this
   978                   error, abort any remaining steps and return.
   979             </li>
   980             <li>The user agent <em class="rfc2119"
   981                   title="MUST NOT">MUST NOT</em> provide the entry script's origin with a <a href=
   982                   "#networkservices"><code>NetworkServices</code></a> object without prior permission given by the
   983                   user.
   984               <p>
   985                 If <var>services found</var> is not an empty array then the <a href="#dfn-user-agent"
   986                    class="internalDFN">user agent</a> <em class="rfc2119"
   987                    title="MAY">MAY</em> choose to prompt the user in a user-agent-specific manner for permission to
   988                    provide the <a href=
   989                    "http://www.whatwg.org/specs/web-apps/current-work/complete/browsers.html#entry-script"
   990                    class="externalDFN">entry script</a>'s <a href=
   991                    "http://www.whatwg.org/specs/web-apps/current-work/complete/origin-0.html#origin"
   992                    class="externalDFN">origin</a> with a <a href="#networkservices"><code>NetworkServices</code></a>
   993                    object representing the <a href="#dfn-user-authorized"
   994                    class="internalDFN">user-authorized</a> subset of <var>services found</var>.
   995               </p>
   996               <p>
   997                 Alternatively, the user agent <em class="rfc2119"
   998                    title="MAY">MAY</em> wish to skip this user opt-in step and choose to fulfill <var>Network Service
   999                    Promise</var> immediately based on a previously-established user preference, for security reasons,
  1000                    or due to platform limitations. In such an implementation, if <var>Network Service Promise</var> is
  1001                    to be fulfilled as a result of a previously-established user preference then the <a href=
  1002                    "#dfn-user-agent"
  1003                    class="internalDFN">user agent</a> <em class="rfc2119"
  1004                    title="MUST">MUST</em> continue at the next step of this algorithm.
  1005               </p>
  1006               <p>
  1007                 If permission has been granted by the user to access one or more networked services then the <a href=
  1008                 "#dfn-user-agent"
  1009                    class="internalDFN">user agent</a> <em class="rfc2119"
  1010                    title="SHOULD">SHOULD</em> include an "ongoing local-network communication" indicator.
  1011               </p>
  1012               <p>
  1013                 If permission has been denied by the user, <a href="#dfn-user-agent"
  1014                    class="internalDFN">user agent</a> or platform, then the <a href="#dfn-user-agent"
  1015                    class="internalDFN">user agent</a> <em class="rfc2119"
  1016                    title="MUST">MUST</em> reject <var>Network Service Promise</var> by running the <a href=
  1017                    "http://dom.spec.whatwg.org/#concept-resolver-reject"
  1018                    class="externalDFN">resolver reject algorithm</a> against the <var>Network Service Promise's
  1019                    Resolver</var>, passing in a newly constructed <a href="http://dom.spec.whatwg.org/#domerror"
  1020                    class="externalDFN"><code>DOMError</code></a> object whose <code>name</code> attribute has the
  1021                    string value "PermissionDeniedError" (<a href=
  1022                    "#dom-domerror-extensions-permission_denied"><code>PERMISSION_DENIED_ERR</code></a>) and whose
  1023                    <code>message</code> attribute has a helpful implementation-dependent message that explains this
  1024                    error, abort any remaining steps and return.
  1025               </p>
  1026               <p>
  1027                 If the user never responds or no previously-established user preference has been met, this algorithm
  1028                 stalls on this step.
  1029               </p>
  1030             </li>
  1031             <li>Let <var>services</var> be an empty array.
  1032             </li>
  1033             <li>If <var>services found</var> is not an empty array then set <var>services</var> to be an array of one
  1034             or more <a href="#networkservice"><code>NetworkService</code></a> objects for which the user granted
  1035             permission above - known as the current objects <dfn id="dfn-user-authorized">user-authorized</dfn>
  1036             services.
  1037             </li>
  1038             <li>Remove all previously whitelisted urls from the <a href="#dfn-entry-script-origin-s-url-whitelist"
  1039                   class="internalDFN">entry script origin's <abbr title="Uniform Resource Locator">URL</abbr>
  1040                   whitelist</a> granted in the current <a href=
  1041                   "http://www.whatwg.org/specs/web-apps/current-work/complete/browsers.html#entry-script"
  1042                   class="externalDFN">entry script</a>'s <a href=
  1043                   "http://www.whatwg.org/specs/web-apps/current-work/complete/origin-0.html#origin"
  1044                   class="externalDFN">origin</a>.
  1045             </li>
  1046             <li>For each Object <var>service</var> in <var>services</var>, if any, run the following sub-steps:
  1047               <ol class="rule">
  1048                 <li>Add the <var>service</var>'s <code>url</code> parameter to the <a href=
  1049                 "#dfn-entry-script-origin-s-url-whitelist"
  1050                       class="internalDFN">entry script origin's <abbr title="Uniform Resource Locator">URL</abbr>
  1051                       whitelist</a>.
  1052                 </li>
  1053                 <li>If <var>service</var>'s <code>type</code> parameter begins with the DOMString "<code>upnp:</code>"
  1054                 and the <var>service</var>'s <code>eventsUrl</code> parameter is not empty then <a href=
  1055                 "#dfn-setup-a-upnp-events-subscription"
  1056                       class="internalDFN">setup a UPnP Events Subscription</a> for <var>service</var>.
  1057                 </li>
  1058               </ol>
  1059             </li>
  1060             <li>Let <var>services manager</var> be a new <a href="#networkservices"><code>NetworkServices</code></a>
  1061             object.
  1062             </li>
  1063             <li>Store <var>requested control types</var> against <var>services manager</var> as an internal variable.
  1064             </li>
  1065             <li>Set <var>services manager</var>'s <a href=
  1066             "#dom-networkservices-servicesavailable"><code>servicesAvailable</code></a> attribute to the number of
  1067             items currently found in the <a href="#dfn-list-of-available-service-records"
  1068                   class="internalDFN">list of available service records</a> whose <code>type</code> property matches
  1069                   any of the tokens requested in <var>requested control types</var>.
  1070             </li>
  1071             <li>Add <var>services</var>, if any, to the <var>services manager</var> object as its collection of
  1072               <a href="#dfn-indexed-properties-1"
  1073                   class="internalDFN">indexed properties</a>. If <var>services</var> is an empty array then the
  1074                   <var>services manager</var> does not have any <var>indexed properties</var>.
  1075             </li>
  1076             <li>Set <var>services manager</var>'s <a href="#dom-networkservices-length"><code>length</code></a>
  1077             attribute to the number of items in <var>services</var>.
  1078             </li>
  1079             <li>Add <var>services manager</var> to the <a href="#dfn-list-of-active-service-managers"
  1080                   class="internalDFN">list of active service managers</a>.
  1081             </li>
  1082             <li>The <a href="#dfn-user-agent"
  1083                   class="internalDFN">user agent</a> <em class="rfc2119"
  1084                   title="MUST">MUST</em> fulfill <var>Network Service Promise</var> by running the <a href=
  1085                   "http://dom.spec.whatwg.org/#concept-resolver-fulfill"
  1086                   class="externalDFN">resolver fulfill algorithm</a> against the <var>Network Service Promise's
  1087                   Resolver</var>, passing in <var>services manager</var> as its argument.
  1088             </li>
  1089           </ol>
  1090           <p>
  1091             The <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#task-source"
  1092                class="externalDFN">task source</a> for these <a href=
  1093                "http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#concept-task"
  1094                class="externalDFN">tasks</a> is the <a href=
  1095                "http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#user-interaction-task-source"
  1096                class="externalDFN">user interaction task source</a>.
  1097           </p>
  1098           <p>
  1099             When a <a href="#networkservice"><code>NetworkService</code></a> object is provided to a Web page, the
  1100             <a href="#dfn-user-agent"
  1101                class="internalDFN">user agent</a> <em class="rfc2119"
  1102                title="MUST">MUST</em> add its <a href="#dom-networkservice-url"><code>url</code></a> to the <dfn id=
  1103                "dfn-entry-script-origin-s-url-whitelist">entry script origin's <abbr title=
  1104                "Uniform Resource Locator">URL</abbr> whitelist</dfn>. This list enables the Web page to override and
  1105                initiate cross-site resource requests towards these URLs, and any sub-resources of these URLs, within
  1106                the current <a href=
  1107                "http://www.whatwg.org/specs/web-apps/current-work/complete/browsers.html#entry-script"
  1108                class="externalDFN">entry script</a>'s <a href=
  1109                "http://www.whatwg.org/specs/web-apps/current-work/complete/origin-0.html#origin"
  1110                class="externalDFN">origin</a> via various existing mechanisms (e.g. Web Sockets, Server-Sent Events,
  1111                Web Messaging, XMLHttpRequest).
  1112           </p>
  1113           <p>
  1114             If the user navigates away from the <a href=
  1115             "http://www.whatwg.org/specs/web-apps/current-work/complete/browsers.html#entry-script"
  1116                class="externalDFN">entry script</a>'s <a href=
  1117                "http://www.whatwg.org/specs/web-apps/current-work/complete/origin-0.html#origin"
  1118                class="externalDFN">origin</a> or permission to access a given networked service is revoked at any time
  1119                by the platform or user then the <a href="#dfn-user-agent"
  1120                class="internalDFN">user agent</a> <em class="ct"><em class="rfc2119"
  1121                 title="MUST">MUST</em></em> remove its previously whitelisted urls from the <a href=
  1122                 "#dfn-entry-script-origin-s-url-whitelist"
  1123                class="internalDFN">entry script origin's <abbr title="Uniform Resource Locator">URL</abbr>
  1124                whitelist</a>.
  1125           </p>
  1126           <p>
  1127             There is no implied persistence to networked service sharing provided to a web page. It <em class="rfc2119"
  1128                title="MUST NOT">MUST NOT</em> be possible to access a previously white-listed networked service without
  1129                user authorization in all of the following cases:
  1130           </p>
  1131           <ul>
  1132             <li>If the current script is reloaded at any point in the same or different window.
  1133             </li>
  1134             <li>if the current script reinvokes the <a href=
  1135             "#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a> method at any point in its
  1136             execution.
  1137             </li>
  1138             <li>If the user navigates forward or back in their history to reload the current page.
  1139             </li>
  1140             <li>If a script is running in a different origin.
  1141             </li>
  1142           </ul>
  1143         </div>
  1144       </section>
  1145       <section id="error-handling">
  1146         <h3 aria-level="2"
  1147             role="heading"
  1148             id="h3_error-handling">
  1149           <span class="secno">5.2</span> Error Handling
  1150         </h3>
  1151         <dl class="domintro">
  1152           <dt>
  1153             <var title="">error</var> . <code title="dom-NavigatorNetworkServiceError-name"><a href=
  1154             "#dom-domerror-extensions-name">name</a></code>
  1155           </dt>
  1156           <dd>
  1157             <p>
  1158               Returns the current error's error name. At the current time, this will be "PermissionDeniedError" or
  1159               "UnknownTypePrefixError", for which the corresponding error constants <a href=
  1160               "#dom-domerror-extensions-permission_denied"><code>PERMISSION_DENIED_ERR</code></a> and <a href=
  1161               "#dom-domerror-extensions-unknown_type_prefix"><code>UNKNOWN_TYPE_PREFIX_ERR</code></a> are defined.
  1162             </p>
  1163           </dd>
  1164         </dl>
  1165         <p>
  1166           The <dfn id="dom-domerror-extensions-name"
  1167              title="dom-domerror-extensions-name"><code>name</code></dfn> attribute of a <a href=
  1168              "http://dom.spec.whatwg.org/#domerror"
  1169              class="externalDFN"><code>DOMError</code></a> object returned from this <abbr title=
  1170              "Application Programming Interface">API</abbr> <em class="ct"><em class="rfc2119"
  1171               title="MUST">MUST</em></em> return the name for the error, which will be one of the following:
  1172         </p>
  1173         <dl>
  1174           <dt>
  1175             <dfn id="dom-domerror-extensions-permission_denied"
  1176                 title="dom-domerror-extensions-permission_denied"><code>PERMISSION_DENIED_ERR</code></dfn> (DOMString
  1177                 value "PermissionDeniedError")
  1178           </dt>
  1179           <dd>
  1180             The user or user agent denied the page permission to access any services.
  1181           </dd>
  1182           <dt>
  1183             <dfn id="dom-domerror-extensions-unknown_type_prefix"
  1184                 title="dom-domerror-extensions-unknown_type_prefix"><code>UNKNOWN_TYPE_PREFIX_ERR</code></dfn>
  1185                 (DOMString value "UnknownTypePrefixError")
  1186           </dt>
  1187           <dd>
  1188             No <a href="#dfn-valid-service-type"
  1189                 class="internalDFN">valid service type</a> tokens were provided in the method invocation.
  1190           </dd>
  1191         </dl>
  1192       </section>
  1193     </section>
  1194     <section id="obtaining-networked-services">
  1195       <h2 aria-level="1"
  1196           role="heading"
  1197           id="h2_obtaining-networked-services">
  1198         <span class="secno">6.</span> Obtaining networked services
  1199       </h2>
  1200       <p>
  1201         The <a href="#networkservices"><code>NetworkServices</code></a> interface represents a collection of zero or
  1202         more <dfn id="dfn-indexed-properties">indexed properties</dfn> that are each a <a href="#dfn-user-authorized"
  1203            class="internalDFN">user-authorized</a> <a href="#networkservice"><code>NetworkService</code></a> object.
  1204       </p>
  1205       <p>
  1206         A <a href="#networkservices"><code>NetworkServices</code></a> object is the <a href=
  1207         "http://dom.spec.whatwg.org/#concept-promise-result"
  1208            class="externalDFN">promise result</a> from a call to <a href=
  1209            "#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a>.
  1210       </p>
  1211       <pre class="widl">
  1212 [NoInterfaceObject]
  1213 interface <dfn id="networkservices">NetworkServices</dfn> {
  1214   readonly attribute unsigned long    <a href="#dom-networkservices-length">length</a>;
  1215   getter <a href="#networkservice">NetworkService</a> (unsigned long index);
  1216   <a href="#networkservice">NetworkService</a>? <a href=
  1217 "#dom-networkservices-getservicebyid">getServiceById</a>(DOMString id);
  1218 
  1219   readonly attribute unsigned long    <a href="#dom-networkservices-servicesavailable">servicesAvailable</a>;
  1220 
  1221   // event handler attributes
  1222            attribute <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler"
  1223      class="externalDFN">EventHandler</a>     <a href="#dom-networkservices-onservicefound">onservicefound</a>;
  1224            attribute <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler"
  1225      class="externalDFN">EventHandler</a>     <a href="#dom-networkservices-onservicelost">onservicelost</a>;
  1226 
  1227 };
  1228 
  1229 <a href="#networkservices">NetworkServices</a> implements <a href=
  1230 "http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#interface-eventtarget"
  1231      class="externalDFN">EventTarget</a>;
  1232 </pre>
  1233       <section id="attributes">
  1234         <h3 aria-level="2"
  1235             role="heading"
  1236             id="h3_attributes">
  1237           <span class="secno">6.1</span> Attributes
  1238         </h3>
  1239         <dl class="domintro">
  1240           <dt>
  1241             <code title="dom-networkservices-length"><a href="#dom-networkservices-length">length</a></code>
  1242           </dt>
  1243           <dd>
  1244             <p>
  1245               Returns the current number of <a href="#dfn-indexed-properties-1"
  1246                  class="internalDFN">indexed properties</a> in the current object's collection.
  1247             </p>
  1248           </dd>
  1249           <dt>
  1250             <code title="dom-networkservices-servicesavailable"><a href=
  1251             "#dom-networkservices-servicesavailable">servicesAvailable</a></code>
  1252           </dt>
  1253           <dd>
  1254             <p>
  1255               Returns the current number of items matching one of the app-requested <a href="#dfn-valid-service-type"
  1256                  class="internalDFN">valid service type</a> tokens in the <a href=
  1257                  "#dfn-list-of-available-service-records"
  1258                  class="internalDFN">list of available service records</a>.
  1259             </p>
  1260           </dd>
  1261         </dl>
  1262         <div>
  1263           <p>
  1264             The <dfn id="dom-networkservices-length"><code>length</code></dfn> attribute <em class="rfc2119"
  1265                title="MUST">MUST</em> return the number of <a href="#networkservice"><code>NetworkService</code></a>
  1266                objects represented by the collection.
  1267           </p>
  1268           <p>
  1269             The <dfn id="dom-networkservices-servicesavailable"><code>servicesAvailable</code></dfn> attribute
  1270             <em class="rfc2119"
  1271                title="MUST">MUST</em> return the number of services in the <a href=
  1272                "#dfn-list-of-available-service-records"
  1273                class="internalDFN">list of available service records</a> whose <code>type</code> attribute matches any
  1274                of the <a href="#dfn-valid-service-type"
  1275                class="internalDFN">valid service type</a> tokens that were initially used to create the current <a href=
  1276                "#networkservices"><code>NetworkServices</code></a> object.
  1277           </p>
  1278         </div>
  1279       </section>
  1280       <section id="methods-1">
  1281         <h3 aria-level="2"
  1282             role="heading"
  1283             id="h3_methods-1">
  1284           <span class="secno">6.2</span> Methods
  1285         </h3>
  1286         <dl class="domintro">
  1287           <dt>
  1288             <code title="networkservices-getter"><a href="#networkservices">services</a></code> [ <var title=
  1289             "">index</var> ]
  1290           </dt>
  1291           <dd>
  1292             <p>
  1293               Returns the specified <a href="#networkservice"><code>NetworkService</code></a> object.
  1294             </p>
  1295           </dd>
  1296           <dt>
  1297             <code title="networkservices-getter"><a href="#networkservices">services</a></code> . <code title=
  1298             "dom-networkservices-getservicebyid"><a href=
  1299             "#dom-networkservices-getservicebyid">getServiceById</a></code> ( <var title="">id</var> )
  1300           </dt>
  1301           <dd>
  1302             <p>
  1303               Returns the <a href="#networkservice"><code>NetworkService</code></a> object with the given identifier,
  1304               or null if no service has that identifier.
  1305             </p>
  1306           </dd>
  1307         </dl>
  1308         <p>
  1309           A <a href="#networkservices"><code>NetworkServices</code></a> object represents the current collection of
  1310           zero or more <a href="#networkservice"><code>NetworkService</code></a> objects - its <a href=
  1311           "#dfn-indexed-properties-1"
  1312              class="internalDFN">indexed properties</a>. The <a href="#dfn-indexed-properties-1"
  1313              class="internalDFN">indexed properties</a> of a <a href=
  1314              "#networkservices"><code>NetworkServices</code></a> object are <span>immutable</span> meaning that <a href=
  1315              "#dfn-indexed-properties-1"
  1316              class="internalDFN">indexed properties</a> cannot be added and <a href="#dfn-indexed-properties-1"
  1317              class="internalDFN">indexed properties</a> cannot be removed for the lifetime of a <a href=
  1318              "#networkservices"><code>NetworkServices</code></a> object.
  1319         </p>
  1320         <p>
  1321           The <a href=
  1322           "http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#supported-property-indices"
  1323              class="externalDFN">supported property indices</a> of <a href=
  1324              "#networkservices"><code>NetworkServices</code></a> objects at any instant are the numbers from zero to
  1325              the number of the <a href="#networkservice"><code>NetworkService</code></a> objects in the collection
  1326              minus one.
  1327         </p>
  1328         <div class="note">
  1329           <div class="note-title"
  1330                aria-level="3"
  1331                role="heading"
  1332                id="h_note_1">
  1333             <span>Note</span>
  1334           </div>
  1335           <p class="">
  1336             Each service in a <a href="#networkservices"><code>NetworkServices</code></a> object thus has an index; the
  1337             first has the index 0, and each subsequent service is numbered one higher than the previous one.
  1338           </p>
  1339         </div>
  1340         <p>
  1341           To <a href=
  1342           "http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#determine-the-value-of-an-indexed-property"
  1343              class="externalDFN">determine the value of an indexed property</a> for a given index <var>index</var> in a
  1344              <a href="#networkservices"><code>NetworkServices</code></a> object the user agent <em class="rfc2119"
  1345              title="MUST">MUST</em> return the <a href="#networkservice"><code>NetworkService</code></a> object that
  1346              represents the <var>index</var>th item in the collection.
  1347         </p>
  1348         <p>
  1349           The <dfn id="dom-networkservices-getservicebyid"><code>getServiceById(id)</code></dfn> method <em class=
  1350           "ct"><em class="rfc2119"
  1351               title="MUST">MUST</em></em> return the first <a href="#networkservice"><code>NetworkService</code></a>
  1352               object in the collection whose <a href="#dom-networkservice-id"><code>id</code></a> attribute is equal to
  1353               the value of the <var>id</var> argument provided. When no <a href=
  1354               "#networkservice"><code>NetworkService</code></a> objects match the given argument, the method <em class=
  1355               "rfc2119"
  1356              title="MUST">MUST</em> return null.
  1357         </p>
  1358       </section>
  1359       <section id="events">
  1360         <h3 aria-level="2"
  1361             role="heading"
  1362             id="h3_events">
  1363           <span class="secno">6.3</span> Events
  1364         </h3>
  1365         <p>
  1366           The following are the event handlers (and their corresponding event handler event types) that <em class=
  1367           "ct"><em class="rfc2119"
  1368               title="MUST">MUST</em></em> be supported, as IDL attributes, by all objects implementing the <a href=
  1369               "#networkservices"><code>NetworkServices</code></a> interface:
  1370         </p>
  1371         <table border="1">
  1372           <thead>
  1373             <tr>
  1374               <th>
  1375                 <span title="event handlers">Event handler</span>
  1376               </th>
  1377               <th>
  1378                 <span>Event handler event type</span>
  1379               </th>
  1380             </tr>
  1381           </thead>
  1382           <tbody>
  1383             <tr>
  1384               <td>
  1385                 <dfn id="dom-networkservices-onservicefound"
  1386                     title="dom-NetworkServices-onservicefound"><code>onservicefound</code></dfn>
  1387               </td>
  1388               <td>
  1389                 <a href="#event-servicefound"><code>servicefound</code></a>
  1390               </td>
  1391             </tr>
  1392             <tr>
  1393               <td>
  1394                 <dfn id="dom-networkservices-onservicelost"
  1395                     title="dom-NetworkServices-onservicelost"><code>onservicelost</code></dfn>
  1396               </td>
  1397               <td>
  1398                 <a href="#event-servicelost"><code>servicelost</code></a>
  1399               </td>
  1400             </tr>
  1401           </tbody>
  1402         </table>
  1403       </section>
  1404     </section>
  1405     <section id="communicating-with-a-networked-service">
  1406       <h2 aria-level="1"
  1407           role="heading"
  1408           id="h2_communicating-with-a-networked-service">
  1409         <span class="secno">7.</span> Communicating with a networked service
  1410       </h2>
  1411       <p>
  1412         The <a href="#networkservice"><code>NetworkService</code></a> interface is used to provide a set of connection
  1413         information for an <abbr title="Hypertext Transfer Protocol">HTTP</abbr> service endpoint and if available,
  1414         service events, running on a networked device.
  1415       </p>
  1416       <pre class="widl">
  1417 [NoInterfaceObject]
  1418 interface <dfn id="networkservice">NetworkService</dfn> {
  1419   readonly attribute DOMString        <a href="#dom-networkservice-id">id</a>;
  1420   readonly attribute DOMString        <a href="#dom-networkservice-name">name</a>;
  1421   readonly attribute DOMString        <a href="#dom-networkservice-type">type</a>;
  1422   readonly attribute DOMString        <a href="#dom-networkservice-url">url</a>;
  1423   readonly attribute DOMString        <a href="#dom-networkservice-config">config</a>;
  1424 
  1425   readonly attribute boolean          <a href="#dom-networkservice-online">online</a>;
  1426 
  1427   // event handler attributes
  1428            attribute <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler"
  1429      class="externalDFN">EventHandler</a>     <a href="#dom-networkservice-onavailable">onavailable</a>;
  1430            attribute <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler"
  1431      class="externalDFN">EventHandler</a>     <a href="#dom-networkservice-onunavailable">onunavailable</a>;
  1432 
  1433            attribute <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler"
  1434      class="externalDFN">EventHandler</a>     <a href="#dom-networkservice-onnotify">onnotify</a>;
  1435 };
  1436 
  1437 <a href="#networkservice">NetworkService</a> implements <a href=
  1438 "http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#interface-eventtarget"
  1439      class="externalDFN">EventTarget</a>;
  1440 </pre>
  1441       <section id="attributes-1">
  1442         <h3 aria-level="2"
  1443             role="heading"
  1444             id="h3_attributes-1">
  1445           <span class="secno">7.1</span> Attributes
  1446         </h3>
  1447         <dl class="domintro">
  1448           <dt>
  1449             <var title="">service</var> . <code title="dom-networkservice-id"><a href=
  1450             "#dom-networkservice-id">id</a></code>
  1451           </dt>
  1452           <dd>
  1453             <p>
  1454               A unique identifier for the given user-selected service instance.
  1455             </p>
  1456           </dd>
  1457           <dt>
  1458             <var title="">service</var> . <code title="dom-networkservice-name"><a href=
  1459             "#dom-networkservice-name">name</a></code>
  1460           </dt>
  1461           <dd>
  1462             <p>
  1463               The name of the user-selected service.
  1464             </p>
  1465           </dd>
  1466           <dt>
  1467             <var title="">service</var> . <code title="dom-networkservice-type"><a href=
  1468             "#dom-networkservice-type">type</a></code>
  1469           </dt>
  1470           <dd>
  1471             <p>
  1472               The <a href="#dfn-valid-service-type"
  1473                  class="internalDFN">valid service type</a> token value of the user-selected service.
  1474             </p>
  1475           </dd>
  1476           <dt>
  1477             <var title="">service</var> . <code title="dom-networkservice-url"><a href=
  1478             "#dom-networkservice-url">url</a></code>
  1479           </dt>
  1480           <dd>
  1481             <p>
  1482               The control <abbr title="Uniform Resource Locator">URL</abbr> endpoint (including any required port
  1483               information) of the user-selected control service that has been added to the <a href=
  1484               "#dfn-entry-script-origin-s-url-whitelist"
  1485                  class="internalDFN">entry script origin's <abbr title="Uniform Resource Locator">URL</abbr>
  1486                  whitelist</a>.
  1487             </p>
  1488           </dd>
  1489           <dt>
  1490             <var title="">service</var> . <code title="dom-networkservice-config"><a href=
  1491             "#dom-networkservice-config">config</a></code>
  1492           </dt>
  1493           <dd>
  1494             <p>
  1495               The configuration information associated with the service depending on the requested service type.
  1496             </p>
  1497           </dd>
  1498         </dl>
  1499         <p>
  1500           The <dfn id="dom-networkservice-id"><code>id</code></dfn> attribute is a unique identifier for the service.
  1501           The same service provided at different times or on different objects <em class="rfc2119"
  1502              title="MUST">MUST</em> have the same <a href="#dom-networkservice-id"><code>id</code></a> value.
  1503         </p>
  1504         <p>
  1505           The <dfn id="dom-networkservice-name"><code>name</code></dfn> attribute represents a human-readable title for
  1506           the service.
  1507         </p>
  1508         <p>
  1509           The <dfn id="dom-networkservice-type"><code>type</code></dfn> attribute reflects the value of the <a href=
  1510           "#dfn-valid-service-type"
  1511              class="internalDFN">valid service type</a> of the service.
  1512         </p>
  1513         <p>
  1514           The <dfn id="dom-networkservice-url"><code>url</code></dfn> attribute is an <a href=
  1515           "http://url.spec.whatwg.org/#concept-absolute-url"
  1516              class="externalDFN">absolute <abbr title="Uniform Resource Locator">URL</abbr></a> pointing to the root
  1517              <abbr title="Hypertext Transfer Protocol">HTTP</abbr> endpoint for the service that has been added to the
  1518              <a href="#dfn-entry-script-origin-s-url-whitelist"
  1519              class="internalDFN">entry script origin's <abbr title="Uniform Resource Locator">URL</abbr> whitelist</a>.
  1520              Web pages can subsequently use this value for implicit cross-document messaging via various existing
  1521              mechanisms (e.g. Web Sockets, Server-Sent Events, Web Messaging, XMLHttpRequest).
  1522         </p>
  1523         <p>
  1524           The <dfn id="dom-networkservice-config"><code>config</code></dfn> attribute provides the raw configuration
  1525           information extracted from the given network service.
  1526         </p>
  1527       </section>
  1528       <section id="states">
  1529         <h3 aria-level="2"
  1530             role="heading"
  1531             id="h3_states">
  1532           <span class="secno">7.2</span> States
  1533         </h3>
  1534         <dl class="domintro">
  1535           <dt>
  1536             <var title="">service</var> . <code title="dom-networkservice-online"><a href=
  1537             "#dom-networkservice-online">online</a></code>
  1538           </dt>
  1539           <dd>
  1540             <p>
  1541               Returns <code>true</code> if the service is reporting that it is accessible on the local network or
  1542               <code>false</code> if the service is no longer accessible (temporarily or permanently) on the local
  1543               network.
  1544             </p>
  1545           </dd>
  1546         </dl>
  1547         <p>
  1548           The <dfn id="dom-networkservice-online"><code>online</code></dfn> attribute indicates whether the service is
  1549           either <var>online</var>, and therefore accessible on the local network, in which case this attribute will
  1550           return <code>true</code> or, <var>offline</var>, and therefore not accessible on the local network, either
  1551           temporarily or permanently, in which case this attribute will return <code>false</code>. This attribute
  1552           <em class="rfc2119"
  1553              title="MUST">MUST</em> default to <code>true</code>.
  1554         </p>
  1555       </section>
  1556       <section id="events-1">
  1557         <h3 aria-level="2"
  1558             role="heading"
  1559             id="h3_events-1">
  1560           <span class="secno">7.3</span> Events
  1561         </h3>
  1562         <p>
  1563           The following are the event handlers (and their corresponding event handler event types) that <em class=
  1564           "ct"><em class="rfc2119"
  1565               title="MUST">MUST</em></em> be supported, as IDL attributes, by all objects implementing the <a href=
  1566               "#networkservice"><code>NetworkService</code></a> interface:
  1567         </p>
  1568         <table border="1">
  1569           <thead>
  1570             <tr>
  1571               <th>
  1572                 <span title="event handlers">Event handler</span>
  1573               </th>
  1574               <th>
  1575                 <span>Event handler event type</span>
  1576               </th>
  1577             </tr>
  1578           </thead>
  1579           <tbody>
  1580             <tr>
  1581               <td>
  1582                 <dfn id="dom-networkservice-onnotify"
  1583                     title="dom-NetworkService-onnotify"><code>onnotify</code></dfn>
  1584               </td>
  1585               <td>
  1586                 <a href="#event-notify"><code>notify</code></a>
  1587               </td>
  1588             </tr>
  1589             <tr>
  1590               <td>
  1591                 <dfn id="dom-networkservice-onavailable"
  1592                     title="dom-NetworkService-onavailable"><code>onavailable</code></dfn>
  1593               </td>
  1594               <td>
  1595                 <a href="#event-available"><code>available</code></a>
  1596               </td>
  1597             </tr>
  1598             <tr>
  1599               <td>
  1600                 <dfn id="dom-networkservice-onunavailable"
  1601                     title="dom-NetworkService-onunavailable"><code>onunavailable</code></dfn>
  1602               </td>
  1603               <td>
  1604                 <a href="#event-unavailable"><code>unavailable</code></a>
  1605               </td>
  1606             </tr>
  1607           </tbody>
  1608         </table>
  1609       </section>
  1610     </section>
  1611     <section id="service-discovery">
  1612       <h2 aria-level="1"
  1613           role="heading"
  1614           id="h2_service-discovery">
  1615         <span class="secno">8.</span> Service Discovery
  1616       </h2>
  1617       <p>
  1618         A <a href="#dfn-user-agent"
  1619            class="internalDFN">user agent</a> conforming to this specification <em class="rfc2119"
  1620            title="MAY">MAY</em> implement <abbr title="Simple Service Discovery Protocol">SSDP</abbr> [<cite><a class=
  1621            "bibref"
  1622            href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>], Zeroconf [<cite><a class="bibref"
  1623            href="#bib-DNS-SD">DNS-SD</a></cite>] + [<cite><a class="bibref"
  1624            href="#bib-MDNS">MDNS</a></cite>] and/or <abbr title="Discovery and Launch Protocol">DIAL</abbr> [<a href=
  1625            "https://sites.google.com/a/dial-multiscreen.org/dial/dial-protocol-specification"><abbr title=
  1626            "Discovery and Launch Protocol">DIAL</abbr></a>] <dfn id="dfn-service-discovery-mechanisms">service
  1627            discovery mechanisms</dfn> - the requirements detailed in this section of the specification - to enable Web
  1628            pages to request and connect with <abbr title="Hypertext Transfer Protocol">HTTP</abbr> services running on
  1629            networked devices, discovered via any of these mechanisms, through this <abbr title=
  1630            "Application Programming Interface">API</abbr>. When a <a href="#dfn-user-agent"
  1631            class="internalDFN">user agent</a> implements any of these <a href="#dfn-service-discovery-mechanisms"
  1632            class="internalDFN">service discovery mechanisms</a>, then it <em class="rfc2119"
  1633            title="MUST">MUST</em> conform to the corresponding algorithms provided in this section of the
  1634            specification.
  1635       </p>
  1636       <p>
  1637         This section presents how the results of these <a href="#dfn-service-discovery-mechanisms"
  1638            class="internalDFN">service discovery mechanisms</a> will be matched to requested service types, how the
  1639            user agent stores available and active services and how their properties are applied to any resulting
  1640            <a href="#networkservice"><code>NetworkService</code></a> objects.
  1641       </p>
  1642       <p>
  1643         It is expected that user agents will perform these <a href="#dfn-service-discovery-mechanisms"
  1644            class="internalDFN">service discovery mechanisms</a> asynchronously and periodically update the <a href=
  1645            "#dfn-list-of-available-service-records"
  1646            class="internalDFN">list of available service records</a> as required. The timing of any <a href=
  1647            "#dfn-service-discovery-mechanisms"
  1648            class="internalDFN">service discovery mechanisms</a> is an implementation detail left to the discretion of
  1649            the implementer (e.g. by continuously monitoring the network as a background process or on invocation of
  1650            this <abbr title="Application Programming Interface">API</abbr> from a Web page).
  1651       </p>
  1652       <p>
  1653         The <dfn id="dfn-list-of-available-service-records">list of available service records</dfn> is a single dynamic
  1654         internal lookup table within user agents that is used to track all the services that have been discovered and
  1655         are available in the current network at the current time. At any point during the running of any of the
  1656         <a href="#dfn-service-discovery-mechanisms"
  1657            class="internalDFN">service discovery mechanisms</a> then existing entries within this table can be updated,
  1658            entries can be added and entries can be removed as the status of networked services changes according to the
  1659            rules defined in this specification.
  1660       </p>
  1661       <p>
  1662         The <dfn id="dfn-list-of-active-service-managers">list of active service managers</dfn> is an internal list
  1663         within user agents that is used to track all <a href="#networkservices"><code>NetworkServices</code></a>
  1664         objects currently being shared with any web pages at the current time within the user agent. Each <a href=
  1665         "#networkservices"><code>NetworkServices</code></a> object in the <a href=
  1666         "#dfn-list-of-active-service-managers"
  1667            class="internalDFN">list of active service managers</a> represents a collection of zero or more <a href=
  1668            "#networkservice"><code>NetworkService</code></a> objects - known as its <dfn id=
  1669            "dfn-indexed-properties-1">indexed properties</dfn>. <a href=
  1670            "#networkservice"><code>NetworkService</code></a> objects are attached as the <a href=
  1671            "#dfn-indexed-properties-1"
  1672            class="internalDFN">indexed properties</a> of a <a href="#networkservices"><code>NetworkServices</code></a>
  1673            object as part of the <a href="#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a>
  1674            algorithm.
  1675       </p>
  1676       <p>
  1677         The rule for <dfn id="dfn-adding-an-available-service">adding an available service</dfn> is the process of
  1678         adding a <a href="#dfn-new-service"
  1679            class="internalDFN">new service</a> or updating an <a href="#dfn-existing-service"
  1680            class="internalDFN">existing service</a> that is generally available on the user's current network in the
  1681            <a href="#dfn-list-of-available-service-records"
  1682            class="internalDFN">list of available service records</a>. This rule takes one argument, <var>network
  1683            service record</var>, and consists of running the following steps:
  1684       </p>
  1685       <ol class="rule">
  1686         <li>For each <var>existing service record</var> in the current <a href="#dfn-list-of-available-service-records"
  1687               class="internalDFN">list of available service records</a>, run the following sub-steps:
  1688           <ol class="rule">
  1689             <li>If the <var>existing service record</var>'s <code>id</code> property does not equal <var>network
  1690             service record</var>'s <code>id</code> property then abort any remaining sub-steps and continue at the next
  1691             available <var>existing service record</var>.
  1692             </li>
  1693             <li>Replace the value of <var>existing service record</var> in the current <a href=
  1694             "#dfn-list-of-available-service-records"
  1695                   class="internalDFN">list of available service records</a> with the value of <var>network service
  1696                   record</var>, aborting any remaining steps in this algorithm and return.
  1697             </li>
  1698           </ol>
  1699         </li>
  1700         <li>Add <var>network service record</var> to the <a href="#dfn-list-of-available-service-records"
  1701               class="internalDFN">list of available service records</a> as a new item.
  1702         </li>
  1703         <li>For each <var>service manager</var> in the <a href="#dfn-list-of-active-service-managers"
  1704               class="internalDFN">list of active service managers</a> run the following steps:
  1705           <ol class="rule">
  1706             <li>For each <var>active service</var> in <var>service manager</var> run the following steps:
  1707               <ol class="rule">
  1708                 <li>If the <var>network service record</var>'s <code>id</code> property equals the <var>active
  1709                 service</var>'s <code>id</code> attribute and <var>active service</var>'s <code>online</code> attribute
  1710                 is currently set to <code>false</code> then set <var>active service</var>'s <a href=
  1711                 "#dom-networkservice-online"><code>online</code></a> attribute to <code>true</code> and then <a href=
  1712                 "http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task"
  1713                       class="externalDFN">queue a task</a> to dispatch a newly created event with the name <a href=
  1714                       "#event-available"><code>available</code></a> that uses the <a href=
  1715                       "http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event"
  1716                       class="externalDFN"><code>Event</code></a> interface, which does not bubble, is not cancellable,
  1717                       and has no default action, at the current <var>active service</var> object.
  1718                 </li>
  1719               </ol>
  1720             </li>
  1721             <li>Let <var>'service type in current service manager' flag</var> be <code>false</code>.
  1722             </li>
  1723             <li>For each <var>requested control type</var> of the <var>requested control types</var> in <var>service
  1724             manager</var> run the following steps:
  1725               <ol class="rule">
  1726                 <li>If <var>network service record</var>'s <code>type</code> property does not equal <var>requested
  1727                 control type</var> then abort any remaining sub-steps and continue at the next available <var>requested
  1728                 control type</var>.
  1729                 </li>
  1730                 <li>Set the <var>'service type in current service manager' flag</var> to <code>true</code>, abort any
  1731                 remaining sub-steps and continue.
  1732                 </li>
  1733               </ol>
  1734             </li>
  1735             <li>If the <var>'service type in current service manager' flag</var> is set to <code>true</code> then
  1736             increment <var>service manager</var>'s <a href=
  1737             "#dom-networkservices-servicesavailable"><code>servicesAvailable</code></a> attribute by <code>1</code> and
  1738             then <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task"
  1739                   class="externalDFN">queue a task</a> to dispatch a newly created event with the name <a href=
  1740                   "#event-servicefound"><code>servicefound</code></a> that uses the <a href=
  1741                   "http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event"
  1742                   class="externalDFN"><code>Event</code></a> interface, which does not bubble, is not cancellable, and
  1743                   has no default action, at the current <var>service manager</var> object.
  1744             </li>
  1745           </ol>
  1746         </li>
  1747       </ol>
  1748       <p>
  1749         The rule for <dfn id="dfn-removing-an-available-service">removing an available service</dfn> is the general
  1750         process of removing an <a href="#dfn-existing-service"
  1751            class="internalDFN">existing service</a> from the <a href="#dfn-list-of-available-service-records"
  1752            class="internalDFN">list of available service records</a> that has left the user's current network or has
  1753            otherwise expired. This rule takes one argument, <var>service identifier</var>, and consists of running the
  1754            following steps:
  1755       </p>
  1756       <ol class="rule">
  1757         <li>For each <var>existing service record</var> in the current <a href="#dfn-list-of-available-service-records"
  1758               class="internalDFN">list of available service records</a>, run the following sub-steps:
  1759           <ol class="rule">
  1760             <li>If the <var>existing service record</var>'s <code>id</code> property does not match <var>service
  1761             identifier</var> then skip any remaining sub-steps for the current <var>existing service record</var> and
  1762             continue at the next available <var>existing service record</var>.
  1763             </li>
  1764             <li>Let <var>'service type in use' flag</var> be <code>false</code>.
  1765             </li>
  1766             <li>For each <var>service manager</var> in the <a href="#dfn-list-of-active-service-managers"
  1767                   class="internalDFN">list of active service managers</a> run the following steps:
  1768               <ol class="rule">
  1769                 <li>Let <var>'service type in current service manager' flag</var> be <code>false</code>.
  1770                 </li>
  1771                 <li>For each <var>active service</var> in <var>service manager</var> run the following steps:
  1772                   <ol class="rule">
  1773                     <li>If <var>existing service record</var>'s <code>id</code> property equals the <var>active
  1774                     service</var>'s <code>id</code> attribute and <var>active service</var>'s <a href=
  1775                     "#dom-networkservice-online"><code>online</code></a> attribute is currently set to
  1776                     <code>true</code> then set <var>active service</var>'s <a href="#dom-networkservice-online"><code>
  1777                       online</code></a> attribute to <code>false</code> and then <a href=
  1778                       "http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task"
  1779                           class="externalDFN">queue a task</a> to dispatch a newly created event with the name <a href=
  1780                           "#event-unavailable"><code>unavailable</code></a> that uses the <a href=
  1781                           "http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event"
  1782                           class="externalDFN"><code>Event</code></a> interface, which does not bubble, is not
  1783                           cancellable, and has no default action, at the current <var>active service</var>.
  1784                     </li>
  1785                   </ol>
  1786                 </li>
  1787                 <li>For each <var>requested control type</var> of the <var>requested control types</var> in
  1788                 <var>service manager</var> run the following steps:
  1789                   <ol class="rule">
  1790                     <li>If <var>existing service record</var>'s <code>type</code> property does not equal
  1791                     <var>requested control type</var> then abort any remaining sub-steps and continue at the next
  1792                     available <var>requested control type</var>.
  1793                     </li>
  1794                     <li>Set the <var>'service type in current service manager' flag</var> to <code>true</code> and the
  1795                     <var>'service type in use' flag</var> to <code>true</code>, abort any remaining sub-steps and
  1796                     continue.
  1797                     </li>
  1798                   </ol>
  1799                 </li>
  1800                 <li>If the <var>'service type in current service manager' flag</var> is set to <code>true</code> then
  1801                 decrement <var>service manager</var>'s <a href=
  1802                 "#dom-networkservices-servicesavailable"><code>servicesAvailable</code></a> attribute by <code>1</code>
  1803                 and then <a href=
  1804                 "http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task"
  1805                       class="externalDFN">queue a task</a> to dispatch a newly created event with the name <a href=
  1806                       "#event-servicelost"><code>servicelost</code></a> that uses the <a href=
  1807                       "http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event"
  1808                       class="externalDFN"><code>Event</code></a> interface, which does not bubble, is not cancellable,
  1809                       and has no default action, at the current <var>service manager</var> object.
  1810                 </li>
  1811               </ol>
  1812             </li>
  1813             <li>If the <var>'service type in use' flag</var> is <code>false</code> and the <var>existing service
  1814             record</var>'s <code>type</code> property begins with the DOMString "<code>upnp:</code>" and <var>existing
  1815             service record</var>'s <code>eventsURL</code> property is set then run the rule to <a href=
  1816             "#dfn-terminate-an-existing-upnp-events-subscription"
  1817                   class="internalDFN">terminate an existing UPnP Events Subscription</a>, if one is currently active
  1818                   (as a result of having previously called <a href="#dfn-setup-a-upnp-events-subscription"
  1819                   class="internalDFN">setup a UPnP Events Subscription</a> against the current <var>existing service
  1820                   record</var>).
  1821             </li>
  1822             <li>Remove <var>existing service record</var> from the current <a href=
  1823             "#dfn-list-of-available-service-records"
  1824                   class="internalDFN">list of available service records</a>.
  1825             </li>
  1826           </ol>
  1827         </li>
  1828       </ol>
  1829       <p>
  1830         User agents <em class="rfc2119"
  1831            title="SHOULD">SHOULD</em> expire a service record from the <a href="#dfn-list-of-available-service-records"
  1832            class="internalDFN">list of available service records</a> when its <code>expiryTimestamp</code> attribute
  1833            exceeds the current UTC timestamp. When this condition is met the <a href="#dfn-user-agent"
  1834            class="internalDFN">user agent</a> <em class="rfc2119"
  1835            title="SHOULD">SHOULD</em> run the rule for <a href="#dfn-removing-an-available-service"
  1836            class="internalDFN">removing an available service</a>, passing in the expired service record's
  1837            <code>id</code> attribute as the only argument.
  1838       </p>
  1839       <section id="zeroconf-mdns-dns-sd">
  1840         <h3 aria-level="2"
  1841             role="heading"
  1842             id="h3_zeroconf-mdns-dns-sd">
  1843           <span class="secno">8.1</span> Zeroconf (<abbr title="Multicast DNS">mDNS</abbr> + <abbr title=
  1844           "Domain Name System">DNS</abbr>-<abbr title="Service Discovery">SD</abbr>)
  1845         </h3>
  1846         <p>
  1847           For each <abbr title="Domain Name System">DNS</abbr> response received from a user-agent-initiated Multicast
  1848           <abbr title="Domain Name System">DNS</abbr> Browse for <abbr title="DNS Pointer Record">PTR</abbr> records
  1849           with the name <code>_services._dns-sd._udp</code> on the resolved recommended automatic browsing domain
  1850           [<cite><a class="bibref"
  1851              href="#bib-MDNS">MDNS</a></cite>], the <a href="#dfn-user-agent"
  1852              class="internalDFN">user agent</a> <em class="rfc2119"
  1853              title="MUST">MUST</em> run the following steps:
  1854         </p>
  1855         <ol class="rule">
  1856           <li>Let <var>service <abbr title="Multicast DNS">mDNS</abbr> responses</var> be an array of <abbr title=
  1857           "DNS Pointer Record">PTR</abbr> records received by issuing a Multicast <abbr title=
  1858           "Domain Name System">DNS</abbr> Browse for <abbr title="DNS Pointer Record">PTR</abbr> records with the name
  1859           of the current discovered service type.
  1860           </li>
  1861           <li>For each Object <var>service <abbr title="Multicast DNS">mDNS</abbr> response</var> in <var>service
  1862           <abbr title="Multicast DNS">mDNS</abbr> responses</var>, run the following steps:
  1863             <ol>
  1864               <li>Let <var>network service record</var> be an Object consisting of the following empty properties:
  1865               <code>id</code>, <code>name</code>, <code>type</code>, <code>url</code>, <code>config</code>,
  1866               <code>expiryTimestamp</code>.
  1867               </li>
  1868               <li>Set <var>network service record</var>'s <code>id</code> property to the value of the full
  1869                 <abbr title="DNS Pointer Record">PTR</abbr> Service Instance Name [<cite><a class="bibref"
  1870                    href="#bib-MDNS">MDNS</a></cite>].
  1871               </li>
  1872               <li>Set <var>network service record</var>'s <code>name</code> property to the value of the <abbr title=
  1873               "DNS Pointer Record">PTR</abbr> Service Instance Name's <var>Instance</var> component [<cite><a class=
  1874               "bibref"
  1875                    href="#bib-MDNS">MDNS</a></cite>].
  1876               </li>
  1877               <li>Set <var>network service record</var>'s <code>type</code> property to the concatenation of the string
  1878               <code>zeroconf:</code> followed be the value of the <abbr title="DNS Pointer Record">PTR</abbr> Service
  1879               Instance Name's <var>Service</var> component [<cite><a class="bibref"
  1880                    href="#bib-MDNS">MDNS</a></cite>].
  1881               </li>
  1882               <li>Set <var>network service record</var>'s <code>url</code> property to the resolvable Service
  1883               <abbr title="Uniform Resource Locator">URL</abbr> obtained from performing an <abbr title=
  1884               "Domain Name System">DNS</abbr>-<abbr title="Service Discovery">SD</abbr> Lookup [<cite><a class="bibref"
  1885                    href="#bib-DNS-SD">DNS-SD</a></cite>] of the current service from the <abbr title=
  1886                    "DNS Pointer Record">PTR</abbr> record provided [<cite><a class="bibref"
  1887                    href="#bib-MDNS">MDNS</a></cite>].
  1888               </li>
  1889               <li>Set <var>network service record</var>'s <code>config</code> property to the string value of the
  1890               contents of the first <abbr title="Domain Name System">DNS</abbr>-<abbr title=
  1891               "Service Discovery">SD</abbr> TXT record associated with the <var>service <abbr title=
  1892               "Multicast DNS">mDNS</abbr> response</var> as defined in [<cite><a class="bibref"
  1893                    href="#bib-DNS-SD">DNS-SD</a></cite>].
  1894               </li>
  1895               <li>Set <var>network service record</var>'s <code>expiryTimestamp</code> property to the value of the
  1896               current date, in UTC timestamp format, plus a value of <code>120</code> seconds.
  1897               </li>
  1898               <li>Run the general rule for <a href="#dfn-adding-an-available-service"
  1899                     class="internalDFN">adding an available service</a>, passing in the current <var>network service
  1900                     record</var> as the only argument.
  1901               </li>
  1902             </ol>
  1903           </li>
  1904         </ol>
  1905       </section>
  1906       <section id="simple-service-discovery-protocol-ssdp">
  1907         <h3 aria-level="2"
  1908             role="heading"
  1909             id="h3_simple-service-discovery-protocol-ssdp">
  1910           <span class="secno">8.2</span> Simple Service Discovery Protocol (<abbr title=
  1911           "Simple Service Discovery Protocol">SSDP</abbr>)
  1912         </h3>
  1913         <p>
  1914           A user agent that implements UPnP service discovery <em class="rfc2119"
  1915              title="MUST">MUST</em> issue a <dfn id="dfn-search-request-for-upnp-root-devices">search request for UPnP
  1916              root devices</dfn> against the user's current local network according to the full normative text and
  1917              timing provided in 'Section 1.3.2: Search request with M-SEARCH' detailed in [<cite><a class="bibref"
  1918              href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>].
  1919         </p>
  1920         <p>
  1921           The user agent <em class="rfc2119"
  1922              title="MUST">MUST</em> issue all <a title="search request for UPnP root devices"
  1923              href="#dfn-search-request-for-upnp-root-devices"
  1924              class="internalDFN">search requests for UPnP root devices</a> with a <abbr title=
  1925              "Hypertext Transfer Protocol">HTTP</abbr> request line equal to <code>M-SEARCH * <abbr title=
  1926              "Hypertext Transfer Protocol">HTTP</abbr>/1.1</code>, with a HOST header equal to the reserved multicast
  1927              address and port of <code>239.255.255.250:1900</code> and a MAN header equal to
  1928              <code>ssdp:discover</code>. The <a href="#dfn-user-agent"
  1929              class="internalDFN">user agent</a> must also send an ST header with this <abbr title=
  1930              "Hypertext Transfer Protocol">HTTP</abbr> request equal to the String value of <code>ssdp:all</code> or
  1931              <code>upnp:rootdevice</code> or a single <a href="#dfn-valid-service-type"
  1932              class="internalDFN">valid service type</a> token beginning with the String value <code>upnp:</code>. If a
  1933              single <a href="#dfn-valid-service-type"
  1934              class="internalDFN">valid service type</a> token beginning with the String value <code>upnp:</code> is to
  1935              be used, the user agent <em class="rfc2119"
  1936              title="MUST">MUST</em> strip the leading String <code>upnp:</code> before using this value in this
  1937              <abbr title="Hypertext Transfer Protocol">HTTP</abbr> request. The user-agent <em class="rfc2119"
  1938              title="MUST">MUST</em> also send an MX header equal to a <dfn id=
  1939              "dfn-maximum-upnp-advertisement-response-wait-time">maximum UPnP advertisement response wait time</dfn>
  1940              value between <code>1</code> and <code>5</code> seconds with this <abbr title=
  1941              "Hypertext Transfer Protocol">HTTP</abbr> request.
  1942         </p>
  1943         <p>
  1944           The user agent <em class="rfc2119"
  1945              title="MUST">MUST</em> listen for any incoming responses to any <a href=
  1946              "#dfn-search-request-for-upnp-root-devices"
  1947              class="internalDFN">search request for UPnP root devices</a>.
  1948         </p>
  1949         <p>
  1950           For each <dfn id="dfn-http-response"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Response</dfn>
  1951           following an initial <a href="#dfn-search-request-for-upnp-root-devices"
  1952              class="internalDFN">search request for UPnP root devices</a> sent on a <a href=
  1953              "#dfn-standard-upnp-address-and-port"
  1954              class="internalDFN">standard UPnP address and port</a> the user agent <em class="rfc2119"
  1955              title="MUST">MUST</em> run the following steps:
  1956         </p>
  1957         <ol class="rule">
  1958           <li>If the <a href="#dfn-http-response"
  1959                 class="internalDFN"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Response</a> is not a
  1960                 <abbr title="Hypertext Transfer Protocol">HTTP</abbr> 200 OK response then this response is invalid and
  1961                 the user agent <em class="rfc2119"
  1962                 title="MUST">MUST</em> discard this response, abort any remaining steps and return. The user agent
  1963                 <em class="rfc2119"
  1964                 title="MAY">MAY</em> issue a new <a href="#dfn-search-request-for-upnp-root-devices"
  1965                 class="internalDFN">search request for UPnP root devices</a> as a result of this error occurring.
  1966           </li>
  1967           <li>If the <a href="#dfn-maximum-upnp-advertisement-response-wait-time"
  1968                 class="internalDFN">maximum UPnP advertisement response wait time</a> has been exceeded since the
  1969                 initial <a href="#dfn-search-request-for-upnp-root-devices"
  1970                 class="internalDFN">search request for UPnP root devices</a> was sent then the <a href=
  1971                 "#dfn-http-response"
  1972                 class="internalDFN"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Response</a> is invalid and
  1973                 the user agent <em class="rfc2119"
  1974                 title="MUST">MUST</em> discard this response, abort any remaining steps and return. The user agent
  1975                 <em class="rfc2119"
  1976                 title="MAY">MAY</em> stop listening for responses from the current <a href=
  1977                 "#dfn-search-request-for-upnp-root-devices"
  1978                 class="internalDFN">search request for UPnP root devices</a> as a result of this error occurring.
  1979                 Equally, the user agent <em class="rfc2119"
  1980                 title="MAY">MAY</em> issue a new <a href="#dfn-search-request-for-upnp-root-devices"
  1981                 class="internalDFN">search request for UPnP root devices</a> as a result of this error occurring.
  1982           </li>
  1983           <li>Let <var>ssdp device</var> be an Object with a property for each <abbr title=
  1984           "Hypertext Transfer Protocol">HTTP</abbr> header received in the <a href="#dfn-http-response"
  1985                 class="internalDFN"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Response</a>, with each key
  1986                 being the name of a <abbr title="Hypertext Transfer Protocol">HTTP</abbr> response header and each
  1987                 value being that <abbr title="Hypertext Transfer Protocol">HTTP</abbr> response header's value.
  1988           </li>
  1989           <li>If <var>ssdp device</var> does not contain at least one <var>CACHE-CONTROL</var> entry, at least one
  1990           <var>USN</var> entry, at least one <var>ST</var> entry and at least one <var>LOCATION</var> entry then the
  1991           <a href="#dfn-http-response"
  1992                 class="internalDFN"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Response</a> is invalid and
  1993                 the <a href="#dfn-user-agent"
  1994                 class="internalDFN">user agent</a> <em class="rfc2119"
  1995                 title="MUST">MUST</em> discard this response, abort any remaining steps and return.
  1996           </li>
  1997           <li>The user agent <em class="rfc2119"
  1998                 title="MUST">MUST</em> run the rule for <a href="#dfn-obtaining-a-upnp-device-description-file"
  1999                 class="internalDFN">obtaining a UPnP Device Description File</a> passing in the first occurrence of
  2000                 <var>LOCATION</var> from <var>ssdp device</var> as the <var>device descriptor <abbr title=
  2001                 "Uniform Resource Locator">URL</abbr></var> argument and the first occurrence of <var>USN</var> from
  2002                 <var>ssdp device</var> as the <var>device identifier</var> argument and the first occurrence of
  2003                 <var>CACHE-CONTROL</var> from <var>ssdp device</var> (minus the leading string of
  2004                 <code>max-age=</code>) as the <var>device expiry</var> argument.
  2005           </li>
  2006         </ol>
  2007         <p>
  2008           The user agent <em class="rfc2119"
  2009              title="MUST">MUST</em> listen for incoming requests on the <dfn id=
  2010              "dfn-standard-upnp-address-and-port">standard UPnP address and port</dfn> on all current local network
  2011              interface addresses with the port <code>1900</code>.
  2012         </p>
  2013         <p>
  2014           For each <dfn id="dfn-http-request"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Request</dfn>
  2015           received on a <a href="#dfn-standard-upnp-address-and-port"
  2016              class="internalDFN">standard UPnP address and port</a> the user agent <em class="rfc2119"
  2017              title="MUST">MUST</em> run the following steps:
  2018         </p>
  2019         <ol class="rule">
  2020           <li>If the <a href="#dfn-http-request"
  2021                 class="internalDFN"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Request</a> is not a
  2022                 <abbr title="Hypertext Transfer Protocol">HTTP</abbr> NOTIFY request then it is not a valid UPnP
  2023                 Request and the user agent <em class="rfc2119"
  2024                 title="MUST">MUST</em> discard this request, abort any remaining steps and return.
  2025           </li>
  2026           <li>Let <var>ssdp device</var> be an Object with a property for each <abbr title=
  2027           "Hypertext Transfer Protocol">HTTP</abbr> header received in the <a href="#dfn-http-request"
  2028                 class="internalDFN"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Request</a>, with each key
  2029                 being the name of a <abbr title="Hypertext Transfer Protocol">HTTP</abbr> header and each value being
  2030                 that <abbr title="Hypertext Transfer Protocol">HTTP</abbr> header's value.
  2031           </li>
  2032           <li>If <var>ssdp device</var>'s <var>NTS</var> entry is equal to <code>ssdp:alive</code> and the <a href=
  2033           "#dfn-http-request"
  2034                 class="internalDFN"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Request</a> does not contain
  2035                 at least one <var>CACHE-CONTROL</var> entry, at least one <var>USN</var> entry, at least one
  2036                 <var>NT</var> entry, at least one <var>NTS</var> entry and at least one <var>LOCATION</var> entry, then
  2037                 the <a href="#dfn-user-agent"
  2038                 class="internalDFN">user agent</a> <em class="rfc2119"
  2039                 title="MUST">MUST</em> discard this request, abort any remaining steps and return.
  2040           </li>
  2041           <li>If <var>ssdp device</var>'s <var>NTS</var> entry is equal to <code>ssdp:alive</code> then the user agent
  2042           <em class="rfc2119"
  2043                 title="MUST">MUST</em> run the rule for <a href="#dfn-obtaining-a-upnp-device-description-file"
  2044                 class="internalDFN">obtaining a UPnP Device Description File</a> passing in the first occurrence of
  2045                 <var>LOCATION</var> from <var>ssdp device</var> as the <var>device descriptor <abbr title=
  2046                 "Uniform Resource Locator">URL</abbr></var> argument and the first occurrence of <var>USN</var> from
  2047                 <var>ssdp device</var> as the <var>device identifier</var> argument and the first occurrence of
  2048                 <var>CACHE-CONTROL</var> from <var>ssdp device</var> (minus the leading string of
  2049                 <code>max-age=</code>) as the <var>device expiry</var>.<br>
  2050             <br>
  2051             Otherwise, if <var>ssdp device</var>'s <var>NTS</var> entry is equal to <code>ssdp:byebye</code> then the
  2052             user agent <em class="rfc2119"
  2053                 title="MUST">MUST</em> run the rule for <a href=
  2054                 "#dfn-removing-all-services-from-a-registered-upnp-device"
  2055                 class="internalDFN">removing all services from a registered UPnP Device</a> passing in the first
  2056                 occurrence of <var>USN</var> from <var>ssdp device</var> as the <var>device identifier</var> argument.
  2057           </li>
  2058         </ol>
  2059         <p>
  2060           The rule for <dfn id="dfn-obtaining-a-upnp-device-description-file">obtaining a UPnP Device Description
  2061           File</dfn> is the process of obtaining the contents of a standard UPnP Device Description [<cite><a class=
  2062           "bibref"
  2063              href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>] from a <abbr title=
  2064              "Uniform Resource Locator">URL</abbr>-based resource. This rule takes three arguments - <var>device
  2065              descriptor <abbr title="Uniform Resource Locator">URL</abbr></var>, <var>device identifier</var> and
  2066              <var>device expiry</var> - and when called the user agent <em class="rfc2119"
  2067              title="MUST">MUST</em> run the following steps:
  2068         </p>
  2069         <ol class="rule">
  2070           <li>Let <var>device descriptor file</var> contain the contents of the file located at the <abbr title=
  2071           "Uniform Resource Locator">URL</abbr> provided in <var>device descriptor <abbr title=
  2072           "Uniform Resource Locator">URL</abbr></var> obtained according to the rules defined in 'Section 2.11:
  2073           Retrieving a description using <abbr title="Hypertext Transfer Protocol">HTTP</abbr>' in [<cite><a class=
  2074           "bibref"
  2075                href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>].
  2076           </li>
  2077           <li>If the value provided in <var>device descriptor <abbr title="Uniform Resource Locator">URL</abbr></var>
  2078           cannot be resolved as a reachable <abbr title="Uniform Resource Locator">URL</abbr> on the current network or
  2079           the <var>device descriptor file</var> remains empty then it is invalid and the <a href="#dfn-user-agent"
  2080                 class="internalDFN">user agent</a> <em class="rfc2119"
  2081                 title="MUST">MUST</em> abort any remaining steps and return.
  2082           </li>
  2083           <li>Run the rule for <a href="#dfn-processing-a-upnp-device-description-file"
  2084                 class="internalDFN">processing a UPnP Device Description File</a>, passing in the current <var>device
  2085                 descriptor file</var>, <var>device identifier</var> and <var>device expiry</var> arguments.
  2086           </li>
  2087         </ol>
  2088         <p>
  2089           The rule for <dfn id="dfn-processing-a-upnp-device-description-file">processing a UPnP Device Description
  2090           File</dfn> is the process of parsing the contents of a standard UPnP Device Description [<cite><a class=
  2091           "bibref"
  2092              href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>] and registering the UPnP services contained
  2093              therein within the <a href="#dfn-list-of-available-service-records"
  2094              class="internalDFN">list of available service records</a>.
  2095         </p>
  2096         <p>
  2097           The rule for <a href="#dfn-processing-a-upnp-device-description-file"
  2098              class="internalDFN">processing a UPnP Device Description File</a> takes three arguments - <var>device
  2099              descriptor file</var>, <var>device identifier</var> and <var>device expiry</var> - and when called the
  2100              user agent <em class="rfc2119"
  2101              title="MUST">MUST</em> run the following steps:
  2102         </p>
  2103         <ol class="rule">
  2104           <li>Let <var>advertised services</var> be a list of all advertised services obtained from the <var>device
  2105           descriptor file</var> containing the value of the first occurrence of the <code>&lt;serviceList&gt;</code>
  2106           element as it is defined in 'Section 2.3: Device Description' in [<cite><a class="bibref"
  2107                href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>].
  2108           </li>
  2109           <li>For each <code>&lt;service&gt;</code> element - known as an <var>advertised service</var> - in
  2110           <var>advertised services</var> run the following steps:
  2111             <ol class="rule">
  2112               <li>Let <var>network service record</var> be a new Object consisting of the following empty properties:
  2113               <code>id</code>, <code>deviceId</code>, <code>name</code>, <code>type</code>, <code>url</code>,
  2114               <code>eventsUrl</code>, <code>config</code>, <code>expiryTimestamp</code>.
  2115               </li>
  2116               <li>Set <var>network service record</var>'s <code>id</code> property to the concatenated string value of
  2117               the first occurrence of the <code>&lt;UDN&gt;</code> element in the <var>device descriptor file</var>
  2118               with the <var>advertised service</var>'s <code>&lt;serviceId&gt;</code> sub-element.
  2119               </li>
  2120               <li>Set <var>network service record</var>'s <code>deviceId</code> property to the value of <var>device
  2121               identifier</var>.
  2122               </li>
  2123               <li>Set <var>network service record</var>'s <code>name</code> property to the string value of the first
  2124               occurrence of the <var>advertised service</var>'s <code>&lt;serviceId&gt;</code> sub-element.
  2125               </li>
  2126               <li>Set <var>network service record</var>'s <code>type</code> property to the concatenation of the string
  2127               <code>upnp:</code> followed by the string value of the first occurrence of the <var>advertised
  2128               service</var>'s <code>&lt;serviceType&gt;</code> sub-element.
  2129               </li>
  2130               <li>Set <var>network service record</var>'s <code>url</code> property to the string value of the first
  2131               occurrence of the <var>advertised service</var>'s <code>&lt;controlURL&gt;</code> sub-element.
  2132               </li>
  2133               <li>Set <var>network service record</var>'s <code>config</code> property to the string value of the
  2134               contents of the first occurrence of the <code>&lt;device&gt;</code> element in the <var>device descriptor
  2135               file</var>.
  2136               </li>
  2137               <li>If <var>advertised service</var>'s <code>&lt;eventSubURL&gt;</code> sub-element is not empty, then
  2138               set <var>network service record</var>'s <code>eventsUrl</code> property to the string value of the first
  2139               occurrence of the <var>advertised service</var>'s <code>&lt;eventSubURL&gt;</code> sub-element.
  2140               Otherwise, do not set <var>network service record</var>'s <code>eventsUrl</code> property.
  2141               </li>
  2142               <li>Set <var>network service record</var>'s <code>expiryTimestamp</code> property to the value of the
  2143               current date, in UTC timestamp format, plus the value of <var>device expiry</var>.
  2144               </li>
  2145               <li>Run the general rule for <a href="#dfn-adding-an-available-service"
  2146                     class="internalDFN">adding an available service</a>, passing in the current <var>network service
  2147                     record</var> as the only argument.
  2148               </li>
  2149             </ol>
  2150           </li>
  2151           <li>If <var>device descriptor file</var> contains a <code>&lt;deviceList&gt;</code> element then for each
  2152           <code>&lt;device&gt;</code> element within <code>&lt;deviceList&gt;</code> - herein known as an <var>embedded
  2153           device descriptor file</var> - the user agent <em class="rfc2119"
  2154                 title="MUST">MUST</em> run the rule for <a href="#dfn-processing-a-upnp-device-description-file"
  2155                 class="internalDFN">processing a UPnP Device Description File</a>, passing in the current <var>embedded
  2156                 device descriptor file</var> as the <var>device descriptor file</var> argument, along with the current
  2157                 <var>device identifier</var> and <var>device expiry</var> arguments.
  2158           </li>
  2159         </ol>
  2160         <p>
  2161           The rule for <dfn id="dfn-removing-all-services-from-a-registered-upnp-device">removing all services from a
  2162           registered UPnP Device</dfn> is the process of removing all services associated with a device from the
  2163           <a href="#dfn-list-of-available-service-records"
  2164              class="internalDFN">list of available service records</a> that has left the user's current network or has
  2165              otherwise timed out or expired. This rule takes one argument, <var>device identifier</var>, and consists
  2166              of running the following steps:
  2167         </p>
  2168         <ol class="rule">
  2169           <li>For each <var>existing service record</var> in the current <a href=
  2170           "#dfn-list-of-available-service-records"
  2171                 class="internalDFN">list of available service records</a>, run the following sub-steps:
  2172             <ol class="rule">
  2173               <li>If the <var>existing service record</var>'s <code>deviceId</code> property does not match <var>device
  2174               identifier</var> then skip any remaining sub-steps for the current <var>existing service record</var> and
  2175               continue at the next available <var>existing service record</var>.
  2176               </li>
  2177               <li>Run the general rule for <a href="#dfn-removing-an-available-service"
  2178                     class="internalDFN">removing an available service</a> passing in <var>existing service
  2179                     record</var>'s <code>id</code> property as the only argument.
  2180               </li>
  2181             </ol>
  2182           </li>
  2183         </ol>
  2184         <p>
  2185           When the <a href="#dfn-user-agent"
  2186              class="internalDFN">user agent</a> is to <dfn id="dfn-setup-a-upnp-events-subscription">setup a UPnP
  2187              Events Subscription</dfn>, it is to run the following steps with the current <var>network service
  2188              record</var> object as defined in 'Section 4.1.2: SUBSCRIBE with NT and CALLBACK' in [<cite><a class=
  2189              "bibref"
  2190              href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>]:
  2191         </p>
  2192         <ol class="rule">
  2193           <li>If <var>network service record</var>'s <code>eventsUrl</code> property is empty then the <a href=
  2194           "#dfn-user-agent"
  2195                 class="internalDFN">user agent</a> <em class="rfc2119"
  2196                 title="MUST">MUST</em> abort these steps.
  2197           </li>
  2198           <li>Let <var>callback <abbr title="Uniform Resource Locator">URL</abbr></var> be the value of creating a new
  2199           <a href="#dfn-user-agent-generated-callback-url"
  2200                 class="internalDFN">user-agent generated callback url</a>.
  2201           </li>
  2202           <li>Send a <abbr title="Hypertext Transfer Protocol">HTTP</abbr> SUBSCRIBE request with a <em>NT</em> header
  2203           with a string value of <code>upnp:event</code>, a <em>TIMEOUT</em> header with a user-agent defined timeout
  2204           value (in the form <code>Second-XX</code> where <code>XX</code> is the user-agent defined timeout value in
  2205           seconds) and a <em>CALLBACK</em> header with a string value of <var>callback <abbr title=
  2206           "Uniform Resource Locator">URL</abbr></var> towards the <var>network service record</var>'s
  2207           <code>eventsUrl</code> property.
  2208           </li>
  2209           <li>If a non-200 OK response is received from the <abbr title="Hypertext Transfer Protocol">HTTP</abbr>
  2210           SUBSCRIBE request then the <a href="#dfn-user-agent"
  2211                 class="internalDFN">user agent</a> <em class="rfc2119"
  2212                 title="MUST">MUST</em> abort these steps.
  2213           </li>
  2214           <li>On receiving a valid 200 OK response, run the following steps:
  2215             <ol class="rule">
  2216               <li>Let <var>callback ID</var> equal the string value of the first included <em>SID</em> header, if it
  2217               exists.
  2218               </li>
  2219               <li>Let <var>timeout date</var> equal the sum of the current UTC date value plus the integer value of the
  2220               first included <em>TIMEOUT</em> header (minus the leading string of <code>Second-</code>), if it exists.
  2221               </li>
  2222               <li>Run the following steps asynchronously and continue to the step labeled <em>listen</em> below.
  2223               </li>
  2224               <li>
  2225                 <em>Refresh Subscription</em>: Run the following steps at a set interval (X) within the <a href=
  2226                 "#dfn-user-agent"
  2227                     class="internalDFN">user agent</a>:
  2228                 <ol class="rule">
  2229                   <li>Let <var>current date</var> equal the current UTC date.
  2230                   </li>
  2231                   <li>If <var>current date</var> is less than the <var>timeout date</var> then continue to the step
  2232                   labeled <em>refresh subscription</em> above.
  2233                   </li>
  2234                   <li>Send a <abbr title="Hypertext Transfer Protocol">HTTP</abbr> SUBSCRIBE request with a
  2235                   <em>SID</em> header with the string value of <var>callback ID</var> and a user-agent defined
  2236                   <em>TIMEOUT</em> header (in the form <code>Second-XX</code> where <code>XX</code> is the user-agent
  2237                   defined timeout value in seconds) towards the <var>network service record</var>'s
  2238                   <code>eventsUrl</code> property.
  2239                   </li>
  2240                   <li>On receiving a valid 200 OK, update <var>callback ID</var> with the string value of the first
  2241                   included <em>SID</em> header and set <var>timeout date</var> to the sum of the current UTC date value
  2242                   plus the integer value of the first included <em>TIMEOUT</em> header (minus the leading string of
  2243                   <code>Second-</code>), if it exists. If the current date is greater than or equal to <var>timeout
  2244                   date</var> then the <a href="#dfn-user-agent"
  2245                         class="internalDFN">user agent</a> <em class="rfc2119"
  2246                         title="SHOULD">SHOULD</em> continue from the step labeled <em>refresh subscription</em> above.
  2247                         For all non 200 OK responses the <a href="#dfn-user-agent"
  2248                         class="internalDFN">user agent</a> <em class="rfc2119"
  2249                         title="SHOULD">SHOULD</em> continue from the step labeled <em>refresh subscription</em> above.
  2250                   </li>
  2251                 </ol>
  2252               </li>
  2253               <li>
  2254                 <em>Listen</em>: For each <abbr title="Hypertext Transfer Protocol">HTTP</abbr> NOTIFY request received
  2255                 at the <var>callback <abbr title="Uniform Resource Locator">URL</abbr></var> the <a href=
  2256                 "#dfn-user-agent"
  2257                     class="internalDFN">user agent</a> is to run the following steps:
  2258                 <ol class="rule">
  2259                   <li>Let <var>content clone</var> be the result of obtaining the message body of the <abbr title=
  2260                   "Hypertext Transfer Protocol">HTTP</abbr> NOTIFY request. If <var>content clone</var> is empty, then
  2261                   the <a href="#dfn-user-agent"
  2262                         class="internalDFN">user agent</a> <em class="rfc2119"
  2263                         title="MUST">MUST</em> abort these steps.
  2264                   </li>
  2265                   <li>Let <var>notification event</var> be a new simple event that uses the <a href=
  2266                   "http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event"
  2267                         class="externalDFN"><code>Event</code></a> interface with the name <a href=
  2268                         "#event-notify"><code>notify</code></a>, which does not bubble, is not cancellable, and has no
  2269                         default action.
  2270                   </li>
  2271                   <li>Let the <code>data</code> attribute of <var>notification event</var> have the DOMString value of
  2272                   <var>content clone</var>.
  2273                   </li>
  2274                   <li>
  2275                     <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task"
  2276                         class="externalDFN">Queue a task</a> to dispatch <var>notification event</var> at the current
  2277                         <a href="#networkservice"
  2278                         class="internalDFN"><code>NetworkService</code></a> object.
  2279                   </li>
  2280                   <li>Return a <abbr title="Hypertext Transfer Protocol">HTTP</abbr> 200 OK response to the sender of
  2281                   the <abbr title="Hypertext Transfer Protocol">HTTP</abbr> NOTIFY request.
  2282                   </li>
  2283                 </ol>
  2284               </li>
  2285             </ol>
  2286           </li>
  2287         </ol>
  2288         <p>
  2289           A <a href="#dfn-user-agent"
  2290              class="internalDFN">user agent</a> can <dfn id=
  2291              "dfn-terminate-an-existing-upnp-events-subscription">terminate an existing UPnP Events Subscription</dfn>
  2292              at any time for a <var>network service record</var> by sending an <abbr title=
  2293              "Hypertext Transfer Protocol">HTTP</abbr> UNSUBSCRIBE request - as defined in 'Section 4.1.4: Cancelling a
  2294              subscription with UNSUBSCRIBE' in [<cite><a class="bibref"
  2295              href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>] - with a HOST header set to that <var>active
  2296              service</var>'s <code>eventsUrl</code> property and a SID header set to the <var>callback ID</var>
  2297              obtained when the initial <a href="#dfn-setup-a-upnp-events-subscription"
  2298              class="internalDFN">setup a UPnP Events Subscription</a> action occurred.
  2299         </p>
  2300       </section>
  2301       <section id="discovery-and-launch-protocol-dial">
  2302         <h3 aria-level="2"
  2303             role="heading"
  2304             id="h3_discovery-and-launch-protocol-dial">
  2305           <span class="secno">8.3</span> Discovery and Launch Protocol (<abbr title=
  2306           "Discovery and Launch Protocol">DIAL</abbr>)
  2307         </h3>
  2308         <p>
  2309           A user agent that implements <abbr title="Discovery and Launch Protocol">DIAL</abbr> service discovery
  2310           <em class="rfc2119"
  2311              title="MUST">MUST</em> issue a <dfn id="dfn-search-request-for-dial-enabled-devices">search request for
  2312              <abbr title="Discovery and Launch Protocol">DIAL</abbr>-enabled devices</dfn> against the user's current
  2313              local network according to the full normative text and timing provided in 'Section 1.3.2: Search request
  2314              with M-SEARCH' detailed in [<cite><a class="bibref"
  2315              href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>].
  2316         </p>
  2317         <p>
  2318           Let <var>dial version</var> be the version number specified in the <a href="#dfn-valid-service-type"
  2319              class="internalDFN">valid service type</a> token. Let <var>dial search target</var> be the concatentation
  2320              of the <code>urn:dial-multiscreen-org:service:dial:</code> string constant with the <var>dial
  2321              version</var> (currently, <var>dial version</var> can only be <code>1</code>)
  2322         </p>
  2323         <p>
  2324           The user agent <em class="rfc2119"
  2325              title="MUST">MUST</em> issue all <a title="search request for DIAL devices">search requests for
  2326              <abbr title="Discovery and Launch Protocol">DIAL</abbr> devices</a> with a <abbr title=
  2327              "Hypertext Transfer Protocol">HTTP</abbr> request line equal to <code>M-SEARCH * <abbr title=
  2328              "Hypertext Transfer Protocol">HTTP</abbr>/1.1</code>, with a HOST header equal to the reserved multicast
  2329              address and port of <code>239.255.255.250:1900</code>, a MAN header equal to <code>ssdp:discover</code>,
  2330              an ST header equal to <var>dial search target</var> and a user-agent defined MX header equal to a <dfn id=
  2331              "dfn-maximum-dial-advertisement-response-wait-time">maximum <abbr title=
  2332              "Discovery and Launch Protocol">DIAL</abbr> advertisement response wait time</dfn> value between
  2333              <code>1</code> and <code>5</code> seconds.
  2334         </p>
  2335         <p>
  2336           The user agent <em class="rfc2119"
  2337              title="MUST">MUST</em> listen for any incoming responses to a <a>search request for <abbr title=
  2338              "Discovery and Launch Protocol">DIAL</abbr> devices</a>.
  2339         </p>
  2340         <p>
  2341           For each <abbr title="Hypertext Transfer Protocol">HTTP</abbr> Response following an initial <a>search
  2342           request for <abbr title="Discovery and Launch Protocol">DIAL</abbr> devices</a> sent on a <a href=
  2343           "#dfn-standard-upnp-address-and-port"
  2344              class="internalDFN">standard UPnP address and port</a> the user agent <em class="rfc2119"
  2345              title="MUST">MUST</em> run the following steps:
  2346         </p>
  2347         <ol class="rule">
  2348           <li>If the <abbr title="Hypertext Transfer Protocol">HTTP</abbr> Response is not a <abbr title=
  2349           "Hypertext Transfer Protocol">HTTP</abbr> 200 OK response then this response is invalid and the user agent
  2350           <em class="rfc2119"
  2351                 title="MUST">MUST</em> discard this response, abort any remaining steps and return. The user agent
  2352                 <em class="rfc2119"
  2353                 title="MAY">MAY</em> issue a new <a>search request for <abbr title=
  2354                 "Discovery and Launch Protocol">DIAL</abbr> devices</a> as a result of this error occurring.
  2355           </li>
  2356           <li>If the <a href="#dfn-maximum-dial-advertisement-response-wait-time"
  2357                 class="internalDFN">maximum <abbr title="Discovery and Launch Protocol">DIAL</abbr> advertisement
  2358                 response wait time</a> has been exceeded since the initial <a>search request for <abbr title=
  2359                 "Discovery and Launch Protocol">DIAL</abbr> devices</a> was sent then the <a href="#dfn-http-response"
  2360                 class="internalDFN"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Response</a> is invalid and
  2361                 the user agent <em class="rfc2119"
  2362                 title="MUST">MUST</em> discard this response, abort any remaining steps and return. The user agent
  2363                 <em class="rfc2119"
  2364                 title="MAY">MAY</em> stop listening for responses from the current <a>search request for <abbr title=
  2365                 "Discovery and Launch Protocol">DIAL</abbr> devices</a> as a result of this error occurring. Equally,
  2366                 the user agent <em class="rfc2119"
  2367                 title="MAY">MAY</em> issue a new <a>search request for <abbr title=
  2368                 "Discovery and Launch Protocol">DIAL</abbr> devices</a> as a result of this error occurring.
  2369           </li>
  2370           <li>Let <var>dial device</var> be an Object with a property for each <abbr title=
  2371           "Hypertext Transfer Protocol">HTTP</abbr> header received in the <a href="#dfn-http-response"
  2372                 class="internalDFN"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Response</a>, with each key
  2373                 being the name of a <abbr title="Hypertext Transfer Protocol">HTTP</abbr> response header and each
  2374                 value being that <abbr title="Hypertext Transfer Protocol">HTTP</abbr> response header's value.
  2375           </li>
  2376           <li>If <var>dial device</var> does not contain at least one <var>CACHE-CONTROL</var> entry, at least one
  2377           <var>USN</var> entry, at least one <var>ST</var> entry and at least one <var>LOCATION</var> entry or the
  2378           value of its <var>ST</var> entry is not <var>dial search target</var>, then the <a href="#dfn-http-response"
  2379                 class="internalDFN"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Response</a> is invalid and
  2380                 the <a href="#dfn-user-agent"
  2381                 class="internalDFN">user agent</a> <em class="rfc2119"
  2382                 title="MUST">MUST</em> discard this response, abort any remaining steps and return.
  2383           </li>
  2384           <li>The user agent <em class="rfc2119"
  2385                 title="MUST">MUST</em> run the rule for <a href="#dfn-obtaining-a-upnp-device-description-file"
  2386                 class="internalDFN">obtaining a UPnP Device Description File</a> passing in the first occurrence of
  2387                 <var>LOCATION</var> from <var>dial device</var> as the <var>device descriptor <abbr title=
  2388                 "Uniform Resource Locator">URL</abbr></var> argument and the first occurrence of <var>USN</var> from
  2389                 <var>dial device</var> as the <var>device identifier</var> argument and the first occurrence of
  2390                 <var>CACHE-CONTROL</var> from <var>dial device</var> (minus the leading string of
  2391                 <code>max-age=</code>) as the <var>device expiry</var> argument.
  2392           </li>
  2393         </ol>
  2394         <p>
  2395           The rule for <dfn id="dfn-obtaining-a-dial-device-description-file">obtaining a <abbr title=
  2396           "Discovery and Launch Protocol">DIAL</abbr> Device Description File</dfn> is the process of obtaining the
  2397           contents of a standard UPnP Device Description [<cite><a class="bibref"
  2398              href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>] from a <abbr title=
  2399              "Uniform Resource Locator">URL</abbr>-based resource. This rule takes three arguments - <var>device
  2400              descriptor <abbr title="Uniform Resource Locator">URL</abbr></var>, <var>device identifier</var> and
  2401              <var>device expiry</var> - and when called the user agent <em class="rfc2119"
  2402              title="MUST">MUST</em> run the following steps:
  2403         </p>
  2404         <ol class="rule">
  2405           <li>Let <var>device descriptor file</var> contain the contents of the file located at the <abbr title=
  2406           "Uniform Resource Locator">URL</abbr> provided in <var>device descriptor <abbr title=
  2407           "Uniform Resource Locator">URL</abbr></var> obtained according to the rules defined in 'Section 2.11:
  2408           Retrieving a description using <abbr title="Hypertext Transfer Protocol">HTTP</abbr>' in [<cite><a class=
  2409           "bibref"
  2410                href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>].
  2411           </li>
  2412           <li>Let <var>application url</var> be the value of the first occurrence of the
  2413             <code>Application-<abbr title="Uniform Resource Locator">URL</abbr></code> response header field obtained
  2414             according to the rules defined in 'Section 5.4: Device Description Response' in [<a href=
  2415             "https://sites.google.com/a/dial-multiscreen.org/dial/dial-protocol-specification"><abbr title=
  2416             "Discovery and Launch Protocol">DIAL</abbr></a>]
  2417           </li>
  2418           <li>If the value provided in <var>device descriptor <abbr title="Uniform Resource Locator">URL</abbr></var>
  2419           cannot be resolved as a reachable <abbr title="Uniform Resource Locator">URL</abbr> on the current network or
  2420           the <var>device descriptor file</var> remains empty or <var>application url</var> is undefined then it is
  2421           invalid and the <a href="#dfn-user-agent"
  2422                 class="internalDFN">user agent</a> <em class="rfc2119"
  2423                 title="MUST">MUST</em> abort any remaining steps and return.
  2424           </li>
  2425           <li>Run the following steps to add the newly discovered <abbr title=
  2426           "Discovery and Launch Protocol">DIAL</abbr> service:
  2427             <ol class="rule">
  2428               <li>Let <var>network service record</var> be a new Object consisting of the following empty properties:
  2429               <code>id</code>, <code>deviceId</code>, <code>name</code>, <code>type</code>, <code>url</code>,
  2430               <code>expiryTimestamp</code>.
  2431               </li>
  2432               <li>Set <var>network service record</var>'s <code>id</code> property to the first occurrence of the
  2433               <code>&lt;UDN&gt;</code> element in the <var>descriptor file</var> prefixed with the <code>dial:</code>
  2434               string constant
  2435               </li>
  2436               <li>Set <var>network service record</var>'s <code>deviceId</code> property to the value of <var>device
  2437               identifier</var>.
  2438               </li>
  2439               <li>Set <var>network service record</var>'s <code>name</code> property to the string value of the first
  2440               occurrence of the <code>&lt;friendlyName&gt;</code> element in the <var>descriptor file</var>.
  2441               </li>
  2442               <li>Set <var>network service record</var>'s <code>type</code> property to <var>dial search target</var>.
  2443               </li>
  2444               <li>Set <var>network service record</var>'s <code>url</code> property to the string value of the
  2445               <var>application url</var>.
  2446               </li>
  2447               <li>Set <var>network service record</var>'s <code>expiryTimestamp</code> property to the value of the
  2448               current date, in UTC timestamp format, plus the value of <var>device expiry</var>.
  2449               </li>
  2450               <li>Run the general rule for <a href="#dfn-adding-an-available-service"
  2451                     class="internalDFN">adding an available service</a>, passing in the current <var>network service
  2452                     record</var> as the only argument.
  2453               </li>
  2454             </ol>
  2455           </li>
  2456         </ol>
  2457       </section>
  2458       <section id="network-topology-monitoring">
  2459         <h3 aria-level="2"
  2460             role="heading"
  2461             id="h3_network-topology-monitoring">
  2462           <span class="secno">8.4</span> Network Topology Monitoring
  2463         </h3>
  2464         <div>
  2465           <p>
  2466             When the <a href="#dfn-user-agent"
  2467                class="internalDFN">user agent</a> detects that the user has dropped from a connected network then, for
  2468                each <var>existing service record</var> in the <a href="#dfn-list-of-available-service-records"
  2469                class="internalDFN">list of available service records</a> discovered via that network connection, the
  2470                <a href="#dfn-user-agent"
  2471                class="internalDFN">user agent</a> <em class="rfc2119"
  2472                title="MUST">MUST</em> run the general rule for <a href="#dfn-removing-an-available-service"
  2473                class="internalDFN">removing an available service</a> passing in each <var>existing service
  2474                record</var>'s <code>id</code> property as the only argument for each call.
  2475           </p>
  2476           <p>
  2477             When the <a href="#dfn-user-agent"
  2478                class="internalDFN">user agent</a> detects that the user has connected to a new network or reconnected
  2479                to an existing network, then it <em class="rfc2119"
  2480                title="SHOULD">SHOULD</em> restart its discovery mechanisms as defined in the <a href=
  2481                "#service-discovery">Service Discovery</a> section of this specification, maintaining the existing
  2482                <a href="#dfn-list-of-active-service-managers"
  2483                class="internalDFN">list of active service managers</a> currently in use.
  2484           </p>
  2485         </div>
  2486       </section>
  2487     </section>
  2488     <section id="events-summary">
  2489       <h2 aria-level="1"
  2490           role="heading"
  2491           id="h2_events-summary">
  2492         <span class="secno">9.</span> Events Summary
  2493       </h2>
  2494       <p>
  2495         The following events are dispatched on the <a href="#networkservices"><code>NetworkServices</code></a> and/or
  2496         <a href="#networkservice"><code>NetworkService</code></a> objects:
  2497       </p>
  2498       <table border="1">
  2499         <thead>
  2500           <tr>
  2501             <th>
  2502               <span>Event name</span>
  2503             </th>
  2504             <th>
  2505               <span>Interface</span>
  2506             </th>
  2507             <th>
  2508               <span>Dispatched when...</span>
  2509             </th>
  2510           </tr>
  2511         </thead>
  2512         <tbody>
  2513           <tr>
  2514             <td>
  2515               <dfn id="event-servicefound"><code>servicefound</code></dfn>
  2516             </td>
  2517             <td>
  2518               <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event"
  2519                   class="externalDFN"><code>Event</code></a>
  2520             </td>
  2521             <td>
  2522               When a <a href="#dfn-new-service"
  2523                   class="internalDFN">new service</a> that matches one of the <a>requested type tokens</a> is found in
  2524                   the current network.
  2525             </td>
  2526           </tr>
  2527           <tr>
  2528             <td>
  2529               <dfn id="event-servicelost"><code>servicelost</code></dfn>
  2530             </td>
  2531             <td>
  2532               <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event"
  2533                   class="externalDFN"><code>Event</code></a>
  2534             </td>
  2535             <td>
  2536               When an <a href="#dfn-existing-service"
  2537                   class="internalDFN">existing service</a> that matches one of the <a>requested type tokens</a>
  2538                   gracefully leaves or expires from the current network.
  2539             </td>
  2540           </tr>
  2541           <tr>
  2542             <td>
  2543               <dfn id="event-available"><code>available</code></dfn>
  2544             </td>
  2545             <td>
  2546               <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event"
  2547                   class="externalDFN"><code>Event</code></a>
  2548             </td>
  2549             <td>
  2550               When a <a href="#dfn-current-service"
  2551                   class="internalDFN">current service</a> renews its service registration within the current network.
  2552             </td>
  2553           </tr>
  2554           <tr>
  2555             <td>
  2556               <dfn id="event-unavailable"><code>unavailable</code></dfn>
  2557             </td>
  2558             <td>
  2559               <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event"
  2560                   class="externalDFN"><code>Event</code></a>
  2561             </td>
  2562             <td>
  2563               When a <a href="#dfn-current-service"
  2564                   class="internalDFN">current service</a> gracefully leaves or otherwise expires from the current
  2565                   network.
  2566             </td>
  2567           </tr>
  2568           <tr>
  2569             <td>
  2570               <dfn id="event-notify"><code>notify</code></dfn>
  2571             </td>
  2572             <td>
  2573               <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event"
  2574                   class="externalDFN"><code>Event</code></a>
  2575             </td>
  2576             <td>
  2577               When a valid UPnP Events Subscription Message is received on a <a href=
  2578               "#dfn-user-agent-generated-callback-url"
  2579                   class="internalDFN">user-agent generated callback url</a> for a <a href="#dfn-current-service"
  2580                   class="internalDFN">current service</a>. This event never fires for Zeroconf-based services.
  2581             </td>
  2582           </tr>
  2583         </tbody>
  2584       </table>
  2585     </section>
  2586     <section id="garbage-collection">
  2587       <h2 aria-level="1"
  2588           role="heading"
  2589           id="h2_garbage-collection">
  2590         <span class="secno">10.</span> Garbage collection
  2591       </h2>
  2592       <p>
  2593         There is an <dfn id="dfn-implied-strong-reference">implied strong reference</dfn> from any IDL attribute in
  2594         this <abbr title="Application Programming Interface">API</abbr> that returns a pre-existing object to that
  2595         object.
  2596       </p>
  2597       <div class="note">
  2598         <div class="note-title"
  2599              aria-level="2"
  2600              role="heading"
  2601              id="h_note_2">
  2602           <span>Note</span>
  2603         </div>
  2604         <p class="">
  2605           For example, if a <a href="#networkservices"
  2606              class="internalDFN"><code>NetworkServices</code></a> object has one or more <a href=
  2607              "#dfn-indexed-properties-1"
  2608              class="internalDFN">indexed properties</a> attached to it then there is a strong reference from that
  2609              <a href="#networkservices"
  2610              class="internalDFN"><code>NetworkServices</code></a> object toward each of its <a href=
  2611              "#dfn-indexed-properties-1"
  2612              class="internalDFN">indexed properties</a>.
  2613         </p>
  2614       </div>
  2615       <p>
  2616         If a <a href="#dfn-user-agent"
  2617            class="internalDFN">user agent</a> is to <dfn id="dfn-make-disappear">make disappear</dfn> a <a href=
  2618            "#networkservices"
  2619            class="internalDFN"><code>NetworkServices</code></a> object (this happens when a <a href=
  2620            "http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#document"
  2621            class="externalDFN"><code>Document</code></a> object goes away), the <a href="#dfn-user-agent"
  2622            class="internalDFN">user agent</a> <em class="rfc2119"
  2623            title="MUST">MUST</em> remove this object from the <a href="#dfn-list-of-active-service-managers"
  2624            class="internalDFN">list of active service managers</a> and remove the <a href=
  2625            "#dom-networkservice-url"><code>url</code></a> of each of its <a href="#dfn-indexed-properties-1"
  2626            class="internalDFN">indexed properties</a> from the <a href="#dfn-entry-script-origin-s-url-whitelist"
  2627            class="internalDFN">entry script origin's <abbr title="Uniform Resource Locator">URL</abbr> whitelist</a>.
  2628       </p>
  2629     </section>
  2630     <section id="use-cases-and-requirements">
  2631       <h2 aria-level="1"
  2632           role="heading"
  2633           id="h2_use-cases-and-requirements">
  2634         <span class="secno">11.</span> Use Cases and Requirements
  2635       </h2>
  2636       <p>
  2637         This section covers what the requirements are for this <abbr title=
  2638         "Application Programming Interface">API</abbr>, as well as illustrates some use cases.
  2639       </p>
  2640       <ul class="rule">
  2641         <li>Once a user has given permission, user agents should provide the ability for Web pages to communicate
  2642         directly with a Local-networked Service.
  2643           <ul class="rule">
  2644             <li>Example: A web-based TV remote control. A Web page wants to control the current user's TV, changing the
  2645             programming shown or increasing/decreasing/muting the volume of the Local-networked Device. The Web page
  2646             requests a service type that is known to be implemented by television sets to which it has the application
  2647             logic to communicate. Local devices providing the request service types are discovered and presented to the
  2648             user for authorization. The user selects one or more of the discovered television sets to be accessible to
  2649             the current Web page and then clicks 'Share'. The Web page can now communicate directly with the
  2650             user-authorized Local-networked services.
  2651             </li>
  2652           </ul>
  2653         </li>
  2654         <li>Web pages should be able to communicate with Local-networked Services using the messaging channel supported
  2655         by those Devices.
  2656           <ul class="rule">
  2657             <li>Example: A Web page advertises that it is capable of controlling multiple Home Media Servers. The user
  2658             can select their Home Media Server type from a drop-down list, at which point the Web page sends a request
  2659             to the user agent to connect with the associated service type of the Home Media Server. The Media Server
  2660             selected implements a Web Socket channel for bi-directional service communication and so the Web page opens
  2661             a web socket to the requested Media Server and can communicate as required via that appropriate channel.
  2662             </li>
  2663           </ul>
  2664         </li>
  2665         <li>Web pages should be able to communicate with Local-networked Services using the messaging format supported
  2666         by those Devices.
  2667           <ul class="rule">
  2668             <li>Example: A Web page advertises that it is capable of interacting with and controlling multiple types of
  2669             Home Media Server. The user can select their Home Media Server type from a drop-down list or known Media
  2670             Servers, at which point the Web page sends a request to the user agent to connect with the associated
  2671             service type (and, optionally, the associated event type) of the Home Media Server. The communication
  2672             protocols supported by Home Media Servers typically vary between UPnP, JSON-RPC, Protocol Buffers or other
  2673             messaging formats depending on the Home Media Server requested. The Web page is able to communicate with
  2674             the user-selected Home Media Server in the messaging format supported by that Device, which, in this
  2675             example is a simple key/value pair text format.
  2676             </li>
  2677           </ul>
  2678         </li>
  2679         <li>Web pages should not be able to communicate with Local-networked Services that have not been authorized by
  2680         the user thereby maintaining the user's privacy.
  2681           <ul class="rule">
  2682             <li>Example: A Web page requests access to one type of Local-networked service. The user authorizes access
  2683             to that particular service. Other services running on that same device, and on other devices within the
  2684             network, should not be accessible to the current Web page.
  2685             </li>
  2686           </ul>
  2687         </li>
  2688         <li>A user should be able to share one or more Local-networked Services based on a particular service type
  2689         request from a Web page.
  2690           <ul class="rule">
  2691             <li>Example: A Web page is capable of interacting with a specific profile of Local-networked Service. As
  2692             such, it makes a request to the user agent to access those services, of which multiple matches are found.
  2693             The user is capable of selecting one or more of the discovered services to share with the Web page. The Web
  2694             page can then implement a drag-and-drop interface for the user to drag specific actions on to one or more
  2695             of the authorized Local-networked Services.
  2696             </li>
  2697           </ul>
  2698         </li>
  2699         <li>User agents should provide an <abbr title="Application Programming Interface">API</abbr> exposed to script
  2700         that exposes the features above. The user is notified by UI anytime interaction with Local-networked Services
  2701         is requested, giving the user full ability to cancel or abort the transaction. The user selects the
  2702         Local-networked Services to be connected to the current Web page, and can cancel these at any time. No
  2703         invocations to these APIs occur silently without user intervention.
  2704         </li>
  2705       </ul>
  2706     </section>
  2707     <section class="informative appendix"
  2708              id="examples">
  2709       <h2 aria-level="1"
  2710           role="heading"
  2711           id="h2_examples">
  2712         <span class="secno">A.</span> Examples
  2713       </h2>
  2714       <p>
  2715         <em>This section is non-normative.</em>
  2716       </p>
  2717       <div class="example">
  2718         <p>
  2719           This sample code exposes a button. When clicked, this button is disabled and the user is prompted to offer a
  2720           network service. The user may also select multiple network services. When the user has authorized a network
  2721           service to be connected to the web page then the web page issues a simple command to get a list of all the
  2722           albums stored on the connected media player service.
  2723         </p>
  2724         <p>
  2725           The button is re-enabled only when the connected network service disconnects for whatever reason (the service
  2726           becomes unavailable on the network, the user disconnects from their current network or the user revokes
  2727           access to the service from the current web page). At this point the user can re-click the button to select a
  2728           new network service to connect to the web page and the above steps are repeated.
  2729         </p>
  2730         <p>
  2731           The provided service type identifier and service interaction used in this example is based on the
  2732           well-defined service type and messaging format supported by the <a href="http://xbmc.org/about/">XBMC Media
  2733           Server</a>.
  2734         </p>
  2735         <hr>
  2736         <pre class="highlight prettyprint">
  2737 <span class="tag">&lt;input</span><span class="pln"> </span><span class="atn">type</span><span class=
  2738 "pun">=</span><span class="atv">"button"</span><span class="pln"> </span><span class="atn">value</span><span class=
  2739 "pun">=</span><span class="atv">"Start"</span><span class="pln"> </span><span class="atn">onclick</span><span class=
  2740 "pun">=</span><span class="atv">"</span><span class="pln">start</span><span class="pun">()</span><span class=
  2741 "atv">"</span><span class="pln"> </span><span class="atn">id</span><span class="pun">=</span><span class=
  2742 "atv">"startBtn"</span><span class="tag">/&gt;</span><span class="pln">
  2743 </span><span class="tag">&lt;div</span><span class="pln"> </span><span class="atn">id</span><span class=
  2744 "pun">=</span><span class="atv">"debugconsole"</span><span class="tag">&gt;&lt;/div&gt;</span><span class="pln">
  2745 
  2746 </span><span class="tag">&lt;script&gt;</span><span class="pln">
  2747  </span><span class="kwd">var</span><span class="pln"> startBtn </span><span class="pun">=</span><span class=
  2748 "pln"> document</span><span class="pun">.</span><span class="pln">getElementById</span><span class=
  2749 "pun">(</span><span class="str">'startBtn'</span><span class="pun">),</span><span class="pln">
  2750      debug </span><span class="pun">=</span><span class="pln"> document</span><span class="pun">.</span><span class=
  2751 "pln">getElementById</span><span class="pun">(</span><span class="str">'debugconsole'</span><span class=
  2752 "pun">);</span><span class="pln">
  2753 
  2754  </span><span class="kwd">function</span><span class="pln"> start</span><span class="pun">()</span><span class=
  2755 "pln"> </span><span class="pun">{</span><span class="pln">
  2756    </span><span class="kwd">if</span><span class="pun">(</span><span class="pln">navigator</span><span class=
  2757 "pun">.</span><span class="pln">getNetworkServices</span><span class="pun">)</span><span class=
  2758 "pln"> </span><span class="pun">{</span><span class="pln">
  2759       navigator</span><span class="pun">.</span><span class="pln">getNetworkServices</span><span class=
  2760 "pun">(</span><span class="str">'zeroconf:_xbmc-jsonrpc._tcp'</span><span class="pun">).</span><span class=
  2761 "pln">then</span><span class="pun">(</span><span class="pln">gotXBMCService</span><span class=
  2762 "pun">).</span><span class="kwd">catch</span><span class="pun">(</span><span class="pln">error</span><span class=
  2763 "pun">);</span><span class="pln">
  2764       startBtn</span><span class="pun">.</span><span class="pln">disabled </span><span class="pun">=</span><span class=
  2765 "pln"> </span><span class="kwd">true</span><span class="pun">;</span><span class="pln">
  2766    </span><span class="pun">}</span><span class="pln"> </span><span class="kwd">else</span><span class=
  2767 "pln"> </span><span class="pun">{</span><span class="pln">
  2768       debug</span><span class="pun">.</span><span class="pln">innerHTML </span><span class="pun">+=</span><span class=
  2769 "pln"> </span><span class="str">"&lt;br&gt;Service Discovery not supported!"</span><span class=
  2770 "pun">;</span><span class="pln">
  2771    </span><span class="pun">}</span><span class="pln">
  2772  </span><span class="pun">}</span><span class="pln">
  2773 
  2774  </span><span class="kwd">function</span><span class="pln"> gotXBMCService</span><span class="pun">(</span><span class=
  2775 "pln">services</span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
  2776 
  2777 </span><span class="com">// Listen for service disconnect messages</span><span class="pln">
  2778 
  2779    services</span><span class="pun">[</span><span class="lit">0</span><span class="pun">].</span><span class=
  2780 "pln">addEventListener</span><span class="pun">(</span><span class="str">'unavailable'</span><span class=
  2781 "pun">,</span><span class="pln"> </span><span class="kwd">function</span><span class="pln"> </span><span class=
  2782 "pun">(</span><span class="pln"> e </span><span class="pun">)</span><span class="pln"> </span><span class=
  2783 "pun">{</span><span class="pln">
  2784        debug</span><span class="pun">.</span><span class="pln">innerHTML </span><span class="pun">+=</span><span class=
  2785 "pln"> </span><span class="str">"&lt;br&gt;"</span><span class="pln"> </span><span class="pun">+</span><span class=
  2786 "pln"> services</span><span class="pun">[</span><span class="lit">0</span><span class="pun">].</span><span class=
  2787 "pln">name </span><span class="pun">+</span><span class="pln"> </span><span class=
  2788 "str">" disconnected."</span><span class="pun">;</span><span class="pln">
  2789        startBtn</span><span class="pun">.</span><span class="pln">disabled </span><span class=
  2790 "pun">=</span><span class="pln"> </span><span class="kwd">false</span><span class="pun">;</span><span class="pln">
  2791    </span><span class="pun">},</span><span class="pln"> </span><span class="kwd">false</span><span class=
  2792 "pun">);</span><span class="pln">
  2793 
  2794 </span><span class=
  2795 "com">// Send a service message to get albums list (and process the service response)</span><span class="pln">
  2796 
  2797    </span><span class="kwd">var</span><span class="pln"> svcXhr </span><span class="pun">=</span><span class=
  2798 "pln"> </span><span class="kwd">new</span><span class="pln"> </span><span class="typ">XMLHttpRequest</span><span class=
  2799 "pun">();</span><span class="pln">
  2800    svcXhr</span><span class="pun">.</span><span class="pln">open</span><span class="pun">(</span><span class=
  2801 "str">"POST"</span><span class="pun">,</span><span class="pln"> services</span><span class="pun">[</span><span class=
  2802 "lit">0</span><span class="pun">].</span><span class="pln">url </span><span class="pun">+</span><span class=
  2803 "pln"> </span><span class="str">"/getAlbums"</span><span class="pun">);</span><span class="pln"> </span><span class=
  2804 "com">// services[0].url and its sub-resources have been</span><span class="pln">
  2805                                                         </span><span class=
  2806 "com">// whitelisted for cross-site XHR use in this</span><span class="pln">
  2807                                                         </span><span class=
  2808 "com">// current browsing context.</span><span class="pln">
  2809 
  2810    svcXhr</span><span class="pun">.</span><span class="pln">setRequestHeader</span><span class=
  2811 "pun">(</span><span class="str">'Content-Type'</span><span class="pun">,</span><span class="pln"> </span><span class=
  2812 "str">'application/json-rpc'</span><span class="pun">);</span><span class="pln">
  2813 
  2814    svcXhr</span><span class="pun">.</span><span class="pln">addEventListener</span><span class=
  2815 "pun">(</span><span class="str">'readystatechange'</span><span class="pun">,</span><span class=
  2816 "pln"> </span><span class="kwd">function</span><span class="pln"> </span><span class="pun">(</span><span class=
  2817 "pln"> response </span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
  2818      </span><span class="kwd">if</span><span class="pun">(</span><span class="pln"> response</span><span class=
  2819 "pun">.</span><span class="pln">readyState </span><span class="pun">!=</span><span class="pln"> </span><span class=
  2820 "lit">4</span><span class="pln"> </span><span class="pun">||</span><span class="pln"> response</span><span class=
  2821 "pun">.</span><span class="pln">status </span><span class="pun">!=</span><span class="pln"> </span><span class=
  2822 "lit">200</span><span class="pln"> </span><span class="pun">)</span><span class="pln">
  2823         </span><span class="kwd">return</span><span class="pun">;</span><span class="pln">
  2824      debug</span><span class="pun">.</span><span class="pln">innerHTML </span><span class="pun">+=</span><span class=
  2825 "pln"> </span><span class="str">"&lt;br&gt;"</span><span class="pln"> </span><span class="pun">+</span><span class=
  2826 "pln"> services</span><span class="pun">[</span><span class="lit">0</span><span class="pun">].</span><span class=
  2827 "pln">name </span><span class="pun">+</span><span class="pln"> </span><span class=
  2828 "str">" response received: "</span><span class="pun">;</span><span class="pln">
  2829      debug</span><span class="pun">.</span><span class="pln">textContent </span><span class="pun">+=</span><span class=
  2830 "pln"> JSON</span><span class="pun">.</span><span class="pln">parse</span><span class="pun">(</span><span class=
  2831 "pln">response</span><span class="pun">.</span><span class="pln">responseText</span><span class=
  2832 "pun">);</span><span class="pln">
  2833    </span><span class="pun">},</span><span class="pln"> </span><span class="kwd">false</span><span class=
  2834 "pun">);</span><span class="pln">
  2835 
  2836    </span><span class="kwd">var</span><span class="pln"> svcMsg </span><span class="pun">=</span><span class=
  2837 "pln"> </span><span class="pun">[</span><span class="pln">
  2838      </span><span class="pun">{</span><span class="pln"> </span><span class="str">"jsonrpc"</span><span class=
  2839 "pun">:</span><span class="pln"> </span><span class="str">"2.0"</span><span class="pun">,</span><span class=
  2840 "pln"> </span><span class="str">"method"</span><span class="pun">:</span><span class="pln"> </span><span class=
  2841 "str">"AudioLibrary.GetAlbums"</span><span class="pun">,</span><span class="pln"> </span><span class=
  2842 "str">"params"</span><span class="pun">:</span><span class="pln"> </span><span class="pun">{</span><span class=
  2843 "pln"> </span><span class="str">"genreid"</span><span class="pun">:</span><span class="pln"> </span><span class=
  2844 "pun">-</span><span class="lit">1</span><span class="pun">,</span><span class="pln">
  2845          </span><span class="str">"artistid"</span><span class="pun">:</span><span class="pln"> </span><span class=
  2846 "pun">-</span><span class="lit">1</span><span class="pun">,</span><span class="pln"> </span><span class=
  2847 "str">"start"</span><span class="pun">:</span><span class="pln"> </span><span class="pun">-</span><span class=
  2848 "lit">1</span><span class="pun">,</span><span class="pln"> </span><span class="str">"end"</span><span class=
  2849 "pun">:</span><span class="pln"> </span><span class="pun">-</span><span class="lit">1</span><span class=
  2850 "pln"> </span><span class="pun">},</span><span class="pln"> </span><span class="str">"id"</span><span class=
  2851 "pun">:</span><span class="pln"> </span><span class="str">"1"</span><span class="pln"> </span><span class=
  2852 "pun">}</span><span class="pln">
  2853    </span><span class="pun">];</span><span class="pln">
  2854 
  2855    svcXhr</span><span class="pun">.</span><span class="pln">send</span><span class="pun">(</span><span class=
  2856 "pln">JSON</span><span class="pun">.</span><span class="pln">stringify</span><span class="pun">(</span><span class=
  2857 "pln">svcMsg</span><span class="pun">));</span><span class="pln">
  2858    debug</span><span class="pun">.</span><span class="pln">innerHTML </span><span class="pun">+=</span><span class=
  2859 "pln"> </span><span class="str">"&lt;br&gt;"</span><span class="pln"> </span><span class="pun">+</span><span class=
  2860 "pln"> services</span><span class="pun">[</span><span class="lit">0</span><span class="pun">].</span><span class=
  2861 "pln">name </span><span class="pun">+</span><span class="pln"> </span><span class=
  2862 "str">" request sent: "</span><span class="pun">;</span><span class="pln">
  2863    debug</span><span class="pun">.</span><span class="pln">textContent </span><span class="pun">+=</span><span class=
  2864 "pln"> JSON</span><span class="pun">.</span><span class="pln">stringify</span><span class="pun">(</span><span class=
  2865 "pln">svcMsg</span><span class="pun">);</span><span class="pln">
  2866 
  2867  </span><span class="pun">}</span><span class="pln">
  2868 
  2869  </span><span class="kwd">function</span><span class="pln"> error</span><span class="pun">(</span><span class=
  2870 "pln"> err </span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
  2871    debug</span><span class="pun">.</span><span class="pln">innerHTML </span><span class="pun">+=</span><span class=
  2872 "pln"> </span><span class="str">"&lt;br&gt;An error occurred obtaining a local network service."</span><span class=
  2873 "pun">;</span><span class="pln">
  2874    startBtn</span><span class="pun">.</span><span class="pln">disabled </span><span class="pun">=</span><span class=
  2875 "pln"> </span><span class="kwd">false</span><span class="pun">;</span><span class="pln">
  2876  </span><span class="pun">}</span><span class="pln">
  2877 </span><span class="tag">&lt;/script&gt;</span>
  2878 </pre>
  2879       </div>
  2880       <div class="example">
  2881         <p>
  2882           This sample exposes a drop-down list containing a number of common Home-based audio devices. When the user
  2883           selects an audio device from the list provided, they are prompted to authorize a network service based on the
  2884           service type requested. The user may also select multiple network services matching the selected service
  2885           type. In this example, the user selects their make as being <var>Sony</var> and their model as being
  2886           <var>Bravia S1000</var> from which the Web page can derive a service type
  2887           (<var>urn:schemas-upnp-org:service:RenderingControl:1</var>).<br>
  2888           <br>
  2889           Once the user has authorized the device, the web page sends a simple mute command according to the messaging
  2890           format supported by the device.
  2891         </p>
  2892         <hr>
  2893         <pre class="highlight prettyprint">
  2894 <span class="tag">&lt;select</span><span class="pln"> </span><span class="atn">name</span><span class=
  2895 "pun">=</span><span class="atv">"make"</span><span class="pln"> </span><span class="atn">id</span><span class=
  2896 "pun">=</span><span class="atv">"make"</span><span class="tag">&gt;</span><span class="pln">
  2897   </span><span class="tag">&lt;option</span><span class="pln"> </span><span class="atn">selected</span><span class=
  2898 "pun">=</span><span class="atv">"selected"</span><span class="pln"> </span><span class=
  2899 "atn">disabled</span><span class="pun">=</span><span class="atv">"disabled"</span><span class=
  2900 "tag">&gt;</span><span class="pln">Select make</span><span class="tag">&lt;/option&gt;</span><span class="pln">
  2901   </span><span class="tag">&lt;option&gt;</span><span class="pln">Sony</span><span class=
  2902 "tag">&lt;/option&gt;</span><span class="pln">
  2903   </span><span class="tag">&lt;option&gt;</span><span class="pln">Philips</span><span class=
  2904 "tag">&lt;/option&gt;</span><span class="pln">
  2905   </span><span class="tag">&lt;option&gt;</span><span class="pln">Alba</span><span class=
  2906 "tag">&lt;/option&gt;</span><span class="pln">
  2907 </span><span class="tag">&lt;/select&gt;</span><span class="pln">
  2908 </span><span class="tag">&lt;select</span><span class="pln"> </span><span class="atn">name</span><span class=
  2909 "pun">=</span><span class="atv">"model"</span><span class="pln"> </span><span class="atn">id</span><span class=
  2910 "pun">=</span><span class="atv">"model"</span><span class="tag">&gt;&lt;/select&gt;</span><span class="pln">
  2911 </span><span class="tag">&lt;div</span><span class="pln"> </span><span class="atn">id</span><span class=
  2912 "pun">=</span><span class="atv">"debugconsole"</span><span class="tag">&gt;&lt;/div&gt;</span><span class="pln">
  2913 
  2914 </span><span class="tag">&lt;script&gt;</span><span class="pln">
  2915   </span><span class="kwd">var</span><span class="pln"> debug </span><span class="pun">=</span><span class=
  2916 "pln"> document</span><span class="pun">.</span><span class="pln">getElementById</span><span class=
  2917 "pun">(</span><span class="str">'debugconsole'</span><span class="pun">);</span><span class="pln">
  2918 
  2919   </span><span class="kwd">var</span><span class="pln"> models </span><span class="pun">=</span><span class=
  2920 "pln"> </span><span class="pun">{</span><span class="pln">
  2921     </span><span class="str">"Sony"</span><span class="pun">:</span><span class="pln"> </span><span class=
  2922 "pun">[</span><span class="pln">
  2923       </span><span class="pun">{</span><span class="str">"name"</span><span class="pun">:</span><span class=
  2924 "pln"> </span><span class="str">"Bravia TV S1000"</span><span class="pun">,</span><span class=
  2925 "pln"> </span><span class="str">"type"</span><span class="pun">:</span><span class="pln"> </span><span class=
  2926 "str">"upnp"</span><span class="pun">,</span><span class="pln"> </span><span class="str">"service"</span><span class=
  2927 "pun">:</span><span class="pln"> </span><span class=
  2928 "str">"urn:schemas-upnp-org:service:RenderingControl:1"</span><span class="pln"> </span><span class=
  2929 "pun">},</span><span class="pln">
  2930       </span><span class="pun">{</span><span class="str">"name"</span><span class="pun">:</span><span class=
  2931 "pln"> </span><span class="str">"Bravia TV S2000"</span><span class="pun">,</span><span class=
  2932 "pln"> </span><span class="str">"type"</span><span class="pun">:</span><span class="pln"> </span><span class=
  2933 "str">"zeroconf"</span><span class="pun">,</span><span class="pln"> </span><span class=
  2934 "str">"service"</span><span class="pun">:</span><span class="pln"> </span><span class=
  2935 "str">"_mediarenderer._http._tcp"</span><span class="pln"> </span><span class="pun">},</span><span class="pln">
  2936       </span><span class="pun">{</span><span class="str">"name"</span><span class="pun">:</span><span class=
  2937 "pln"> </span><span class="str">"HiFi WD10"</span><span class="pun">,</span><span class="pln"> </span><span class=
  2938 "str">"type"</span><span class="pun">:</span><span class="pln"> </span><span class="str">"upnp"</span><span class=
  2939 "pun">,</span><span class="pln"> </span><span class="str">"service"</span><span class="pun">:</span><span class=
  2940 "pln"> </span><span class="str">"urn:schemas-upnp-org:service:RenderingControl:1"</span><span class=
  2941 "pln"> </span><span class="pun">}</span><span class="pln">
  2942     </span><span class="pun">],</span><span class="pln">
  2943     </span><span class="str">"Philips"</span><span class="pun">:</span><span class="pln"> </span><span class=
  2944 "pun">[</span><span class="pln"> </span><span class="com">/* ... */</span><span class="pln"> </span><span class=
  2945 "pun">],</span><span class="pln">
  2946     </span><span class="str">"Alba"</span><span class="pun">:</span><span class="pln"> </span><span class=
  2947 "pun">[</span><span class="pln"> </span><span class="com">/* ... */</span><span class="pln"> </span><span class=
  2948 "pun">]</span><span class="pln">
  2949   </span><span class="pun">};</span><span class="pln">
  2950 
  2951   </span><span class="kwd">var</span><span class="pln"> makeEl </span><span class="pun">=</span><span class=
  2952 "pln"> document</span><span class="pun">.</span><span class="pln">getElementById</span><span class=
  2953 "pun">(</span><span class="str">"make"</span><span class="pun">),</span><span class="pln">
  2954       modelEl </span><span class="pun">=</span><span class="pln"> document</span><span class="pun">.</span><span class=
  2955 "pln">getElementById</span><span class="pun">(</span><span class="str">"model"</span><span class=
  2956 "pun">);</span><span class="pln">
  2957 
  2958   makeEl</span><span class="pun">.</span><span class="pln">addEventListener</span><span class=
  2959 "pun">(</span><span class="str">'change'</span><span class="pun">,</span><span class="pln"> </span><span class=
  2960 "kwd">function</span><span class="pun">()</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
  2961     modelEl</span><span class="pun">.</span><span class="pln">innerHTML </span><span class="pun">=</span><span class=
  2962 "pln"> </span><span class="str">""</span><span class="pun">;</span><span class="pln"> </span><span class=
  2963 "com">// reset</span><span class="pln">
  2964     </span><span class="kwd">var</span><span class="pln"> defaultOption </span><span class="pun">=</span><span class=
  2965 "pln"> document</span><span class="pun">.</span><span class="pln">createElement</span><span class=
  2966 "pun">(</span><span class="str">"option"</span><span class="pun">);</span><span class="pln">
  2967     defaultOption</span><span class="pun">.</span><span class="pln">textContent </span><span class=
  2968 "pun">=</span><span class="pln"> </span><span class="str">"Select model"</span><span class="pun">;</span><span class=
  2969 "pln">
  2970     defaultOption</span><span class="pun">.</span><span class="pln">setAttribute</span><span class=
  2971 "pun">(</span><span class="str">"disabled"</span><span class="pun">,</span><span class="pln"> </span><span class=
  2972 "str">"disabled"</span><span class="pun">);</span><span class="pln">
  2973     defaultOption</span><span class="pun">.</span><span class="pln">setAttribute</span><span class=
  2974 "pun">(</span><span class="str">"selected"</span><span class="pun">,</span><span class="pln"> </span><span class=
  2975 "str">"selected"</span><span class="pun">);</span><span class="pln">
  2976     modelEl</span><span class="pun">.</span><span class="pln">appendChild</span><span class="pun">(</span><span class=
  2977 "pln">defaultOption</span><span class="pun">);</span><span class="pln">
  2978     </span><span class="kwd">for</span><span class="pun">(</span><span class="kwd">var</span><span class=
  2979 "pln"> i </span><span class="pun">=</span><span class="pln"> </span><span class="lit">0</span><span class=
  2980 "pun">,</span><span class="pln"> l </span><span class="pun">=</span><span class="pln"> models</span><span class=
  2981 "pun">[</span><span class="pln">makeEl</span><span class="pun">.</span><span class="pln">value</span><span class=
  2982 "pun">].</span><span class="pln">length</span><span class="pun">;</span><span class="pln"> i </span><span class=
  2983 "pun">&lt;</span><span class="pln"> l</span><span class="pun">;</span><span class="pln"> i</span><span class=
  2984 "pun">++)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
  2985       </span><span class="kwd">var</span><span class="pln"> option </span><span class="pun">=</span><span class=
  2986 "pln"> document</span><span class="pun">.</span><span class="pln">createElement</span><span class=
  2987 "pun">(</span><span class="str">"option"</span><span class="pun">);</span><span class="pln">
  2988       option</span><span class="pun">.</span><span class="pln">textContent </span><span class=
  2989 "pun">=</span><span class="pln"> models</span><span class="pun">[</span><span class="pln">makeEl</span><span class=
  2990 "pun">.</span><span class="pln">value</span><span class="pun">][</span><span class="pln">i</span><span class=
  2991 "pun">][</span><span class="str">"name"</span><span class="pun">];</span><span class="pln">
  2992       option</span><span class="pun">.</span><span class="pln">setAttribute</span><span class=
  2993 "pun">(</span><span class="str">"value"</span><span class="pun">,</span><span class="pln"> models</span><span class=
  2994 "pun">[</span><span class="pln">makeEl</span><span class="pun">.</span><span class="pln">value</span><span class=
  2995 "pun">][</span><span class="pln">i</span><span class="pun">][</span><span class="str">"type"</span><span class=
  2996 "pun">]</span><span class="pln"> </span><span class="pun">+</span><span class="pln"> </span><span class=
  2997 "str">":"</span><span class="pln"> </span><span class="pun">+</span><span class="pln"> models</span><span class=
  2998 "pun">[</span><span class="pln">makeEl</span><span class="pun">.</span><span class="pln">value</span><span class=
  2999 "pun">][</span><span class="pln">i</span><span class="pun">][</span><span class="str">"service"</span><span class=
  3000 "pun">]);</span><span class="pln">
  3001       modelEl</span><span class="pun">.</span><span class="pln">appendChild</span><span class=
  3002 "pun">(</span><span class="pln">option</span><span class="pun">);</span><span class="pln">
  3003     </span><span class="pun">}</span><span class="pln">
  3004   </span><span class="pun">},</span><span class="pln"> </span><span class="kwd">false</span><span class=
  3005 "pun">);</span><span class="pln">
  3006 
  3007   modelEl</span><span class="pun">.</span><span class="pln">addEventListener</span><span class=
  3008 "pun">(</span><span class="str">'change'</span><span class="pun">,</span><span class="pln"> </span><span class=
  3009 "kwd">function</span><span class="pun">()</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
  3010     </span><span class="kwd">if</span><span class="pun">(</span><span class="pln">navigator</span><span class=
  3011 "pun">.</span><span class="pln">getNetworkServices </span><span class="pun">&amp;&amp;</span><span class="pln">
  3012          modelEl</span><span class="pun">.</span><span class="pln">value </span><span class="pun">==</span><span class=
  3013 "pln"> </span><span class="str">"upnp:urn:schemas-upnp-org:service:RenderingControl:1"</span><span class=
  3014 "pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
  3015       </span><span class="kwd">var</span><span class="pln"> servicesPromise </span><span class=
  3016 "pun">=</span><span class="pln"> navigator</span><span class="pun">.</span><span class=
  3017 "pln">getNetworkServices</span><span class="pun">(</span><span class="pln">modelEl</span><span class=
  3018 "pun">.</span><span class="pln">value</span><span class="pun">).</span><span class="pln">then</span><span class=
  3019 "pun">(</span><span class="pln">successCallback</span><span class="pun">,</span><span class=
  3020 "pln"> errorCallback</span><span class="pun">);</span><span class="pln">
  3021     </span><span class="pun">}</span><span class="pln"> </span><span class="kwd">else</span><span class=
  3022 "pln"> </span><span class="kwd">if</span><span class="pln"> </span><span class="pun">(</span><span class=
  3023 "pln">modelEl</span><span class="pun">.</span><span class="pln">value </span><span class="pun">==</span><span class=
  3024 "pln"> </span><span class="str">"zeroconf:_mediarenderer._http._tcp"</span><span class="pun">)</span><span class=
  3025 "pln"> </span><span class="pun">{</span><span class="pln">
  3026       debug</span><span class="pun">.</span><span class="pln">innerHTML </span><span class="pun">+=</span><span class=
  3027 "pln"> </span><span class="str">"&lt;br&gt;Service type is not implemented by this application."</span><span class=
  3028 "pun">;</span><span class="pln">
  3029     </span><span class="pun">}</span><span class="pln"> </span><span class="kwd">else</span><span class=
  3030 "pln"> </span><span class="pun">{</span><span class="pln">
  3031       debug</span><span class="pun">.</span><span class="pln">innerHTML </span><span class="pun">+=</span><span class=
  3032 "pln"> </span><span class="str">"&lt;br&gt;Service Discovery is not supported!"</span><span class=
  3033 "pun">;</span><span class="pln">
  3034     </span><span class="pun">}</span><span class="pln">
  3035   </span><span class="pun">},</span><span class="pln"> </span><span class="kwd">false</span><span class=
  3036 "pun">);</span><span class="pln">
  3037 </span><span class="tag">&lt;/script&gt;</span><span class="pln">
  3038 
  3039 </span><span class="tag">&lt;script&gt;</span><span class="pln">
  3040   </span><span class="kwd">function</span><span class="pln"> successCallback</span><span class=
  3041 "pun">(</span><span class="pln"> services </span><span class="pun">)</span><span class="pln"> </span><span class=
  3042 "pun">{</span><span class="pln">
  3043 
  3044   </span><span class="com">// Listen for service push notification messages</span><span class="pln">
  3045 
  3046     services</span><span class="pun">[</span><span class="lit">0</span><span class="pun">].</span><span class=
  3047 "pln">addEventListener</span><span class="pun">(</span><span class="str">'notify'</span><span class=
  3048 "pun">,</span><span class="pln"> </span><span class="kwd">function</span><span class="pln"> </span><span class=
  3049 "pun">(</span><span class="pln"> msg </span><span class="pun">)</span><span class="pln"> </span><span class=
  3050 "pun">{</span><span class="pln">
  3051          debug</span><span class="pun">.</span><span class="pln">innerHTML </span><span class=
  3052 "pun">+=</span><span class="pln"> </span><span class="str">"&lt;br&gt;"</span><span class="pln"> </span><span class=
  3053 "pun">+</span><span class="pln"> services</span><span class="pun">[</span><span class="lit">0</span><span class=
  3054 "pun">].</span><span class="pln">name </span><span class="pun">+</span><span class="pln"> </span><span class=
  3055 "str">" event received: "</span><span class="pun">;</span><span class="pln">
  3056          debug</span><span class="pun">.</span><span class="pln">textContent </span><span class=
  3057 "pun">+=</span><span class="pln"> msg</span><span class="pun">.</span><span class="pln">data</span><span class=
  3058 "pun">;</span><span class="pln">
  3059     </span><span class="pun">},</span><span class="pln"> </span><span class="kwd">false</span><span class=
  3060 "pun">);</span><span class="pln">
  3061 
  3062  </span><span class="com">// Send a control signal to mute the service audio</span><span class="pln">
  3063 
  3064     </span><span class="kwd">var</span><span class="pln"> svcXhr </span><span class="pun">=</span><span class=
  3065 "pln"> </span><span class="kwd">new</span><span class="pln"> </span><span class="typ">XMLHttpRequest</span><span class=
  3066 "pun">();</span><span class="pln">
  3067     svcXhr</span><span class="pun">.</span><span class="pln">open</span><span class="pun">(</span><span class=
  3068 "str">"POST"</span><span class="pun">,</span><span class="pln"> services</span><span class="pun">[</span><span class=
  3069 "lit">0</span><span class="pun">].</span><span class="pln">url</span><span class="pun">);</span><span class=
  3070 "pln"> </span><span class="com">// services[0].url and its</span><span class="pln">
  3071                                           </span><span class=
  3072 "com">// sub-resources have been whitelisted for</span><span class="pln">
  3073                                           </span><span class=
  3074 "com">// cross-site XHR use in this current</span><span class="pln">
  3075                                           </span><span class="com">// browsing context.</span><span class="pln">
  3076 
  3077     svcXhr</span><span class="pun">.</span><span class="pln">setRequestHeader</span><span class=
  3078 "pun">(</span><span class="str">'SOAPAction'</span><span class="pun">,</span><span class="pln"> </span><span class=
  3079 "str">'urn:schemas-upnp-org:service:RenderingControl:1#SetMute'</span><span class="pun">);</span><span class="pln">
  3080     svcXhr</span><span class="pun">.</span><span class="pln">setRequestHeader</span><span class=
  3081 "pun">(</span><span class="str">'Content-Type'</span><span class="pun">,</span><span class="pln"> </span><span class=
  3082 "str">'text/xml; charset="utf-8";'</span><span class="pun">);</span><span class="pln">
  3083 
  3084     svcXhr</span><span class="pun">.</span><span class="pln">onreadystatechange </span><span class=
  3085 "pun">=</span><span class="pln"> </span><span class="kwd">function</span><span class="pln"> </span><span class=
  3086 "pun">(</span><span class="pln"> response </span><span class="pun">)</span><span class="pln"> </span><span class=
  3087 "pun">{</span><span class="pln">
  3088       </span><span class="kwd">if</span><span class="pun">(</span><span class="pln"> response</span><span class=
  3089 "pun">.</span><span class="pln">readyState </span><span class="pun">!=</span><span class="pln"> </span><span class=
  3090 "lit">4</span><span class="pln"> </span><span class="pun">||</span><span class="pln"> response</span><span class=
  3091 "pun">.</span><span class="pln">status </span><span class="pun">!=</span><span class="pln"> </span><span class=
  3092 "lit">200</span><span class="pln"> </span><span class="pun">)</span><span class="pln">
  3093         </span><span class="kwd">return</span><span class="pun">;</span><span class="pln">
  3094       debug</span><span class="pun">.</span><span class="pln">innerHTML </span><span class="pun">+=</span><span class=
  3095 "pln"> </span><span class="str">"&lt;br&gt;"</span><span class="pln"> </span><span class="pun">+</span><span class=
  3096 "pln"> services</span><span class="pun">[</span><span class="lit">0</span><span class="pun">].</span><span class=
  3097 "pln">name </span><span class="pun">+</span><span class="pln"> </span><span class=
  3098 "str">" response received: "</span><span class="pun">;</span><span class="pln">
  3099       debug</span><span class="pun">.</span><span class="pln">textContent </span><span class=
  3100 "pun">+=</span><span class="pln"> response</span><span class="pun">.</span><span class=
  3101 "pln">responseXML</span><span class="pun">;</span><span class="pln">
  3102     </span><span class="pun">}</span><span class="pln">
  3103 
  3104     </span><span class="com">// Service messaging to mute the provided service</span><span class="pln">
  3105     </span><span class="kwd">var</span><span class="pln"> svcMsg </span><span class="pun">=</span><span class=
  3106 "pln"> </span><span class="str">'&lt;?xml version="1.0" encoding="utf-8"?&gt;'</span><span class=
  3107 "pln"> </span><span class="pun">+</span><span class="pln">
  3108                  </span><span class=
  3109 "str">'&lt;s:Envelope s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" '</span><span class=
  3110 "pln"> </span><span class="pun">+</span><span class="pln">
  3111                    </span><span class=
  3112 "str">'xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"&gt;'</span><span class="pln"> </span><span class=
  3113 "pun">+</span><span class="pln">
  3114                    </span><span class="str">'&lt;s:Body&gt;'</span><span class="pln"> </span><span class=
  3115 "pun">+</span><span class="pln">
  3116                      </span><span class=
  3117 "str">'&lt;u:SetMute xmlns:u="urn:schemas-upnp-org:service:RenderingControl:1"&gt;'</span><span class=
  3118 "pln"> </span><span class="pun">+</span><span class="pln">
  3119                        </span><span class="str">'&lt;InstanceID&gt;0&lt;/InstanceID&gt;'</span><span class=
  3120 "pln"> </span><span class="pun">+</span><span class="pln">
  3121                        </span><span class="str">'&lt;Channel&gt;Master&lt;/Channel&gt;'</span><span class=
  3122 "pln"> </span><span class="pun">+</span><span class="pln">
  3123                        </span><span class="str">'&lt;DesiredMute&gt;true&lt;/DesiredMute&gt;'</span><span class=
  3124 "pln"> </span><span class="pun">+</span><span class="pln">
  3125                      </span><span class="str">'&lt;/u:SetMute&gt;'</span><span class="pln"> </span><span class=
  3126 "pun">+</span><span class="pln">
  3127                    </span><span class="str">'&lt;/s:Body&gt;'</span><span class="pln"> </span><span class=
  3128 "pun">+</span><span class="pln">
  3129                  </span><span class="str">'&lt;/s:Envelope&gt;'</span><span class="pun">;</span><span class="pln">
  3130 
  3131     svcXhr</span><span class="pun">.</span><span class="pln">send</span><span class="pun">(</span><span class=
  3132 "pln">svcMsg</span><span class="pun">);</span><span class="pln">
  3133     debug</span><span class="pun">.</span><span class="pln">innerHTML </span><span class="pun">+=</span><span class=
  3134 "pln"> </span><span class="str">"&lt;br&gt;"</span><span class="pln"> </span><span class="pun">+</span><span class=
  3135 "pln"> services</span><span class="pun">[</span><span class="lit">0</span><span class="pun">].</span><span class=
  3136 "pln">name </span><span class="pun">+</span><span class="pln"> </span><span class=
  3137 "str">" request sent: "</span><span class="pun">;</span><span class="pln">
  3138     debug</span><span class="pun">.</span><span class="pln">textContent </span><span class="pun">+=</span><span class=
  3139 "pln"> svcMsg</span><span class="pun">;</span><span class="pln">
  3140   </span><span class="pun">}</span><span class="pln">
  3141 
  3142   </span><span class="kwd">function</span><span class="pln"> errorCallback</span><span class="pun">(</span><span class=
  3143 "pln"> error </span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
  3144     debug</span><span class="pun">.</span><span class="pln">innerHTML </span><span class="pun">+=</span><span class=
  3145 "pln"> </span><span class="str">"&lt;br&gt;An error occurred: "</span><span class="pln"> </span><span class=
  3146 "pun">+</span><span class="pln"> error</span><span class="pun">.</span><span class="pln">name</span><span class=
  3147 "pun">;</span><span class="pln">
  3148   </span><span class="pun">}</span><span class="pln">
  3149 </span><span class="tag">&lt;/script&gt;</span>
  3150 </pre>
  3151       </div>
  3152     </section>
  3153     <section id="acknowledgements">
  3154       <h2 aria-level="1"
  3155           role="heading"
  3156           id="h2_acknowledgements">
  3157         <span class="secno">B.</span> Acknowledgements
  3158       </h2>
  3159       <p>
  3160         Thanks are expressed by the editor to the following individuals for their feedback on this specification to
  3161         date (in alphabetical order):<br>
  3162         <br>
  3163         Adam Barth, Gar Bergstedt, Robin Berjon, Lars-Erik Bolstad, Marcos Caceres, Cathy Chan, Daniel Danciu,
  3164         Jean-Claude Dufourd, Mark Foltz, Dominique Hazael-Massieux, Frederick Hirsch, Hari G Kumar, Bob Lund, Giuseppe
  3165         Pascale, Marcin Simonides, Clarke Stevens, Christian Söderström, Mark Vickers.
  3166       </p>
  3167       <p>
  3168         Thanks are also expressed by the editor to the following organizations and groups for their support in
  3169         producing this specification to date (in alphabetical order):<br>
  3170         <br>
  3171         CableLabs, Google Inc., Opera Software ASA, Nokia Corp., Télécom ParisTech, <abbr title=
  3172         "World Wide Web Consortium">W3C</abbr> Device APIs Working Group, <abbr title=
  3173         "World Wide Web Consortium">W3C</abbr> Web and TV Interest Group.
  3174       </p>
  3175     </section><style>
  3176 a.externalDFN { color: #00C; border-bottom: 1px dashed #00C; }
  3177     a.internalDFN { color: #00C; text-decoration: solid; }
  3178     </style>
  3179     <section id="references"
  3180              class="appendix"
  3181              typeof="bibo:Chapter"
  3182              resource="#references"
  3183              rel="bibo:chapter">
  3184       <h2 aria-level="1"
  3185           role="heading"
  3186           id="h2_references">
  3187         <span class="secno">C.</span> References
  3188       </h2>
  3189       <section id="normative-references"
  3190                typeof="bibo:Chapter"
  3191                resource="#normative-references"
  3192                rel="bibo:chapter">
  3193         <h3 aria-level="2"
  3194             role="heading"
  3195             id="h3_normative-references">
  3196           <span class="secno">C.1</span> Normative references
  3197         </h3>
  3198         <dl class="bibliography"
  3199             about="">
  3200           <dt id="bib-DNS-SD">
  3201             [DNS-SD]
  3202           </dt>
  3203           <dd rel="dcterms:requires">
  3204             S. Cheshire; M. Krochmal. <a href="http://www.ietf.org/rfc/rfc6763.txt"><cite>DNS-Based Service
  3205             Discovery</cite></a>. February 2013. RFC. URL: <a href=
  3206             "http://www.ietf.org/rfc/rfc6763.txt">http://www.ietf.org/rfc/rfc6763.txt</a>
  3207           </dd>
  3208           <dt id="bib-DOM4">
  3209             [DOM4]
  3210           </dt>
  3211           <dd rel="dcterms:requires">
  3212             Anne van Kesteren; Aryeh Gregor; Lachlan Hunt; Ms2ger. <a href=
  3213             "http://www.w3.org/TR/dom/"><cite>DOM4</cite></a>. 6 December 2012. W3C Working Draft. URL: <a href=
  3214             "http://www.w3.org/TR/dom/">http://www.w3.org/TR/dom/</a>
  3215           </dd>
  3216           <dt id="bib-HTML5">
  3217             [HTML5]
  3218           </dt>
  3219           <dd rel="dcterms:requires">
  3220             Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Edward O'Connor; Silvia Pfeiffer.
  3221             <a href="http://www.w3.org/TR/html5/"><cite>HTML5</cite></a>. 6 August 2013. W3C Candidate Recommendation.
  3222             URL: <a href="http://www.w3.org/TR/html5/">http://www.w3.org/TR/html5/</a>
  3223           </dd>
  3224           <dt id="bib-MDNS">
  3225             [MDNS]
  3226           </dt>
  3227           <dd rel="dcterms:requires">
  3228             S. Cheshire; M. Krochmal. <a href="http://www.ietf.org/rfc/rfc6763.txt"><cite>Multicast DNS</cite></a>.
  3229             February 2013. RFC. URL: <a href=
  3230             "http://www.ietf.org/rfc/rfc6763.txt">http://www.ietf.org/rfc/rfc6763.txt</a>
  3231           </dd>
  3232           <dt id="bib-RFC2119">
  3233             [RFC2119]
  3234           </dt>
  3235           <dd rel="dcterms:requires">
  3236             S. Bradner. <a href="http://www.ietf.org/rfc/rfc2119.txt"><cite>Key words for use in RFCs to Indicate
  3237             Requirement Levels.</cite></a> March 1997. Internet RFC 2119. URL: <a href=
  3238             "http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a>
  3239           </dd>
  3240           <dt id="bib-UPNP-DEVICEARCH11">
  3241             [UPNP-DEVICEARCH11]
  3242           </dt>
  3243           <dd rel="dcterms:requires">
  3244             <a href="http://upnp.org/specs/arch/UPnP-arch-DeviceArchitecture-v1.1.pdf"><cite>UPnP Device Architecture
  3245             1.1</cite></a>. 15 October 2008. UPnP Forum. PDF document. URL: <a href=
  3246             "http://upnp.org/specs/arch/UPnP-arch-DeviceArchitecture-v1.1.pdf">http://upnp.org/specs/arch/UPnP-arch-DeviceArchitecture-v1.1.pdf</a>
  3247           </dd>
  3248           <dt id="bib-WEBIDL">
  3249             [WEBIDL]
  3250           </dt>
  3251           <dd rel="dcterms:requires">
  3252             Cameron McCormack. <a href="http://www.w3.org/TR/WebIDL/"><cite>Web IDL</cite></a>. 19 April 2012. W3C
  3253             Candidate Recommendation. URL: <a href="http://www.w3.org/TR/WebIDL/">http://www.w3.org/TR/WebIDL/</a>
  3254           </dd>
  3255         </dl>
  3256       </section>
  3257       <section id="informative-references"
  3258                typeof="bibo:Chapter"
  3259                resource="#informative-references"
  3260                rel="bibo:chapter">
  3261         <h3 aria-level="2"
  3262             role="heading"
  3263             id="h3_informative-references">
  3264           <span class="secno">C.2</span> Informative references
  3265         </h3>
  3266         <dl class="bibliography"
  3267             about="">
  3268           <dt id="bib-hnreq">
  3269             [hnreq]
  3270           </dt>
  3271           <dd rel="dcterms:references">
  3272             Giuseppe Pascale. <a href="http://www.w3.org/TR/hnreq/"><cite>Requirements for Home Networking
  3273             Scenarios</cite></a>. 1 December 2011. W3C Note. URL: <a href=
  3274             "http://www.w3.org/TR/hnreq/">http://www.w3.org/TR/hnreq/</a>
  3275           </dd>
  3276         </dl>
  3277       </section>
  3278     </section>
  3279   </body>
  3280 </html>