discovery-api/Overview.src.html
author Robin Berjon <robin@berjon.com>
Fri, 03 Aug 2012 15:48:19 +0200
changeset 183 21b44409354f
parent 182 595192a920a0
child 185 ef42cb5f9a60
permissions -rw-r--r--
shortname
     1 <!DOCTYPE html>
     2 <html>
     3   <head>
     4     <title>Networked Service Discovery and Messaging</title>
     5     <meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
     6     <script type="text/javascript" class='remove'>
     7       var respecConfig = {
     8           specStatus: "ED",
     9           shortName:  "discovery-api",
    10           edDraftURI: "http://w3c-test.org/dap/discovery-api/",
    11           editors: [
    12                 {   name:       "Rich Tibbett",
    13                     //url:        "http://richt.me/",
    14                     company:    "Opera Software ASA",
    15                     companyURL: "http://opera.com/" },
    16                 {   name:       "Clarke Stevens",
    17                     //url:      "",
    18                     company:    "CableLabs",
    19                     companyURL: "http://cablelabs.com/"
    20                 }
    21           ],
    22           noIDLIn:  true,
    23 
    24           wg:           "Device APIs and Policy Working Group",
    25           wgURI:        "http://www.w3.org/2009/dap/",
    26           wgPublicList: "public-device-apis",
    27           wgPatentURI:  "http://www.w3.org/2004/01/pp-impl/43696/status",
    28       };
    29     </script>
    30 
    31     <style type="text/css">
    32       /**
    33        * SyntaxHighlighter
    34        * http://alexgorbatchev.com/SyntaxHighlighter
    35        *
    36        * SyntaxHighlighter is donationware. If you are using it, please donate.
    37        * http://alexgorbatchev.com/SyntaxHighlighter/donate.html
    38        *
    39        * @version
    40        * 3.0.83 (July 02 2010)
    41        *
    42        * @copyright
    43        * Copyright (C) 2004-2010 Alex Gorbatchev.
    44        *
    45        * @license
    46        * Dual licensed under the MIT and GPL licenses.
    47        */
    48       .syntaxhighlighter a,
    49       .syntaxhighlighter div,
    50       .syntaxhighlighter code,
    51       .syntaxhighlighter table,
    52       .syntaxhighlighter table td,
    53       .syntaxhighlighter table tr,
    54       .syntaxhighlighter table tbody,
    55       .syntaxhighlighter table thead,
    56       .syntaxhighlighter table caption,
    57       .syntaxhighlighter textarea {
    58         -moz-border-radius: 0 0 0 0 !important;
    59         -webkit-border-radius: 0 0 0 0 !important;
    60         background: none !important;
    61         border: 0 !important;
    62         bottom: auto !important;
    63         float: none !important;
    64         height: auto !important;
    65         left: auto !important;
    66         line-height: 1.1em !important;
    67         margin: 0 !important;
    68         outline: 0 !important;
    69         overflow: visible !important;
    70         padding: 0 !important;
    71         position: static !important;
    72         right: auto !important;
    73         text-align: left !important;
    74         top: auto !important;
    75         vertical-align: baseline !important;
    76         width: auto !important;
    77         box-sizing: content-box !important;
    78         font-family: "Consolas", "Bitstream Vera Sans Mono", "Courier New", Courier, monospace !important;
    79         font-weight: normal !important;
    80         font-style: normal !important;
    81         font-size: 1em !important;
    82         min-height: inherit !important;
    83         min-height: auto !important;
    84       }
    85 
    86       .syntaxhighlighter {
    87         width: 100% !important;
    88         margin: 1em 0 1em 0 !important;
    89         position: relative !important;
    90         overflow: auto !important;
    91         font-size: 0.8em !important;
    92       }
    93       .syntaxhighlighter.source {
    94         overflow: hidden !important;
    95       }
    96       .syntaxhighlighter .bold {
    97         font-weight: bold !important;
    98       }
    99       .syntaxhighlighter .italic {
   100         font-style: italic !important;
   101       }
   102       .syntaxhighlighter .line {
   103         white-space: pre !important;
   104       }
   105       .syntaxhighlighter table {
   106         width: 100% !important;
   107       }
   108       .syntaxhighlighter table caption {
   109         text-align: left !important;
   110         padding: .5em 0 0.5em 1em !important;
   111       }
   112       .syntaxhighlighter table td.code {
   113         width: 100% !important;
   114       }
   115       .syntaxhighlighter table td.code .container {
   116         position: relative !important;
   117       }
   118       .syntaxhighlighter table td.code .container textarea {
   119         box-sizing: border-box !important;
   120         position: absolute !important;
   121         left: 0 !important;
   122         top: 0 !important;
   123         width: 100% !important;
   124         height: 100% !important;
   125         border: none !important;
   126 
   127         padding-left: 1em !important;
   128         overflow: hidden !important;
   129         white-space: pre !important;
   130       }
   131       .syntaxhighlighter table td.gutter .line {
   132         text-align: right !important;
   133         padding: 0 0.5em 0 1em !important;
   134       }
   135       .syntaxhighlighter table td.code .line {
   136         padding: 0 1em !important;
   137       }
   138       .syntaxhighlighter.nogutter td.code .container textarea, .syntaxhighlighter.nogutter td.code .line {
   139         padding-left: 0em !important;
   140       }
   141       .syntaxhighlighter.show {
   142         display: block !important;
   143       }
   144       .syntaxhighlighter.collapsed table {
   145         display: none !important;
   146       }
   147       .syntaxhighlighter.collapsed .toolbar {
   148         padding: 0.1em 0.8em 0em 0.8em !important;
   149         font-size: 1em !important;
   150         position: static !important;
   151         width: auto !important;
   152         height: auto !important;
   153       }
   154       .syntaxhighlighter.collapsed .toolbar span {
   155         display: inline !important;
   156         margin-right: 1em !important;
   157       }
   158       .syntaxhighlighter.collapsed .toolbar span a {
   159         padding: 0 !important;
   160         display: none !important;
   161       }
   162       .syntaxhighlighter.collapsed .toolbar span a.expandSource {
   163         display: inline !important;
   164       }
   165       .syntaxhighlighter .toolbar {
   166         position: absolute !important;
   167         right: 1px !important;
   168         top: 1px !important;
   169         width: 11px !important;
   170         height: 11px !important;
   171         font-size: 10px !important;
   172         z-index: 10 !important;
   173       }
   174       .syntaxhighlighter .toolbar span.title {
   175         display: inline !important;
   176       }
   177       .syntaxhighlighter .toolbar a {
   178         display: block !important;
   179         text-align: center !important;
   180         text-decoration: none !important;
   181         padding-top: 1px !important;
   182       }
   183       .syntaxhighlighter .toolbar a.expandSource {
   184         display: none !important;
   185       }
   186       .syntaxhighlighter.ie {
   187         font-size: .9em !important;
   188         padding: 1px 0 1px 0 !important;
   189       }
   190       .syntaxhighlighter.ie .toolbar {
   191         line-height: 8px !important;
   192       }
   193       .syntaxhighlighter.ie .toolbar a {
   194         padding-top: 0px !important;
   195       }
   196       .syntaxhighlighter.printing .line.alt1 .content,
   197       .syntaxhighlighter.printing .line.alt2 .content,
   198       .syntaxhighlighter.printing .line.highlighted .number,
   199       .syntaxhighlighter.printing .line.highlighted.alt1 .content,
   200       .syntaxhighlighter.printing .line.highlighted.alt2 .content {
   201         background: none !important;
   202       }
   203       .syntaxhighlighter.printing .line .number {
   204         color: #bbbbbb !important;
   205       }
   206       .syntaxhighlighter.printing .line .content {
   207         color: black !important;
   208       }
   209       .syntaxhighlighter.printing .toolbar {
   210         display: none !important;
   211       }
   212       .syntaxhighlighter.printing a {
   213         text-decoration: none !important;
   214       }
   215       .syntaxhighlighter.printing .plain, .syntaxhighlighter.printing .plain a {
   216         color: black !important;
   217       }
   218       .syntaxhighlighter.printing .comments, .syntaxhighlighter.printing .comments a {
   219         color: #008200 !important;
   220       }
   221       .syntaxhighlighter.printing .string, .syntaxhighlighter.printing .string a {
   222         color: blue !important;
   223       }
   224       .syntaxhighlighter.printing .keyword {
   225         color: #006699 !important;
   226         font-weight: bold !important;
   227       }
   228       .syntaxhighlighter.printing .preprocessor {
   229         color: gray !important;
   230       }
   231       .syntaxhighlighter.printing .variable {
   232         color: #aa7700 !important;
   233       }
   234       .syntaxhighlighter.printing .value {
   235         color: #009900 !important;
   236       }
   237       .syntaxhighlighter.printing .functions {
   238         color: #ff1493 !important;
   239       }
   240       .syntaxhighlighter.printing .constants {
   241         color: #0066cc !important;
   242       }
   243       .syntaxhighlighter.printing .script {
   244         font-weight: bold !important;
   245       }
   246       .syntaxhighlighter.printing .color1, .syntaxhighlighter.printing .color1 a {
   247         color: gray !important;
   248       }
   249       .syntaxhighlighter.printing .color2, .syntaxhighlighter.printing .color2 a {
   250         color: #ff1493 !important;
   251       }
   252       .syntaxhighlighter.printing .color3, .syntaxhighlighter.printing .color3 a {
   253         color: red !important;
   254       }
   255       .syntaxhighlighter.printing .break, .syntaxhighlighter.printing .break a {
   256         color: black !important;
   257       }
   258     </style>
   259     <style type="text/css">
   260       /**
   261        * SyntaxHighlighter
   262        * http://alexgorbatchev.com/SyntaxHighlighter
   263        *
   264        * SyntaxHighlighter is donationware. If you are using it, please donate.
   265        * http://alexgorbatchev.com/SyntaxHighlighter/donate.html
   266        *
   267        * @version
   268        * 3.0.83 (July 02 2010)
   269        *
   270        * @copyright
   271        * Copyright (C) 2004-2010 Alex Gorbatchev.
   272        *
   273        * @license
   274        * Dual licensed under the MIT and GPL licenses.
   275        */
   276       .syntaxhighlighter {
   277         background-color: none !important;
   278       }
   279       .syntaxhighlighter .line.alt1 {
   280         background-color: none !important;
   281       }
   282       .syntaxhighlighter .line.alt2 {
   283         background-color: none !important;
   284       }
   285       .syntaxhighlighter .line.highlighted.alt1, .syntaxhighlighter .line.highlighted.alt2 {
   286         background-color: none !important;
   287       }
   288       .syntaxhighlighter .line.highlighted.number {
   289         color: black !important;
   290       }
   291       .syntaxhighlighter table caption {
   292         color: black !important;
   293       }
   294       .syntaxhighlighter .gutter {
   295         color: #afafaf !important;
   296       }
   297       .syntaxhighlighter .gutter .line {
   298         border-right: 3px solid #6ce26c !important;
   299       }
   300       .syntaxhighlighter .gutter .line.highlighted {
   301         background-color: #6ce26c !important;
   302         color: white !important;
   303       }
   304       .syntaxhighlighter.printing .line .content {
   305         border: none !important;
   306       }
   307       .syntaxhighlighter.collapsed {
   308         overflow: visible !important;
   309       }
   310       .syntaxhighlighter.collapsed .toolbar {
   311         color: blue !important;
   312         background: none !important;
   313         border: 1px solid #6ce26c !important;
   314       }
   315       .syntaxhighlighter.collapsed .toolbar a {
   316         color: blue !important;
   317       }
   318       .syntaxhighlighter.collapsed .toolbar a:hover {
   319         color: red !important;
   320       }
   321       .syntaxhighlighter .toolbar {
   322         color: white !important;
   323         background: #6ce26c !important;
   324         border: none !important;
   325       }
   326       .syntaxhighlighter .toolbar a {
   327         color: white !important;
   328       }
   329       .syntaxhighlighter .toolbar a:hover {
   330         color: black !important;
   331       }
   332       .syntaxhighlighter .plain, .syntaxhighlighter .plain a {
   333         color: black !important;
   334       }
   335       .syntaxhighlighter .comments, .syntaxhighlighter .comments a {
   336         color: #008200 !important;
   337       }
   338       .syntaxhighlighter .string, .syntaxhighlighter .string a {
   339         color: blue !important;
   340       }
   341       .syntaxhighlighter .keyword {
   342         color: #006699 !important;
   343       }
   344       .syntaxhighlighter .preprocessor {
   345         color: gray !important;
   346       }
   347       .syntaxhighlighter .variable {
   348         color: #aa7700 !important;
   349       }
   350       .syntaxhighlighter .value {
   351         color: #009900 !important;
   352       }
   353       .syntaxhighlighter .functions {
   354         color: #ff1493 !important;
   355       }
   356       .syntaxhighlighter .constants {
   357         color: #0066cc !important;
   358       }
   359       .syntaxhighlighter .script {
   360         font-weight: bold !important;
   361         color: #006699 !important;
   362         background-color: none !important;
   363       }
   364       .syntaxhighlighter .color1, .syntaxhighlighter .color1 a {
   365         color: gray !important;
   366       }
   367       .syntaxhighlighter .color2, .syntaxhighlighter .color2 a {
   368         color: #ff1493 !important;
   369       }
   370       .syntaxhighlighter .color3, .syntaxhighlighter .color3 a {
   371         color: red !important;
   372       }
   373 
   374       .syntaxhighlighter .keyword {
   375         font-weight: bold !important;
   376       }
   377     </style>
   378     <script src="tools/syntaxhighlighter/js/shCore.js" type="text/javascript" class='remove'></script>
   379     <script src="tools/syntaxhighlighter/js/shAutoloader.js" type="text/javascript" class='remove'></script>
   380     <script src="tools/syntaxhighlighter/js/shBrushXml.js" type="text/javascript" class='remove'></script>
   381     <script src="tools/syntaxhighlighter/js/shBrushJScript.js" type="text/javascript" class='remove'></script>
   382 
   383     <script src='http://www.w3.org/Tools/respec/respec-w3c-common' type="text/javascript" class='remove' async></script>
   384     <style type="text/css">
   385       /* Custom CSS optimizations (Richard Tibbett) */
   386 
   387       /* Add better spacing to sections */
   388       section, .section { margin-bottom: 2em; }
   389 
   390       /* Reduce note & issue render size */
   391       .note, .issue { font-size:0.8em; }
   392 
   393       /* Add addition spacing to <ol> and <ul> for rule definition */
   394       ol.rule li, ul.rule li { padding:0.6em; }
   395 
   396       pre.widl { border: solid thin; background: #EEEEEE; color: black; padding: 0.5em 1em; position: relative; }
   397       pre.widl :link, pre.widl :visited { color: #000; background: transparent; }
   398       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 }
   399 
   400       div.example { border: solid thin red; background: #F7DFE5; color: black; padding: 0.5em 1em; position: relative; margin: 1em 0 1em 4.6em; width: auto; }
   401       div.example:before { content: "EXAMPLE"; font: bold small sans-serif; padding: 0.5em; background: red; color: white; position: absolute; top: 0; margin: -1px 0 0 -7.6em; width: 5em; border: thin solid red; border-radius: 0 0 0 0.5em }
   402 
   403       dl.domintro { color: green; margin: 2em 0 2em 2em; padding: 0.5em 1em; border: none; background: #DDFFDD; }
   404       hr + dl.domintro, div.impl + dl.domintro { margin-top: 2.5em; margin-bottom: 1.5em; }
   405       dl.domintro dt, dl.domintro dt * { color: black; text-decoration: none; }
   406       dl.domintro dd { margin: 0.5em 0 1em 2em; padding: 0; }
   407       dl.domintro dd p { margin: 0.5em 0; }
   408       dl.domintro code {font-size: inherit; font-style: italic; }
   409       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; }
   410     </style>
   411   </head>
   412 
   413   <body>
   414     <section id='abstract'>
   415       <p>
   416         This specification defines a mechanism for an HTML document to discover and subsequently communicate with <acronym title="Hypertext Transfer Protocol">HTTP</acronym>-based services
   417         advertised via common discovery protocols within a user's network.
   418       </p>
   419     </section>
   420 
   421     <section id='sotd'>
   422       <p>
   423         This document represents the early consensus of the group on the scope and features of the proposed
   424         API.
   425       </p>
   426     </section>
   427 
   428     <section class="informative">
   429       <h3>Introduction</h3>
   430 
   431       <p>To enable Web pages to connect and communicate with Local-networked Services provided over HTTP, this specification introduces the
   432       <a href="#navigatornetworkservice"><code>NavigatorNetworkService</code></a> interface.</p>
   433 
   434       <p>
   435          Using this <acronym title="Application Programming Interface">API</acronym> consists of requesting a well-known service type, known by developers and advertised by Local-networked Devices. User authorization, where the user connects the web page to one or more discovered services,
   436          is expected before the web page is able to interact with any Local-networked Services.
   437       </p>
   438 
   439       <p>
   440          A web page creates a request to obtain connectivity to services running in the network by specifying a well-known discovery service type that it wishes to interact with.
   441       </p>
   442 
   443       <p>
   444          The user agent, having captured all advertised services on the network from the Service Discovery mechanisms included in this recommendation, attempts to match
   445       the requested service type to a discovered service according to the processing described herein.
   446       </p>
   447 
   448       <p>
   449           If a service connectivity request is successful then the Web page is provided with the necessary information to communicate with the authorized Local-networked Service.
   450           If the request fails then the Web page will receive an error callback containing an error code describing the cause of Local-networked Service connectivity failure.
   451       </p>
   452 
   453       <p>
   454          Once connected to a Local-networked Service the Web page can send requests and receive responses to the Local-networked Service via the messaging format and appropriate channel inferred from the service type
   455          authorized via the provided API.
   456          The Web page, once connected, can also receive service-pushed events, in the messaging format supported by the Local-networked Device, if such event subscription functionality is provided by the
   457          connected Local-networked Service.
   458       </p>
   459 
   460       <div class="example">
   461        <p>Example of requesting a DNS-SD advertised service:</p>
   462        <hr />
   463        <pre class="brush:js">function showServices( services ) {
   464   // Show a list of all the services provided to the web page
   465   for(var i = 0, l = services.length; i < l; i++) console.log( services[i].name );
   466 }
   467 
   468 navigator.getNetworkServices('zeroconf:_boxee-jsonrpc._tcp', showServices);</pre>
   469       </div>
   470 
   471       <div class="example">
   472         <p>Example of requesting a UPnP advertised service, also handling error conditions:</p>
   473         <hr />
   474         <pre class="brush:js">function showServices( services ) {
   475   // Show a list of all the services provided to the web page
   476   for(var i = 0, l = services.length; i < l; i++) console.log( services[i].name );
   477 }
   478 
   479 function error( e ) {
   480   console.log( "Error occurred: " + e.code );
   481 }
   482 
   483 navigator.getNetworkServices('upnp:urn:schemas-upnp-org:service:ContentDirectory:1', showServices, error);</pre>
   484       </div>
   485 
   486       <div class="example">
   487         <p>Example of requesting either a DNS-SD or UPnP advertised service:</p>
   488         <hr />
   489         <pre class="brush:js">function showServices( services ) {
   490   // Show a list of all the services provided to the web page (+ service type)
   491   for(var i = 0, l = services.length; i < l; i++)
   492      console.log( services[i].name + '(' + services[i].type + ')' );
   493 }
   494 
   495 navigator.getNetworkServices([
   496   'zeroconf:_boxee-jsonrpc._tcp',
   497   'upnp:urn:schemas-upnp-org:service:ContentDirectory:1'
   498 ], showServices);</pre>
   499       </div>
   500 
   501       <p>For more detailed examples see the <a href="#examples">Examples</a> section.
   502     </section>
   503 
   504     <section
   505      id='conformance'>
   506 
   507      <p>Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the
   508      meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.</p>
   509 
   510      <p>
   511       Some conformance requirements are phrased as requirements on attributes, methods or objects. Such requirements are to be interpreted as requirements on user agents.
   512      </p>
   513 
   514      <p>
   515       Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in
   516       this specification are intended to be easy to follow, and not intended to be performant.)
   517      </p>
   518 
   519      <p>
   520       The only conformance class defined by this specification is a <dfn>user agent</dfn>.
   521      </p>
   522 
   523      <p>
   524       User agents may impose implementation-specific limits on otherwise unconstrained inputs, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work
   525       around platform-specific limitations.
   526      </p>
   527 
   528      <p>
   529       When support for a feature is disabled (e.g. as an emergency measure to mitigate a security problem, or to aid in development, or for performance reasons), user agents must act as if
   530       they had no support for the feature whatsoever, and as if the feature was not mentioned in this specification. For example, if a particular feature is accessed via an attribute in a Web
   531       IDL interface, the attribute itself would be omitted from the objects that implement that interface - leaving the attribute on the object but making it return null or throw an exception
   532       is insufficient.
   533      </p>
   534 
   535       <section>
   536          <h3>Dependencies</h3>
   537 
   538          This specification relies on several other underlying specifications.
   539 
   540          <dl>
   541             <dt>HTML</dt>
   542             <dd>Many fundamental concepts from HTML are used by this specification. [[!HTML5]]</dd>
   543             <dt>WebIDL</dt>
   544             <dd>The IDL blocks in this specification use the semantics of the WebIDL specification. [[!WEBIDL]]</dd>
   545          </dl>
   546       </section>
   547     </section>
   548 
   549     <section>
   550       <h3>Terminology</h3>
   551 
   552       <p>
   553          The construction "a <code>Foo</code> object", where <code>Foo</code> is actually an interface, is sometimes used instead of the more accurate "an object implementing the interface <code>Foo</code>".
   554       </p>
   555 
   556       <p>
   557          The term DOM is used to refer to the API set made available to scripts in Web applications, and does not necessarily imply the existence of an actual <code>Document</code> object or of any
   558          other <code>Node</code> objects as defined in the DOM Core specifications. [[!DOM4]]
   559       </p>
   560 
   561       <p>
   562          An IDL attribute is said to be <em>getting</em> when its value is being retrieved (e.g. by author script), and is said to be <em>setting</em> when a new value is assigned to it.
   563       </p>
   564 
   565       <p>
   566         A <dfn>valid service type</dfn> is a string that begins with <code>upnp:</code> or <code>zeroconf:</code> followed by one or more characters in the ranges U+0021, U+0023 to U+0027, U+002A to U+002B, U+002D to U+002E, U+0030 to U+0039, U+0041 to U+005A, U+005E to U+007E.
   567       </p>
   568 
   569       <p>
   570         A <a>valid service type</a> provided in the <code>type</code> attribute of the <code>getNetworkServices()</code> method will be matched against the services currently contained in the <a>list of available service records</a> according to the algorithms defined in this specification.
   571       </p>
   572     </section>
   573 
   574     <section>
   575      <h2>Requesting networked services</h2>
   576 
   577 
   578 <pre class="widl">[Supplemental, NoInterfaceObject]
   579 interface <dfn id="navigatornetworkservice">NavigatorNetworkService</dfn> {
   580   // Obtain a Local-networked Service
   581   void <a href="#dom-navigator-getnetworkservices">getNetworkServices</a>( in any type,
   582                            in <a href="#navigatornetworkservicesuccesscallback">NavigatorNetworkServiceSuccessCallback</a> successCallback,
   583                            in optional <a href="#navigatornetworkserviceerrorcallback">NavigatorNetworkServiceErrorCallback</a> errorCallback );
   584 };
   585 <a class="externalDFN" href="http://www.whatwg.org/specs/web-apps/current-work/complete/timers.html#navigator">Navigator</a> implements <a href="#navigatornetworkservice">NavigatorNetworkService</a>;
   586 
   587 [Callback=FunctionOnly, NoInterfaceObject]
   588 interface <dfn id="navigatornetworkservicesuccesscallback">NavigatorNetworkServiceSuccessCallback</dfn> {
   589   void handleEvent( in <a href="#networkservices">NetworkServices</a> services );
   590 };
   591 
   592 [NoInterfaceObject]
   593 interface <dfn id="navigatornetworkserviceerror">NavigatorNetworkServiceError</dfn> {
   594   const unsigned short <a href="#dom-navigatornetworkserviceerror-permission_denied">PERMISSION_DENIED_ERR</a> = 1;
   595   const unsigned short <a href="#dom-navigatornetworkserviceerror-unknown_type_prefix">UNKNOWN_TYPE_PREFIX_ERR</a> = 2;
   596   readonly attribute unsigned short <a href="#dom-navigatornetworkserviceerror-code">code</a>;
   597 };
   598 
   599 [Callback=FunctionOnly, NoInterfaceObject]
   600 interface <dfn id="navigatornetworkserviceerrorcallback">NavigatorNetworkServiceErrorCallback</dfn> {
   601   void handleEvent( in <a href="#navigatornetworkserviceerror">NavigatorNetworkServiceError</a> error );
   602 };
   603 </pre>
   604 
   605   <section>
   606    <h2>Methods</h2>
   607 
   608       <dl class="domintro">
   609         <dt>
   610           <var title="">window</var>
   611            .
   612           <code title="dom-navigator">
   613             <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/timers.html#navigator">navigator</a>
   614           </code>
   615            .
   616           <code title="dom-navigator-getNetworkServices">
   617             <a href="#dom-navigator-getnetworkservices">getNetworkServices</a>
   618           </code>
   619           (
   620           <var title="">type</var>
   621           ,
   622           <var title="">successCallback</var>
   623            [,
   624           <var title="">errorCallback</var>
   625            ] )
   626         </dt>
   627         <dd>
   628           <p>Prompts the user to select one or more discovered network services that have advertised support for the requested service type.</p>
   629           <p>
   630             The
   631             <var title="">type</var>
   632              argument contains one or more <a>valid service type</a> tokens that the web page would like to interact with.
   633           </p>
   634           <p>
   635             If the user accepts, the
   636             <var title="">successCallback</var>
   637              is
   638           invoked, with one or more
   639             <code>
   640               <a href="#networkservice"><code>NetworkService</code></a>
   641             </code>
   642              objects as
   643           its argument.
   644           </p>
   645           <p>
   646             If the user declines, the
   647             <var title="">errorCallback</var>
   648              (if
   649           any) is invoked.
   650           </p>
   651         </dd>
   652       </dl>
   653 
   654        <div>
   655           <p>
   656             When the <dfn id="dom-navigator-getnetworkservices" title="dom-navigator-getnetworkservices"><code>getNetworkServices(type, successCallback[, errorCallback])</code></dfn> method is called, the <a>user agent</a> MUST run the following steps:
   657           </p>
   658 
   659           <ol class="rule">
   660             <li>
   661                If <var>successCallback</var> is empty or is not an object of type <code>Function</code> then the <a>user agent</a> MUST abort these steps.
   662             </li>
   663 
   664             <li>
   665               Let <var>requested control types</var> be initially set to an empty array.
   666             </li>
   667 
   668             <li>
   669                If <var>type</var> is an array consisting of one or more <a>valid service type</a> tokens, then let <var>requested control types</var> by the value of <var>type</var>, removing any non-<a>valid service type</a> tokens from the resulting array.
   670             </li>
   671 
   672             <li>
   673                If <var>type</var> is a string consisting of one <a>valid service type</a> token, then let <var>requested control types</var> be an array containing one item with a value of <var>type</var>.
   674             </li>
   675 
   676             <li>
   677                If <var>requested control types</var> is an array that contains at least one or more <a title="valid service type">valid service type</a> tokens then continue to the step labeled <em>process</em> below. Otherwise, the <a>user agent</a> MUST <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an object of type <code>Function</code>, with a new <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose
   678                  <a href="#dom-navigatornetworkserviceerror-code"><code>code</code></a> attribute has the numeric value 2
   679                   (<a href="#dom-navigatornetworkserviceerror-unknown_type_prefix"><code>UNKNOWN_TYPE_PREFIX_ERR</code></a>) as its argument,
   680                    abort any remaining steps and return.
   681             </li>
   682 
   683             <li>
   684                <em>Process</em>: Let <var>services found</var> be an empty array.
   685             </li>
   686 
   687             <li>
   688                For each <var>available service</var> in the <a>list of available service records</a> run the following steps:
   689                <ol class="rule">
   690                   <li>
   691                     For each <var>requested control type</var> in <var>requested control types</var>: If <var>available service</var>'s <code>type</code> attribute equals the <var>requested control type</var> then let <var>matched service</var> equal the value of <var>available service</var> and continue at the step labeled <var>attach</var> below.
   692                   </li>
   693                   <li>
   694                      Continue at the next <var>available service</var>.
   695                   </li>
   696                   <li>
   697                      <em>Attach</em>: If <var>matched service</var> is not empty then run the following steps:
   698 
   699                      <ol class="rule">
   700                         <li>
   701                            Let <var>new service object</var> be a new <a href="#networkservice"><code>NetworkService</code></a> object, mapping the parameters of
   702                      <var>matched service</var> to this new object where possible.
   703                         </li>
   704                         <li>
   705                            Append <var>new service object</var> to the <var>services found</var> array.
   706                         </li>
   707                      </ol>
   708                   </li>
   709                </ol>
   710             </li>
   711 
   712             <li>
   713                If <var>services found</var> is an empty array, then the <a>user agent</a> MUST <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an object of type <code>Function</code>, with a new <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose
   714                  <a href="#dom-navigatornetworkserviceerror-code"><code>code</code></a> attribute has the numeric value 1
   715                  (<a href="#dom-navigatornetworkserviceerror-permission_denied"><code>PERMISSION_DENIED_ERR</code></a>) as its argument, abort any remaining steps and return.
   716             </li>
   717 
   718             <li>
   719                Return, and run the remaining steps asynchronously.
   720             </li>
   721 
   722             <li>
   723                Optionally, e.g. based on a previously-established user preference, for security reasons, or due to platform limitations, the <a>user agent</a> MAY <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an object of type <code>Function</code>, with a new <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose
   724                  <a href="#dom-navigatornetworkserviceerror-code"><code>code</code></a> attribute has the numeric value 1
   725                  (<a href="#dom-navigatornetworkserviceerror-permission_denied"><code>PERMISSION_DENIED_ERR</code></a>) as its argument, abort any remaining steps and return.
   726             </li>
   727 
   728             <li>
   729                   The <a>user agent</a> MUST prompt the user in a user-agent-specific manner for permission to provide the
   730                   <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/browsers.html#entry-script" class="externalDFN">entry script</a>'s
   731                   <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/origin-0.html#origin" class="externalDFN">origin</a> with an array of
   732                   <a href="#networkservice"><code>NetworkService</code></a> objects representing the user-authorized subset of <var>services found</var>.
   733 
   734                <p>
   735                   If the user grants permission to access one or more networked services then the <a>user agent</a> SHOULD include an
   736                   "ongoing local-network communication" indicator.
   737                </p>
   738 
   739                <p>If the user denies permission, then the <a>user agent</a> MUST <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an object of type <code>Function</code>, with a new <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose
   740                 <a href="#dom-navigatornetworkserviceerror-code"><code>code</code></a> attribute has the numeric value 1
   741                 (<a href="#dom-navigatornetworkserviceerror-permission_denied"><code>PERMISSION_DENIED_ERR</code></a>) as its argument, abort any remaining steps and return.
   742               </p>
   743 
   744               <p>
   745                 If the user never responds, this algorithm stalls on this step.
   746               </p>
   747 
   748             </li>
   749 
   750             <li>
   751                Let <var>services</var> be the array of one or more <a href="#networkservice"><code>NetworkService</code></a> objects for which the user granted permission.
   752             </li>
   753 
   754             <li>
   755                For each Object <var>service</var> in <var>services</var>, run the following substeps:
   756 
   757                <ol class="rule">
   758                   <li>
   759                      Add the <var>service</var>'s <code>url</code> parameter to the <a>entry script origin's <acronym title="Uniform Resource Locator">URL</acronym> whitelist</a>.
   760                   </li>
   761                   <li>
   762                     If <var>service</var> was originally created from a UPnP discovery process and the <var>service</var>'s <code>eventsUrl</code> parameter is not empty then <a>setup a UPnP Events Subscription</a> for <var>service</var>.
   763                   </li>
   764                </ol>
   765             </li>
   766 
   767             <li>
   768                Let <var>services manager</var> be a new <a href="#networkservices"><code>NetworkServices</code></a> object.
   769             </li>
   770 
   771             <li>
   772                Set <var>services manager</var>'s <code>servicesAvailable</code> attribute to the length of <var>services</var>.
   773             </li>
   774 
   775             <li>
   776               Store the set of <var>services</var> as <dfn id="current_authorized_services">current authorized services</dfn> internally against the newly created <var>services manager</var> object.
   777             </li>
   778 
   779             <li>
   780                The <a>user agent</a> MUST <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>successCallback</var> with
   781                <var>services manager</var> as its argument.
   782             </li>
   783 
   784           </ol>
   785 
   786           <p>
   787             The <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#task-source" class="externalDFN">task source</a> for these
   788             <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#concept-task" class="externalDFN">tasks</a> is the
   789             <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#user-interaction-task-source" class="externalDFN">user interaction task source</a>.
   790           </p>
   791 
   792           <p>
   793             When a <a href="#networkservice"><code>NetworkService</code></a> object is provided to a Web page, the <a>user agent</a> MUST add the <code>url</code> property
   794              to the <dfn>entry script origin's URL whitelist</dfn>. This list enables the
   795             Web page to override and initiate cross-site resource requests towards these URLs, and any sub-resources of these URLs, within the current
   796             <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/browsers.html#entry-script" class="externalDFN">entry script</a>'s
   797             <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/origin-0.html#origin" class="externalDFN">origin</a> via various existing mechanisms (e.g. Web Sockets, Server-Sent Events,
   798             Web Messaging, XMLHttpRequest).
   799          </p>
   800 
   801          <p>
   802             If the user navigates away from the current browsing context, the <a>user agent</a> MUST remove all previously whitelisted urls from the <a>entry script origin's URL whitelist</a>.
   803             There is no persistence to network service selections provided to a web page. It is not possible to access a previously white-listed networked service without the necessary user authorization in all of the following cases:
   804             <ul>
   805               <li>If the current script is reloaded at any point in the same or different window.</li>
   806               <li>if the current script reinvokes the <a href="#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a> method at any point in its execution.</li>
   807               <li>If the user navigates forward or back in their history to reload the current page.</li>
   808               <li>If a script is running in a different origin.</li>
   809             </ul>
   810          </p>
   811 
   812       </div>
   813       </section>
   814 
   815       <section>
   816          <h3>Error Handling</h3>
   817 
   818       <dl class="domintro">
   819         <dt>
   820           <var title="">error</var>
   821            .
   822           <code title="dom-NavigatorNetworkServiceError-code">
   823             <a href="#dom-navigatornetworkserviceerror-code">code</a>
   824           </code>
   825         </dt>
   826         <dd>
   827           <p>
   828             Returns the current error's error code. At the current time, this may be <code>1</code> or <code>2</code>, for which the
   829             corresponding error constants
   830             <a href="#dom-navigatornetworkserviceerror-permission_denied"><code>PERMISSION_DENIED_ERR</code></a> and
   831             <a href="#dom-navigatornetworkserviceerror-unknown_type_prefix"><code>UNKNOWN_TYPE_PREFIX_ERR</code></a> are defined.
   832           </p>
   833         </dd>
   834       </dl>
   835 
   836          <p>
   837             The <dfn id="dom-navigatornetworkserviceerror-code" title="dom-navigatornetworkserviceerror-code"><code>code</code></dfn> attribute of a
   838             <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object MUST return the code for the error, which will be one of the following:
   839          </p>
   840 
   841          <dl>
   842             <dt>
   843                <dfn id="dom-navigatornetworkserviceerror-permission_denied" title="dom-navigatornetworkserviceerror-permission_denied"><code>PERMISSION_DENIED_ERR</code></dfn> (numeric value 1)
   844             </dt>
   845             <dd>
   846                The user denied the page permission to access any services.
   847             </dd>
   848             <dt>
   849                <dfn id="dom-navigatornetworkserviceerror-unknown_type_prefix" title="dom-navigatornetworkserviceerror-unknown_type_prefix"><code>UNKNOWN_TYPE_PREFIX_ERR</code></dfn> (numeric value 2)
   850             </dt>
   851             <dd>
   852                No <a>valid service type</a> tokens were provided in the method invocation.
   853             </dd>
   854          </dl>
   855 
   856       </section>
   857 
   858       </section>
   859       <section>
   860       <h2>Obtaining networked services</h2>
   861 
   862       <p>
   863          The <a href="#networkservices"><code>NetworkServices</code></a> interface is the top-level response object from a call to <a href="#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a> and provides access to a set of user-authorized <a href="#networkservice"><code>NetworkService</code></a> objects for the given request.
   864       </p>
   865 
   866 <pre class="widl">
   867 [NoInterfaceObject]
   868 interface <dfn id="networkservices">NetworkServices</dfn> {
   869   readonly attribute unsigned long    <a href="#dom-networkservices-length">length</a>;
   870   getter <a href="#networkservice">NetworkService</a> (unsigned long index);
   871   <a href="#networkservice">NetworkService</a>? <a href="#dom-networkservices-getservicebyid">getServiceById</a>(DOMString id);
   872 
   873   readonly attribute unsigned long    <a href="#dom-networkservices-servicesavailable">servicesAvailable</a>;
   874 
   875   // event handler attributes
   876            attribute <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler" class="externalDFN">EventHandler</a>     <a href="#dom-networkservices-onserviceavailable">onserviceavailable</a>;
   877            attribute <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler" class="externalDFN">EventHandler</a>     <a href="#dom-networkservices-onserviceunavailable">onserviceunavailable</a>;
   878 
   879 };
   880 
   881 <a href="#networkservices">NetworkServices</a> implements <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#interface-eventtarget" class="externalDFN">EventTarget</a>;
   882 </pre>
   883 
   884       <section>
   885       <h2>Attributes</h2>
   886 
   887         <dl class="domintro">
   888           <dt>
   889             <code title="dom-networkservices-length">
   890               <a href="#dom-networkservices-length">length</a>
   891             </code>
   892           </dt>
   893           <dd>
   894             <p>
   895               Returns the current number of services in the respective object's <a>current authorized services</a>.
   896             </p>
   897           </dd>
   898           <dt>
   899             <code title="dom-networkservices-servicesavailable">
   900               <a href="#dom-networkservices-servicesavailable">servicesAvailable</a>
   901             </code>
   902           </dt>
   903           <dd>
   904             <p>
   905               Returns the current number of services matching one of the app-requested <a>valid service type</a> tokens that are actively available within the user's current network.
   906             </p>
   907           </dd>
   908         </dl>
   909 
   910         <div>
   911            <p>
   912               The <dfn id="dom-networkservices-length"><code>length</code></dfn> attribute MUST return the number of services represented in the object's corresponding <a>current authorized services</a> list at the time of getting.
   913            </p>
   914 
   915            <p>
   916               The <dfn id="dom-networkservices-servicesavailable"><code>servicesAvailable</code></dfn> attribute MUST return the number of services available in the
   917               user's network that match the <a>valid service type</a> that was initially used to create the current <a href="#networkservices"><code>NetworkServices</code></a> object.
   918               By default, <a href="#dom-networkservices-servicesavailable"><code>servicesAvailable</code></a> MUST be set to <code>1</code>.
   919            </p>
   920 
   921            <p>
   922              When a previously unknown instance of a networked service matching one or the requested <a href="#dfn-valid-service-type">valid service types</a> becomes available on the user's current network, the <a>user agent</a> MUST fire a new simple
   923              event at the <a href="#dom-networkservices-onserviceavailable"><code>onserviceavailable</code></a> event handler.
   924            </p>
   925 
   926            <p>
   927              When a previously known instance of a networked service matching one or the requested <a href="#dfn-valid-service-type">valid service types</a> becomes unavailable on the user's current network, the <a>user agent</a> MUST fire a new simple
   928              event at the <a href="#dom-networkservices-onserviceunavailable"><code>onserviceunavailable</code></a> event handler.
   929            </p>
   930         </div>
   931 
   932       </section>
   933 
   934       <section>
   935       <h2>Methods</h2>
   936         <dl class="domintro">
   937         <dt>
   938           <code title="networkservices-getter">
   939             <a href="#networkservices">services</a>
   940           </code>
   941           [
   942           <var title="">index</var>
   943           ]
   944         </dt>
   945         <dd>
   946           <p>
   947             Returns the specified <a href="#networkservice"><code>NetworkService</code></a> object.
   948           </p>
   949         </dd>
   950         <dt>
   951           <code title="networkservices-getter">
   952             <a href="#networkservices">services</a>
   953           </code>
   954           .
   955           <code title="dom-networkservices-getservicebyid">
   956             <a href="#dom-networkservices-getservicebyid">getServiceById</a>
   957           </code>
   958           (
   959           <var title="">id</var>
   960           )
   961         </dt>
   962         <dd>
   963           <p>
   964             Returns the <a href="#networkservice"><code>NetworkService</code></a> object with the given identifier, or null if no
   965             service has that identifier.
   966           </p>
   967         </dd>
   968       </dl>
   969 
   970       <p>
   971         A <a href="#networkservices"><code>NetworkServices</code></a> object represents the current list of zero or more <a>current authorized services</a>, of which zero or more can be available at a time. Each item in <a>current authorized services</a> is represented by a <a href="#networkservice"><code>NetworkService</code></a> object.
   972       </p>
   973 
   974       <p class="note">
   975         Each service in a <a href="#networkservices"><code>NetworkServices</code></a> object thus has an index; the first has the index 0, and each subsequent service is numbered one higher than the previous one. If the <a>user agent</a> dynamically adds or removes network services for any reason, then the indices of the services in <a>current authorized services</a> will change dynamically. If the set of network services changes entirely, then all the previous services will be removed from <a>current authorized services</a> and replaced with new services.
   976       </p>
   977 
   978       <p>
   979         The <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#supported-property-indices" class="externalDFN">supported property indices</a> of <a href="#networkservices"><code>NetworkServices</code></a> objects at any instant are the numbers from zero to the number of items in <a>current authorized services</a> represented by the respective object minus one, if any services are represented in <a>current authorized services</a>. If a <a href="#networkservices"><code>NetworkServices</code></a> object represents no <a>current authorized services</a>, it has no <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#supported-property-indices" class="externalDFN">supported property indices</a>.
   980       </p>
   981 
   982       <p>
   983         To <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#determine-the-value-of-an-indexed-property" class="externalDFN">determine the value of an indexed property</a> for a given index <var>index</var> in a <a href="#networkservices"><code>NetworkServices</code></a> object's <a>current authorized services</a>, the user agent MUST return the <a href="#networkservice"><code>NetworkService</code></a> object that represents the <var>index</var>th service in <a>current authorized services</a>.
   984       </p>
   985 
   986       <p>
   987         The <dfn id="dom-networkservices-getservicebyid"><code>getServiceById(id)</code></dfn> method MUST return the first <a href="#networkservice"><code>NetworkService</code></a> object in <a>current authorized services</a> represented by the respective object whose <a href="#dom-networkservice-id"><code>id</code></a> attribute is equal to the value of the <var>id</var> argument.
   988         When no services in <a>current authorized services</a> match the given argument, the method MUST return null.
   989       </p>
   990 
   991       <p>
   992          Services available within the local network can connect and disconnect at different times during the execution of a web page. A <a>user agent</a> can
   993          inform a web page when the state of networked services matching the requested <a>valid service type</a> change. Web pages can use this information to enable in-page experiences for communicating the state of networked services
   994          with the ability to change the particular service or set of services the page is connected to by re-invoking the <a href="#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a> method.
   995       </p>
   996 
   997       </section>
   998 
   999       <section>
  1000       <h2>Events</h2>
  1001 
  1002       <p>
  1003          The following are the event handlers (and their corresponding event handler event types) that must be supported, as IDL attributes, by all objects implementing the <a href="#networkservices"><code>NetworkServices</code></a> interface:
  1004        </p>
  1005 
  1006        <table border="1">
  1007         <thead>
  1008           <tr>
  1009             <th>
  1010               <span title="event handlers">Event handler</span>
  1011             </th>
  1012             <th>
  1013               <span>Event handler event type</span>
  1014             </th>
  1015           </tr>
  1016         </thead>
  1017         <tbody>
  1018           <tr>
  1019             <td>
  1020               <dfn id="dom-networkservices-onserviceavailable" title="dom-NetworkServices-onserviceavailable">
  1021                 <code>onserviceavailable</code>
  1022               </dfn>
  1023             </td>
  1024             <td>
  1025               <code title="event-serviceavailable">serviceavailable</code>
  1026             </td>
  1027           </tr>
  1028           <tr>
  1029             <td>
  1030               <dfn id="dom-networkservices-onserviceunavailable" title="dom-NetworkServices-onserviceunavailable">
  1031                 <code>onserviceunavailable</code>
  1032               </dfn>
  1033             </td>
  1034             <td>
  1035               <code title="event-serviceunavailable">serviceunavailable</code>
  1036             </td>
  1037           </tr>
  1038         </tbody>
  1039       </table>
  1040 
  1041       <p>
  1042          Events with an event type of <code>serviceavailable</code> or <code>serviceunavailable</code> defined in this specification are simple <code>Event</code> objects.
  1043       </p>
  1044 
  1045       </section>
  1046 
  1047     </section>
  1048     <section>
  1049     <h2>Communicating with a networked service</h3>
  1050 
  1051 <p>
  1052    The <a href="#networkservice"><code>NetworkService</code></a> interface is used to provide a set of connection information for an HTTP service endpoint and if available, service events, running on a networked device.
  1053 </p>
  1054 
  1055 <pre class="widl">
  1056 [NoInterfaceObject]
  1057 interface <dfn id="networkservice">NetworkService</dfn> {
  1058   readonly attribute DOMString        <a href="#dom-networkservice-id">id</a>;
  1059   readonly attribute DOMString        <a href="#dom-networkservice-name">name</a>;
  1060   readonly attribute DOMString        <a href="#dom-networkservice-type">type</a>;
  1061   readonly attribute DOMString        <a href="#dom-networkservice-url">url</a>;
  1062   readonly attribute DOMString        <a href="#dom-networkservice-config">config</a>;
  1063 
  1064   const unsigned short <a href="#dom-networkservice-AVAILABLE">AVAILABLE</a>      = 1;
  1065   const unsigned short <a href="#dom-networkservice-UNAVAILABLE">UNAVAILABLE</a>    = 2;
  1066   readonly attribute unsigned short   <a href="#dom-networkservice-readystate">readyState</a>;
  1067 
  1068   // event handler attributes
  1069            attribute <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler" class="externalDFN">EventHandler</a>     <a href="#dom-networkservice-onreadystatechange">onreadystatechange</a>;
  1070            attribute <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler" class="externalDFN">EventHandler</a>     <a href="#dom-networkservice-onmessage">onmessage</a>;
  1071 };
  1072 
  1073 <a href="#networkservice">NetworkService</a> implements <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#interface-eventtarget" class="externalDFN">EventTarget</a>;
  1074 </pre>
  1075 
  1076 <section>
  1077   <h2>Attributes</h2>
  1078 
  1079       <dl class="domintro">
  1080         <dt>
  1081           <var title="">service</var>
  1082            .
  1083           <code title="dom-networkservice-id">
  1084             <a href="#dom-networkservice-id">id</a>
  1085           </code>
  1086         </dt>
  1087         <dd>
  1088           <p>
  1089             A unique identifier for the given user-selected service instance.
  1090           </p>
  1091         </dd>
  1092         <dt>
  1093           <var title="">service</var>
  1094            .
  1095           <code title="dom-networkservice-name">
  1096             <a href="#dom-networkservice-name">name</a>
  1097           </code>
  1098         </dt>
  1099         <dd>
  1100           <p>
  1101             The name of the user-selected service.
  1102           </p>
  1103         </dd>
  1104         <dt>
  1105           <var title="">service</var>
  1106            .
  1107           <code title="dom-networkservice-type">
  1108             <a href="#dom-networkservice-type">type</a>
  1109           </code>
  1110         </dt>
  1111         <dd>
  1112           <p>
  1113             The <a>valid service type</a> token value of the user-selected service.
  1114           </p>
  1115         </dd>
  1116         <dt>
  1117           <var title="">service</var>
  1118            .
  1119           <code title="dom-networkservice-url">
  1120             <a href="#dom-networkservice-url">url</a>
  1121           </code>
  1122         </dt>
  1123         <dd>
  1124           <p>
  1125             The control URL endpoint (including any required port information) of the user-selected control service that has been added to the <a>entry script origin's URL whitelist</a>.
  1126           </p>
  1127         </dd>
  1128         <dt>
  1129           <var title="">service</var>
  1130            .
  1131           <code title="dom-networkservice-config">
  1132             <a href="#dom-networkservice-config">config</a>
  1133           </code>
  1134         </dt>
  1135         <dd>
  1136           <p>
  1137             The configuration information associated with the service depending on the requested service type.
  1138           </p>
  1139         </dd>
  1140       </dl>
  1141 
  1142           <p>
  1143             The <dfn id="dom-networkservice-id"><code>id</code></dfn> attribute is a unique identifier for the service. Two services provided at different times or on different objects MUST have the same <a href="#dom-networkservice-id"><code>id</code></a> value.
  1144          </p>
  1145 
  1146          <p>
  1147             The <dfn id="dom-networkservice-name"><code>name</code></dfn> attribute represents a human-readable title for the service.
  1148          </p>
  1149 
  1150          <p>
  1151              The <dfn id="dom-networkservice-type"><code>type</code></dfn> attribute reflects the value of the <a>valid service type</a> of the service.
  1152           </p>
  1153 
  1154          <p>
  1155             The <dfn id="dom-networkservice-url"><code>url</code></dfn> attribute is an <a href="http://www.w3.org/TR/html5/urls.html#absolute-url" class="externalDFN">absolute URL</a> pointing to the root HTTP
  1156             endpoint for the service that has been added to the <a>entry script origin's URL whitelist</a>. Web pages can subsequently use this value for implicit cross-document messaging via various existing mechanisms (e.g. Web Sockets, Server-Sent Events, Web Messaging, XMLHttpRequest).
  1157          </p>
  1158 
  1159          <p>
  1160             The <dfn id="dom-networkservice-config"><code>config</code></dfn> attribute provides the raw configuration information extracted from the given network service.
  1161          </p>
  1162 
  1163       </section>
  1164 
  1165       <section>
  1166          <h3>States</h3>
  1167 
  1168       <dl class="domintro">
  1169         <dt>
  1170           <var title="">service</var>
  1171            .
  1172           <code title="dom-networkservice-readystate">
  1173             <a href="#dom-networkservice-readystate">readyState</a>
  1174           </code>
  1175         </dt>
  1176         <dd>
  1177           <p>
  1178             Returns the current state.
  1179           </p>
  1180         </dd>
  1181       </dl>
  1182 
  1183          A <a href="#networkservice"><code>NetworkService</code></a> object can be in several states. The <dfn id="dom-networkservice-readystate"><code>readyState</code></dfn> attribute MUST return the current state of the networked service,
  1184          which MUST be one of the following values:
  1185 
  1186          <dl>
  1187            <dt>
  1188              <dfn id="dom-networkservice-AVAILABLE" title="dom-networkservice-AVAILABLE">
  1189                <code>AVAILABLE</code>
  1190              </dfn>
  1191               (numeric value
  1192              1)
  1193 
  1194 
  1195            </dt>
  1196            <dd>
  1197              <p>The object is connected to its service endpoint.
  1198 
  1199             </p>
  1200            </dd>
  1201            <dt>
  1202              <dfn id="dom-networkservice-UNAVAILABLE" title="dom-networkservice-UNAVAILABLE">
  1203                <code>UNAVAILABLE</code>
  1204              </dfn>
  1205               (numeric value
  1206              2)
  1207            </dt>
  1208            <dd>
  1209              <p>The object is not connected to its service endpoint.
  1210             </p>
  1211            </dd>
  1212          </dl>
  1213 
  1214       </section>
  1215 
  1216       <section>
  1217          <h3>Events</h3>
  1218 
  1219       <p>
  1220          The following are the event handlers (and their corresponding event handler event types) that must be supported, as IDL attributes, by all objects implementing the
  1221          <a href="#networkservice"><code>NetworkService</code></a> interface:
  1222        </p>
  1223 
  1224        <table border="1">
  1225         <thead>
  1226           <tr>
  1227             <th>
  1228               <span title="event handlers">Event handler</span>
  1229             </th>
  1230             <th>
  1231               <span>Event handler event type</span>
  1232             </th>
  1233           </tr>
  1234         </thead>
  1235         <tbody>
  1236           <tr>
  1237             <td>
  1238               <dfn id="dom-networkservice-onmessage" title="dom-NetworkService-onmessage">
  1239                 <code>onmessage</code>
  1240               </dfn>
  1241             </td>
  1242             <td>
  1243               <code title="event-message">message</code>
  1244             </td>
  1245           </tr>
  1246           <tr>
  1247             <td>
  1248               <dfn id="dom-networkservice-onreadystatechange" title="dom-NetworkService-onreadystatechange">
  1249                 <code>onreadystatechange</code>
  1250               </dfn>
  1251             </td>
  1252             <td>
  1253               <code title="event-onreadystatechange">readystatechange</code>
  1254             </td>
  1255           </tr>
  1256         </tbody>
  1257       </table>
  1258 
  1259       <p>
  1260          Events with an event type of <code>message</code> defined in this specification are <a href="http://dev.w3.org/html5/postmsg/#messageevent" class="externalDFN"><code>MessageEvent</code></a> objects as defined in [[!POSTMSG]].
  1261       </p>
  1262 
  1263       <p>
  1264          Events with an event type of <code>readystatechange</code> defined in this specification are simple <code>Event</code> objects.
  1265       </p>
  1266 
  1267       </section>
  1268    </section>
  1269 
  1270       <section>
  1271             <h2>Service Discovery</h2>
  1272 
  1273       <p>
  1274          A <a>user agent</a> conforming to this specification MAY implement <acronym title="Simple Service Discovery Protocol">SSDP</acronym> [[!UPNP-DEVICEARCH11]] and Zeroconf [[!ZEROCONF]] service discovery mechanisms
  1275          to enable Web pages to request and connect with HTTP services running on networked devices, discovered via either mechanism, through this API. When a <a>user agent</a> implements either of these service discovery mechanisms, then it MUST conform to the corresponding algorithms provided in this section of the specification.
  1276       </p>
  1277       <p>
  1278          This section presents how the results of these two service discovery
  1279          mechanisms will be matched to requested service types and how their properties will be applied to any resulting <a href="#networkservice"><code>NetworkService</code></a> objects.
  1280       </p>
  1281 
  1282       <p>
  1283          It is expected that user agents will perform these service discovery mechansisms asynchronously and periodically update the <a>list of networked devices</a> as required. The timing of any
  1284          service discovery mechanisms is an implementation detail left to the discretion of the implementer (e.g. once on user agent start-up, every X seconds during user agent execution or on
  1285          invocation of this API from a Web page).
  1286       </p>
  1287 
  1288       <p>
  1289          The <dfn>list of available service records</dfn> is a single dynamic internal lookup table within user agents that is used to track the current services available in the network at any given time.
  1290          At any point during the running of either of the two service discovery mechanisms then existing entries within this table can be updated, entries can be added and entries can be removed as the status of networked
  1291          services changes. Each record contained within this table contains the attributes: <code>id</code>, <code>name</code>, <code>type</code>, <code>url</code> and <code>config</code>.
  1292       </p>
  1293 
  1294             <section>
  1295          <h4>Zeroconf (<acronym title="Multicast DNS">mDNS</acronym> + <acronym title="Domain Name System">DNS</acronym>-<acronym title="Service Discovery">SD</acronym>)</h4>
  1296 
  1297          <p>
  1298             For each DNS response received from a user-agent-initiated Multicast DNS Browse for <acronym title="DNS Pointer Record">PTR</acronym> records with the name <code>_services._dns-sd._udp</code> on the resolved recommended automatic browsing
  1299    domain [[!MDNS]], the <a>user agent</a> MUST run the following steps:
  1300          </p>
  1301 
  1302          <ol class="rule">
  1303 
  1304             <li>Let <var>service mDNS responses</var> be an array of PTR records received by issuing a Multicast DNS Browse for PTR records with the name of the current discovered service type.</li>
  1305 
  1306             <li>For each Object <var>service mDNS response</var> in <var>service mDNS responses</var>, run the following steps:
  1307                <ol>
  1308 
  1309                   <li>
  1310                      Let <var>network service record</var> be an Object consisting of the following empty properties: <code>id</code>, <code>name</code>, <code>type</code>, <code>url</code>, <code>config</code>.
  1311                   </li>
  1312 
  1313                   <li>
  1314                      Set <var>network service record</var>'s <code>id</code> property to the value of the full PTR Service Instance Name [[!MDNS]].
  1315                   </li>
  1316 
  1317                   <li>
  1318                      Set <var>network service record</var>'s <code>name</code> property to the value of the PTR Service Instance Name's <var>Instance</var> component [[!MDNS]].
  1319                   </li>
  1320 
  1321                   <li>
  1322                      Set <var>network service record</var>'s <code>type</code> property to the concatenation of the string <code>zeroconf:</code> followed by the value of the PTR Service Instance Name's <var>Service</var> component [[!MDNS]].
  1323                   </li>
  1324 
  1325                   <li>
  1326                      Set <var>network service record</var>'s <code>url</code> property to the resolvable Service URL obtained from performing an DNS-SD Lookup [[!DNS-SD]] of the current service from the PTR record provided [[!MDNS]].
  1327                   </li>
  1328 
  1329                   <li>
  1330                      Set <var>network service record</var>'s <code>config</code> property to the string value of the contents of the first DNS-SD TXT record associated with the <var>service mDNS response</var> as defined in [[!DNS-SD]].
  1331                   </li>
  1332 
  1333                   <li>
  1334                      For each Object <var>existing service record</var> in the current <a>list of available service records</a>, run the following sub-steps:
  1335                      <ol class="rule">
  1336 
  1337                        <li>
  1338                         If the <var>existing service record</var>'s <code>id</code> property matches the value of the <var>network service record</var>'s <code>id</code>, then set the
  1339                         value of <var>existing service record</var> in the current <a>list of available service records</a>  to the value of the
  1340                         <var>network service record</var> and skip the next step.
  1341                        </li>
  1342                      </ol>
  1343                   </li>
  1344 
  1345                   <li>
  1346                      Add <var>network service record</var> to the <a>list of available service records</a>.
  1347                   </li>
  1348 
  1349                   <li>
  1350                      For each non-garbage collected <a href="#networkservice"><code>NetworkService</code></a> object run the following steps:
  1351 
  1352                      <ol class="rule">
  1353                         <li>
  1354                            If the <a href="#networkservice"><code>NetworkService</code></a> object's <code>type</code> attribute does not equal the
  1355                            current <a>network service record</a>'s <code>type</code> property then continue at the next available active
  1356                            <a href="#networkservice"><code>NetworkService</code></a> object.
  1357                         </li>
  1358                         <li>
  1359                            Increment the <code>servicesAvailable</code> attribute of the <a href="#networkservices"><code>NetworkServices</code></a> object by <code>1</code>.
  1360                         </li>
  1361                      </ol>
  1362                   </li>
  1363             </ol>
  1364            </li>
  1365          </ol>
  1366 
  1367       </section>
  1368 
  1369       <section>
  1370          <h5>Universal Plug-and-Play (<acronym title="Universal Plug-and-Play">UPnP</acronym>)</h5>
  1371 
  1372          <p>
  1373             For each SSDP Presence Announcement [[!UPNP-DEVICEARCH11]] - a HTTP NOTIFY request - received from a user-agent-initiated SSDP Discovery Request [[!UPNP-DEVICEARCH11]], the <a>user agent</a> MUST run the following steps:
  1374          </p>
  1375 
  1376          <ol class="rule">
  1377             <li>
  1378                Let <var>ssdp device</var> be an Object with a property for each HTTP header received in the received SSDP Presence Announcement, with each key being the name of a HTTP header and its
  1379                value being that HTTP header's accompanying value.
  1380             </li>
  1381 
  1382             <li>
  1383                If <var>ssdp device</var> does not contain at least one <var>NTS</var>, <var>USN</var> and <var>Location</var> parameter, then the <a>user agent</a> MUST abort these steps.
  1384             </li>
  1385 
  1386             <li>
  1387                If the first occurrence of <var>NTS</var> has a value other than <code>ssdp:alive</code>, then continue to the step labeled <var>update service monitor</var> below.
  1388             </li>
  1389 
  1390             <li>
  1391                Let <var>root device descriptor file</var> contain the contents of the file located at the URL provided in the first occurrence of <var>Location</var> obtained according to the rules
  1392                defined in the section 'Retrieving a description using HTTP' [[!UPNP-DEVICEARCH11]].
  1393             </li>
  1394 
  1395             <li>
  1396                If <var>root device descriptor file</var> is empty, then the <a>user agent</a> MUST abort these steps.
  1397             </li>
  1398 
  1399             <li>
  1400                Let <var>advertised services</var> be a <a>list of all advertised services</a> obtained from the <var>root device descriptor file</var> containing all sub-nodes of the <code>serviceList</code> node as described in
  1401                the section 'Device Description' [[!UPNP-DEVICEARCH11]].
  1402             </li>
  1403 
  1404             <li>
  1405                For each Object <var>advertised service</var> in <var>advertised services</var> run the following steps:
  1406                <ol class="rule">
  1407 
  1408                   <li>
  1409                      Let <var>network service record</var> be an Object consisting of the following empty properties: <code>id</code>, <code>name</code>, <code>type</code>, <code>url</code>, <code>eventsUrl</code>, <code>config</code>.
  1410                   </li>
  1411 
  1412                   <li>
  1413                      Set <var>network service record</var>'s <code>id</code> property to the string value of the first occurrence of <var>ssdp device</var>'s <var>USN</var> parameter.
  1414                   </li>
  1415 
  1416                   <li>
  1417                      Set <var>network service record</var>'s <code>name</code> property to the string value of the first occurrence of the <var>service</var>'s <code>serviceId</code> property.
  1418                   </li>
  1419 
  1420                   <li>
  1421                      Set <var>network service record</var>'s <code>type</code> property to the concatenation of the string <code>upnp:</code> followed by the string value of the first occurrence of the <var>service</var>'s <code>serviceType</code> property.
  1422                   </li>
  1423 
  1424                   <li>
  1425                      Set <var>network service record</var>'s <code>url</code> property to the string value of the first occurrence of the <var>service</var>'s <code>controlURL</code> property.
  1426                   </li>
  1427 
  1428                   <li>
  1429                      Set <var>network service record</var>'s <code>config</code> property to the string value of the first occurrence of the <var>device</var> property.
  1430                   </li>
  1431 
  1432                   <li>
  1433                      If <var>service</var>'s <code>eventSubURL</code> property is empty, then continue to the step labeled <em>register</em> below.
  1434                   </li>
  1435 
  1436                   <li>
  1437                      Set <var>network service record</var>'s <code>eventsUrl</code> property to the string value of the first occurrence of the <var>service</var>'s <code>eventSubURL</code> property.
  1438                   </li>
  1439 
  1440                   <li>
  1441                      <em>Register</em>: For each Object <var>existing service record</var> in the current <a>list of available service records</a>, run the following sub-steps:
  1442                      <ol class="rule">
  1443 
  1444                        <li>
  1445                         If the <var>existing service record</var>'s <var>id</var> property matches the value of the first occurrence of <var>USN</var> and the
  1446                         <var>existing service record</var>'s <code>type</code> property matches the value of <var>network service record</var>'s <code>type</code>, then set the
  1447                         value of <var>existing service record</var> in the current <a>list of available service records</a>  to the value of the
  1448                         <var>network service record</var> and skip the next step.
  1449                        </li>
  1450                      </ol>
  1451                   </li>
  1452 
  1453                   <li>
  1454                      Add <var>network service record</var> to the <a>list of available service records</a>.
  1455                   </li>
  1456 
  1457                </ol>
  1458             </li>
  1459             <li>
  1460                <em>Update Service Monitor</em>: For each non-garbage collected <a href="#networkservice"><code>NetworkService</code></a> object run the following steps:
  1461 
  1462                <ol class="rule">
  1463                   <li>
  1464                      If this <a href="#networkservice"><code>NetworkService</code></a> object's <code>type</code> attribute does not equal the
  1465                      current <a>network service record</a>'s <code>type</code> property then continue at the next available active
  1466                      <a href="#networkservice"><code>NetworkService</code></a> object.
  1467                   </li>
  1468                   <li>
  1469                      If the <var>announcement type</var> equals <code>ssdp:alive</code> then Increment the <code>servicesAvailable</code> attribute of the <a href="#networkservices"><code>NetworkServices</code></a>
  1470                      object by <code>1</code>. Otherwise, decrement the <code>servicesAvailable</code> attribute of the <a href="#networkservices"><code>NetworkServices</code></a>
  1471                      object by <code>1</code>.
  1472                   </li>
  1473                </ol>
  1474             </li>
  1475          </ol>
  1476 
  1477          <p>
  1478             A <dfn>user-agent generated callback url</dfn> is a Local-network accessible URL endpoint that a <a>user agent</a> must generate and maintain for receiving HTTP NOTIFY requests from UPnP Event sources.
  1479          </p>
  1480 
  1481          <p>When the <a>user agent</a> is to <dfn>setup a UPnP Events Subscription</dfn>, it is to run the following steps with the current <var>network service record</var> object:</p>
  1482 
  1483          <ol class="rule">
  1484             <li>
  1485                If <var>network service record</var>'s <code>eventsUrl</code> property is empty then the <a>user agent</a> MUST abort these steps.
  1486             </li>
  1487 
  1488             <li>
  1489                Let <var>callback URL</var> be the value of creating a new <a>user-agent generated callback url</a>.
  1490             </li>
  1491 
  1492             <li>
  1493                Send a HTTP SUBSCRIBE request with a <em>NT</em> header with a string value of <code>upnp:event</code>, a <em>TIMEOUT</em> header with an integer value of
  1494                <code>86400</code> and a <em>CALLBACK</em> header
  1495                with a string value of <var>callback URL</var> towards the <var>network service record</var>'s <code>eventsUrl</code> property.
  1496             </li>
  1497 
  1498             <li>
  1499                If a non-200 OK response is received from the HTTP SUBSCRIBE request then the <a>user agent</a> MUST abort these steps.
  1500             </li>
  1501 
  1502             <li>
  1503                On receiving a valid 200 OK response, run the following steps:
  1504 
  1505                <ol class="rule">
  1506                   <li>
  1507                      Let <var>callback ID</var> equal the string value of the first included <em>SID</em> header, if it exists.
  1508                   </li>
  1509                   <li>
  1510                      Let <var>timeout date</var> equal the sum of the current UTC date value plus the integer value of the first included <em>TIMEOUT</em> header, if it exists.
  1511                   </li>
  1512                   <li>
  1513                      Run the following steps aynchronously and continue to the step labeled <em>listen</em> below.
  1514                   </li>
  1515                   <li>
  1516                      <em>Refresh Subscription</em>: Run the following steps at a set interval (X) within the <a>user agent</a>:
  1517 
  1518                      <ol class="rule">
  1519                         <li>
  1520                            Let <var>current date</var> equal the current UTC date.
  1521                         </li>
  1522                         <li>
  1523                            If <var>current date</var> is less than the <var>timeout date</var> then continue to the step labeled <em>refresh subscription</em> above.
  1524                         </li>
  1525                         <li>
  1526                            Send a HTTP SUBSCRIBE request with a <em>SID</em> header with the string value of <var>callback ID</var> and a <em>TIMEOUT</em> header
  1527                            with an integer value of <code>86400</code> towards the <var>network service record</var>'s <code>eventsUrl</code> property.
  1528                         </li>
  1529                         <li>
  1530                            On receiving a valid 200 OK, update <var>callback ID</var> with the string value of the first included <em>SID</em> header, if it exists. All other HTTP
  1531                            responses should cause the <a>user agent</a> to continue from the step labeled <em>refresh subscription</em> above.
  1532                         </li>
  1533                      </ol>
  1534 
  1535                   </li>
  1536 
  1537                   <li>
  1538                      <em>Listen</em>: For each HTTP NOTIFY request received at the <var>callback URL</var> the <a>user agent</a> is to run the following steps:
  1539 
  1540                      <ol class="rule">
  1541                         <li>
  1542                            Let <var>content clone</var> be the result of obtaining the message body of the HTTP NOTIFY request. If <var>content clone</var> is empty, then the <a>user agent</a> MUST abort these steps.
  1543                         </li>
  1544                         <li>
  1545                           Create a new <code>message</code> event that uses the <a href="http://dev.w3.org/html5/postmsg/#messageevent" class="externalDFN"><code>MessageEvent</code></a> interface [[!POSTMSG]], with the name <code>message</code>,
  1546                            which does not bubble, is not cancelable, and has no default action.
  1547                         </li>
  1548                         <li>
  1549                            Let the <code>data</code> attribute of the event have the DOMString value of <var>content clone</var>.
  1550                         </li>
  1551                         <li>
  1552                            <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">Queue a task</a> to
  1553                             dispatch the newly created event at the current <a><code>NetworkService</code></a> object.
  1554                         </li>
  1555                      </ol>
  1556                   </li>
  1557 
  1558                </ol>
  1559 
  1560             </li>
  1561          </ol>
  1562 
  1563          </section>
  1564 
  1565          <section>
  1566             <h3>Network Topology Monitoring</h3>
  1567 
  1568                   <div>
  1569                      <p>
  1570                         When the <a>user agent</a> detects that the user has dropped from their connected network, then it MUST run the following steps:
  1571                      </p>
  1572 
  1573                      <ol class="rule">
  1574                         <li>
  1575                            Flush all entries from the <a>list of available service records</a>.
  1576                         </li>
  1577                         <li>
  1578                            For each <a href="#networkservice"><code>NetworkService</code></a> object currently active in the <a>user agent</a> perform the following steps:
  1579 
  1580                            <ol class="rule">
  1581                               <li>
  1582                                  Set the <a href="#dom-networkservice-readystate"><code>readyState</code></a> attribute to <code>2</code> (<a href="#dom-networkservice-UNAVAILABLE"><code>UNAVAILABLE</code></a>).
  1583                               </li>
  1584                               <li>
  1585                                  Create a new <code>readystatechange</code> event that uses the <code>Event</code> interface which does not bubble, is not cancelable, and has no default action.
  1586                               </li>
  1587                               <li>
  1588                                  <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">Queue a task</a> to
  1589                                         dispatch the newly created event at the <a href="#networkservice"><code>NetworkService</code></a> object.
  1590                               </li>
  1591                            </ol>
  1592                         </li>
  1593                      </ol>
  1594 
  1595                      <p>
  1596                         When the <a>user agent</a> detects that the user has connected to a new network, then it SHOULD run the following steps:
  1597                      </p>
  1598 
  1599                      <ol class="rule">
  1600                         <li>
  1601                            Re-issue an mDNS search and SSDP discovery search and handle the responses according to the processing defined in <a href="#service-discovery">Section 6: Service Discovery</a>.
  1602                         </li>
  1603                      </ol>
  1604                   </div>
  1605          </section>
  1606       </section>
  1607 
  1608    <section>
  1609       <h3>Garbage collection</h3>
  1610 
  1611       <p>
  1612          A <a><code>NetworkService</code></a> object containing a <code>url</code> parameter currently in the <a>entry script origin's URL whitelist</a> MUST NOT be garbage collected.
  1613       </p>
  1614 
  1615       <p>
  1616          Only when the user navigates away from the current browsing context can <a><code>NetworkService</code></a> objects be garbage-collected and records in the <a>entry script origin's URL whitelist</a> be removed.
  1617       </p>
  1618 
  1619    </section>
  1620 
  1621 
  1622     <section>
  1623       <h3>Use Cases and Requirements</h3>
  1624 
  1625       <p>This section covers what the requirements are for this API, as well as illustrates some use cases.</p>
  1626 
  1627       <ul class="rule">
  1628          <li>
  1629             Once a user has given permission, user agents should provide the ability for Web pages to communicate directly with a Local-networked Service.
  1630             <ul class="rule">
  1631                <li>
  1632                   Example: A web-based TV remote control. A Web page wants to control the current user's TV, changing the programming shown or increasing/decreasing/muting the
  1633                   volume of the Local-networked Device. The Web page requests a service type that is known to be implemented by television sets to which it has the
  1634                   application logic to communicate. Local devices providing the request service types are discovered and presented to the user for authorization. The user selects one
  1635                   or more of the discovered television sets to be accessible to the current Web page and then clicks 'Share'. The Web page can now communicate directly with
  1636                   the user-authorized Local-networked services.
  1637                </li>
  1638             </ul>
  1639          </li>
  1640 
  1641          <li>
  1642            Web pages should be able to communicate with Local-networked Services using the messaging channel supported by those Devices.
  1643            <ul class="rule">
  1644             <li>
  1645                Example: A Web page advertises that it is capable of controlling multiple Home Media Servers. The user can select their Home Media Server type from a drop-down list, at which point the
  1646                Web page sends a request to the user agent to connect with the associated service type of the Home Media Server. The Media Server selected implements a Web Socket channel for
  1647                bi-directional service communication and so the Web page opens a web socket to the requested Media Server and can communicate as required via that appropriate channel.
  1648             </li>
  1649            </ul>
  1650          </li>
  1651 
  1652          <li>
  1653            Web pages should be able to communicate with Local-networked Services using the messaging format supported by those Devices.
  1654            <ul class="rule">
  1655             <li>
  1656                Example: A Web page advertises that it is capable of interacting with and controlling multiple types of Home Media Server. The user can select their Home Media Server type from a drop-down list or known Media Servers, at which point the
  1657                Web page sends a request to the user agent to connect with the associated service type (and, optionally, the associated event type) of the Home Media Server. The communiciation protocols supported by Home Media Servers typically vary
  1658                between UPnP, JSON-RPC, Protocol Buffers or other messaging formats depending on the Home Media Server requested. The Web page is able to communicate with the user-selected Home Media
  1659                Server in the messaging format supported by that Device, which, in this example is a simple key/value pair text format.
  1660             </li>
  1661            </ul>
  1662          </li>
  1663 
  1664          <li>
  1665            Web pages should not be able to communicate with Local-networked Services that have not been authorized by the user thereby maintaining the user's privacy.
  1666            <ul class="rule">
  1667             <li>
  1668                Example: A Web page requests access to one type of Local-networked service. The user authorizes access to that particular service. Other services running on that same device, and on other devices
  1669                within the network, should not be accessible to the current Web page.
  1670             </li>
  1671            </ul>
  1672          </li>
  1673 
  1674          <li>
  1675            A user should be able to share one or more Local-networked Services based on a particular service type request from a Web page.
  1676            <ul class="rule">
  1677             <li>
  1678                Example: A Web page is capable of interacting with a specific profile of Local-networked Service. As such, it makes a request to the user agent to access those services, of which multiple matches
  1679                are found. The user is capable of selecting one or more of the discovered services to share with the Web page. The Web page can then implement a drag-and-drop interface for the user to drag specific
  1680                actions on to one or more of the authorized Local-networked Services.
  1681             </li>
  1682            </ul>
  1683          </li>
  1684 
  1685          <li>
  1686            User agents should provide an API exposed to script that exposes the features above. The user is notified by UI anytime interaction with Local-networked Services is requested, giving the user
  1687            full ability to cancel or abort the transaction. The user selects the Local-networked Services to be connected to the current Web page, and can cancel these at any time. No invocations to
  1688            these APIs occur silently without user intervention.
  1689          </li>
  1690       </ul>
  1691     </section>
  1692 
  1693           <section class="informative appendix">
  1694              <h3>Examples</h3>
  1695 
  1696            <div class="example">
  1697             <p>This sample code exposes a button. When clicked, this button is disabled and the user is prompted to offer a network service. The user may also select multiple network services. When the user has authorized a network service to be connected to the web page then the web page issues a simple command to get a list of all the albums stored on the connected media player service.
  1698             <p>The button is re-enabled only when the connected network service disconnects for whatever reason (the service becomes unavailable on the network, the user disconnects from their current network or the user revokes access to the service from the current web page). At this point the user can re-click the button to select a new network service to connect to the web page and the above steps are repeated.</p>
  1699             <p>The provided service type identifier and service interaction used in this example is based on the well-defined service type and messaging format supported by the <a href="http://xbmc.org/about/">XBMC Media Server</a>. </p>
  1700             <hr />
  1701             <pre class="brush:js">&lt;input type="button" value="Start" onclick="start()" id="startBtn"/&gt;
  1702 &lt;div id="debugconsole">&lt;/div>
  1703 
  1704 &lt;script>
  1705  var startBtn = document.getElementById('startBtn'),
  1706      debug = document.getElementById('debugconsole');
  1707 
  1708  function start() {
  1709    if(navigator.getNetworkServices) {
  1710       navigator.getNetworkServices('zeroconf:_xbmc-jsonrpc._tcp', gotXBMCService, error);
  1711       startBtn.disabled = true;
  1712    } else {
  1713       debug.innerHTML += "&lt;br&gt;Service Discovery API not supported!";
  1714    }
  1715  }
  1716 
  1717  function gotXBMCService(services) {
  1718 
  1719 // Listen for service disconnect messages
  1720 
  1721    services[0].addEventListener('readystatechange', function ( e ) {
  1722      if(services[0].readyState === services[0].UNAVAILABLE) {
  1723        debug.innerHTML += "&lt;br>" + services[0].name + " disconnected.";
  1724        startBtn.disabled = false;
  1725      }
  1726    }, false);
  1727 
  1728 // Send a service message to get albums list (and process the service response)
  1729 
  1730    var svcXhr = new XMLHttpRequest();
  1731    svcXhr.open("POST", services[0].url + "/getAlbums"); // services[0].url and its subresources have been
  1732                                                         // whitelisted for cross-site XHR use in this
  1733                                                         // current browsing context.
  1734 
  1735    svcXhr.setRequestHeader('Content-Type', 'application/json-rpc');
  1736 
  1737    svcXhr.addEventListener('readystatechange', function ( response ) {
  1738      if( response.readyState != 4 || response.status != 200 )
  1739         return;
  1740      debug.innerHTML += "&lt;br>" + services[0].name + " response received: ";
  1741      debug.textContent += JSON.parse(response.responseText);
  1742    }, false);
  1743 
  1744    var svcMsg = [
  1745      { "jsonrpc": "2.0", "method": "AudioLibrary.GetAlbums", "params": { "genreid": -1,
  1746          "artistid": -1, "start": -1, "end": -1 }, "id": "1" }
  1747    ];
  1748 
  1749    svcXhr.send(JSON.stringify(svcMsg));
  1750    debug.innerHTML += "&lt;br>" + services[0].name + " request sent: ";
  1751    debug.textContent += JSON.stringify(svcMsg);
  1752 
  1753  }
  1754 
  1755  function error( err ) {
  1756    debug.innerHTML += "&lt;br>An error occurred obtaining a local network service.";
  1757    startBtn.disabled = false;
  1758  }
  1759 &lt;/script></pre>
  1760            </div>
  1761 
  1762            <div class="example">
  1763             <p>
  1764              This sample exposes a drop-down list containing a number of common Home-based audio devices. When the user selects an audio device from the list provided, they are prompted to authorize a network service
  1765              based on the service type requested. The user may also select multiple network services matching the selected service type.
  1766              In this example, the user selects their make as being <var>Sony</var> and their model as being <var>Bravia S1000</var> from which the Web page can derive a service type
  1767              (<var>urn:schemas-upnp-org:service:RenderingControl:1</var>).
  1768              <br /><br />Once the user has authorized the device, the web page sends a simple mute command according to the messaging format supported by the device.
  1769             </p>
  1770             <hr />
  1771             <pre class="brush:js">&lt;select name="make" id="make"&gt;
  1772   &lt;option selected="selected" disabled="disabled"&gt;Select make&lt;/option&gt;
  1773   &lt;option&gt;Sony&lt;/option&gt;
  1774   &lt;option&gt;Philips&lt;/option&gt;
  1775   &lt;option&gt;Alba&lt;/option&gt;
  1776 &lt;/select&gt;
  1777 &lt;select name="model" id="model"&gt;&lt;/select&gt;
  1778 &lt;div id="debugconsole"&gt;&lt;/div&gt;
  1779 
  1780 &lt;script&gt;
  1781   var debug = document.getElementById('debugconsole');
  1782 
  1783   var models = {
  1784     "Sony": [
  1785       {"name": "Bravia TV S1000", "type": "upnp", "service": "urn:schemas-upnp-org:service:RenderingControl:1" },
  1786       {"name": "Bravia TV S2000", "type": "zeroconf", "service": "_mediarenderer._http._tcp" },
  1787       {"name": "HiFi WD10", "type": "upnp", "service": "urn:schemas-upnp-org:service:RenderingControl:1" }
  1788     ],
  1789     "Philips": [ /* ... */ ],
  1790     "Alba": [ /* ... */ ]
  1791   };
  1792 
  1793   var makeEl = document.getElementById("make"),
  1794       modelEl = document.getElementById("model");
  1795 
  1796   makeEl.addEventListener('change', function() {
  1797     modelEl.innerHTML = ""; // reset
  1798     var defaultOption = document.createElement("option");
  1799     defaultOption.textContent = "Select model";
  1800     defaultOption.setAttribute("disabled", "disabled");
  1801     defaultOption.setAttribute("selected", "selected");
  1802     modelEl.appendChild(defaultOption);
  1803     for(var i = 0, l = models[makeEl.value].length; i < l; i++) {
  1804       var option = document.createElement("option");
  1805       option.textContent = models[makeEl.value][i]["name"];
  1806       option.setAttribute("value", models[makeEl.value][i]["type"] + ":" + models[makeEl.value][i]["service"]);
  1807       modelEl.appendChild(option);
  1808     }
  1809   }, false);
  1810 
  1811   modelEl.addEventListener('change', function() {
  1812     if(navigator.getNetworkServices &&
  1813          modelEl.value == "upnp:urn:schemas-upnp-org:service:RenderingControl:1") {
  1814       navigator.getNetworkServices(modelEl.value, successCallback, errorCallback);
  1815     } else if (modelEl.value == "zeroconf:_mediarenderer._http._tcp") {
  1816       debug.innerHTML += "&lt;br&gt;Service type is not implemented by this application.";
  1817     } else {
  1818       debug.innerHTML += "&lt;br&gt;Service Discovery is not supported!";
  1819     }
  1820   }, false);
  1821 &lt;/script&gt;
  1822 
  1823 &lt;script&gt;
  1824   function successCallback( services ) {
  1825 
  1826   // Listen for service push messages
  1827 
  1828     services[0].addEventListener('message', function ( msg ) {
  1829          debug.innerHTML += "&lt;br>" + services[0].name + " event received: ";
  1830          debug.textContent += msg.data;
  1831     }, false);
  1832 
  1833  // Send a control signal to mute the service audio
  1834 
  1835     var svcXhr = new XMLHttpRequest();
  1836     svcXhr.open("POST", services[0].url); // services[0].url and its
  1837                                           // subresources have been whitelisted for
  1838                                           // cross-site XHR use in this current
  1839                                           // browsing context.
  1840 
  1841     svcXhr.setRequestHeader('SOAPAction', 'urn:schemas-upnp-org:service:RenderingControl:1#SetMute');
  1842     svcXhr.setRequestHeader('Content-Type', 'text/xml; charset="utf-8";');
  1843 
  1844     svcXhr.onreadystatechange = function ( response ) {
  1845       if( response.readyState != 4 || response.status != 200 )
  1846         return;
  1847       debug.innerHTML += "&lt;br&gt;" + services[0].name + " response received: ";
  1848       debug.textContent += response.responseXML;
  1849     }
  1850 
  1851     // Service messaging to mute the provided service
  1852     var svcMsg = '&lt;?xml version="1.0" encoding="utf-8"?&gt;' +
  1853                  '&lt;s:Envelope s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" ' +
  1854                    'xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"&gt;' +
  1855                    '&lt;s:Body&gt;' +
  1856                      '&lt;u:SetMute xmlns:u="urn:schemas-upnp-org:service:RenderingControl:1"&gt;' +
  1857                        '&lt;InstanceID&gt;0&lt;/InstanceID&gt;' +
  1858                        '&lt;Channel&gt;Master&lt;/Channel&gt;' +
  1859                        '&lt;DesiredMute&gt;true&lt;/DesiredMute&gt;' +
  1860                      '&lt;/u:SetMute&gt;' +
  1861                    '&lt;/s:Body&gt;' +
  1862                  '&lt;/s:Envelope&gt;';
  1863 
  1864     svcXhr.send(svcMsg);
  1865     debug.innerHTML += "&lt;br&gt;" + services[0].name + " request sent: ";
  1866     debug.textContent += svcMsg;
  1867   }
  1868 
  1869   function errorCallback( error ) {
  1870     debug.innerHTML += "&lt;br&gt;An error occurred: " + error.code;
  1871   }
  1872 &lt;/script&gt;</pre>
  1873           </div>
  1874 
  1875        </section>
  1876 
  1877     <section>
  1878       <h3>Acknowledgements</h3>
  1879 
  1880       <p>Thanks are expressed by the editor to the following individuals for their feedback on this specification to date (in alphabetical order):
  1881       <br /><br />
  1882       Gar Bergstedt, Lars-Erik Bolstad, Hari G Kumar, Bob Lund, Giuseppe Pascale, Marcin Simonides, Clarke Stevens, Christian S&ouml;derstr&ouml;m, Mark Vickers, ...</p>
  1883 
  1884       <p>Thanks are also expressed by the editor to the following organizations and groups for their support in producing this specification to date (in alphabetical order):
  1885       <br /></br />
  1886       CableLabs, Opera Software ASA, W3C Device APIs Working Group, W3C Web and TV Interest Group, ...</p>
  1887     </section>
  1888 
  1889     <script class='remove'>
  1890     if(SyntaxHighlighter) {
  1891       SyntaxHighlighter.defaults['gutter'] = false;
  1892       SyntaxHighlighter.defaults['toolbar'] = false;
  1893       SyntaxHighlighter.all()
  1894     }
  1895     </script>
  1896 
  1897 </body>
  1898 </html>