discovery-api/Overview.html
author Rich Tibbett <richt@opera.com>
Tue, 18 Feb 2014 14:24:48 +0100
changeset 492 2f37e8af951a
parent 484 608edb43c84d
permissions -rw-r--r--
Update working version to latest respec build
richt@194
     1
<!DOCTYPE html>
richt@437
     2
<html lang="en"
richt@437
     3
      dir="ltr"
richt@437
     4
      typeof="bibo:Document"
richt@437
     5
      about=""
richt@437
     6
      property="dcterms:language"
richt@437
     7
      content="en">
richt@437
     8
  <head>
richt@239
     9
    <title>
richt@239
    10
      Network Service Discovery
richt@239
    11
    </title>
richt@437
    12
    <meta http-equiv="Content-Type"
richt@437
    13
          content="text/html; charset=utf-8">
richt@402
    14
    <style>
richt@437
    15
/* Custom ReSpec CSS (by Rich Tibbett) */
richt@180
    16
richt@402
    17
     /* Add better spacing to sections */
richt@402
    18
     section, .section { margin-bottom: 2em; }
richt@180
    19
richt@402
    20
     /* Add addition spacing to <ol> and <ul> for rule definition */
richt@402
    21
     ol.rule li, ul.rule li { padding:0.6em; }
richt@180
    22
richt@402
    23
     pre.widl { border: solid thin; background: #EEEEEE; color: black; padding: 0.5em 1em; position: relative; }
richt@402
    24
     pre.widl :link, pre.widl :visited { color: #000; background: transparent; }
richt@402
    25
     pre.widl:before { content: "IDL"; font: bold small sans-serif; padding: 0.5em; background: white; position: absolute; top: 0; margin: -1px 0 0 -4em; width: 1.5em; border: thin solid; border-radius: 0 0 0 0.5em }
richt@238
    26
richt@402
    27
     div.example { border: solid thin black; background: #FFFFF0; color: black; padding: 0.5em 1em; position: relative; margin: 1em 0 1em 4.6em; width: auto; }
richt@402
    28
     div.example:before { content: "EXAMPLE"; font: bold small sans-serif; padding: 0.5em; background: white; color: black; position: absolute; top: 0; margin: -1px 0 0 -7.6em; width: 5em; border: thin solid black; border-radius: 0 0 0 0.5em }
richt@180
    29
richt@402
    30
     dl.domintro { color: green; margin: 2em 0 2em 2em; padding: 0.5em 1em; border: none; background: #DDFFDD; }
richt@402
    31
     hr + dl.domintro, div.impl + dl.domintro { margin-top: 2.5em; margin-bottom: 1.5em; }
richt@402
    32
     dl.domintro dt, dl.domintro dt * { color: black; text-decoration: none; }
richt@402
    33
     dl.domintro dd { margin: 0.5em 0 1em 2em; padding: 0; }
richt@402
    34
     dl.domintro dd p { margin: 0.5em 0; }
richt@402
    35
     dl.domintro code {font-size: inherit; font-style: italic; }
richt@402
    36
     dl.domintro:before { display: table; margin: -1em -0.5em 0.5em auto; width: auto; content: 'This box is non-normative. Implementation requirements are given below this box.'; color: red; border: solid 2px; background: white; padding: 0 0.25em; font-size:0.8em; }
richt@402
    37
richt@402
    38
     table { border-collapse:collapse; border-style:hidden hidden none hidden }
richt@402
    39
     table thead { border-bottom:solid }
richt@402
    40
     table tbody th:first-child { border-left:solid }
richt@402
    41
     table td, table th { border-left:solid; border-right:solid; border-bottom:solid thin; vertical-align:top; padding:0.2em }
richt@437
    42
    </style>
richt@437
    43
    <style>
richt@437
    44
/*****************************************************************
richt@437
    45
    * ReSpec 3 CSS
richt@437
    46
    * Robin Berjon - http://berjon.com/
richt@437
    47
    *****************************************************************/
richt@402
    48
richt@437
    49
    /* --- INLINES --- */
richt@492
    50
    em.rfc2119 {
richt@180
    51
    text-transform:     lowercase;
richt@180
    52
    font-variant:       small-caps;
richt@180
    53
    font-style:         normal;
richt@180
    54
    color:              #900;
richt@437
    55
    }
richt@180
    56
richt@437
    57
    h1 acronym, h2 acronym, h3 acronym, h4 acronym, h5 acronym, h6 acronym, a acronym,
richt@437
    58
    h1 abbr, h2 abbr, h3 abbr, h4 abbr, h5 abbr, h6 abbr, a abbr {
richt@180
    59
    border: none;
richt@437
    60
    }
richt@180
    61
richt@437
    62
    dfn {
richt@180
    63
    font-weight:    bold;
richt@437
    64
    }
richt@180
    65
richt@437
    66
    a.internalDFN {
richt@180
    67
    color:  inherit;
richt@194
    68
    border-bottom:  1px solid #99c;
richt@180
    69
    text-decoration:    none;
richt@437
    70
    }
richt@180
    71
richt@437
    72
    a.externalDFN {
richt@180
    73
    color:  inherit;
richt@194
    74
    border-bottom:  1px dotted #ccc;
richt@180
    75
    text-decoration:    none;
richt@437
    76
    }
richt@180
    77
richt@437
    78
    a.bibref {
richt@180
    79
    text-decoration:    none;
richt@437
    80
    }
richt@180
    81
richt@437
    82
    cite .bibref {
richt@194
    83
    font-style: normal;
richt@437
    84
    }
richt@194
    85
richt@437
    86
    code {
richt@180
    87
    color:  #ff4500;
richt@437
    88
    }
richt@180
    89
richt@437
    90
    /* --- TOC --- */
richt@437
    91
    .toc a, .tof a {
richt@437
    92
    text-decoration:    none;
richt@437
    93
    }
richt@180
    94
richt@437
    95
    a .secno, a .figno {
richt@437
    96
    color:  #000;
richt@437
    97
    }
richt@180
    98
richt@437
    99
    ul.tof, ol.tof {
richt@437
   100
    list-style: none outside none;
richt@437
   101
    }
richt@180
   102
richt@437
   103
    .caption {
richt@194
   104
    margin-top: 0.5em;
richt@194
   105
    font-style:   italic;
richt@437
   106
    }
richt@180
   107
richt@437
   108
    /* --- TABLE --- */
richt@437
   109
    table.simple {
richt@180
   110
    border-spacing: 0;
richt@180
   111
    border-collapse:    collapse;
richt@180
   112
    border-bottom:  3px solid #005a9c;
richt@437
   113
    }
richt@180
   114
richt@437
   115
    .simple th {
richt@180
   116
    background: #005a9c;
richt@180
   117
    color:  #fff;
richt@180
   118
    padding:    3px 5px;
richt@180
   119
    text-align: left;
richt@437
   120
    }
richt@180
   121
richt@437
   122
    .simple th[scope="row"] {
richt@180
   123
    background: inherit;
richt@180
   124
    color:  inherit;
richt@180
   125
    border-top: 1px solid #ddd;
richt@437
   126
    }
richt@180
   127
richt@437
   128
    .simple td {
richt@180
   129
    padding:    3px 10px;
richt@180
   130
    border-top: 1px solid #ddd;
richt@437
   131
    }
richt@180
   132
richt@437
   133
    .simple tr:nth-child(even) {
richt@180
   134
    background: #f0f6ff;
richt@437
   135
    }
richt@180
   136
richt@437
   137
    /* --- DL --- */
richt@437
   138
    .section dd > p:first-child {
richt@180
   139
    margin-top: 0;
richt@437
   140
    }
richt@180
   141
richt@437
   142
    .section dd > p:last-child {
richt@180
   143
    margin-bottom: 0;
richt@437
   144
    }
richt@180
   145
richt@437
   146
    .section dd {
richt@180
   147
    margin-bottom:  1em;
richt@437
   148
    }
richt@180
   149
richt@437
   150
    .section dl.attrs dd, .section dl.eldef dd {
richt@180
   151
    margin-bottom:  0;
richt@437
   152
    }
richt@492
   153
richt@492
   154
    @media print {
richt@492
   155
    .removeOnSave {
richt@492
   156
        display: none;
richt@492
   157
    }
richt@492
   158
    }
richt@437
   159
    </style>
richt@437
   160
    <style>
richt@437
   161
/* --- ISSUES/NOTES --- */
richt@437
   162
    div.issue-title, div.note-title {
richt@194
   163
    padding-right:  1em;
richt@194
   164
    min-width: 7.5em;
richt@194
   165
    color: #b9ab2d;
richt@437
   166
    }
richt@437
   167
    div.issue-title { color: #e05252; }
richt@437
   168
    div.note-title { color: #2b2; }
richt@437
   169
    div.issue-title span, div.note-title span {
richt@194
   170
    text-transform: uppercase;
richt@437
   171
    }
richt@437
   172
    div.note, div.issue {
richt@194
   173
    margin-top: 1em;
richt@194
   174
    margin-bottom: 1em;
richt@437
   175
    }
richt@437
   176
    .note > p:first-child, .issue > p:first-child { margin-top: 0 }
richt@437
   177
    .issue, .note {
richt@194
   178
    padding: .5em;
richt@194
   179
    border-left-width: .5em;
richt@194
   180
    border-left-style: solid;
richt@437
   181
    }
richt@437
   182
    div.issue, div.note {
richt@437
   183
    padding: 1em 1.2em 0.5em;
richt@194
   184
    margin: 1em 0;
richt@194
   185
    position: relative;
richt@194
   186
    clear: both;
richt@437
   187
    }
richt@437
   188
    span.note, span.issue { padding: .1em .5em .15em; }
richt@180
   189
richt@437
   190
    .issue {
richt@194
   191
    border-color: #e05252;
richt@194
   192
    background: #fbe9e9;
richt@437
   193
    }
richt@437
   194
    .note {
richt@194
   195
    border-color: #52e052;
richt@194
   196
    background: #e9fbe9;
richt@437
   197
    }
richt@180
   198
richt@194
   199
richt@437
   200
    </style>
richt@437
   201
    <style>
richt@437
   202
/* HIGHLIGHTS */
richt@437
   203
    code.prettyprint {
richt@194
   204
    color:  inherit;
richt@437
   205
    }
richt@180
   206
richt@437
   207
    /* this from google-code-prettify */
richt@437
   208
    .pln{color:#000}@media screen{.str{color:#080}.kwd{color:#008}.com{color:#800}.typ{color:#606}.lit{color:#066}.pun,.opn,.clo{color:#660}.tag{color:#008}.atn{color:#606}.atv{color:#080}.dec,.var{color:#606}.fun{color:red}}@media print,projection{.str{color:#060}.kwd{color:#006;font-weight:bold}.com{color:#600;font-style:italic}.typ{color:#404;font-weight:bold}.lit{color:#044}.pun,.opn,.clo{color:#440}.tag{color:#006;font-weight:bold}.atn{color:#404}.atv{color:#060}}ol.linenums{margin-top:0;margin-bottom:0}li.L0,li.L1,li.L2,li.L3,li.L5,li.L6,li.L7,li.L8{list-style-type:none}li.L1,li.L3,li.L5,li.L7,li.L9{background:#eee}
richt@437
   209
    </style>
richt@437
   210
    <link rel="stylesheet"
richt@437
   211
          href="https://www.w3.org/StyleSheets/TR/W3C-ED">
richt@437
   212
  </head>
richt@447
   213
  <body class="h-entry"
richt@480
   214
        style=""
richt@447
   215
        role="document"
richt@447
   216
        id="respecDocument">
richt@447
   217
    <div class="head"
richt@447
   218
         role="contentinfo"
richt@447
   219
         id="respecHeader">
richt@437
   220
      <p>
richt@437
   221
        <a href="http://www.w3.org/"><img width="72"
richt@437
   222
             height="48"
richt@437
   223
             src="https://www.w3.org/Icons/w3c_home"
richt@437
   224
             alt="W3C"></a>
richt@437
   225
      </p>
richt@437
   226
      <h1 class="title p-name"
richt@437
   227
          id="title"
richt@437
   228
          property="dcterms:title">
richt@437
   229
        Network Service Discovery
richt@437
   230
      </h1>
richt@437
   231
      <h2 property="dcterms:issued"
richt@437
   232
          datatype="xsd:dateTime"
richt@492
   233
          content="2014-02-18T12:22:23.000Z"
richt@492
   234
          id="w3c-editor-s-draft-18-february-2014">
richt@437
   235
        <abbr title="World Wide Web Consortium">W3C</abbr> Editor's Draft <time class="dt-published"
richt@492
   236
            datetime="2014-02-18">18 February 2014</time>
richt@437
   237
      </h2>
richt@437
   238
      <dl>
richt@437
   239
        <dt>
richt@437
   240
          This version:
richt@437
   241
        </dt>
richt@437
   242
        <dd>
richt@437
   243
          <a class="u-url"
richt@437
   244
              href=
richt@437
   245
              "http://dvcs.w3.org/hg/dap/raw-file/tip/discovery-api/Overview.html">http://dvcs.w3.org/hg/dap/raw-file/tip/discovery-api/Overview.html</a>
richt@437
   246
        </dd>
richt@437
   247
        <dt>
richt@437
   248
          Latest published version:
richt@437
   249
        </dt>
richt@437
   250
        <dd>
richt@437
   251
          <a href="http://www.w3.org/TR/discovery-api/">http://www.w3.org/TR/discovery-api/</a>
richt@437
   252
        </dd>
richt@437
   253
        <dt>
richt@437
   254
          Latest editor's draft:
richt@437
   255
        </dt>
richt@437
   256
        <dd>
richt@437
   257
          <a href=
richt@437
   258
          "http://dvcs.w3.org/hg/dap/raw-file/tip/discovery-api/Overview.html">http://dvcs.w3.org/hg/dap/raw-file/tip/discovery-api/Overview.html</a>
richt@437
   259
        </dd>
richt@437
   260
        <dt>
richt@437
   261
          Editor:
richt@437
   262
        </dt>
richt@437
   263
        <dd class="p-author h-card vcard"
richt@437
   264
            rel="bibo:editor"
richt@437
   265
            inlist="">
richt@437
   266
          <span typeof="foaf:Person"><span property="foaf:name"
richt@437
   267
                class="p-name fn">Rich Tibbett</span>, <a rel="foaf:workplaceHomepage"
richt@437
   268
             class="p-org org h-org h-card"
richt@437
   269
             href="http://opera.com/">Opera Software ASA</a></span>
richt@437
   270
        </dd>
richt@437
   271
      </dl>
richt@402
   272
      <p class="copyright">
richt@492
   273
        <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © 2014 <a href=
richt@437
   274
        "http://www.w3.org/"><abbr title="World Wide Web Consortium">W3C</abbr></a><sup>®</sup> (<a href=
richt@437
   275
        "http://www.csail.mit.edu/"><abbr title="Massachusetts Institute of Technology">MIT</abbr></a>, <a href=
richt@437
   276
        "http://www.ercim.eu/"><abbr title=
richt@437
   277
        "European Research Consortium for Informatics and Mathematics">ERCIM</abbr></a>, <a href=
richt@437
   278
        "http://www.keio.ac.jp/">Keio</a>, <a href="http://ev.buaa.edu.cn/">Beihang</a>), All Rights Reserved.
richt@437
   279
        <abbr title="World Wide Web Consortium">W3C</abbr> <a href=
richt@437
   280
        "http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href=
richt@437
   281
        "http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href=
richt@437
   282
        "http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.
richt@379
   283
      </p>
richt@437
   284
      <hr>
richt@437
   285
    </div>
richt@437
   286
    <section id="abstract"
richt@437
   287
             class="introductory"
richt@437
   288
             property="dcterms:abstract"
richt@437
   289
             datatype=""
richt@437
   290
             typeof="bibo:Chapter"
richt@484
   291
             resource="#ref"
richt@484
   292
             rel="bibo:Chapter">
richt@447
   293
      <h2 aria-level="1"
richt@447
   294
          role="heading"
richt@447
   295
          id="h2_abstract">
richt@437
   296
        Abstract
richt@437
   297
      </h2>
richt@180
   298
      <p>
richt@239
   299
        This specification defines a mechanism for an HTML document to discover and subsequently communicate with
richt@239
   300
        <abbr title="Hypertext Transfer Protocol">HTTP</abbr>-based services advertised via common discovery protocols
richt@239
   301
        within the current network.
richt@180
   302
      </p>
richt@437
   303
    </section>
richt@480
   304
    <section id="sotd"
richt@480
   305
             class="introductory"
richt@480
   306
             typeof="bibo:Chapter"
richt@484
   307
             resource="#ref"
richt@484
   308
             rel="bibo:Chapter">
richt@480
   309
      <h2 aria-level="1"
richt@480
   310
          role="heading"
richt@480
   311
          id="h2_sotd">
richt@480
   312
        Status of This Document
richt@480
   313
      </h2>
richt@480
   314
      <p>
richt@480
   315
        <em>This section describes the status of this document at the time of its publication. Other documents may
richt@480
   316
        supersede this document. A list of current <abbr title="World Wide Web Consortium">W3C</abbr> publications and
richt@480
   317
        the latest revision of this technical report can be found in the <a href="http://www.w3.org/TR/"><abbr title=
richt@480
   318
        "World Wide Web Consortium">W3C</abbr> technical reports index</a> at http://www.w3.org/TR/.</em>
richt@480
   319
      </p>
richt@480
   320
      <p>
richt@480
   321
        This document represents the early consensus of the group on the scope and features of the proposed
richt@480
   322
        <abbr title="Application Programming Interface">API</abbr>.
richt@480
   323
      </p>
richt@480
   324
      <p>
richt@480
   325
        This document was published by the <a href="http://www.w3.org/2009/dap/">Device APIs Working Group</a> as an
richt@480
   326
        Editor's Draft. If you wish to make comments regarding this document, please send them to <a href=
richt@480
   327
        "mailto:public-device-apis@w3.org">public-device-apis@w3.org</a> (<a href=
richt@480
   328
        "mailto:public-device-apis-request@w3.org?subject=subscribe">subscribe</a>, <a href=
richt@480
   329
        "http://lists.w3.org/Archives/Public/public-device-apis/">archives</a>). All comments are welcome.
richt@480
   330
      </p>
richt@480
   331
      <p>
richt@480
   332
        Publication as an Editor's Draft does not imply endorsement by the <abbr title=
richt@480
   333
        "World Wide Web Consortium">W3C</abbr> Membership. This is a draft document and may be updated, replaced or
richt@480
   334
        obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in
richt@480
   335
        progress.
richt@480
   336
      </p>
richt@480
   337
      <p>
richt@480
   338
        This document was produced by a group operating under the <a id="sotd_patent"
richt@480
   339
           about=""
richt@480
   340
           rel="w3p:patentRules"
richt@480
   341
           href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February 2004 <abbr title=
richt@480
   342
           "World Wide Web Consortium">W3C</abbr> Patent Policy</a>. <abbr title="World Wide Web Consortium">W3C</abbr>
richt@480
   343
           maintains a <a href="http://www.w3.org/2004/01/pp-impl/43696/status"
richt@480
   344
           rel="disclosure">public list of any patent disclosures</a> made in connection with the deliverables of the
richt@480
   345
           group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge
richt@480
   346
           of a patent which the individual believes contains <a href=
richt@480
   347
           "http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential Claim(s)</a> must disclose
richt@480
   348
           the information in accordance with <a href=
richt@480
   349
           "http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section 6 of the <abbr title=
richt@480
   350
           "World Wide Web Consortium">W3C</abbr> Patent Policy</a>.
richt@480
   351
      </p>
richt@480
   352
    </section>
richt@437
   353
    <section id="toc">
richt@447
   354
      <h2 class="introductory"
richt@447
   355
          aria-level="1"
richt@447
   356
          role="heading"
richt@447
   357
          id="h2_toc">
richt@437
   358
        Table of Contents
richt@437
   359
      </h2>
richt@447
   360
      <ul class="toc"
richt@447
   361
          role="directory"
richt@447
   362
          id="respecContents">
richt@437
   363
        <li class="tocline">
richt@437
   364
          <a href="#introduction"
richt@437
   365
              class="tocxref"><span class="secno">1.</span> Introduction</a>
richt@437
   366
        </li>
richt@437
   367
        <li class="tocline">
richt@437
   368
          <a href="#conformance"
richt@437
   369
              class="tocxref"><span class="secno">2.</span> Conformance</a>
richt@437
   370
          <ul class="toc">
richt@437
   371
            <li class="tocline">
richt@437
   372
              <a href="#dependencies"
richt@437
   373
                  class="tocxref"><span class="secno">2.1</span> Dependencies</a>
richt@437
   374
            </li>
richt@437
   375
          </ul>
richt@437
   376
        </li>
richt@437
   377
        <li class="tocline">
richt@437
   378
          <a href="#terminology"
richt@437
   379
              class="tocxref"><span class="secno">3.</span> Terminology</a>
richt@437
   380
        </li>
richt@437
   381
        <li class="tocline">
richt@440
   382
          <a href="#security-and-privacy-considerations"
richt@440
   383
              class="tocxref"><span class="secno">4.</span> Security and privacy considerations</a>
richt@440
   384
          <ul class="toc">
richt@440
   385
            <li class="tocline">
richt@480
   386
              <a href="#security-considerations-for-api-implementations"
richt@480
   387
                  class="tocxref"><span class="secno">4.1</span> Security considerations for <abbr title=
richt@480
   388
                  "Application Programming Interface">API</abbr> implementations</a>
richt@480
   389
            </li>
richt@480
   390
            <li class="tocline">
richt@440
   391
              <a href="#privacy-considerations-for-api-implementations"
richt@480
   392
                  class="tocxref"><span class="secno">4.2</span> Privacy considerations for <abbr title=
richt@440
   393
                  "Application Programming Interface">API</abbr> implementations</a>
richt@440
   394
            </li>
richt@440
   395
            <li class="tocline">
richt@440
   396
              <a href="#additional-api-implementation-considerations"
richt@480
   397
                  class="tocxref"><span class="secno">4.3</span> Additional <abbr title=
richt@440
   398
                  "Application Programming Interface">API</abbr> implementation considerations</a>
richt@440
   399
            </li>
richt@440
   400
          </ul>
richt@440
   401
        </li>
richt@440
   402
        <li class="tocline">
richt@437
   403
          <a href="#requesting-networked-services"
richt@440
   404
              class="tocxref"><span class="secno">5.</span> Requesting networked services</a>
richt@437
   405
          <ul class="toc">
richt@437
   406
            <li class="tocline">
richt@437
   407
              <a href="#methods"
richt@440
   408
                  class="tocxref"><span class="secno">5.1</span> Methods</a>
richt@437
   409
            </li>
richt@437
   410
            <li class="tocline">
richt@437
   411
              <a href="#error-handling"
richt@440
   412
                  class="tocxref"><span class="secno">5.2</span> Error Handling</a>
richt@437
   413
            </li>
richt@437
   414
          </ul>
richt@437
   415
        </li>
richt@437
   416
        <li class="tocline">
richt@437
   417
          <a href="#obtaining-networked-services"
richt@440
   418
              class="tocxref"><span class="secno">6.</span> Obtaining networked services</a>
richt@437
   419
          <ul class="toc">
richt@437
   420
            <li class="tocline">
richt@437
   421
              <a href="#attributes"
richt@440
   422
                  class="tocxref"><span class="secno">6.1</span> Attributes</a>
richt@437
   423
            </li>
richt@437
   424
            <li class="tocline">
richt@437
   425
              <a href="#methods-1"
richt@440
   426
                  class="tocxref"><span class="secno">6.2</span> Methods</a>
richt@437
   427
            </li>
richt@437
   428
            <li class="tocline">
richt@437
   429
              <a href="#events"
richt@440
   430
                  class="tocxref"><span class="secno">6.3</span> Events</a>
richt@437
   431
            </li>
richt@437
   432
          </ul>
richt@437
   433
        </li>
richt@437
   434
        <li class="tocline">
richt@437
   435
          <a href="#communicating-with-a-networked-service"
richt@440
   436
              class="tocxref"><span class="secno">7.</span> Communicating with a networked service</a>
richt@437
   437
          <ul class="toc">
richt@437
   438
            <li class="tocline">
richt@437
   439
              <a href="#attributes-1"
richt@440
   440
                  class="tocxref"><span class="secno">7.1</span> Attributes</a>
richt@437
   441
            </li>
richt@437
   442
            <li class="tocline">
richt@437
   443
              <a href="#states"
richt@440
   444
                  class="tocxref"><span class="secno">7.2</span> States</a>
richt@437
   445
            </li>
richt@437
   446
            <li class="tocline">
richt@437
   447
              <a href="#events-1"
richt@440
   448
                  class="tocxref"><span class="secno">7.3</span> Events</a>
richt@437
   449
            </li>
richt@437
   450
          </ul>
richt@437
   451
        </li>
richt@437
   452
        <li class="tocline">
richt@437
   453
          <a href="#service-discovery"
richt@440
   454
              class="tocxref"><span class="secno">8.</span> Service Discovery</a>
richt@437
   455
          <ul class="toc">
richt@437
   456
            <li class="tocline">
richt@437
   457
              <a href="#zeroconf-mdns-dns-sd"
richt@440
   458
                  class="tocxref"><span class="secno">8.1</span> Zeroconf (<abbr title="Multicast DNS">mDNS</abbr> +
richt@437
   459
                  <abbr title="Domain Name System">DNS</abbr>-<abbr title="Service Discovery">SD</abbr>)</a>
richt@437
   460
            </li>
richt@437
   461
            <li class="tocline">
richt@437
   462
              <a href="#simple-service-discovery-protocol-ssdp"
richt@440
   463
                  class="tocxref"><span class="secno">8.2</span> Simple Service Discovery Protocol (<abbr title=
richt@437
   464
                  "Simple Service Discovery Protocol">SSDP</abbr>)</a>
richt@437
   465
            </li>
richt@437
   466
            <li class="tocline">
richt@437
   467
              <a href="#discovery-and-launch-protocol-dial"
richt@440
   468
                  class="tocxref"><span class="secno">8.3</span> Discovery and Launch Protocol (<abbr title=
richt@437
   469
                  "Discovery and Launch Protocol">DIAL</abbr>)</a>
richt@437
   470
            </li>
richt@437
   471
            <li class="tocline">
richt@437
   472
              <a href="#network-topology-monitoring"
richt@440
   473
                  class="tocxref"><span class="secno">8.4</span> Network Topology Monitoring</a>
richt@437
   474
            </li>
richt@437
   475
          </ul>
richt@437
   476
        </li>
richt@437
   477
        <li class="tocline">
richt@437
   478
          <a href="#events-summary"
richt@440
   479
              class="tocxref"><span class="secno">9.</span> Events Summary</a>
richt@437
   480
        </li>
richt@437
   481
        <li class="tocline">
richt@437
   482
          <a href="#garbage-collection"
richt@440
   483
              class="tocxref"><span class="secno">10.</span> Garbage collection</a>
richt@437
   484
        </li>
richt@437
   485
        <li class="tocline">
richt@437
   486
          <a href="#use-cases-and-requirements"
richt@440
   487
              class="tocxref"><span class="secno">11.</span> Use Cases and Requirements</a>
richt@437
   488
        </li>
richt@437
   489
        <li class="tocline">
richt@437
   490
          <a href="#examples"
richt@437
   491
              class="tocxref"><span class="secno">A.</span> Examples</a>
richt@437
   492
        </li>
richt@437
   493
        <li class="tocline">
richt@437
   494
          <a href="#acknowledgements"
richt@437
   495
              class="tocxref"><span class="secno">B.</span> Acknowledgements</a>
richt@437
   496
        </li>
richt@437
   497
        <li class="tocline">
richt@437
   498
          <a href="#references"
richt@437
   499
              class="tocxref"><span class="secno">C.</span> References</a>
richt@437
   500
          <ul class="toc">
richt@437
   501
            <li class="tocline">
richt@437
   502
              <a href="#normative-references"
richt@437
   503
                  class="tocxref"><span class="secno">C.1</span> Normative references</a>
richt@437
   504
            </li>
richt@453
   505
            <li class="tocline">
richt@453
   506
              <a href="#informative-references"
richt@453
   507
                  class="tocxref"><span class="secno">C.2</span> Informative references</a>
richt@453
   508
            </li>
richt@437
   509
          </ul>
richt@437
   510
        </li>
richt@437
   511
      </ul>
richt@437
   512
    </section>
richt@437
   513
    <section class="informative"
richt@437
   514
             id="introduction">
richt@447
   515
      <h2 aria-level="1"
richt@447
   516
          role="heading"
richt@447
   517
          id="h2_introduction">
richt@437
   518
        <span class="secno">1.</span> Introduction
richt@437
   519
      </h2>
richt@437
   520
      <p>
richt@437
   521
        <em>This section is non-normative.</em>
richt@437
   522
      </p>
richt@437
   523
      <p>
richt@453
   524
        This specification defines the <a href="#navigatornetworkservice"><code>NavigatorNetworkService</code></a>
richt@453
   525
        interface to enable Web pages to connect and communicate with Local-networked Services provided over
richt@453
   526
        <abbr title="Hypertext Transfer Protocol">HTTP</abbr>. This enables access to services and content provided by
richt@453
   527
        home network devices, including the discovery and playback of content available to those devices, both from
richt@453
   528
        services such as traditional broadcast media and internet based services as well as local services. Initial
richt@453
   529
        design goals and requirements provided by the <a href="http://www.w3.org/2011/webtv/"><abbr title=
richt@453
   530
        "World Wide Web Consortium">W3C</abbr> Web &amp; TV interest group</a> are documented in [<cite><a class=
richt@453
   531
        "bibref"
richt@453
   532
           href="#bib-hnreq">hnreq</a></cite>].
richt@239
   533
      </p>
richt@239
   534
      <p>
richt@239
   535
        Using this <abbr title="Application Programming Interface">API</abbr> consists of requesting a well-known
richt@239
   536
        service type, known by developers and advertised by Local-networked Devices. User authorization, where the user
richt@379
   537
        connects the web page to discovered services, is expected before the web page is able to interact with any
richt@379
   538
        Local-networked Services.
richt@239
   539
      </p>
richt@239
   540
      <p>
richt@239
   541
        A web page creates a request to obtain connectivity to services running in the network by specifying a
richt@239
   542
        well-known discovery service type that it wishes to interact with.
richt@239
   543
      </p>
richt@239
   544
      <p>
richt@437
   545
        The user agent, having captured all advertised services on the network from the <a href=
richt@437
   546
        "#dfn-service-discovery-mechanisms"
richt@437
   547
           class="internalDFN">service discovery mechanisms</a> included in this recommendation, attempts to match the
richt@480
   548
           requested service type to a discovered service according to the processing described herein. Only
richt@483
   549
           Local-networked Services that pass a <a href="#dfn-preliminary-cors-check"
richt@483
   550
           class="internalDFN">preliminary CORS check</a> should be made available to web pages by a user agent. A user
richt@480
   551
           agent may provide a way for users to white-list non-CORS enabled Local-networked Services but implementation
richt@480
   552
           of such a feature is left to the discretion of the implementer.
richt@239
   553
      </p>
richt@239
   554
      <p>
richt@437
   555
        If a service connectivity request is successful then the Web page is provided with a promise-based success
richt@437
   556
        callback with the all necessary information to communicate with the authorized Local-networked Service. If the
richt@447
   557
        request fails then the Web page will receive a promise-based error callback containing an error string
richt@447
   558
        describing the cause of Local-networked Service connectivity failure.
richt@239
   559
      </p>
richt@239
   560
      <p>
richt@239
   561
        Once connected to a Local-networked Service the Web page can send requests and receive responses to the
richt@239
   562
        Local-networked Service via the messaging format and appropriate channel inferred from the service type
richt@437
   563
        authorized via the provided <abbr title="Application Programming Interface">API</abbr>. The Web page, once
richt@437
   564
        connected, can also receive service-pushed events, in the messaging format supported by the Local-networked
richt@437
   565
        Device, if such event subscription functionality is provided by the connected Local-networked Service.
richt@402
   566
      </p>
richt@402
   567
      <p>
richt@437
   568
        Services available within the local network can connect and disconnect at different times during the execution
richt@437
   569
        of a web page. The user agent can inform a web page when the state of networked services matching any of the
richt@437
   570
        requested valid service types change. Web pages can use this information to enable in-page experiences for
richt@437
   571
        communicating the state of networked services with the ability to change the particular service or set of
richt@437
   572
        services the page is connected to (by re-invoking the <a href=
richt@437
   573
        "#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a> method defined herein).
richt@239
   574
      </p>
richt@239
   575
      <div class="example">
richt@191
   576
        <p>
richt@437
   577
          Example of requesting a <abbr title="Domain Name System">DNS</abbr>-<abbr title="Service Discovery">SD</abbr>
richt@437
   578
          advertised service:
richt@191
   579
        </p>
richt@239
   580
        <hr>
richt@492
   581
        <pre class="highlight prettyprint prettyprinted"
richt@492
   582
             style="">
richt@437
   583
<span class="kwd">function</span><span class="pln"> showServices</span><span class="pun">(</span><span class=
richt@437
   584
"pln"> services </span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
richt@194
   585
  </span><span class="com">// Show a list of all the services provided to the web page</span><span class="pln">
richt@437
   586
  </span><span class="kwd">for</span><span class="pun">(</span><span class="kwd">var</span><span class=
richt@437
   587
"pln"> i </span><span class="pun">=</span><span class="pln"> </span><span class="lit">0</span><span class=
richt@437
   588
"pun">,</span><span class="pln"> l </span><span class="pun">=</span><span class="pln"> services</span><span class=
richt@437
   589
"pun">.</span><span class="pln">length</span><span class="pun">;</span><span class="pln"> i </span><span class=
richt@437
   590
"pun">&lt;</span><span class="pln"> l</span><span class="pun">;</span><span class="pln"> i</span><span class=
richt@437
   591
"pun">++)</span><span class="pln"> console</span><span class="pun">.</span><span class="pln">log</span><span class=
richt@437
   592
"pun">(</span><span class="pln"> services</span><span class="pun">[</span><span class="pln">i</span><span class=
richt@437
   593
"pun">].</span><span class="pln">name </span><span class="pun">);</span><span class="pln">
richt@194
   594
</span><span class="pun">}</span><span class="pln">
richt@194
   595
richt@437
   596
navigator</span><span class="pun">.</span><span class="pln">getNetworkServices</span><span class=
richt@437
   597
"pun">(</span><span class="str">'zeroconf:_boxee-jsonrpc._tcp'</span><span class="pun">).</span><span class=
richt@437
   598
"kwd">then</span><span class="pun">(</span><span class="pln">showServices</span><span class="pun">);</span>
richt@437
   599
</pre>
richt@180
   600
      </div>
richt@180
   601
      <div class="example">
richt@239
   602
        <p>
richt@239
   603
          Example of requesting a UPnP advertised service, also handling error conditions:
richt@239
   604
        </p>
richt@180
   605
        <hr>
richt@492
   606
        <pre class="highlight prettyprint prettyprinted"
richt@492
   607
             style="">
richt@437
   608
<span class="kwd">function</span><span class="pln"> showServices</span><span class="pun">(</span><span class=
richt@437
   609
"pln"> services </span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
richt@194
   610
  </span><span class="com">// Show a list of all the services provided to the web page</span><span class="pln">
richt@437
   611
  </span><span class="kwd">for</span><span class="pun">(</span><span class="kwd">var</span><span class=
richt@437
   612
"pln"> i </span><span class="pun">=</span><span class="pln"> </span><span class="lit">0</span><span class=
richt@437
   613
"pun">,</span><span class="pln"> l </span><span class="pun">=</span><span class="pln"> services</span><span class=
richt@437
   614
"pun">.</span><span class="pln">length</span><span class="pun">;</span><span class="pln"> i </span><span class=
richt@437
   615
"pun">&lt;</span><span class="pln"> l</span><span class="pun">;</span><span class="pln"> i</span><span class=
richt@437
   616
"pun">++)</span><span class="pln"> console</span><span class="pun">.</span><span class="pln">log</span><span class=
richt@437
   617
"pun">(</span><span class="pln"> services</span><span class="pun">[</span><span class="pln">i</span><span class=
richt@437
   618
"pun">].</span><span class="pln">name </span><span class="pun">);</span><span class="pln">
richt@194
   619
</span><span class="pun">}</span><span class="pln">
richt@194
   620
richt@437
   621
</span><span class="kwd">function</span><span class="pln"> error</span><span class="pun">(</span><span class=
richt@437
   622
"pln"> e </span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
richt@437
   623
  console</span><span class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class=
richt@437
   624
"pln"> </span><span class="str">"Error occurred: "</span><span class="pln"> </span><span class=
richt@447
   625
"pun">+</span><span class="pln"> e</span><span class="pun">.</span><span class="pln">name </span><span class=
richt@437
   626
"pun">);</span><span class="pln">
richt@194
   627
</span><span class="pun">}</span><span class="pln">
richt@194
   628
richt@437
   629
navigator</span><span class="pun">.</span><span class="pln">getNetworkServices</span><span class=
richt@437
   630
"pun">(</span><span class="str">'upnp:urn:schemas-upnp-org:service:ContentDirectory:1'</span><span class=
richt@437
   631
"pun">).</span><span class="kwd">then</span><span class="pun">(</span><span class="pln">showServices</span><span class=
richt@437
   632
"pun">,</span><span class="pln"> error</span><span class="pun">);</span>
richt@437
   633
</pre>
richt@180
   634
      </div>
richt@180
   635
      <div class="example">
richt@239
   636
        <p>
richt@437
   637
          Example of requesting either a <abbr title="Domain Name System">DNS</abbr>-<abbr title=
richt@437
   638
          "Service Discovery">SD</abbr> or UPnP advertised service:
richt@239
   639
        </p>
richt@180
   640
        <hr>
richt@492
   641
        <pre class="highlight prettyprint prettyprinted"
richt@492
   642
             style="">
richt@437
   643
<span class="kwd">function</span><span class="pln"> showServices</span><span class="pun">(</span><span class=
richt@437
   644
"pln"> services </span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
richt@437
   645
  </span><span class=
richt@437
   646
"com">// Show a list of all the services provided to the web page (+ service type)</span><span class="pln">
richt@437
   647
  </span><span class="kwd">for</span><span class="pun">(</span><span class="kwd">var</span><span class=
richt@437
   648
"pln"> i </span><span class="pun">=</span><span class="pln"> </span><span class="lit">0</span><span class=
richt@437
   649
"pun">,</span><span class="pln"> l </span><span class="pun">=</span><span class="pln"> services</span><span class=
richt@437
   650
"pun">.</span><span class="pln">length</span><span class="pun">;</span><span class="pln"> i </span><span class=
richt@437
   651
"pun">&lt;</span><span class="pln"> l</span><span class="pun">;</span><span class="pln"> i</span><span class=
richt@437
   652
"pun">++)</span><span class="pln">
richt@437
   653
     console</span><span class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class=
richt@437
   654
"pln"> services</span><span class="pun">[</span><span class="pln">i</span><span class="pun">].</span><span class=
richt@437
   655
"pln">name </span><span class="pun">+</span><span class="pln"> </span><span class="str">'('</span><span class=
richt@437
   656
"pln"> </span><span class="pun">+</span><span class="pln"> services</span><span class="pun">[</span><span class=
richt@437
   657
"pln">i</span><span class="pun">].</span><span class="pln">type </span><span class="pun">+</span><span class=
richt@437
   658
"pln"> </span><span class="str">')'</span><span class="pln"> </span><span class="pun">);</span><span class="pln">
richt@194
   659
</span><span class="pun">}</span><span class="pln">
richt@194
   660
richt@437
   661
navigator</span><span class="pun">.</span><span class="pln">getNetworkServices</span><span class=
richt@437
   662
"pun">([</span><span class="pln">
richt@194
   663
  </span><span class="str">'zeroconf:_boxee-jsonrpc._tcp'</span><span class="pun">,</span><span class="pln">
richt@194
   664
  </span><span class="str">'upnp:urn:schemas-upnp-org:service:ContentDirectory:1'</span><span class="pln">
richt@437
   665
</span><span class="pun">]).</span><span class="kwd">then</span><span class="pun">(</span><span class=
richt@437
   666
"pln">showServices</span><span class="pun">);</span>
richt@437
   667
</pre>
richt@180
   668
      </div>
richt@239
   669
      <p>
richt@440
   670
        For more detailed examples, including examples of communicating with obtained networked services, see the
richt@440
   671
        <a href="#examples">Examples</a> section.
richt@239
   672
      </p>
richt@239
   673
    </section>
richt@437
   674
    <section id="conformance"
richt@437
   675
             typeof="bibo:Chapter"
richt@484
   676
             resource="#ref"
richt@484
   677
             rel="bibo:Chapter">
richt@447
   678
      <h2 aria-level="1"
richt@447
   679
          role="heading"
richt@447
   680
          id="h2_conformance">
richt@437
   681
        <span class="secno">2.</span> Conformance
richt@437
   682
      </h2>
richt@437
   683
      <p>
richt@437
   684
        As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this
richt@437
   685
        specification are non-normative. Everything else in this specification is normative.
richt@437
   686
      </p>
richt@437
   687
      <p>
richt@437
   688
        The key words <em class="rfc2119"
richt@437
   689
           title="MUST">MUST</em>, <em class="rfc2119"
richt@437
   690
           title="MUST NOT">MUST NOT</em>, <em class="rfc2119"
richt@437
   691
           title="REQUIRED">REQUIRED</em>, <em class="rfc2119"
richt@437
   692
           title="SHOULD">SHOULD</em>, <em class="rfc2119"
richt@437
   693
           title="SHOULD NOT">SHOULD NOT</em>, <em class="rfc2119"
richt@437
   694
           title="RECOMMENDED">RECOMMENDED</em>, <em class="rfc2119"
richt@437
   695
           title="MAY">MAY</em>, and <em class="rfc2119"
richt@437
   696
           title="OPTIONAL">OPTIONAL</em> in this specification are to be interpreted as described in [<cite><a class=
richt@437
   697
           "bibref"
richt@437
   698
           href="#bib-RFC2119">RFC2119</a></cite>].
richt@437
   699
      </p>
richt@239
   700
      <p>
richt@239
   701
        Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or
richt@239
   702
        "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should",
richt@239
   703
        "may", etc) used in introducing the algorithm.
richt@239
   704
      </p>
richt@239
   705
      <p>
richt@239
   706
        Some conformance requirements are phrased as requirements on attributes, methods or objects. Such requirements
richt@239
   707
        are to be interpreted as requirements on user agents.
richt@239
   708
      </p>
richt@239
   709
      <p>
richt@437
   710
        Conformance requirements phrased as algorithms or specific steps <em class="rfc2119"
richt@437
   711
           title="MAY">MAY</em> be implemented in any manner, so long as the end result is equivalent. (In particular,
richt@437
   712
           the algorithms defined in this specification are intended to be easy to follow, and not intended to be
richt@437
   713
           performant.)
richt@239
   714
      </p>
richt@239
   715
      <p>
richt@239
   716
        The only conformance class defined by this specification is a <dfn id="dfn-user-agent">user agent</dfn>.
richt@239
   717
      </p>
richt@239
   718
      <p>
richt@437
   719
        User agents <em class="rfc2119"
richt@437
   720
           title="MAY">MAY</em> impose implementation-specific limits on otherwise unconstrained inputs, e.g. to
richt@437
   721
           prevent denial of service attacks, to guard against running out of memory, or to work around
richt@437
   722
           platform-specific limitations.
richt@239
   723
      </p>
richt@239
   724
      <p>
richt@239
   725
        When support for a feature is disabled (e.g. as an emergency measure to mitigate a security problem, or to aid
richt@437
   726
        in development, or for performance reasons), user agents <em class="rfc2119"
richt@437
   727
           title="MUST">MUST</em> act as if they had no support for the feature whatsoever, and as if the feature was
richt@437
   728
           not mentioned in this specification. For example, if a particular feature is accessed via an attribute in a
richt@437
   729
           Web IDL interface, the attribute itself would be omitted from the objects that implement that interface -
richt@437
   730
           leaving the attribute on the object but making it return null or throw an exception is insufficient.
richt@239
   731
      </p>
richt@194
   732
      <section id="dependencies">
richt@447
   733
        <h3 aria-level="2"
richt@447
   734
            role="heading"
richt@447
   735
            id="h3_dependencies">
richt@437
   736
          <span class="secno">2.1</span> Dependencies
richt@239
   737
        </h3>This specification relies on several other underlying specifications.
richt@239
   738
        <dl>
richt@239
   739
          <dt>
richt@239
   740
            HTML
richt@239
   741
          </dt>
richt@239
   742
          <dd>
richt@437
   743
            Many fundamental concepts from HTML are used by this specification. [<cite><a class="bibref"
richt@437
   744
               href="#bib-HTML5">HTML5</a></cite>]
richt@239
   745
          </dd>
richt@239
   746
          <dt>
richt@239
   747
            WebIDL
richt@239
   748
          </dt>
richt@239
   749
          <dd>
richt@437
   750
            The IDL blocks in this specification use the semantics of the WebIDL specification. [<cite><a class=
richt@437
   751
            "bibref"
richt@437
   752
               href="#bib-WEBIDL">WEBIDL</a></cite>]
richt@239
   753
          </dd>
richt@239
   754
        </dl>
richt@180
   755
      </section>
richt@194
   756
    </section>
richt@194
   757
    <section id="terminology">
richt@447
   758
      <h2 aria-level="1"
richt@447
   759
          role="heading"
richt@447
   760
          id="h2_terminology">
richt@437
   761
        <span class="secno">3.</span> Terminology
richt@239
   762
      </h2>
richt@180
   763
      <p>
richt@239
   764
        The construction "a <code>Foo</code> object", where <code>Foo</code> is actually an interface, is sometimes
richt@239
   765
        used instead of the more accurate "an object implementing the interface <code>Foo</code>".
richt@180
   766
      </p>
richt@180
   767
      <p>
richt@437
   768
        The term DOM is used to refer to the <abbr title="Application Programming Interface">API</abbr> set made
richt@437
   769
        available to scripts in Web applications, and does not necessarily imply the existence of an actual
richt@437
   770
        <code>Document</code> object or of any other <code>Node</code> objects as defined in the DOM Core
richt@437
   771
        specifications. [<cite><a class="bibref"
richt@437
   772
           href="#bib-DOM4">DOM4</a></cite>]
richt@180
   773
      </p>
richt@180
   774
      <p>
richt@239
   775
        An IDL attribute is said to be <em>getting</em> when its value is being retrieved (e.g. by author script), and
richt@239
   776
        is said to be <em>setting</em> when a new value is assigned to it.
richt@180
   777
      </p>
richt@180
   778
      <p>
richt@333
   779
        A <dfn id="dfn-valid-service-type">valid service type</dfn> is any of the following:
richt@379
   780
      </p>
richt@379
   781
      <ul>
richt@379
   782
        <li>a string that begins with <code>upnp:</code> or <code>zeroconf:</code> followed by one or more characters
richt@379
   783
        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,
richt@379
   784
        U+005E to U+007E.
richt@379
   785
        </li>
richt@379
   786
        <li>a string that begins with <code>dial:</code> followed by an integer version.
richt@379
   787
        </li>
richt@379
   788
      </ul>
richt@333
   789
      <p>
richt@437
   790
        A <a href="#dfn-valid-service-type"
richt@437
   791
           class="internalDFN">valid service type</a> provided in the <code>type</code> attribute of the <a href=
richt@437
   792
           "#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a> method will be matched against the
richt@437
   793
           services currently contained in the <a href="#dfn-list-of-available-service-records"
richt@437
   794
           class="internalDFN">list of available service records</a> according to the algorithms defined in this
richt@437
   795
           specification.
richt@180
   796
      </p>
richt@180
   797
      <p>
richt@437
   798
        A <dfn id="dfn-user-agent-generated-callback-url">user-agent generated callback url</dfn> is a Local-network
richt@480
   799
        accessible URL endpoint that a <a href="#dfn-user-agent"
richt@437
   800
           class="internalDFN">user agent</a> generates and maintains for receiving <abbr title=
richt@437
   801
           "Hypertext Transfer Protocol">HTTP</abbr> NOTIFY requests from UPnP Event sources. It is only required when
richt@437
   802
           the user agent implements UPnP Service Discovery as defined in this specification.
richt@230
   803
      </p>
richt@389
   804
      <p>
richt@389
   805
        In this specification we use the following terms to describe the processes required for Local-networked
richt@389
   806
        Services management:
richt@389
   807
      </p>
richt@389
   808
      <ul>
richt@437
   809
        <li>A <dfn id="dfn-new-service">new service</dfn> is a Local-networked Service that has not previously been
richt@437
   810
        discovered or registered in the <a href="#dfn-list-of-available-service-records"
richt@437
   811
              class="internalDFN">list of available service records</a>.
richt@389
   812
        </li>
richt@437
   813
        <li>An <dfn id="dfn-existing-service">existing service</dfn> is a Local-networked Service that has previously
richt@437
   814
        been discovered and is registered in the <a href="#dfn-list-of-available-service-records"
richt@437
   815
              class="internalDFN">list of available service records</a>.
richt@389
   816
        </li>
richt@437
   817
        <li>A <dfn id="dfn-current-service">current service</dfn> is a Local-networked Service, represented by a
richt@437
   818
        <a href="#networkservice"><code>NetworkService</code></a> object, that is currently being shared with a web
richt@437
   819
        page via a <a href="#networkservices"><code>NetworkServices</code></a> object registered in the <a href=
richt@437
   820
        "#dfn-list-of-active-service-managers"
richt@437
   821
              class="internalDFN">list of active service managers</a>.
richt@389
   822
        </li>
richt@389
   823
      </ul>
richt@480
   824
      <p>
richt@480
   825
        A <dfn id="dfn-network-services-whitelist">network services whitelist</dfn> is a list of zero or more <a href=
richt@480
   826
        "#dfn-valid-service-type"
richt@480
   827
           class="internalDFN">valid service type</a> tokens that, when matched to a service type discovered in the
richt@480
   828
           local network, enables that service to be shared with a web page even if that Local-networked Service does
richt@480
   829
           not itself allow Cross-Origin Resource Sharing [<cite><a class="bibref"
richt@480
   830
           href="#bib-CORS">CORS</a></cite>]. A <a href="#dfn-user-agent"
richt@480
   831
           class="internalDFN">user agent</a> <em class="rfc2119"
richt@480
   832
           title="MUST">MUST</em> simulate CORS support for all service interaction in this case. Implementation of
richt@480
   833
           this feature is at implementer's discretion. When a <a href="#dfn-user-agent"
richt@480
   834
           class="internalDFN">user agent</a> does not implement a <a href="#dfn-network-services-whitelist"
richt@480
   835
           class="internalDFN">network services whitelist</a> then it is to treat this as always being an empty list.
richt@480
   836
      </p>
richt@194
   837
    </section>
richt@440
   838
    <section id="security-and-privacy-considerations">
richt@447
   839
      <h2 aria-level="1"
richt@447
   840
          role="heading"
richt@447
   841
          id="h2_security-and-privacy-considerations">
richt@440
   842
        <span class="secno">4.</span> Security and privacy considerations
richt@440
   843
      </h2>
richt@440
   844
      <p>
richt@440
   845
        The <abbr title="Application Programming Interface">API</abbr> defined in this specification can be used to
richt@440
   846
        find and connect to devices and services within a user's current network. This discloses information related to
richt@440
   847
        a user's network: devices available on their network and the publicly-accessible services ("networked
richt@440
   848
        services") currently running and available on those devices. The distribution of this information could
richt@440
   849
        potentially compromise the user's privacy. A conforming implementation of this specification <em class=
richt@440
   850
        "rfc2119"
richt@440
   851
           title="MUST">MUST</em> provide a mechanism that protects the user's privacy. This mechanism <em class=
richt@440
   852
           "rfc2119"
richt@440
   853
           title="MUST">MUST</em> ensure that no networked service information is retrievable without the user's
richt@440
   854
           express permission.
richt@440
   855
      </p>
richt@480
   856
      <section id="security-considerations-for-api-implementations">
richt@480
   857
        <h3 aria-level="2"
richt@480
   858
            role="heading"
richt@480
   859
            id="h3_security-considerations-for-api-implementations">
richt@480
   860
          <span class="secno">4.1</span> Security considerations for <abbr title=
richt@480
   861
          "Application Programming Interface">API</abbr> implementations
richt@480
   862
        </h3>
richt@480
   863
        <p>
richt@480
   864
          A <a href="#dfn-user-agent"
richt@480
   865
             class="internalDFN">user agent</a> <em class="rfc2119"
richt@483
   866
             title="SHOULD">SHOULD</em> only allow web pages to connect with Local-networked Services that have passed
richt@483
   867
             a <a href="#dfn-preliminary-cors-check"
richt@483
   868
             class="internalDFN">preliminary CORS check</a> indicating they support Cross-Origin Resource Sharing
richt@480
   869
             [<cite><a class="bibref"
richt@483
   870
             href="#bib-CORS">CORS</a></cite>]. In this way, a <a href="#dfn-user-agent"
richt@480
   871
             class="internalDFN">user agent</a> <em class="rfc2119"
richt@483
   872
             title="SHOULD NOT">SHOULD NOT</em> allow web pages to access other arbitrary networked services on the
richt@483
   873
             current local network.
richt@480
   874
        </p>
richt@480
   875
        <p>
richt@480
   876
          A <a href="#dfn-user-agent"
richt@480
   877
             class="internalDFN">user agent</a> <em class="rfc2119"
richt@480
   878
             title="MAY">MAY</em> provide a way for users to enable access to non-CORS enabled Local-networked Services
richt@480
   879
             from web pages (i.e. operate a <a href="#dfn-network-services-whitelist"
richt@480
   880
             class="internalDFN">network services whitelist</a>). Implementation of such a <a href=
richt@480
   881
             "#dfn-network-services-whitelist"
richt@480
   882
             class="internalDFN">network services whitelist</a>, if any, is left to an implementer's discretion. Such a
richt@480
   883
             whitelist may be configurable by each user at runtime or may be managed by the implementation itself on
richt@480
   884
             behalf of its users. In the case that a <a href="#dfn-user-agent"
richt@480
   885
             class="internalDFN">user agent</a> provides a <a href="#dfn-network-services-whitelist"
richt@480
   886
             class="internalDFN">network services whitelist</a>, it <em class="rfc2119"
richt@480
   887
             title="MUST">MUST</em> act as if all URLs for the Local-networked Service corresponding to any previously
richt@480
   888
             whitelisted service type had Cross-Origin Resource Sharing [<cite><a class="bibref"
richt@480
   889
             href="#bib-CORS">CORS</a></cite>] enabled indefinitely.
richt@480
   890
        </p>
richt@480
   891
      </section>
richt@440
   892
      <section id="privacy-considerations-for-api-implementations">
richt@447
   893
        <h3 aria-level="2"
richt@447
   894
            role="heading"
richt@447
   895
            id="h3_privacy-considerations-for-api-implementations">
richt@480
   896
          <span class="secno">4.2</span> Privacy considerations for <abbr title=
richt@440
   897
          "Application Programming Interface">API</abbr> implementations
richt@440
   898
        </h3>
richt@440
   899
        <p>
richt@440
   900
          A <a href="#dfn-user-agent"
richt@440
   901
             class="internalDFN">user agent</a> <em class="rfc2119"
richt@440
   902
             title="MUST NOT">MUST NOT</em> provide networked service information to web sites without the express
richt@440
   903
             permission of the user. A user agent <em class="rfc2119"
richt@440
   904
             title="MUST">MUST</em> acquire permission through a user interface, unless they have prearranged trust
richt@440
   905
             relationships with users, as described below. The user interface <em class="rfc2119"
richt@480
   906
             title="MUST">MUST</em> include the document base URL. Those permissions that are acquired through the user
richt@480
   907
             interface and that are preserved beyond the current browsing session (i.e. beyond the time when the
richt@480
   908
             browsing context is navigated to another URL) <em class="rfc2119"
richt@440
   909
             title="MUST">MUST</em> be revocable and a user agent <em class="rfc2119"
richt@440
   910
             title="MUST">MUST</em> respect revoked permissions.
richt@440
   911
        </p>
richt@440
   912
        <p>
richt@440
   913
          Obtaining the user's express permission to access one <abbr title=
richt@440
   914
          "Application Programming Interface">API</abbr> method does not imply the user has granted permission for the
richt@440
   915
          same web site to access any other methods that may be provided by this <abbr title=
richt@440
   916
          "Application Programming Interface">API</abbr>, or to access the same method with a different set of
richt@440
   917
          arguments, as part of the same permission context. If a user has expressed permission for an implementation
richt@440
   918
          to, e.g. find a set of existing networked services, the implementation <em class="rfc2119"
richt@440
   919
             title="MUST">MUST</em> seek the user's express permission if and when any subsequent functions are called
richt@440
   920
             on this <abbr title="Application Programming Interface">API</abbr>.
richt@440
   921
        </p>
richt@440
   922
        <p>
richt@440
   923
          A user agent <em class="rfc2119"
richt@440
   924
             title="MAY">MAY</em> have prearranged trust relationships that do not require such user interfaces. For
richt@440
   925
             example, while a web browser will present a user interface when a web site performs a networked service
richt@440
   926
             lookup, a different runtime may have a prearranged, delegated security relationship with the user and, as
richt@440
   927
             such, a suitable alternative security and privacy mechanism with which to authorise the retrieval of
richt@440
   928
             networked service information.
richt@440
   929
        </p>
richt@440
   930
      </section>
richt@440
   931
      <section class="informative"
richt@440
   932
               id="additional-api-implementation-considerations">
richt@447
   933
        <h3 aria-level="2"
richt@447
   934
            role="heading"
richt@447
   935
            id="h3_additional-api-implementation-considerations">
richt@480
   936
          <span class="secno">4.3</span> Additional <abbr title="Application Programming Interface">API</abbr>
richt@440
   937
          implementation considerations
richt@440
   938
        </h3>
richt@440
   939
        <p>
richt@440
   940
          <em>This section is non-normative.</em>
richt@440
   941
        </p>
richt@440
   942
        <p>
richt@480
   943
          Further to the requirements listed in the previous section, implementers of the Network Service Discovery
richt@440
   944
          <abbr title="Application Programming Interface">API</abbr> are also advised to consider the following aspects
richt@440
   945
          that can negatively affect the privacy of their users: in certain cases, users can inadvertently grant
richt@440
   946
          permission to the user agent to disclose networked services to Web sites. In other cases, the content hosted
richt@480
   947
          at a certain URL changes in such a way that previously granted networked service permissions no longer apply
richt@480
   948
          as far as the user is concerned. Or the users might simply change their minds.
richt@440
   949
        </p>
richt@440
   950
        <p>
richt@440
   951
          Predicting or preventing these situations is inherently difficult. Mitigation and in-depth defensive measures
richt@440
   952
          are an implementation responsibility and not prescribed by this specification. However, in designing these
richt@440
   953
          measures, implementers are advised to enable user awareness of networked service sharing, and to provide easy
richt@440
   954
          access to interfaces that enable revocation of permissions that web applications have for accessing networked
richt@440
   955
          services via this <abbr title="Application Programming Interface">API</abbr>.
richt@440
   956
        </p>
richt@440
   957
      </section>
richt@440
   958
    </section>
richt@194
   959
    <section id="requesting-networked-services">
richt@447
   960
      <h2 aria-level="1"
richt@447
   961
          role="heading"
richt@447
   962
          id="h2_requesting-networked-services">
richt@440
   963
        <span class="secno">5.</span> Requesting networked services
richt@239
   964
      </h2>
richt@437
   965
      <pre class="widl">
richt@437
   966
[Supplemental, NoInterfaceObject]
richt@180
   967
interface <dfn id="navigatornetworkservice">NavigatorNetworkService</dfn> {
richt@437
   968
  <a class="externalDFN"
richt@437
   969
     href="http://dom.spec.whatwg.org/#promise">Promise</a> <a href=
richt@437
   970
     "#dom-navigator-getnetworkservices">getNetworkServices</a>( in any type );
richt@180
   971
};
richt@447
   972
richt@437
   973
<a class="externalDFN"
richt@437
   974
     href=
richt@437
   975
     "http://www.whatwg.org/specs/web-apps/current-work/complete/timers.html#navigator">Navigator</a> implements <a href=
richt@437
   976
     "#navigatornetworkservice">NavigatorNetworkService</a>;
richt@180
   977
</pre>
richt@239
   978
      <section id="methods">
richt@447
   979
        <h3 aria-level="2"
richt@447
   980
            role="heading"
richt@447
   981
            id="h3_methods">
richt@440
   982
          <span class="secno">5.1</span> Methods
richt@239
   983
        </h3>
richt@239
   984
        <dl class="domintro">
richt@239
   985
          <dt>
richt@437
   986
            <var title="">promise</var> = <var title="">window</var> . <code title="dom-navigator"><a href=
richt@437
   987
            "http://www.whatwg.org/specs/web-apps/current-work/complete/timers.html#navigator">navigator</a></code> .
richt@437
   988
            <code title="dom-navigator-getNetworkServices"><a href=
richt@437
   989
            "#dom-navigator-getnetworkservices">getNetworkServices</a></code> ( <var title="">type</var> )
richt@239
   990
          </dt>
richt@239
   991
          <dd>
richt@239
   992
            <p>
richt@437
   993
              Immediately returns a new <a href="http://dom.spec.whatwg.org/#promise"
richt@437
   994
                 class="externalDFN">Promise</a> object and then the user is prompted to select discovered network
richt@437
   995
                 services that have advertised support for the requested service type(s).
richt@239
   996
            </p>
richt@239
   997
            <p>
richt@437
   998
              The <var title="">type</var> argument contains one or more <a href="#dfn-valid-service-type"
richt@437
   999
                 class="internalDFN">valid service type</a> tokens that the web page would like to interact with.
richt@239
  1000
            </p>
richt@239
  1001
            <p>
richt@437
  1002
              If the user accepts, the <var title="">promise</var> object is <a class="externalDFN"
richt@437
  1003
                 href="http://dom.spec.whatwg.org/#concept-resolver-resolve">resolved</a>, with a <a href=
richt@437
  1004
                 "#networkservices"><code>NetworkServices</code></a> object as its argument.
richt@239
  1005
            </p>
richt@239
  1006
            <p>
richt@437
  1007
              If the user declines, or an error occurs, the <var title="">promise</var> object is <a class=
richt@437
  1008
              "externalDFN"
richt@437
  1009
                 href="http://dom.spec.whatwg.org/#concept-resolver-reject">rejected</a>.
richt@239
  1010
            </p>
richt@239
  1011
          </dd>
richt@239
  1012
        </dl>
richt@239
  1013
        <div>
richt@180
  1014
          <p>
richt@437
  1015
            When the <dfn id="dom-navigator-getnetworkservices"
richt@437
  1016
               title="dom-navigator-getnetworkservices"><code>getNetworkServices(type)</code></dfn> method is called,
richt@437
  1017
               the <a href="#dfn-user-agent"
richt@437
  1018
               class="internalDFN">user agent</a> <em class="rfc2119"
richt@437
  1019
               title="MUST">MUST</em> run the following steps:
richt@180
  1020
          </p>
richt@180
  1021
          <ol class="rule">
richt@437
  1022
            <li>Let <var>Network Service Promise</var> be a new <a href="http://dom.spec.whatwg.org/#promise"
richt@437
  1023
                  class="externalDFN"><code>Promise</code></a> object.
richt@437
  1024
            </li>
richt@437
  1025
            <li>Let <var>Network Service Promise's Resolver</var> be the default <a href=
richt@437
  1026
            "http://dom.spec.whatwg.org/#concept-resolver"
richt@437
  1027
                  class="externalDFN">resolver</a> of <var>Network Service Promise</var>.
richt@437
  1028
            </li>
richt@437
  1029
            <li>Return <var>Network Service Promise</var>, and run the remaining steps asynchronously.
richt@437
  1030
            </li>
richt@239
  1031
            <li>Let <var>requested control types</var> be initially set to an empty array.
richt@239
  1032
            </li>
richt@437
  1033
            <li>If <var>type</var> is an array consisting of one or more <a href="#dfn-valid-service-type"
richt@484
  1034
                  class="internalDFN">valid service type</a> tokens, then let <var>requested control types</var> be the
richt@437
  1035
                  value of <var>type</var>, removing any non-<a href="#dfn-valid-service-type"
richt@437
  1036
                  class="internalDFN">valid service type</a> tokens from the resulting array.
richt@239
  1037
            </li>
richt@437
  1038
            <li>If <var>type</var> is a string consisting of one <a href="#dfn-valid-service-type"
richt@437
  1039
                  class="internalDFN">valid service type</a> token, then let <var>requested control types</var> be an
richt@437
  1040
                  array containing one item with a value of <var>type</var>.
richt@239
  1041
            </li>
richt@437
  1042
            <li>If <var>requested control types</var> is an array that contains at least one or more <a title=
richt@437
  1043
            "valid service type"
richt@437
  1044
                  href="#dfn-valid-service-type"
richt@437
  1045
                  class="internalDFN">valid service type</a> tokens then continue to the step labeled <em>process</em>
richt@437
  1046
                  below. Otherwise, reject <var>Network Service Promise</var> by running the <a href=
richt@437
  1047
                  "http://dom.spec.whatwg.org/#concept-resolver-reject"
richt@437
  1048
                  class="externalDFN">resolver reject algorithm</a> against the <var>Network Service Promise's
richt@447
  1049
                  Resolver</var>, passing in a newly constructed <a href="http://dom.spec.whatwg.org/#domerror"
richt@447
  1050
                  class="externalDFN"><code>DOMError</code></a> object whose <code>name</code> attribute has the string
richt@447
  1051
                  value "UnknownTypePrefixError" (<a href=
richt@447
  1052
                  "#dom-domerror-extensions-unknown_type_prefix"><code>UNKNOWN_TYPE_PREFIX_ERR</code></a>) and whose
richt@447
  1053
                  <code>message</code> attribute has a helpful implementation-dependent message that explains this
richt@447
  1054
                  error, abort any remaining steps and return.
richt@239
  1055
            </li>
richt@180
  1056
            <li>
richt@239
  1057
              <em>Process</em>: Let <var>services found</var> be an empty array.
richt@180
  1058
            </li>
richt@437
  1059
            <li>For each <var>available service</var> in the <a href="#dfn-list-of-available-service-records"
richt@437
  1060
                  class="internalDFN">list of available service records</a> run the following steps:
richt@239
  1061
              <ol class="rule">
richt@239
  1062
                <li>For each <var>requested control type</var> in <var>requested control types</var>: If <var>available
richt@239
  1063
                service</var>'s <code>type</code> attribute equals the <var>requested control type</var> then let <var>
richt@483
  1064
                  matched service</var> equal the value of <var>available service</var>. Otherwise, abort the remaining
richt@483
  1065
                  sub-steps and continue above at the next <var>available service</var>.
richt@239
  1066
                </li>
richt@483
  1067
                <li>If <var>matched service</var> is not empty then run the following steps:
richt@239
  1068
                  <ol class="rule">
richt@483
  1069
                    <li>Let <var>CORS check result</var> be the result of running the <a href=
richt@483
  1070
                    "#dfn-preliminary-cors-check"
richt@483
  1071
                          class="internalDFN">preliminary CORS check</a> algorithm, passing in <var>matched
richt@483
  1072
                          services</var>'s <code>url</code> attribute as the <var>control endpoint URL</var> argument
richt@483
  1073
                          and the <a href=
richt@483
  1074
                          "http://www.whatwg.org/specs/web-apps/current-work/complete/browsers.html#entry-script"
richt@483
  1075
                          class="externalDFN">entry script</a>'s <a href=
richt@483
  1076
                          "http://www.whatwg.org/specs/web-apps/current-work/complete/origin-0.html#origin"
richt@483
  1077
                          class="externalDFN">origin</a> as the <var>request origin</var> argument.
richt@483
  1078
                    </li>
richt@483
  1079
                    <li>If <var>CORS check result</var> is not <code>pass</code> and <var>matched service</var>'s
richt@483
  1080
                    <code>type</code> attribute is also not present in the <a href="#dfn-network-services-whitelist"
richt@483
  1081
                          class="internalDFN">network services whitelist</a> then abort the remaining sub-steps and
richt@483
  1082
                          continue above at the next <var>available service</var>.
richt@483
  1083
                    </li>
richt@437
  1084
                    <li>Let <var>new service object</var> be a new <a href=
richt@437
  1085
                    "#networkservice"><code>NetworkService</code></a> object, mapping the parameters of <var>matched
richt@239
  1086
                    service</var> to this new object where possible.
richt@239
  1087
                    </li>
richt@239
  1088
                    <li>Append <var>new service object</var> to the <var>services found</var> array.
richt@239
  1089
                    </li>
richt@239
  1090
                  </ol>
richt@239
  1091
                </li>
richt@239
  1092
              </ol>
richt@180
  1093
            </li>
richt@239
  1094
            <li>Optionally, e.g. based on a previously-established user preference, for security reasons, or due to
richt@437
  1095
            platform limitations, the <a href="#dfn-user-agent"
richt@437
  1096
                  class="internalDFN">user agent</a> <em class="rfc2119"
richt@437
  1097
                  title="MAY">MAY</em> reject <var>Network Service Promise</var> by running the <a href=
richt@437
  1098
                  "http://dom.spec.whatwg.org/#concept-resolver-reject"
richt@437
  1099
                  class="externalDFN">resolver reject algorithm</a> against the <var>Network Service Promise's
richt@447
  1100
                  Resolver</var>, passing in a newly constructed <a href="http://dom.spec.whatwg.org/#domerror"
richt@447
  1101
                  class="externalDFN"><code>DOMError</code></a> object whose <code>name</code> attribute has the string
richt@447
  1102
                  value "PermissionDeniedError" (<a href=
richt@447
  1103
                  "#dom-domerror-extensions-permission_denied"><code>PERMISSION_DENIED_ERR</code></a>) and whose
richt@447
  1104
                  <code>message</code> attribute has a helpful implementation-dependent message that explains this
richt@447
  1105
                  error, abort any remaining steps and return.
richt@180
  1106
            </li>
richt@437
  1107
            <li>The user agent <em class="rfc2119"
richt@437
  1108
                  title="MUST NOT">MUST NOT</em> provide the entry script's origin with a <a href=
richt@437
  1109
                  "#networkservices"><code>NetworkServices</code></a> object without prior permission given by the
richt@437
  1110
                  user.
richt@239
  1111
              <p>
richt@437
  1112
                If <var>services found</var> is not an empty array then the <a href="#dfn-user-agent"
richt@437
  1113
                   class="internalDFN">user agent</a> <em class="rfc2119"
richt@437
  1114
                   title="MAY">MAY</em> choose to prompt the user in a user-agent-specific manner for permission to
richt@437
  1115
                   provide the <a href=
richt@437
  1116
                   "http://www.whatwg.org/specs/web-apps/current-work/complete/browsers.html#entry-script"
richt@437
  1117
                   class="externalDFN">entry script</a>'s <a href=
richt@437
  1118
                   "http://www.whatwg.org/specs/web-apps/current-work/complete/origin-0.html#origin"
richt@437
  1119
                   class="externalDFN">origin</a> with a <a href="#networkservices"><code>NetworkServices</code></a>
richt@437
  1120
                   object representing the <a href="#dfn-user-authorized"
richt@437
  1121
                   class="internalDFN">user-authorized</a> subset of <var>services found</var>.
richt@180
  1122
              </p>
richt@239
  1123
              <p>
richt@437
  1124
                Alternatively, the user agent <em class="rfc2119"
richt@437
  1125
                   title="MAY">MAY</em> wish to skip this user opt-in step and choose to fulfill <var>Network Service
richt@437
  1126
                   Promise</var> immediately based on a previously-established user preference, for security reasons,
richt@437
  1127
                   or due to platform limitations. In such an implementation, if <var>Network Service Promise</var> is
richt@437
  1128
                   to be fulfilled as a result of a previously-established user preference then the <a href=
richt@437
  1129
                   "#dfn-user-agent"
richt@437
  1130
                   class="internalDFN">user agent</a> <em class="rfc2119"
richt@437
  1131
                   title="MUST">MUST</em> continue at the next step of this algorithm.
richt@379
  1132
              </p>
richt@379
  1133
              <p>
richt@437
  1134
                If permission has been granted by the user to access one or more networked services then the <a href=
richt@437
  1135
                "#dfn-user-agent"
richt@437
  1136
                   class="internalDFN">user agent</a> <em class="rfc2119"
richt@437
  1137
                   title="SHOULD">SHOULD</em> include an "ongoing local-network communication" indicator.
richt@379
  1138
              </p>
richt@379
  1139
              <p>
richt@437
  1140
                If permission has been denied by the user, <a href="#dfn-user-agent"
richt@437
  1141
                   class="internalDFN">user agent</a> or platform, then the <a href="#dfn-user-agent"
richt@437
  1142
                   class="internalDFN">user agent</a> <em class="rfc2119"
richt@437
  1143
                   title="MUST">MUST</em> reject <var>Network Service Promise</var> by running the <a href=
richt@437
  1144
                   "http://dom.spec.whatwg.org/#concept-resolver-reject"
richt@437
  1145
                   class="externalDFN">resolver reject algorithm</a> against the <var>Network Service Promise's
richt@447
  1146
                   Resolver</var>, passing in a newly constructed <a href="http://dom.spec.whatwg.org/#domerror"
richt@447
  1147
                   class="externalDFN"><code>DOMError</code></a> object whose <code>name</code> attribute has the
richt@447
  1148
                   string value "PermissionDeniedError" (<a href=
richt@447
  1149
                   "#dom-domerror-extensions-permission_denied"><code>PERMISSION_DENIED_ERR</code></a>) and whose
richt@447
  1150
                   <code>message</code> attribute has a helpful implementation-dependent message that explains this
richt@447
  1151
                   error, abort any remaining steps and return.
richt@239
  1152
              </p>
richt@180
  1153
              <p>
richt@379
  1154
                If the user never responds or no previously-established user preference has been met, this algorithm
richt@379
  1155
                stalls on this step.
richt@180
  1156
              </p>
richt@180
  1157
            </li>
richt@254
  1158
            <li>Let <var>services</var> be an empty array.
richt@180
  1159
            </li>
richt@379
  1160
            <li>If <var>services found</var> is not an empty array then set <var>services</var> to be an array of one
richt@379
  1161
            or more <a href="#networkservice"><code>NetworkService</code></a> objects for which the user granted
richt@437
  1162
            permission above - known as the current objects <dfn id="dfn-user-authorized">user-authorized</dfn>
richt@437
  1163
            services.
richt@379
  1164
            </li>
richt@254
  1165
            <li>For each Object <var>service</var> in <var>services</var>, if any, run the following sub-steps:
richt@239
  1166
              <ol class="rule">
richt@239
  1167
                <li>If <var>service</var>'s <code>type</code> parameter begins with the DOMString "<code>upnp:</code>"
richt@437
  1168
                and the <var>service</var>'s <code>eventsUrl</code> parameter is not empty then <a href=
richt@437
  1169
                "#dfn-setup-a-upnp-events-subscription"
richt@437
  1170
                      class="internalDFN">setup a UPnP Events Subscription</a> for <var>service</var>.
richt@239
  1171
                </li>
richt@239
  1172
              </ol>
richt@180
  1173
            </li>
richt@239
  1174
            <li>Let <var>services manager</var> be a new <a href="#networkservices"><code>NetworkServices</code></a>
richt@239
  1175
            object.
richt@180
  1176
            </li>
richt@379
  1177
            <li>Store <var>requested control types</var> against <var>services manager</var> as an internal variable.
richt@180
  1178
            </li>
richt@437
  1179
            <li>Set <var>services manager</var>'s <a href=
richt@437
  1180
            "#dom-networkservices-servicesavailable"><code>servicesAvailable</code></a> attribute to the number of
richt@437
  1181
            items currently found in the <a href="#dfn-list-of-available-service-records"
richt@437
  1182
                  class="internalDFN">list of available service records</a> whose <code>type</code> property matches
richt@437
  1183
                  any of the tokens requested in <var>requested control types</var>.
richt@379
  1184
            </li>
richt@379
  1185
            <li>Add <var>services</var>, if any, to the <var>services manager</var> object as its collection of
richt@484
  1186
              <a href="#dfn-indexed-properties"
richt@437
  1187
                  class="internalDFN">indexed properties</a>. If <var>services</var> is an empty array then the
richt@437
  1188
                  <var>services manager</var> does not have any <var>indexed properties</var>.
richt@180
  1189
            </li>
richt@250
  1190
            <li>Set <var>services manager</var>'s <a href="#dom-networkservices-length"><code>length</code></a>
richt@250
  1191
            attribute to the number of items in <var>services</var>.
richt@250
  1192
            </li>
richt@437
  1193
            <li>Add <var>services manager</var> to the <a href="#dfn-list-of-active-service-managers"
richt@437
  1194
                  class="internalDFN">list of active service managers</a>.
richt@250
  1195
            </li>
richt@437
  1196
            <li>The <a href="#dfn-user-agent"
richt@437
  1197
                  class="internalDFN">user agent</a> <em class="rfc2119"
richt@437
  1198
                  title="MUST">MUST</em> fulfill <var>Network Service Promise</var> by running the <a href=
richt@437
  1199
                  "http://dom.spec.whatwg.org/#concept-resolver-fulfill"
richt@437
  1200
                  class="externalDFN">resolver fulfill algorithm</a> against the <var>Network Service Promise's
richt@437
  1201
                  Resolver</var>, passing in <var>services manager</var> as its argument.
richt@180
  1202
            </li>
richt@180
  1203
          </ol>
richt@180
  1204
          <p>
richt@437
  1205
            The <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#task-source"
richt@437
  1206
               class="externalDFN">task source</a> for these <a href=
richt@437
  1207
               "http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#concept-task"
richt@437
  1208
               class="externalDFN">tasks</a> is the <a href=
richt@437
  1209
               "http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#user-interaction-task-source"
richt@437
  1210
               class="externalDFN">user interaction task source</a>.
richt@180
  1211
          </p>
richt@180
  1212
          <p>
richt@483
  1213
            The <dfn id="dfn-preliminary-cors-check">preliminary CORS check</dfn> algorithm determines whether a
richt@483
  1214
            Local-networked Service supports Cross-Origin Resource Sharing [<cite><a class="bibref"
richt@483
  1215
               href="#bib-CORS">CORS</a></cite>] as part of a call to the <a href=
richt@483
  1216
               "#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a> method, prior to that service
richt@483
  1217
               being proposed for sharing to users and prior to active sharing with web pages. This algorithm takes two
richt@483
  1218
               arguments, <var>control endpoint URL</var> and <var>request origin</var>, and consists of running the
richt@483
  1219
               following steps:
richt@483
  1220
          </p>
richt@483
  1221
          <ol class="rule">
richt@483
  1222
            <li>Let <var>CORS available check</var> be the result of applying the <a href=
richt@483
  1223
            "http://www.w3.org/TR/cors/#make-a-request-steps"
richt@483
  1224
                  class="externalDFN">make a request steps</a> [<cite><a class="bibref"
richt@483
  1225
                 href="#bib-CORS">CORS</a></cite>], setting the <a href="http://www.w3.org/TR/cors/#request-method"
richt@483
  1226
                  class="externalDFN">request method</a> to <code>OPTIONS</code>, the <a href=
richt@483
  1227
                  "http://www.w3.org/TR/cors/#request-url"
richt@483
  1228
                  class="externalDFN">request URL</a> to <var>control endpoint URL</var>, the <a href=
richt@483
  1229
                  "http://www.w3.org/TR/cors/#source-origin"
richt@483
  1230
                  class="externalDFN">source origin</a> to <var>request origin</var>, setting the <a href=
richt@483
  1231
                  "http://www.w3.org/TR/cors/#omit-credentials-flag"
richt@483
  1232
                  class="externalDFN">omit credentials flag</a> to <code>true</code> and including an <a href=
richt@483
  1233
                  "http://www.w3.org/TR/cors/#http-access-control-request-method"
richt@483
  1234
                  class="externalDFN"><code>Access-Control-Request-Method</code></a> header with a value of
richt@483
  1235
                  <code>GET</code>.
richt@483
  1236
            </li>
richt@483
  1237
            <li>If <var>CORS available check</var> is cancelled by the user, or it results in a network error, or its
richt@483
  1238
            response does not have an <abbr title="Hypertext Transfer Protocol">HTTP</abbr> status code of
richt@483
  1239
            <code>200</code> then abort any remaining steps and return <code>fail</code>.
richt@483
  1240
            </li>
richt@483
  1241
            <li>Return the result of running the <a href="http://www.w3.org/TR/cors/#resource-sharing-check"
richt@483
  1242
                  class="externalDFN">resource sharing check</a> [<cite><a class="bibref"
richt@483
  1243
                 href="#bib-CORS">CORS</a></cite>] against the successful <abbr title=
richt@483
  1244
                 "Hypertext Transfer Protocol">HTTP</abbr> response of the <var>CORS available check</var>.
richt@483
  1245
              <div class="note">
richt@483
  1246
                <div class="note-title"
richt@483
  1247
                     aria-level="3"
richt@483
  1248
                     role="heading"
richt@483
  1249
                     id="h_note_1">
richt@483
  1250
                  <span>Note</span>
richt@483
  1251
                </div>
richt@483
  1252
                <p class="">
richt@483
  1253
                  This returned result will always be either <code>pass</code> or <code>fail</code>.
richt@483
  1254
                </p>
richt@483
  1255
              </div>
richt@483
  1256
            </li>
richt@483
  1257
          </ol>
richt@483
  1258
          <p>
richt@441
  1259
            There is no implied persistence to networked service sharing provided to a web page. It <em class="rfc2119"
richt@483
  1260
               title="MUST NOT">MUST NOT</em> be possible to access a networked service previously granted to a web
richt@483
  1261
               page without user authorization in all of the following cases:
richt@239
  1262
          </p>
richt@239
  1263
          <ul>
richt@239
  1264
            <li>If the current script is reloaded at any point in the same or different window.
richt@239
  1265
            </li>
richt@437
  1266
            <li>if the current script reinvokes the <a href=
richt@437
  1267
            "#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a> method at any point in its
richt@239
  1268
            execution.
richt@239
  1269
            </li>
richt@239
  1270
            <li>If the user navigates forward or back in their history to reload the current page.
richt@239
  1271
            </li>
richt@239
  1272
            <li>If a script is running in a different origin.
richt@239
  1273
            </li>
richt@239
  1274
          </ul>
richt@239
  1275
        </div>
richt@180
  1276
      </section>
richt@194
  1277
      <section id="error-handling">
richt@447
  1278
        <h3 aria-level="2"
richt@447
  1279
            role="heading"
richt@447
  1280
            id="h3_error-handling">
richt@440
  1281
          <span class="secno">5.2</span> Error Handling
richt@239
  1282
        </h3>
richt@239
  1283
        <dl class="domintro">
richt@239
  1284
          <dt>
richt@447
  1285
            <var title="">error</var> . <code title="dom-NavigatorNetworkServiceError-name"><a href=
richt@447
  1286
            "#dom-domerror-extensions-name">name</a></code>
richt@239
  1287
          </dt>
richt@239
  1288
          <dd>
richt@239
  1289
            <p>
richt@447
  1290
              Returns the current error's error name. At the current time, this will be "PermissionDeniedError" or
richt@447
  1291
              "UnknownTypePrefixError", for which the corresponding error constants <a href=
richt@447
  1292
              "#dom-domerror-extensions-permission_denied"><code>PERMISSION_DENIED_ERR</code></a> and <a href=
richt@447
  1293
              "#dom-domerror-extensions-unknown_type_prefix"><code>UNKNOWN_TYPE_PREFIX_ERR</code></a> are defined.
richt@239
  1294
            </p>
richt@239
  1295
          </dd>
richt@239
  1296
        </dl>
richt@239
  1297
        <p>
richt@447
  1298
          The <dfn id="dom-domerror-extensions-name"
richt@447
  1299
             title="dom-domerror-extensions-name"><code>name</code></dfn> attribute of a <a href=
richt@447
  1300
             "http://dom.spec.whatwg.org/#domerror"
richt@447
  1301
             class="externalDFN"><code>DOMError</code></a> object returned from this <abbr title=
richt@447
  1302
             "Application Programming Interface">API</abbr> <em class="ct"><em class="rfc2119"
richt@447
  1303
              title="MUST">MUST</em></em> return the name for the error, which will be one of the following:
richt@239
  1304
        </p>
richt@239
  1305
        <dl>
richt@239
  1306
          <dt>
richt@447
  1307
            <dfn id="dom-domerror-extensions-permission_denied"
richt@447
  1308
                title="dom-domerror-extensions-permission_denied"><code>PERMISSION_DENIED_ERR</code></dfn> (DOMString
richt@447
  1309
                value "PermissionDeniedError")
richt@239
  1310
          </dt>
richt@239
  1311
          <dd>
richt@239
  1312
            The user or user agent denied the page permission to access any services.
richt@239
  1313
          </dd>
richt@239
  1314
          <dt>
richt@447
  1315
            <dfn id="dom-domerror-extensions-unknown_type_prefix"
richt@447
  1316
                title="dom-domerror-extensions-unknown_type_prefix"><code>UNKNOWN_TYPE_PREFIX_ERR</code></dfn>
richt@447
  1317
                (DOMString value "UnknownTypePrefixError")
richt@239
  1318
          </dt>
richt@239
  1319
          <dd>
richt@437
  1320
            No <a href="#dfn-valid-service-type"
richt@437
  1321
                class="internalDFN">valid service type</a> tokens were provided in the method invocation.
richt@239
  1322
          </dd>
richt@239
  1323
        </dl>
richt@180
  1324
      </section>
richt@239
  1325
    </section>
richt@239
  1326
    <section id="obtaining-networked-services">
richt@447
  1327
      <h2 aria-level="1"
richt@447
  1328
          role="heading"
richt@447
  1329
          id="h2_obtaining-networked-services">
richt@440
  1330
        <span class="secno">6.</span> Obtaining networked services
richt@239
  1331
      </h2>
richt@180
  1332
      <p>
richt@379
  1333
        The <a href="#networkservices"><code>NetworkServices</code></a> interface represents a collection of zero or
richt@484
  1334
        more <a href="#dfn-indexed-properties"
richt@484
  1335
           class="internalDFN">indexed properties</a> that are each a <a href="#dfn-user-authorized"
richt@437
  1336
           class="internalDFN">user-authorized</a> <a href="#networkservice"><code>NetworkService</code></a> object.
richt@254
  1337
      </p>
richt@254
  1338
      <p>
richt@437
  1339
        A <a href="#networkservices"><code>NetworkServices</code></a> object is the <a href=
richt@437
  1340
        "http://dom.spec.whatwg.org/#concept-promise-result"
richt@437
  1341
           class="externalDFN">promise result</a> from a call to <a href=
richt@437
  1342
           "#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a>.
richt@180
  1343
      </p>
richt@437
  1344
      <pre class="widl">
richt@437
  1345
[NoInterfaceObject]
richt@180
  1346
interface <dfn id="networkservices">NetworkServices</dfn> {
richt@180
  1347
  readonly attribute unsigned long    <a href="#dom-networkservices-length">length</a>;
richt@180
  1348
  getter <a href="#networkservice">NetworkService</a> (unsigned long index);
richt@437
  1349
  <a href="#networkservice">NetworkService</a>? <a href=
richt@437
  1350
"#dom-networkservices-getservicebyid">getServiceById</a>(DOMString id);
richt@180
  1351
richt@180
  1352
  readonly attribute unsigned long    <a href="#dom-networkservices-servicesavailable">servicesAvailable</a>;
richt@180
  1353
richt@180
  1354
  // event handler attributes
richt@437
  1355
           attribute <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler"
richt@448
  1356
     class="externalDFN">EventHandler</a>     <a href="#dom-networkservices-onservicefound">onservicefound</a>;
richt@437
  1357
           attribute <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler"
richt@448
  1358
     class="externalDFN">EventHandler</a>     <a href="#dom-networkservices-onservicelost">onservicelost</a>;
richt@180
  1359
richt@180
  1360
};
richt@180
  1361
richt@437
  1362
<a href="#networkservices">NetworkServices</a> implements <a href=
richt@437
  1363
"http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#interface-eventtarget"
richt@437
  1364
     class="externalDFN">EventTarget</a>;
richt@180
  1365
</pre>
richt@194
  1366
      <section id="attributes">
richt@447
  1367
        <h3 aria-level="2"
richt@447
  1368
            role="heading"
richt@447
  1369
            id="h3_attributes">
richt@440
  1370
          <span class="secno">6.1</span> Attributes
richt@239
  1371
        </h3>
richt@180
  1372
        <dl class="domintro">
richt@180
  1373
          <dt>
richt@239
  1374
            <code title="dom-networkservices-length"><a href="#dom-networkservices-length">length</a></code>
richt@180
  1375
          </dt>
richt@180
  1376
          <dd>
richt@180
  1377
            <p>
richt@484
  1378
              Returns the current number of <a href="#dfn-indexed-properties"
richt@437
  1379
                 class="internalDFN">indexed properties</a> in the current object's collection.
richt@180
  1380
            </p>
richt@180
  1381
          </dd>
richt@180
  1382
          <dt>
richt@437
  1383
            <code title="dom-networkservices-servicesavailable"><a href=
richt@437
  1384
            "#dom-networkservices-servicesavailable">servicesAvailable</a></code>
richt@180
  1385
          </dt>
richt@180
  1386
          <dd>
richt@180
  1387
            <p>
richt@437
  1388
              Returns the current number of items matching one of the app-requested <a href="#dfn-valid-service-type"
richt@437
  1389
                 class="internalDFN">valid service type</a> tokens in the <a href=
richt@437
  1390
                 "#dfn-list-of-available-service-records"
richt@437
  1391
                 class="internalDFN">list of available service records</a>.
richt@180
  1392
            </p>
richt@180
  1393
          </dd>
richt@180
  1394
        </dl>
richt@180
  1395
        <div>
richt@239
  1396
          <p>
richt@437
  1397
            The <dfn id="dom-networkservices-length"><code>length</code></dfn> attribute <em class="rfc2119"
richt@437
  1398
               title="MUST">MUST</em> return the number of <a href="#networkservice"><code>NetworkService</code></a>
richt@437
  1399
               objects represented by the collection.
richt@239
  1400
          </p>
richt@239
  1401
          <p>
richt@437
  1402
            The <dfn id="dom-networkservices-servicesavailable"><code>servicesAvailable</code></dfn> attribute
richt@437
  1403
            <em class="rfc2119"
richt@437
  1404
               title="MUST">MUST</em> return the number of services in the <a href=
richt@437
  1405
               "#dfn-list-of-available-service-records"
richt@437
  1406
               class="internalDFN">list of available service records</a> whose <code>type</code> attribute matches any
richt@437
  1407
               of the <a href="#dfn-valid-service-type"
richt@437
  1408
               class="internalDFN">valid service type</a> tokens that were initially used to create the current <a href=
richt@437
  1409
               "#networkservices"><code>NetworkServices</code></a> object.
richt@239
  1410
          </p>
richt@180
  1411
        </div>
richt@180
  1412
      </section>
richt@194
  1413
      <section id="methods-1">
richt@447
  1414
        <h3 aria-level="2"
richt@447
  1415
            role="heading"
richt@447
  1416
            id="h3_methods-1">
richt@440
  1417
          <span class="secno">6.2</span> Methods
richt@239
  1418
        </h3>
richt@180
  1419
        <dl class="domintro">
richt@239
  1420
          <dt>
richt@437
  1421
            <code title="networkservices-getter"><a href="#networkservices">services</a></code> [ <var title=
richt@437
  1422
            "">index</var> ]
richt@239
  1423
          </dt>
richt@239
  1424
          <dd>
richt@239
  1425
            <p>
richt@239
  1426
              Returns the specified <a href="#networkservice"><code>NetworkService</code></a> object.
richt@239
  1427
            </p>
richt@239
  1428
          </dd>
richt@239
  1429
          <dt>
richt@437
  1430
            <code title="networkservices-getter"><a href="#networkservices">services</a></code> . <code title=
richt@437
  1431
            "dom-networkservices-getservicebyid"><a href=
richt@437
  1432
            "#dom-networkservices-getservicebyid">getServiceById</a></code> ( <var title="">id</var> )
richt@239
  1433
          </dt>
richt@239
  1434
          <dd>
richt@239
  1435
            <p>
richt@239
  1436
              Returns the <a href="#networkservice"><code>NetworkService</code></a> object with the given identifier,
richt@239
  1437
              or null if no service has that identifier.
richt@239
  1438
            </p>
richt@239
  1439
          </dd>
richt@239
  1440
        </dl>
richt@239
  1441
        <p>
richt@379
  1442
          A <a href="#networkservices"><code>NetworkServices</code></a> object represents the current collection of
richt@437
  1443
          zero or more <a href="#networkservice"><code>NetworkService</code></a> objects - its <a href=
richt@484
  1444
          "#dfn-indexed-properties"
richt@484
  1445
             class="internalDFN">indexed properties</a>. The <a href="#dfn-indexed-properties"
richt@437
  1446
             class="internalDFN">indexed properties</a> of a <a href=
richt@437
  1447
             "#networkservices"><code>NetworkServices</code></a> object are <span>immutable</span> meaning that <a href=
richt@484
  1448
             "#dfn-indexed-properties"
richt@484
  1449
             class="internalDFN">indexed properties</a> cannot be added and <a href="#dfn-indexed-properties"
richt@437
  1450
             class="internalDFN">indexed properties</a> cannot be removed for the lifetime of a <a href=
richt@437
  1451
             "#networkservices"><code>NetworkServices</code></a> object.
richt@239
  1452
        </p>
richt@239
  1453
        <p>
richt@437
  1454
          The <a href=
richt@437
  1455
          "http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#supported-property-indices"
richt@437
  1456
             class="externalDFN">supported property indices</a> of <a href=
richt@437
  1457
             "#networkservices"><code>NetworkServices</code></a> objects at any instant are the numbers from zero to
richt@250
  1458
             the number of the <a href="#networkservice"><code>NetworkService</code></a> objects in the collection
richt@250
  1459
             minus one.
richt@239
  1460
        </p>
richt@437
  1461
        <div class="note">
richt@437
  1462
          <div class="note-title"
richt@447
  1463
               aria-level="3"
richt@437
  1464
               role="heading"
richt@483
  1465
               id="h_note_2">
richt@437
  1466
            <span>Note</span>
richt@437
  1467
          </div>
richt@437
  1468
          <p class="">
richt@437
  1469
            Each service in a <a href="#networkservices"><code>NetworkServices</code></a> object thus has an index; the
richt@437
  1470
            first has the index 0, and each subsequent service is numbered one higher than the previous one.
richt@437
  1471
          </p>
richt@437
  1472
        </div>
richt@239
  1473
        <p>
richt@437
  1474
          To <a href=
richt@437
  1475
          "http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#determine-the-value-of-an-indexed-property"
richt@437
  1476
             class="externalDFN">determine the value of an indexed property</a> for a given index <var>index</var> in a
richt@437
  1477
             <a href="#networkservices"><code>NetworkServices</code></a> object the user agent <em class="rfc2119"
richt@437
  1478
             title="MUST">MUST</em> return the <a href="#networkservice"><code>NetworkService</code></a> object that
richt@437
  1479
             represents the <var>index</var>th item in the collection.
richt@239
  1480
        </p>
richt@239
  1481
        <p>
richt@437
  1482
          The <dfn id="dom-networkservices-getservicebyid"><code>getServiceById(id)</code></dfn> method <em class=
richt@437
  1483
          "ct"><em class="rfc2119"
richt@437
  1484
              title="MUST">MUST</em></em> return the first <a href="#networkservice"><code>NetworkService</code></a>
richt@437
  1485
              object in the collection whose <a href="#dom-networkservice-id"><code>id</code></a> attribute is equal to
richt@437
  1486
              the value of the <var>id</var> argument provided. When no <a href=
richt@437
  1487
              "#networkservice"><code>NetworkService</code></a> objects match the given argument, the method <em class=
richt@437
  1488
              "rfc2119"
richt@437
  1489
             title="MUST">MUST</em> return null.
richt@239
  1490
        </p>
richt@180
  1491
      </section>
richt@194
  1492
      <section id="events">
richt@447
  1493
        <h3 aria-level="2"
richt@447
  1494
            role="heading"
richt@447
  1495
            id="h3_events">
richt@440
  1496
          <span class="secno">6.3</span> Events
richt@239
  1497
        </h3>
richt@239
  1498
        <p>
richt@437
  1499
          The following are the event handlers (and their corresponding event handler event types) that <em class=
richt@437
  1500
          "ct"><em class="rfc2119"
richt@437
  1501
              title="MUST">MUST</em></em> be supported, as IDL attributes, by all objects implementing the <a href=
richt@437
  1502
              "#networkservices"><code>NetworkServices</code></a> interface:
richt@239
  1503
        </p>
richt@243
  1504
        <table border="1">
richt@239
  1505
          <thead>
richt@239
  1506
            <tr>
richt@239
  1507
              <th>
richt@239
  1508
                <span title="event handlers">Event handler</span>
richt@239
  1509
              </th>
richt@239
  1510
              <th>
richt@239
  1511
                <span>Event handler event type</span>
richt@239
  1512
              </th>
richt@239
  1513
            </tr>
richt@239
  1514
          </thead>
richt@239
  1515
          <tbody>
richt@239
  1516
            <tr>
richt@239
  1517
              <td>
richt@448
  1518
                <dfn id="dom-networkservices-onservicefound"
richt@448
  1519
                    title="dom-NetworkServices-onservicefound"><code>onservicefound</code></dfn>
richt@239
  1520
              </td>
richt@239
  1521
              <td>
richt@448
  1522
                <a href="#event-servicefound"><code>servicefound</code></a>
richt@239
  1523
              </td>
richt@239
  1524
            </tr>
richt@239
  1525
            <tr>
richt@239
  1526
              <td>
richt@448
  1527
                <dfn id="dom-networkservices-onservicelost"
richt@448
  1528
                    title="dom-NetworkServices-onservicelost"><code>onservicelost</code></dfn>
richt@239
  1529
              </td>
richt@239
  1530
              <td>
richt@448
  1531
                <a href="#event-servicelost"><code>servicelost</code></a>
richt@239
  1532
              </td>
richt@239
  1533
            </tr>
richt@239
  1534
          </tbody>
richt@239
  1535
        </table>
richt@180
  1536
      </section>
richt@194
  1537
    </section>
richt@194
  1538
    <section id="communicating-with-a-networked-service">
richt@447
  1539
      <h2 aria-level="1"
richt@447
  1540
          role="heading"
richt@447
  1541
          id="h2_communicating-with-a-networked-service">
richt@440
  1542
        <span class="secno">7.</span> Communicating with a networked service
richt@239
  1543
      </h2>
richt@239
  1544
      <p>
richt@239
  1545
        The <a href="#networkservice"><code>NetworkService</code></a> interface is used to provide a set of connection
richt@437
  1546
        information for an <abbr title="Hypertext Transfer Protocol">HTTP</abbr> service endpoint and if available,
richt@437
  1547
        service events, running on a networked device.
richt@239
  1548
      </p>
richt@437
  1549
      <pre class="widl">
richt@437
  1550
[NoInterfaceObject]
richt@180
  1551
interface <dfn id="networkservice">NetworkService</dfn> {
richt@180
  1552
  readonly attribute DOMString        <a href="#dom-networkservice-id">id</a>;
richt@180
  1553
  readonly attribute DOMString        <a href="#dom-networkservice-name">name</a>;
richt@180
  1554
  readonly attribute DOMString        <a href="#dom-networkservice-type">type</a>;
richt@180
  1555
  readonly attribute DOMString        <a href="#dom-networkservice-url">url</a>;
richt@180
  1556
  readonly attribute DOMString        <a href="#dom-networkservice-config">config</a>;
richt@180
  1557
richt@191
  1558
  readonly attribute boolean          <a href="#dom-networkservice-online">online</a>;
richt@180
  1559
richt@180
  1560
  // event handler attributes
richt@437
  1561
           attribute <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler"
richt@448
  1562
     class="externalDFN">EventHandler</a>     <a href="#dom-networkservice-onavailable">onavailable</a>;
richt@437
  1563
           attribute <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler"
richt@448
  1564
     class="externalDFN">EventHandler</a>     <a href="#dom-networkservice-onunavailable">onunavailable</a>;
richt@191
  1565
richt@437
  1566
           attribute <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#eventhandler"
richt@437
  1567
     class="externalDFN">EventHandler</a>     <a href="#dom-networkservice-onnotify">onnotify</a>;
richt@180
  1568
};
richt@180
  1569
richt@437
  1570
<a href="#networkservice">NetworkService</a> implements <a href=
richt@437
  1571
"http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#interface-eventtarget"
richt@437
  1572
     class="externalDFN">EventTarget</a>;
richt@180
  1573
</pre>
richt@239
  1574
      <section id="attributes-1">
richt@447
  1575
        <h3 aria-level="2"
richt@447
  1576
            role="heading"
richt@447
  1577
            id="h3_attributes-1">
richt@440
  1578
          <span class="secno">7.1</span> Attributes
richt@239
  1579
        </h3>
richt@239
  1580
        <dl class="domintro">
richt@239
  1581
          <dt>
richt@437
  1582
            <var title="">service</var> . <code title="dom-networkservice-id"><a href=
richt@437
  1583
            "#dom-networkservice-id">id</a></code>
richt@239
  1584
          </dt>
richt@239
  1585
          <dd>
richt@239
  1586
            <p>
richt@239
  1587
              A unique identifier for the given user-selected service instance.
richt@239
  1588
            </p>
richt@239
  1589
          </dd>
richt@239
  1590
          <dt>
richt@437
  1591
            <var title="">service</var> . <code title="dom-networkservice-name"><a href=
richt@437
  1592
            "#dom-networkservice-name">name</a></code>
richt@239
  1593
          </dt>
richt@239
  1594
          <dd>
richt@239
  1595
            <p>
richt@239
  1596
              The name of the user-selected service.
richt@239
  1597
            </p>
richt@239
  1598
          </dd>
richt@239
  1599
          <dt>
richt@437
  1600
            <var title="">service</var> . <code title="dom-networkservice-type"><a href=
richt@437
  1601
            "#dom-networkservice-type">type</a></code>
richt@239
  1602
          </dt>
richt@239
  1603
          <dd>
richt@239
  1604
            <p>
richt@437
  1605
              The <a href="#dfn-valid-service-type"
richt@437
  1606
                 class="internalDFN">valid service type</a> token value of the user-selected service.
richt@239
  1607
            </p>
richt@239
  1608
          </dd>
richt@239
  1609
          <dt>
richt@437
  1610
            <var title="">service</var> . <code title="dom-networkservice-url"><a href=
richt@437
  1611
            "#dom-networkservice-url">url</a></code>
richt@239
  1612
          </dt>
richt@239
  1613
          <dd>
richt@239
  1614
            <p>
richt@480
  1615
              The control URL endpoint (including any required port information) of the user-selected control service.
richt@239
  1616
            </p>
richt@239
  1617
          </dd>
richt@239
  1618
          <dt>
richt@437
  1619
            <var title="">service</var> . <code title="dom-networkservice-config"><a href=
richt@437
  1620
            "#dom-networkservice-config">config</a></code>
richt@239
  1621
          </dt>
richt@239
  1622
          <dd>
richt@239
  1623
            <p>
richt@239
  1624
              The configuration information associated with the service depending on the requested service type.
richt@239
  1625
            </p>
richt@239
  1626
          </dd>
richt@239
  1627
        </dl>
richt@239
  1628
        <p>
richt@239
  1629
          The <dfn id="dom-networkservice-id"><code>id</code></dfn> attribute is a unique identifier for the service.
richt@437
  1630
          The same service provided at different times or on different objects <em class="rfc2119"
richt@437
  1631
             title="MUST">MUST</em> have the same <a href="#dom-networkservice-id"><code>id</code></a> value.
richt@239
  1632
        </p>
richt@239
  1633
        <p>
richt@239
  1634
          The <dfn id="dom-networkservice-name"><code>name</code></dfn> attribute represents a human-readable title for
richt@239
  1635
          the service.
richt@239
  1636
        </p>
richt@239
  1637
        <p>
richt@437
  1638
          The <dfn id="dom-networkservice-type"><code>type</code></dfn> attribute reflects the value of the <a href=
richt@437
  1639
          "#dfn-valid-service-type"
richt@437
  1640
             class="internalDFN">valid service type</a> of the service.
richt@239
  1641
        </p>
richt@239
  1642
        <p>
richt@437
  1643
          The <dfn id="dom-networkservice-url"><code>url</code></dfn> attribute is an <a href=
richt@453
  1644
          "http://url.spec.whatwg.org/#concept-absolute-url"
richt@480
  1645
             class="externalDFN">absolute URL</a> pointing to the root <abbr title=
richt@480
  1646
             "Hypertext Transfer Protocol">HTTP</abbr> endpoint for the service. Web pages can subsequently use this
richt@480
  1647
             value for implicit cross-document messaging via various existing mechanisms (e.g. Web Sockets, Server-Sent
richt@480
  1648
             Events, Web Messaging, XMLHttpRequest).
richt@239
  1649
        </p>
richt@239
  1650
        <p>
richt@239
  1651
          The <dfn id="dom-networkservice-config"><code>config</code></dfn> attribute provides the raw configuration
richt@239
  1652
          information extracted from the given network service.
richt@239
  1653
        </p>
richt@239
  1654
      </section>
richt@239
  1655
      <section id="states">
richt@447
  1656
        <h3 aria-level="2"
richt@447
  1657
            role="heading"
richt@447
  1658
            id="h3_states">
richt@440
  1659
          <span class="secno">7.2</span> States
richt@239
  1660
        </h3>
richt@239
  1661
        <dl class="domintro">
richt@239
  1662
          <dt>
richt@437
  1663
            <var title="">service</var> . <code title="dom-networkservice-online"><a href=
richt@437
  1664
            "#dom-networkservice-online">online</a></code>
richt@239
  1665
          </dt>
richt@239
  1666
          <dd>
richt@239
  1667
            <p>
richt@239
  1668
              Returns <code>true</code> if the service is reporting that it is accessible on the local network or
richt@390
  1669
              <code>false</code> if the service is no longer accessible (temporarily or permanently) on the local
richt@390
  1670
              network.
richt@239
  1671
            </p>
richt@239
  1672
          </dd>
richt@239
  1673
        </dl>
richt@239
  1674
        <p>
richt@239
  1675
          The <dfn id="dom-networkservice-online"><code>online</code></dfn> attribute indicates whether the service is
richt@390
  1676
          either <var>online</var>, and therefore accessible on the local network, in which case this attribute will
richt@390
  1677
          return <code>true</code> or, <var>offline</var>, and therefore not accessible on the local network, either
richt@437
  1678
          temporarily or permanently, in which case this attribute will return <code>false</code>. This attribute
richt@437
  1679
          <em class="rfc2119"
richt@437
  1680
             title="MUST">MUST</em> default to <code>true</code>.
richt@239
  1681
        </p>
richt@239
  1682
      </section>
richt@239
  1683
      <section id="events-1">
richt@447
  1684
        <h3 aria-level="2"
richt@447
  1685
            role="heading"
richt@447
  1686
            id="h3_events-1">
richt@440
  1687
          <span class="secno">7.3</span> Events
richt@239
  1688
        </h3>
richt@239
  1689
        <p>
richt@437
  1690
          The following are the event handlers (and their corresponding event handler event types) that <em class=
richt@437
  1691
          "ct"><em class="rfc2119"
richt@437
  1692
              title="MUST">MUST</em></em> be supported, as IDL attributes, by all objects implementing the <a href=
richt@437
  1693
              "#networkservice"><code>NetworkService</code></a> interface:
richt@239
  1694
        </p>
richt@243
  1695
        <table border="1">
richt@239
  1696
          <thead>
richt@239
  1697
            <tr>
richt@239
  1698
              <th>
richt@239
  1699
                <span title="event handlers">Event handler</span>
richt@239
  1700
              </th>
richt@239
  1701
              <th>
richt@239
  1702
                <span>Event handler event type</span>
richt@239
  1703
              </th>
richt@239
  1704
            </tr>
richt@239
  1705
          </thead>
richt@239
  1706
          <tbody>
richt@239
  1707
            <tr>
richt@239
  1708
              <td>
richt@437
  1709
                <dfn id="dom-networkservice-onnotify"
richt@437
  1710
                    title="dom-NetworkService-onnotify"><code>onnotify</code></dfn>
richt@239
  1711
              </td>
richt@239
  1712
              <td>
richt@239
  1713
                <a href="#event-notify"><code>notify</code></a>
richt@239
  1714
              </td>
richt@239
  1715
            </tr>
richt@239
  1716
            <tr>
richt@239
  1717
              <td>
richt@448
  1718
                <dfn id="dom-networkservice-onavailable"
richt@448
  1719
                    title="dom-NetworkService-onavailable"><code>onavailable</code></dfn>
richt@239
  1720
              </td>
richt@239
  1721
              <td>
richt@448
  1722
                <a href="#event-available"><code>available</code></a>
richt@239
  1723
              </td>
richt@239
  1724
            </tr>
richt@239
  1725
            <tr>
richt@239
  1726
              <td>
richt@448
  1727
                <dfn id="dom-networkservice-onunavailable"
richt@448
  1728
                    title="dom-NetworkService-onunavailable"><code>onunavailable</code></dfn>
richt@239
  1729
              </td>
richt@239
  1730
              <td>
richt@448
  1731
                <a href="#event-unavailable"><code>unavailable</code></a>
richt@239
  1732
              </td>
richt@239
  1733
            </tr>
richt@239
  1734
          </tbody>
richt@239
  1735
        </table>
richt@239
  1736
      </section>
richt@239
  1737
    </section>
richt@239
  1738
    <section id="service-discovery">
richt@447
  1739
      <h2 aria-level="1"
richt@447
  1740
          role="heading"
richt@447
  1741
          id="h2_service-discovery">
richt@440
  1742
        <span class="secno">8.</span> Service Discovery
richt@239
  1743
      </h2>
richt@239
  1744
      <p>
richt@437
  1745
        A <a href="#dfn-user-agent"
richt@437
  1746
           class="internalDFN">user agent</a> conforming to this specification <em class="rfc2119"
richt@437
  1747
           title="MAY">MAY</em> implement <abbr title="Simple Service Discovery Protocol">SSDP</abbr> [<cite><a class=
richt@437
  1748
           "bibref"
richt@437
  1749
           href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>], Zeroconf [<cite><a class="bibref"
richt@437
  1750
           href="#bib-DNS-SD">DNS-SD</a></cite>] + [<cite><a class="bibref"
richt@437
  1751
           href="#bib-MDNS">MDNS</a></cite>] and/or <abbr title="Discovery and Launch Protocol">DIAL</abbr> [<a href=
richt@437
  1752
           "https://sites.google.com/a/dial-multiscreen.org/dial/dial-protocol-specification"><abbr title=
richt@437
  1753
           "Discovery and Launch Protocol">DIAL</abbr></a>] <dfn id="dfn-service-discovery-mechanisms">service
richt@437
  1754
           discovery mechanisms</dfn> - the requirements detailed in this section of the specification - to enable Web
richt@437
  1755
           pages to request and connect with <abbr title="Hypertext Transfer Protocol">HTTP</abbr> services running on
richt@437
  1756
           networked devices, discovered via any of these mechanisms, through this <abbr title=
richt@437
  1757
           "Application Programming Interface">API</abbr>. When a <a href="#dfn-user-agent"
richt@437
  1758
           class="internalDFN">user agent</a> implements any of these <a href="#dfn-service-discovery-mechanisms"
richt@437
  1759
           class="internalDFN">service discovery mechanisms</a>, then it <em class="rfc2119"
richt@437
  1760
           title="MUST">MUST</em> conform to the corresponding algorithms provided in this section of the
richt@437
  1761
           specification.
richt@239
  1762
      </p>
richt@239
  1763
      <p>
richt@437
  1764
        This section presents how the results of these <a href="#dfn-service-discovery-mechanisms"
richt@437
  1765
           class="internalDFN">service discovery mechanisms</a> will be matched to requested service types, how the
richt@437
  1766
           user agent stores available and active services and how their properties are applied to any resulting
richt@437
  1767
           <a href="#networkservice"><code>NetworkService</code></a> objects.
richt@239
  1768
      </p>
richt@239
  1769
      <p>
richt@437
  1770
        It is expected that user agents will perform these <a href="#dfn-service-discovery-mechanisms"
richt@437
  1771
           class="internalDFN">service discovery mechanisms</a> asynchronously and periodically update the <a href=
richt@437
  1772
           "#dfn-list-of-available-service-records"
richt@437
  1773
           class="internalDFN">list of available service records</a> as required. The timing of any <a href=
richt@437
  1774
           "#dfn-service-discovery-mechanisms"
richt@437
  1775
           class="internalDFN">service discovery mechanisms</a> is an implementation detail left to the discretion of
richt@437
  1776
           the implementer (e.g. by continuously monitoring the network as a background process or on invocation of
richt@437
  1777
           this <abbr title="Application Programming Interface">API</abbr> from a Web page).
richt@239
  1778
      </p>
richt@239
  1779
      <p>
richt@437
  1780
        The <dfn id="dfn-list-of-available-service-records">list of available service records</dfn> is a single dynamic
richt@437
  1781
        internal lookup table within user agents that is used to track all the services that have been discovered and
richt@440
  1782
        are available in the current network at the current time. At any point during the running of any of the
richt@437
  1783
        <a href="#dfn-service-discovery-mechanisms"
richt@437
  1784
           class="internalDFN">service discovery mechanisms</a> then existing entries within this table can be updated,
richt@437
  1785
           entries can be added and entries can be removed as the status of networked services changes according to the
richt@437
  1786
           rules defined in this specification.
richt@239
  1787
      </p>
richt@239
  1788
      <p>
richt@437
  1789
        The <dfn id="dfn-list-of-active-service-managers">list of active service managers</dfn> is an internal list
richt@437
  1790
        within user agents that is used to track all <a href="#networkservices"><code>NetworkServices</code></a>
richt@437
  1791
        objects currently being shared with any web pages at the current time within the user agent. Each <a href=
richt@437
  1792
        "#networkservices"><code>NetworkServices</code></a> object in the <a href=
richt@437
  1793
        "#dfn-list-of-active-service-managers"
richt@437
  1794
           class="internalDFN">list of active service managers</a> represents a collection of zero or more <a href=
richt@437
  1795
           "#networkservice"><code>NetworkService</code></a> objects - known as its <dfn id=
richt@484
  1796
           "dfn-indexed-properties">indexed properties</dfn>. <a href="#networkservice"><code>NetworkService</code></a>
richt@484
  1797
           objects are attached as the <a href="#dfn-indexed-properties"
richt@437
  1798
           class="internalDFN">indexed properties</a> of a <a href="#networkservices"><code>NetworkServices</code></a>
richt@437
  1799
           object as part of the <a href="#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a>
richt@437
  1800
           algorithm.
richt@239
  1801
      </p>
richt@239
  1802
      <p>
richt@437
  1803
        The rule for <dfn id="dfn-adding-an-available-service">adding an available service</dfn> is the process of
richt@437
  1804
        adding a <a href="#dfn-new-service"
richt@437
  1805
           class="internalDFN">new service</a> or updating an <a href="#dfn-existing-service"
richt@437
  1806
           class="internalDFN">existing service</a> that is generally available on the user's current network in the
richt@437
  1807
           <a href="#dfn-list-of-available-service-records"
richt@437
  1808
           class="internalDFN">list of available service records</a>. This rule takes one argument, <var>network
richt@437
  1809
           service record</var>, and consists of running the following steps:
richt@239
  1810
      </p>
richt@239
  1811
      <ol class="rule">
richt@437
  1812
        <li>For each <var>existing service record</var> in the current <a href="#dfn-list-of-available-service-records"
richt@437
  1813
              class="internalDFN">list of available service records</a>, run the following sub-steps:
richt@239
  1814
          <ol class="rule">
richt@239
  1815
            <li>If the <var>existing service record</var>'s <code>id</code> property does not equal <var>network
richt@239
  1816
            service record</var>'s <code>id</code> property then abort any remaining sub-steps and continue at the next
richt@239
  1817
            available <var>existing service record</var>.
richt@239
  1818
            </li>
richt@437
  1819
            <li>Replace the value of <var>existing service record</var> in the current <a href=
richt@437
  1820
            "#dfn-list-of-available-service-records"
richt@437
  1821
                  class="internalDFN">list of available service records</a> with the value of <var>network service
richt@437
  1822
                  record</var>, aborting any remaining steps in this algorithm and return.
richt@239
  1823
            </li>
richt@239
  1824
          </ol>
richt@239
  1825
        </li>
richt@437
  1826
        <li>Add <var>network service record</var> to the <a href="#dfn-list-of-available-service-records"
richt@437
  1827
              class="internalDFN">list of available service records</a> as a new item.
richt@239
  1828
        </li>
richt@437
  1829
        <li>For each <var>service manager</var> in the <a href="#dfn-list-of-active-service-managers"
richt@437
  1830
              class="internalDFN">list of active service managers</a> run the following steps:
richt@239
  1831
          <ol class="rule">
richt@250
  1832
            <li>For each <var>active service</var> in <var>service manager</var> run the following steps:
richt@250
  1833
              <ol class="rule">
richt@379
  1834
                <li>If the <var>network service record</var>'s <code>id</code> property equals the <var>active
richt@392
  1835
                service</var>'s <code>id</code> attribute and <var>active service</var>'s <code>online</code> attribute
richt@437
  1836
                is currently set to <code>false</code> then set <var>active service</var>'s <a href=
richt@437
  1837
                "#dom-networkservice-online"><code>online</code></a> attribute to <code>true</code> and then <a href=
richt@437
  1838
                "http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task"
richt@437
  1839
                      class="externalDFN">queue a task</a> to dispatch a newly created event with the name <a href=
richt@448
  1840
                      "#event-available"><code>available</code></a> that uses the <a href=
richt@437
  1841
                      "http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event"
richt@437
  1842
                      class="externalDFN"><code>Event</code></a> interface, which does not bubble, is not cancellable,
richt@250
  1843
                      and has no default action, at the current <var>active service</var> object.
richt@250
  1844
                </li>
richt@250
  1845
              </ol>
richt@239
  1846
            </li>
richt@379
  1847
            <li>Let <var>'service type in current service manager' flag</var> be <code>false</code>.
richt@379
  1848
            </li>
richt@379
  1849
            <li>For each <var>requested control type</var> of the <var>requested control types</var> in <var>service
richt@379
  1850
            manager</var> run the following steps:
richt@379
  1851
              <ol class="rule">
richt@379
  1852
                <li>If <var>network service record</var>'s <code>type</code> property does not equal <var>requested
richt@379
  1853
                control type</var> then abort any remaining sub-steps and continue at the next available <var>requested
richt@379
  1854
                control type</var>.
richt@379
  1855
                </li>
richt@379
  1856
                <li>Set the <var>'service type in current service manager' flag</var> to <code>true</code>, abort any
richt@379
  1857
                remaining sub-steps and continue.
richt@379
  1858
                </li>
richt@379
  1859
              </ol>
richt@379
  1860
            </li>
richt@379
  1861
            <li>If the <var>'service type in current service manager' flag</var> is set to <code>true</code> then
richt@437
  1862
            increment <var>service manager</var>'s <a href=
richt@437
  1863
            "#dom-networkservices-servicesavailable"><code>servicesAvailable</code></a> attribute by <code>1</code> and
richt@437
  1864
            then <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task"
richt@437
  1865
                  class="externalDFN">queue a task</a> to dispatch a newly created event with the name <a href=
richt@448
  1866
                  "#event-servicefound"><code>servicefound</code></a> that uses the <a href=
richt@437
  1867
                  "http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event"
richt@437
  1868
                  class="externalDFN"><code>Event</code></a> interface, which does not bubble, is not cancellable, and
richt@250
  1869
                  has no default action, at the current <var>service manager</var> object.
richt@239
  1870
            </li>
richt@239
  1871
          </ol>
richt@239
  1872
        </li>
richt@239
  1873
      </ol>
richt@239
  1874
      <p>
richt@437
  1875
        The rule for <dfn id="dfn-removing-an-available-service">removing an available service</dfn> is the general
richt@437
  1876
        process of removing an <a href="#dfn-existing-service"
richt@437
  1877
           class="internalDFN">existing service</a> from the <a href="#dfn-list-of-available-service-records"
richt@437
  1878
           class="internalDFN">list of available service records</a> that has left the user's current network or has
richt@437
  1879
           otherwise expired. This rule takes one argument, <var>service identifier</var>, and consists of running the
richt@437
  1880
           following steps:
richt@239
  1881
      </p>
richt@239
  1882
      <ol class="rule">
richt@437
  1883
        <li>For each <var>existing service record</var> in the current <a href="#dfn-list-of-available-service-records"
richt@437
  1884
              class="internalDFN">list of available service records</a>, run the following sub-steps:
richt@239
  1885
          <ol class="rule">
richt@239
  1886
            <li>If the <var>existing service record</var>'s <code>id</code> property does not match <var>service
richt@239
  1887
            identifier</var> then skip any remaining sub-steps for the current <var>existing service record</var> and
richt@239
  1888
            continue at the next available <var>existing service record</var>.
richt@239
  1889
            </li>
richt@379
  1890
            <li>Let <var>'service type in use' flag</var> be <code>false</code>.
richt@239
  1891
            </li>
richt@437
  1892
            <li>For each <var>service manager</var> in the <a href="#dfn-list-of-active-service-managers"
richt@437
  1893
                  class="internalDFN">list of active service managers</a> run the following steps:
richt@239
  1894
              <ol class="rule">
richt@379
  1895
                <li>Let <var>'service type in current service manager' flag</var> be <code>false</code>.
richt@239
  1896
                </li>
richt@250
  1897
                <li>For each <var>active service</var> in <var>service manager</var> run the following steps:
richt@250
  1898
                  <ol class="rule">
richt@250
  1899
                    <li>If <var>existing service record</var>'s <code>id</code> property equals the <var>active
richt@437
  1900
                    service</var>'s <code>id</code> attribute and <var>active service</var>'s <a href=
richt@437
  1901
                    "#dom-networkservice-online"><code>online</code></a> attribute is currently set to
richt@250
  1902
                    <code>true</code> then set <var>active service</var>'s <a href="#dom-networkservice-online"><code>
richt@437
  1903
                      online</code></a> attribute to <code>false</code> and then <a href=
richt@437
  1904
                      "http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task"
richt@437
  1905
                          class="externalDFN">queue a task</a> to dispatch a newly created event with the name <a href=
richt@448
  1906
                          "#event-unavailable"><code>unavailable</code></a> that uses the <a href=
richt@437
  1907
                          "http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event"
richt@437
  1908
                          class="externalDFN"><code>Event</code></a> interface, which does not bubble, is not
richt@250
  1909
                          cancellable, and has no default action, at the current <var>active service</var>.
richt@250
  1910
                    </li>
richt@250
  1911
                  </ol>
richt@239
  1912
                </li>
richt@379
  1913
                <li>For each <var>requested control type</var> of the <var>requested control types</var> in
richt@379
  1914
                <var>service manager</var> run the following steps:
richt@379
  1915
                  <ol class="rule">
richt@379
  1916
                    <li>If <var>existing service record</var>'s <code>type</code> property does not equal
richt@379
  1917
                    <var>requested control type</var> then abort any remaining sub-steps and continue at the next
richt@379
  1918
                    available <var>requested control type</var>.
richt@379
  1919
                    </li>
richt@379
  1920
                    <li>Set the <var>'service type in current service manager' flag</var> to <code>true</code> and the
richt@379
  1921
                    <var>'service type in use' flag</var> to <code>true</code>, abort any remaining sub-steps and
richt@379
  1922
                    continue.
richt@379
  1923
                    </li>
richt@379
  1924
                  </ol>
richt@379
  1925
                </li>
richt@379
  1926
                <li>If the <var>'service type in current service manager' flag</var> is set to <code>true</code> then
richt@437
  1927
                decrement <var>service manager</var>'s <a href=
richt@437
  1928
                "#dom-networkservices-servicesavailable"><code>servicesAvailable</code></a> attribute by <code>1</code>
richt@437
  1929
                and then <a href=
richt@437
  1930
                "http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task"
richt@437
  1931
                      class="externalDFN">queue a task</a> to dispatch a newly created event with the name <a href=
richt@448
  1932
                      "#event-servicelost"><code>servicelost</code></a> that uses the <a href=
richt@437
  1933
                      "http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event"
richt@437
  1934
                      class="externalDFN"><code>Event</code></a> interface, which does not bubble, is not cancellable,
richt@250
  1935
                      and has no default action, at the current <var>service manager</var> object.
richt@239
  1936
                </li>
richt@239
  1937
              </ol>
richt@239
  1938
            </li>
richt@379
  1939
            <li>If the <var>'service type in use' flag</var> is <code>false</code> and the <var>existing service
richt@379
  1940
            record</var>'s <code>type</code> property begins with the DOMString "<code>upnp:</code>" and <var>existing
richt@437
  1941
            service record</var>'s <code>eventsURL</code> property is set then run the rule to <a href=
richt@437
  1942
            "#dfn-terminate-an-existing-upnp-events-subscription"
richt@437
  1943
                  class="internalDFN">terminate an existing UPnP Events Subscription</a>, if one is currently active
richt@437
  1944
                  (as a result of having previously called <a href="#dfn-setup-a-upnp-events-subscription"
richt@437
  1945
                  class="internalDFN">setup a UPnP Events Subscription</a> against the current <var>existing service
richt@437
  1946
                  record</var>).
richt@379
  1947
            </li>
richt@437
  1948
            <li>Remove <var>existing service record</var> from the current <a href=
richt@437
  1949
            "#dfn-list-of-available-service-records"
richt@437
  1950
                  class="internalDFN">list of available service records</a>.
richt@239
  1951
            </li>
richt@239
  1952
          </ol>
richt@239
  1953
        </li>
richt@239
  1954
      </ol>
richt@239
  1955
      <p>
richt@437
  1956
        User agents <em class="rfc2119"
richt@437
  1957
           title="SHOULD">SHOULD</em> expire a service record from the <a href="#dfn-list-of-available-service-records"
richt@437
  1958
           class="internalDFN">list of available service records</a> when its <code>expiryTimestamp</code> attribute
richt@437
  1959
           exceeds the current UTC timestamp. When this condition is met the <a href="#dfn-user-agent"
richt@437
  1960
           class="internalDFN">user agent</a> <em class="rfc2119"
richt@437
  1961
           title="SHOULD">SHOULD</em> run the rule for <a href="#dfn-removing-an-available-service"
richt@437
  1962
           class="internalDFN">removing an available service</a>, passing in the expired service record's
richt@437
  1963
           <code>id</code> attribute as the only argument.
richt@239
  1964
      </p>
richt@239
  1965
      <section id="zeroconf-mdns-dns-sd">
richt@447
  1966
        <h3 aria-level="2"
richt@447
  1967
            role="heading"
richt@447
  1968
            id="h3_zeroconf-mdns-dns-sd">
richt@440
  1969
          <span class="secno">8.1</span> Zeroconf (<abbr title="Multicast DNS">mDNS</abbr> + <abbr title=
richt@437
  1970
          "Domain Name System">DNS</abbr>-<abbr title="Service Discovery">SD</abbr>)
richt@239
  1971
        </h3>
richt@239
  1972
        <p>
richt@437
  1973
          For each <abbr title="Domain Name System">DNS</abbr> response received from a user-agent-initiated Multicast
richt@437
  1974
          <abbr title="Domain Name System">DNS</abbr> Browse for <abbr title="DNS Pointer Record">PTR</abbr> records
richt@437
  1975
          with the name <code>_services._dns-sd._udp</code> on the resolved recommended automatic browsing domain
richt@437
  1976
          [<cite><a class="bibref"
richt@437
  1977
             href="#bib-MDNS">MDNS</a></cite>], the <a href="#dfn-user-agent"
richt@437
  1978
             class="internalDFN">user agent</a> <em class="rfc2119"
richt@437
  1979
             title="MUST">MUST</em> run the following steps:
richt@239
  1980
        </p>
richt@239
  1981
        <ol class="rule">
richt@437
  1982
          <li>Let <var>service <abbr title="Multicast DNS">mDNS</abbr> responses</var> be an array of <abbr title=
richt@437
  1983
          "DNS Pointer Record">PTR</abbr> records received by issuing a Multicast <abbr title=
richt@437
  1984
          "Domain Name System">DNS</abbr> Browse for <abbr title="DNS Pointer Record">PTR</abbr> records with the name
richt@437
  1985
          of the current discovered service type.
richt@239
  1986
          </li>
richt@437
  1987
          <li>For each Object <var>service <abbr title="Multicast DNS">mDNS</abbr> response</var> in <var>service
richt@437
  1988
          <abbr title="Multicast DNS">mDNS</abbr> responses</var>, run the following steps:
richt@239
  1989
            <ol>
richt@239
  1990
              <li>Let <var>network service record</var> be an Object consisting of the following empty properties:
richt@239
  1991
              <code>id</code>, <code>name</code>, <code>type</code>, <code>url</code>, <code>config</code>,
richt@239
  1992
              <code>expiryTimestamp</code>.
richt@239
  1993
              </li>
richt@437
  1994
              <li>Set <var>network service record</var>'s <code>id</code> property to the value of the full
richt@437
  1995
                <abbr title="DNS Pointer Record">PTR</abbr> Service Instance Name [<cite><a class="bibref"
richt@437
  1996
                   href="#bib-MDNS">MDNS</a></cite>].
richt@239
  1997
              </li>
richt@437
  1998
              <li>Set <var>network service record</var>'s <code>name</code> property to the value of the <abbr title=
richt@437
  1999
              "DNS Pointer Record">PTR</abbr> Service Instance Name's <var>Instance</var> component [<cite><a class=
richt@437
  2000
              "bibref"
richt@437
  2001
                   href="#bib-MDNS">MDNS</a></cite>].
richt@239
  2002
              </li>
richt@239
  2003
              <li>Set <var>network service record</var>'s <code>type</code> property to the concatenation of the string
richt@437
  2004
              <code>zeroconf:</code> followed be the value of the <abbr title="DNS Pointer Record">PTR</abbr> Service
richt@437
  2005
              Instance Name's <var>Service</var> component [<cite><a class="bibref"
richt@437
  2006
                   href="#bib-MDNS">MDNS</a></cite>].
richt@239
  2007
              </li>
richt@480
  2008
              <li>Set <var>network service record</var>'s <code>url</code> property to the resolvable Service URL
richt@480
  2009
              obtained from performing an <abbr title="Domain Name System">DNS</abbr>-<abbr title=
richt@480
  2010
              "Service Discovery">SD</abbr> Lookup [<cite><a class="bibref"
richt@437
  2011
                   href="#bib-DNS-SD">DNS-SD</a></cite>] of the current service from the <abbr title=
richt@437
  2012
                   "DNS Pointer Record">PTR</abbr> record provided [<cite><a class="bibref"
richt@437
  2013
                   href="#bib-MDNS">MDNS</a></cite>].
richt@239
  2014
              </li>
richt@239
  2015
              <li>Set <var>network service record</var>'s <code>config</code> property to the string value of the
richt@437
  2016
              contents of the first <abbr title="Domain Name System">DNS</abbr>-<abbr title=
richt@437
  2017
              "Service Discovery">SD</abbr> TXT record associated with the <var>service <abbr title=
richt@437
  2018
              "Multicast DNS">mDNS</abbr> response</var> as defined in [<cite><a class="bibref"
richt@437
  2019
                   href="#bib-DNS-SD">DNS-SD</a></cite>].
richt@239
  2020
              </li>
richt@239
  2021
              <li>Set <var>network service record</var>'s <code>expiryTimestamp</code> property to the value of the
richt@239
  2022
              current date, in UTC timestamp format, plus a value of <code>120</code> seconds.
richt@239
  2023
              </li>
richt@483
  2024
              <li>Run the general rule for <a href="#dfn-adding-an-available-service"
richt@437
  2025
                    class="internalDFN">adding an available service</a>, passing in the current <var>network service
richt@483
  2026
                    record</var> as the only argument.
richt@239
  2027
              </li>
richt@239
  2028
            </ol>
richt@239
  2029
          </li>
richt@239
  2030
        </ol>
richt@239
  2031
      </section>
richt@239
  2032
      <section id="simple-service-discovery-protocol-ssdp">
richt@447
  2033
        <h3 aria-level="2"
richt@447
  2034
            role="heading"
richt@447
  2035
            id="h3_simple-service-discovery-protocol-ssdp">
richt@440
  2036
          <span class="secno">8.2</span> Simple Service Discovery Protocol (<abbr title=
richt@437
  2037
          "Simple Service Discovery Protocol">SSDP</abbr>)
richt@239
  2038
        </h3>
richt@239
  2039
        <p>
richt@437
  2040
          A user agent that implements UPnP service discovery <em class="rfc2119"
richt@437
  2041
             title="MUST">MUST</em> issue a <dfn id="dfn-search-request-for-upnp-root-devices">search request for UPnP
richt@437
  2042
             root devices</dfn> against the user's current local network according to the full normative text and
richt@437
  2043
             timing provided in 'Section 1.3.2: Search request with M-SEARCH' detailed in [<cite><a class="bibref"
richt@437
  2044
             href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>].
richt@239
  2045
        </p>
richt@239
  2046
        <p>
richt@437
  2047
          The user agent <em class="rfc2119"
richt@437
  2048
             title="MUST">MUST</em> issue all <a title="search request for UPnP root devices"
richt@437
  2049
             href="#dfn-search-request-for-upnp-root-devices"
richt@437
  2050
             class="internalDFN">search requests for UPnP root devices</a> with a <abbr title=
richt@437
  2051
             "Hypertext Transfer Protocol">HTTP</abbr> request line equal to <code>M-SEARCH * <abbr title=
richt@437
  2052
             "Hypertext Transfer Protocol">HTTP</abbr>/1.1</code>, with a HOST header equal to the reserved multicast
richt@437
  2053
             address and port of <code>239.255.255.250:1900</code> and a MAN header equal to
richt@437
  2054
             <code>ssdp:discover</code>. The <a href="#dfn-user-agent"
richt@437
  2055
             class="internalDFN">user agent</a> must also send an ST header with this <abbr title=
richt@437
  2056
             "Hypertext Transfer Protocol">HTTP</abbr> request equal to the String value of <code>ssdp:all</code> or
richt@437
  2057
             <code>upnp:rootdevice</code> or a single <a href="#dfn-valid-service-type"
richt@437
  2058
             class="internalDFN">valid service type</a> token beginning with the String value <code>upnp:</code>. If a
richt@437
  2059
             single <a href="#dfn-valid-service-type"
richt@437
  2060
             class="internalDFN">valid service type</a> token beginning with the String value <code>upnp:</code> is to
richt@437
  2061
             be used, the user agent <em class="rfc2119"
richt@437
  2062
             title="MUST">MUST</em> strip the leading String <code>upnp:</code> before using this value in this
richt@437
  2063
             <abbr title="Hypertext Transfer Protocol">HTTP</abbr> request. The user-agent <em class="rfc2119"
richt@437
  2064
             title="MUST">MUST</em> also send an MX header equal to a <dfn id=
richt@437
  2065
             "dfn-maximum-upnp-advertisement-response-wait-time">maximum UPnP advertisement response wait time</dfn>
richt@437
  2066
             value between <code>1</code> and <code>5</code> seconds with this <abbr title=
richt@437
  2067
             "Hypertext Transfer Protocol">HTTP</abbr> request.
richt@239
  2068
        </p>
richt@239
  2069
        <p>
richt@437
  2070
          The user agent <em class="rfc2119"
richt@437
  2071
             title="MUST">MUST</em> listen for any incoming responses to any <a href=
richt@437
  2072
             "#dfn-search-request-for-upnp-root-devices"
richt@437
  2073
             class="internalDFN">search request for UPnP root devices</a>.
richt@239
  2074
        </p>
richt@239
  2075
        <p>
richt@437
  2076
          For each <dfn id="dfn-http-response"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Response</dfn>
richt@437
  2077
          following an initial <a href="#dfn-search-request-for-upnp-root-devices"
richt@437
  2078
             class="internalDFN">search request for UPnP root devices</a> sent on a <a href=
richt@437
  2079
             "#dfn-standard-upnp-address-and-port"
richt@437
  2080
             class="internalDFN">standard UPnP address and port</a> the user agent <em class="rfc2119"
richt@437
  2081
             title="MUST">MUST</em> run the following steps:
richt@239
  2082
        </p>
richt@239
  2083
        <ol class="rule">
richt@437
  2084
          <li>If the <a href="#dfn-http-response"
richt@437
  2085
                class="internalDFN"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Response</a> is not a
richt@437
  2086
                <abbr title="Hypertext Transfer Protocol">HTTP</abbr> 200 OK response then this response is invalid and
richt@437
  2087
                the user agent <em class="rfc2119"
richt@437
  2088
                title="MUST">MUST</em> discard this response, abort any remaining steps and return. The user agent
richt@437
  2089
                <em class="rfc2119"
richt@437
  2090
                title="MAY">MAY</em> issue a new <a href="#dfn-search-request-for-upnp-root-devices"
richt@437
  2091
                class="internalDFN">search request for UPnP root devices</a> as a result of this error occurring.
richt@239
  2092
          </li>
richt@437
  2093
          <li>If the <a href="#dfn-maximum-upnp-advertisement-response-wait-time"
richt@437
  2094
                class="internalDFN">maximum UPnP advertisement response wait time</a> has been exceeded since the
richt@437
  2095
                initial <a href="#dfn-search-request-for-upnp-root-devices"
richt@437
  2096
                class="internalDFN">search request for UPnP root devices</a> was sent then the <a href=
richt@437
  2097
                "#dfn-http-response"
richt@437
  2098
                class="internalDFN"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Response</a> is invalid and
richt@437
  2099
                the user agent <em class="rfc2119"
richt@437
  2100
                title="MUST">MUST</em> discard this response, abort any remaining steps and return. The user agent
richt@437
  2101
                <em class="rfc2119"
richt@437
  2102
                title="MAY">MAY</em> stop listening for responses from the current <a href=
richt@437
  2103
                "#dfn-search-request-for-upnp-root-devices"
richt@437
  2104
                class="internalDFN">search request for UPnP root devices</a> as a result of this error occurring.
richt@437
  2105
                Equally, the user agent <em class="rfc2119"
richt@437
  2106
                title="MAY">MAY</em> issue a new <a href="#dfn-search-request-for-upnp-root-devices"
richt@437
  2107
                class="internalDFN">search request for UPnP root devices</a> as a result of this error occurring.
richt@239
  2108
          </li>
richt@437
  2109
          <li>Let <var>ssdp device</var> be an Object with a property for each <abbr title=
richt@437
  2110
          "Hypertext Transfer Protocol">HTTP</abbr> header received in the <a href="#dfn-http-response"
richt@437
  2111
                class="internalDFN"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Response</a>, with each key
richt@437
  2112
                being the name of a <abbr title="Hypertext Transfer Protocol">HTTP</abbr> response header and each
richt@437
  2113
                value being that <abbr title="Hypertext Transfer Protocol">HTTP</abbr> response header's value.
richt@239
  2114
          </li>
richt@239
  2115
          <li>If <var>ssdp device</var> does not contain at least one <var>CACHE-CONTROL</var> entry, at least one
richt@379
  2116
          <var>USN</var> entry, at least one <var>ST</var> entry and at least one <var>LOCATION</var> entry then the
richt@437
  2117
          <a href="#dfn-http-response"
richt@437
  2118
                class="internalDFN"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Response</a> is invalid and
richt@437
  2119
                the <a href="#dfn-user-agent"
richt@437
  2120
                class="internalDFN">user agent</a> <em class="rfc2119"
richt@437
  2121
                title="MUST">MUST</em> discard this response, abort any remaining steps and return.
richt@239
  2122
          </li>
richt@437
  2123
          <li>The user agent <em class="rfc2119"
richt@437
  2124
                title="MUST">MUST</em> run the rule for <a href="#dfn-obtaining-a-upnp-device-description-file"
richt@437
  2125
                class="internalDFN">obtaining a UPnP Device Description File</a> passing in the first occurrence of
richt@480
  2126
                <var>LOCATION</var> from <var>ssdp device</var> as the <var>device descriptor URL</var> argument and
richt@480
  2127
                the first occurrence of <var>USN</var> from <var>ssdp device</var> as the <var>device identifier</var>
richt@480
  2128
                argument and the first occurrence of <var>CACHE-CONTROL</var> from <var>ssdp device</var> (minus the
richt@480
  2129
                leading string of <code>max-age=</code>) as the <var>device expiry</var> argument.
richt@239
  2130
          </li>
richt@239
  2131
        </ol>
richt@239
  2132
        <p>
richt@437
  2133
          The user agent <em class="rfc2119"
richt@437
  2134
             title="MUST">MUST</em> listen for incoming requests on the <dfn id=
richt@437
  2135
             "dfn-standard-upnp-address-and-port">standard UPnP address and port</dfn> on all current local network
richt@437
  2136
             interface addresses with the port <code>1900</code>.
richt@250
  2137
        </p>
richt@250
  2138
        <p>
richt@437
  2139
          For each <dfn id="dfn-http-request"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Request</dfn>
richt@437
  2140
          received on a <a href="#dfn-standard-upnp-address-and-port"
richt@437
  2141
             class="internalDFN">standard UPnP address and port</a> the user agent <em class="rfc2119"
richt@437
  2142
             title="MUST">MUST</em> run the following steps:
richt@239
  2143
        </p>
richt@239
  2144
        <ol class="rule">
richt@437
  2145
          <li>If the <a href="#dfn-http-request"
richt@437
  2146
                class="internalDFN"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Request</a> is not a
richt@437
  2147
                <abbr title="Hypertext Transfer Protocol">HTTP</abbr> NOTIFY request then it is not a valid UPnP
richt@437
  2148
                Request and the user agent <em class="rfc2119"
richt@437
  2149
                title="MUST">MUST</em> discard this request, abort any remaining steps and return.
richt@239
  2150
          </li>
richt@437
  2151
          <li>Let <var>ssdp device</var> be an Object with a property for each <abbr title=
richt@437
  2152
          "Hypertext Transfer Protocol">HTTP</abbr> header received in the <a href="#dfn-http-request"
richt@437
  2153
                class="internalDFN"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Request</a>, with each key
richt@437
  2154
                being the name of a <abbr title="Hypertext Transfer Protocol">HTTP</abbr> header and each value being
richt@437
  2155
                that <abbr title="Hypertext Transfer Protocol">HTTP</abbr> header's value.
richt@239
  2156
          </li>
richt@437
  2157
          <li>If <var>ssdp device</var>'s <var>NTS</var> entry is equal to <code>ssdp:alive</code> and the <a href=
richt@437
  2158
          "#dfn-http-request"
richt@437
  2159
                class="internalDFN"><abbr title="Hypertext Transfer Protocol">HTTP</abbr> Request</a> does not contain
richt@437
  2160
                at least one <var>CACHE-CONTROL</var> entry, at least one <var>USN</var> entry, at least one
richt@437
  2161
                <var>NT</var> entry, at least one <var>NTS</var> entry and at least one <var>LOCATION</var> entry, then
richt@437
  2162
                the <a href="#dfn-user-agent"
richt@437
  2163
                class="internalDFN">user agent</a> <em class="rfc2119"
richt@437
  2164
                title="MUST">MUST</em> discard this request, abort any remaining steps and return.
richt@239
  2165
          </li>
richt@250
  2166
          <li>If <var>ssdp device</var>'s <var>NTS</var> entry is equal to <code>ssdp:alive</code> then the user agent
richt@437
  2167
          <em class="rfc2119"
richt@437
  2168
                title="MUST">MUST</em> run the rule for <a href="#dfn-obtaining-a-upnp-device-description-file"
richt@437
  2169
                class="internalDFN">obtaining a UPnP Device Description File</a> passing in the first occurrence of
richt@480
  2170
                <var>LOCATION</var> from <var>ssdp device</var> as the <var>device descriptor URL</var> argument and
richt@480
  2171
                the first occurrence of <var>USN</var> from <var>ssdp device</var> as the <var>device identifier</var>
richt@480
  2172
                argument and the first occurrence of <var>CACHE-CONTROL</var> from <var>ssdp device</var> (minus the
richt@480
  2173
                leading string of <code>max-age=</code>) as the <var>device expiry</var>.<br>
richt@239
  2174
            <br>
richt@239
  2175
            Otherwise, if <var>ssdp device</var>'s <var>NTS</var> entry is equal to <code>ssdp:byebye</code> then the
richt@437
  2176
            user agent <em class="rfc2119"
richt@437
  2177
                title="MUST">MUST</em> run the rule for <a href=
richt@437
  2178
                "#dfn-removing-all-services-from-a-registered-upnp-device"
richt@437
  2179
                class="internalDFN">removing all services from a registered UPnP Device</a> passing in the first
richt@437
  2180
                occurrence of <var>USN</var> from <var>ssdp device</var> as the <var>device identifier</var> argument.
richt@239
  2181
          </li>
richt@239
  2182
        </ol>
richt@239
  2183
        <p>
richt@437
  2184
          The rule for <dfn id="dfn-obtaining-a-upnp-device-description-file">obtaining a UPnP Device Description
richt@437
  2185
          File</dfn> is the process of obtaining the contents of a standard UPnP Device Description [<cite><a class=
richt@437
  2186
          "bibref"
richt@480
  2187
             href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>] from a URL-based resource. This rule takes
richt@480
  2188
             three arguments - <var>device descriptor URL</var>, <var>device identifier</var> and <var>device
richt@480
  2189
             expiry</var> - and when called the user agent <em class="rfc2119"
richt@437
  2190
             title="MUST">MUST</em> run the following steps:
richt@239
  2191
        </p>
richt@239
  2192
        <ol class="rule">
richt@480
  2193
          <li>Let <var>device descriptor file</var> contain the contents of the file located at the URL provided in
richt@480
  2194
          <var>device descriptor URL</var> obtained according to the rules defined in 'Section 2.11: Retrieving a
richt@480
  2195
          description using <abbr title="Hypertext Transfer Protocol">HTTP</abbr>' in [<cite><a class="bibref"
richt@437
  2196
               href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>].
richt@239
  2197
          </li>
richt@480
  2198
          <li>If the value provided in <var>device descriptor URL</var> cannot be resolved as a reachable URL on the
richt@480
  2199
          current network or the <var>device descriptor file</var> remains empty then it is invalid and the <a href=
richt@480
  2200
          "#dfn-user-agent"
richt@437
  2201
                class="internalDFN">user agent</a> <em class="rfc2119"
richt@437
  2202
                title="MUST">MUST</em> abort any remaining steps and return.
richt@239
  2203
          </li>
richt@437
  2204
          <li>Run the rule for <a href="#dfn-processing-a-upnp-device-description-file"
richt@437
  2205
                class="internalDFN">processing a UPnP Device Description File</a>, passing in the current <var>device
richt@437
  2206
                descriptor file</var>, <var>device identifier</var> and <var>device expiry</var> arguments.
richt@239
  2207
          </li>
richt@239
  2208
        </ol>
richt@239
  2209
        <p>
richt@437
  2210
          The rule for <dfn id="dfn-processing-a-upnp-device-description-file">processing a UPnP Device Description
richt@437
  2211
          File</dfn> is the process of parsing the contents of a standard UPnP Device Description [<cite><a class=
richt@437
  2212
          "bibref"
richt@437
  2213
             href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>] and registering the UPnP services contained
richt@437
  2214
             therein within the <a href="#dfn-list-of-available-service-records"
richt@437
  2215
             class="internalDFN">list of available service records</a>.
richt@239
  2216
        </p>
richt@239
  2217
        <p>
richt@437
  2218
          The rule for <a href="#dfn-processing-a-upnp-device-description-file"
richt@437
  2219
             class="internalDFN">processing a UPnP Device Description File</a> takes three arguments - <var>device
richt@437
  2220
             descriptor file</var>, <var>device identifier</var> and <var>device expiry</var> - and when called the
richt@437
  2221
             user agent <em class="rfc2119"
richt@437
  2222
             title="MUST">MUST</em> run the following steps:
richt@239
  2223
        </p>
richt@239
  2224
        <ol class="rule">
richt@239
  2225
          <li>Let <var>advertised services</var> be a list of all advertised services obtained from the <var>device
richt@239
  2226
          descriptor file</var> containing the value of the first occurrence of the <code>&lt;serviceList&gt;</code>
richt@437
  2227
          element as it is defined in 'Section 2.3: Device Description' in [<cite><a class="bibref"
richt@437
  2228
               href="#bib-UPNP-DEVICEARCH11">UPNP-DEVICEARCH11</a></cite>].
richt@239
  2229
          </li>
richt@239
  2230
          <li>For each <code>&lt;service&gt;</code> element - known as an <var>advertised service</var> - in
richt@239
  2231
          <var>advertised services</var> run the following steps:
richt@239
  2232
            <ol class="rule">
richt@239
  2233
              <li>Let <var>network service record</var> be a new Object consisting of the following empty properties:
richt@239
  2234
              <code>id</code>, <code>deviceId</code>, <code>name</code>, <code>type</code>, <code>url</code>,
richt@239
  2235
              <code>eventsUrl</code>, <code>config</code>, <code>expiryTimestamp</code>.
richt@239
  2236
              </li>
richt@239
  2237
              <li>Set <var>network service record</var>'s <code>id</code> property to the concatenated string value of
richt@250
  2238
              the first occurrence of the <code>&lt;UDN&gt;</code> element in the <var>device descriptor file</var>
richt@250
  2239
              with the <var>advertised service</var>'s <code>&lt;serviceId&gt;</code> sub-element.
richt@239
  2240
              </li>
richt@239
  2241
              <li>Set <var>network service record</var>'s <code>deviceId</code> property to the value of <var>device
richt@239
  2242
              identifier</var>.
richt@239
  2243
              </li>
richt@239
  2244
              <li>Set <var>network service record</var>'s <code>name</code> property to the string value of the first
richt@239
  2245
              occurrence of the <var>advertised service</var>'s <code>&lt;serviceId&gt;</code> sub-element.
richt@239
  2246
              </li>
richt@239
  2247
              <li>Set <var>network service record</var>'s <code>type</code> property to the concatenation of the string
richt@239
  2248
              <code>upnp:</code> followed by the string value of the first occurrence of the <var>advertised
richt@239
  2249
              service</var>'s <code>&lt;serviceType&gt;</code> sub-element.
richt@239
  2250
              </li>
richt@239