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