88 Using this <abbr title="Application Programming Interface">API</abbr> consists of requesting a well-known service type, known by developers and advertised by Local-networked Devices. User authorization, where the user connects the web page to one or more discovered services,

89 is expected before the web page is able to interact with any Local-networked Services.

107 Once connected to a Local-networked Service the Web page can send requests and receive responses to the Local-networked Service via the messaging format and appropriate channel inferred from the service type

206 The construction "a <code>Foo</code> object", where <code>Foo</code> is actually an interface, is sometimes used instead of the more accurate "an object implementing the interface <code>Foo</code>".

219 A <dfn>valid service type</dfn> is a string that begins with <code>upnp:</code> or <code>zeroconf:</code> followed by one or more characters in the ranges U+0021, U+0023 to U+0027, U+002A to U+002B, U+002D to U+002E, U+0030 to U+0039, U+0041 to U+005A, U+005E to U+007E.

224 A <a>valid service type</a> provided in the <code>type</code> attribute of the <a href="#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a> method will be matched against the services currently contained in the <a>list of available service records</a> according to the algorithms defined in this specification.

228 A <dfn>user-agent generated callback url</dfn> is a Local-network accessible URL endpoint that a <a>user agent</a> must generate and maintain for receiving HTTP NOTIFY requests from UPnP Event sources. It is only required when the user agent implements UPnP Service Discovery as defined in

316 When the <dfn id="dom-navigator-getnetworkservices" title="dom-navigator-getnetworkservices"><code>getNetworkServices(type, successCallback[, errorCallback])</code></dfn> method is called, the <a>user agent</a> MUST run the following steps:

326 If <var>type</var> is an array consisting of one or more <a>valid service type</a> tokens, then let <var>requested control types</var> by the value of <var>type</var>, removing any non-<a>valid service type</a> tokens from the resulting array.

334 If <var>requested control types</var> is an array that contains at least one or more <a title="valid service type">valid service type</a> tokens then continue to the step labeled <em>process</em> below. Otherwise, the <a>user agent</a> MUST <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an object of type <code>Function</code>, with a new <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose

348 For each <var>requested control type</var> in <var>requested control types</var>: If <var>available service</var>'s <code>type</code> attribute equals the <var>requested control type</var> then let <var>matched service</var> equal the value of <var>available service</var> and continue at the step labeled <var>attach</var> below.

370 If <var>services found</var> is an empty array, then the <a>user agent</a> MUST <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an object of type <code>Function</code>, with a new <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose

380 Optionally, e.g. based on a previously-established user preference, for security reasons, or due to platform limitations, the <a>user agent</a> MAY <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an object of type <code>Function</code>, with a new <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose

396 <p>If the user denies permission, then the <a>user agent</a> MUST <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>errorCallback</var>, if it is provided and is an object of type <code>Function</code>, with a new <a href="#navigatornetworkserviceerror"><code>NavigatorNetworkServiceError</code></a> object whose

419 If <var>service</var>'s <code>type</code> parameter begins with the DOMString &quot;<code>upnp:</code>&quot; and the <var>service</var>'s <code>eventsUrl</code> parameter is not empty then <a>setup a UPnP Events Subscription</a> for <var>service</var>.

429 Set <var>services manager</var>'s <a href="#dom-networkservices-servicesavailable"><code>servicesAvailable</code></a> attribute to the number of services currently found in the <a>list of available service records</a> whose <code>type</code> property matches any of the tokens requested in <var>requested control types</var>.

437 The <a>user agent</a> MUST <a href="http://www.whatwg.org/specs/web-apps/current-work/complete/webappapis.html#queue-a-task" class="externalDFN">queue a task</a> to invoke <var>successCallback</var> with

459 If the user navigates away from the current browsing context, the <a>user agent</a> MUST remove all previously whitelisted urls from the <a>entry script origin's URL whitelist</a>.

460 There is no persistence to network service selections provided to a web page. It is not possible to access a previously white-listed networked service without the necessary user authorization in all of the following cases:

520 The <a href="#networkservices"><code>NetworkServices</code></a> interface is the top-level response object from a call to <a href="#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a> and provides access to a set of user-authorized <a href="#networkservice"><code>NetworkService</code></a> objects for the given request.

570 The <dfn id="dom-networkservices-length"><code>length</code></dfn> attribute MUST return the number of services represented in the object's corresponding <a>list of authorized service records</a> at the time of getting.

574 The <dfn id="dom-networkservices-servicesavailable"><code>servicesAvailable</code></dfn> attribute MUST return the number of services in the <a>list of available service records</a> whose <code>type</code> attribute matches any of the <a>valid service type</a> tokens that was initially used to create the current <a href="#networkservices"><code>NetworkServices</code></a> object.

618 A <a href="#networkservices"><code>NetworkServices</code></a> object represents the current list of one or more current authorized services - the <a>list of authorized service records</a>. Each item in the <a>list of authorized service records</a> is represented by a <a href="#networkservice"><code>NetworkService</code></a> object. The <a>list of authorized service records</a> is <span>immutable</span> meaning that it cannot be modified for the lifetime of a <a href="#networkservices"><code>NetworkServices</code></a> object.

622 Each service in a <a href="#networkservices"><code>NetworkServices</code></a> object thus has an index; the first has the index 0, and each subsequent service is numbered one higher than the previous one.

626 The <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#supported-property-indices" class="externalDFN">supported property indices</a> of <a href="#networkservices"><code>NetworkServices</code></a> objects at any instant are the numbers from zero to the number of items in the <a>list of authorized service records</a> represented by the respective object minus one, if any services are represented in the <a>list of authorized service records</a>.

630 To <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#determine-the-value-of-an-indexed-property" class="externalDFN">determine the value of an indexed property</a> for a given index <var>index</var> in a <a href="#networkservices"><code>NetworkServices</code></a> object's <a>list of authorized service records</a>, the user agent MUST return the <a href="#networkservice"><code>NetworkService</code></a> object that represents the <var>index</var>th service in the <a>list of authorized service records</a>.

634 The <dfn id="dom-networkservices-getservicebyid"><code>getServiceById(id)</code></dfn> method MUST return the first <a href="#networkservice"><code>NetworkService</code></a> object in the <a>list of authorized service records</a> represented by the respective object whose <a href="#dom-networkservice-id"><code>id</code></a> attribute is equal to the value of the <var>id</var> argument.

635 When no services in the <a>list of authorized service records</a> match the given argument, the method MUST return null.

639 Services available within the local network can connect and disconnect at different times during the execution of a web page. A <a>user agent</a> can

640 inform a web page when the state of networked services matching the requested <a>valid service type</a> change. Web pages can use this information to enable in-page experiences for communicating the state of networked services

641 with the ability to change the particular service or set of services the page is connected to by re-invoking the <a href="#dom-navigator-getnetworkservices"><code>getNetworkServices()</code></a> method.

650 The following are the event handlers (and their corresponding event handler event types) that must be supported, as IDL attributes, by all objects implementing the <a href="#networkservices"><code>NetworkServices</code></a> interface:

699 The <a href="#networkservice"><code>NetworkService</code></a> interface is used to provide a set of connection information for an HTTP service endpoint and if available, service events, running on a networked device.

790 The <dfn id="dom-networkservice-id"><code>id</code></dfn> attribute is a unique identifier for the service. The same service provided at different times or on different objects MUST have the same <a href="#dom-networkservice-id"><code>id</code></a> value.

802 The <dfn id="dom-networkservice-url"><code>url</code></dfn> attribute is an <a href="http://www.w3.org/TR/html5/urls.html#absolute-url" class="externalDFN">absolute URL</a> pointing to the root HTTP

803 endpoint for the service that has been added to the <a>entry script origin's URL whitelist</a>. Web pages can subsequently use this value for implicit cross-document messaging via various existing mechanisms (e.g. Web Sockets, Server-Sent Events, Web Messaging, XMLHttpRequest).

825 Returns <code>true</code> if the service is reporting that it is accessible on the local network or <code>false</code> if the service is reporting that it is no longer accessible (temporarily or permanently) on the local network.

831 The <dfn id="dom-networkservice-online"><code>online</code></dfn> attribute indicates whether the service is reporting itself as being

832 either <var>online</var>, and therefore accessible on the local network, in which case this attribute will return <code>true</code> or, <var>offline</var>, and therefore not accessible on the local network, either temporarily or permanently, in which case this attribute will return <code>false</code>. This attribute MUST default to <code>true</code>.

902 to enable Web pages to request and connect with HTTP services running on networked devices, discovered via either mechanism, through this API. When a <a>user agent</a> implements either of these service discovery mechanisms, then it MUST conform to the corresponding algorithms provided in this section of the specification.

905 This section presents how the results of these two service discovery

906 mechanisms will be matched to requested service types, how the user agent stores available and active services, how their properties are applied to any resulting <a href="#networkservice"><code>NetworkService</code></a> objects.

916 The <dfn>list of available service records</dfn> is a single dynamic internal lookup table within user agents that is used to track all the services that have been discovered and are available in the current network at any given time.

917 At any point during the running of either of the two service discovery mechanisms then existing entries within this table can be updated, entries can be added and entries can be removed as the status of networked

918 services changes according to the rules defined in this specification. <!--Each record contained within this table contains the attributes: <code>id</code>, <code>deviceId</code>, <code>name</code>, <code>type</code>, <code>url</code>, <code>config</code> and <code>expiryTimestamp</code>.-->

922 The <dfn>list of authorized service records</dfn> is a single dynamic internal lookup table within user agents that is used to track the

923 current services that are being shared with web pages at any given time from the <a>list of available service records</a>. Each record in the <a>list of authorized service records</a> is associated with a <var>services manager</var> object that is assigned as part of the

928 The rule for <dfn>adding an available service</dfn> is the process of adding a new service or updating an existing service in the <a>list of available service records</a> that is generally available on the user's current network. This rule takes one argument, <var>network service record</var>, and consists of

973 If the <var>new service registration flag</var> is set to <code>true</code> then increment the <a href="#dom-networkservices-servicesavailable"><code>servicesAvailable</code></a> attribute of the <var>services manager</var> associated with

1007 If the <var>existing service record</var>'s <code>id</code> property does not match <var>service identifier</var> then skip any remaining sub-steps for the current <var>existing service record</var> and continue at the next available <var>existing service record</var>.

1068 For each DNS response received from a user-agent-initiated Multicast DNS Browse for <abbr title="DNS Pointer Record">PTR</abbr> records with the name <code>_services._dns-sd._udp</code> on the resolved recommended automatic browsing

1069 domain [[!MDNS]], the <a>user agent</a> MUST run the following steps:

1092 Set <var>network service record</var>'s <code>type</code> property to the concatenation of the string <code>zeroconf:</code> followed by the value of the PTR Service Instance Name's <var>Service</var> component [[!MDNS]].

1096 Set <var>network service record</var>'s <code>url</code> property to the resolvable Service URL obtained from performing an DNS-SD Lookup [[!DNS-SD]] of the current service from the PTR record provided [[!MDNS]].

1100 Set <var>network service record</var>'s <code>config</code> property to the string value of the contents of the first DNS-SD TXT record associated with the <var>service mDNS response</var> as defined in [[!DNS-SD]].

1127 The user agent <em class="ct">MUST</em> issue all <a title="advertisement for UPnP root devices">advertisements for UPnP root devices</a> with a HTTP request line equal to <code>M-SEARCH * HTTP/1.1</code>, with a HOST header equal to the reserved multicast address and port of <code>239.255.255.250:1900</code>, a MAN header equal to <code>ssdp:discover</code>, an ST header equal to <code>upnp:rootdevice</code> and a user-agent defined MX header equal to a <dfn>maximum UPnP advertisement response wait time</dfn> value between <code>1</code> and <code>5</code> seconds.

1131 The user agent <em class="ct">MUST</em> listen for incoming requests and process any incoming responses to any <a>advertisement for UPnP root devices</a> on the <dfn>standard UPnP address and port</dfn>, on all current local network interface addresses with the port <code>1900</code>, according to the rules defined in this section.

1141 If the <a>HTTP Response</a> is not a HTTP 200 OK response then this response is invalid and the user agent <em class="ct">MUST</em> discard this response, abort any remaining steps and return. The user agent <em class="ct">MAY</em> issue a new <a>advertisement for UPnP root devices</a> as a result of this error occurring.

1145 If the <a>maximum UPnP advertisement response wait time</a> has been exceeded since the initial <a>advertisement for UPnP root devices</a> was sent then the <a>HTTP Response</a> is invalid and the user agent <em class="ct">MUST</em> discard this response, abort any remaining steps and return.

1149 Let <var>ssdp device</var> be an Object with a property for each HTTP header received in the <a>HTTP Response</a>, with each key being the name of a HTTP response header and each value being that HTTP response header's value.

1153 If <var>ssdp device</var> does not contain at least one <var>CACHE-CONTROL</var> entry, at least one <var>USN</var> entry, at least one <var>ST</var> entry and at least one <var>LOCATION</var> entry or the value of its <var>ST</var> entry is not <code>upnp:rootdevice</code>, then the <a>HTTP Response</a> is invalid and the <a>user agent</a> MUST discard this response, abort any remaining steps and return.

1157 The user agent <em class="ct">MUST</em> run the rule for <a>processing a UPnP Device Description File</a> passing in the first occurrence of <var>LOCATION</var> from <var>ssdp device</var> as the <var>device descriptor</var> argument and the first occurrence of <var>USN</var> from <var>ssdp device</var> as the <var>device identifier</var> argument and the first occurrence of <var>CACHE-CONTROL</var> from <var>ssdp device</var> as the <var>device expiry</var> argument

1169 If the <a>HTTP Request</a> is not a HTTP NOTIFY request then it is not a valid UPnP Request and the user agent <em class="ct">MUST</em> return a HTTP 200 OK response, discard this request, abort any remaining steps and return.

1173 Let <var>ssdp device</var> be an Object with a property for each HTTP header received in the <a>HTTP Request</a>, with each key being the name of a HTTP header and each value being that HTTP header's value.

1177 If <var>ssdp device</var> does not contain at least one <var>CACHE-CONTROL</var> entry, at least one <var>USN</var> entry, at least one <var>NT</var> entry, at least one <var>NTS</var> entry and at least one <var>LOCATION</var> entry or the value of its <var>NT</var> entry is not <code>upnp:rootdevice</code>, then the <a>HTTP Request</a> is a malformed UPnP Request and the <a>user agent</a> MUST return a 400 Bad Request response, discard this request, abort any remaining steps and return.

1181 If <var>ssdp device</var>'s <var>NTS</var> entry is equal to <code>ssdp:alive</code> or <code>ssdp:update</code> then the user agent <em class="ct">MUST</em> run the rule for <a>processing a UPnP Device Description File</a> passing in the first occurrence of <var>LOCATION</var> from <var>ssdp device</var> as the <var>device descriptor</var> argument and the first occurrence of <var>USN</var> from <var>ssdp device</var> as the <var>device identifier</var> argument and the first occurrence of <var>CACHE-CONTROL</var> from <var>ssdp device</var> as the <var>device expiry</var>. <br/><br/>Otherwise, if <var>ssdp device</var>'s <var>NTS</var> entry is equal to <code>ssdp:byebye</code> then the user agent <em class="ct">MUST</em> run the rule for <a>removing all services from a registered UPnP Device</a> passing in the first occurrence of <var>USN</var> from <var>ssdp device</var> as the <var>device identifier</var> argument.

1197 Let <var>root device descriptor file</var> contain the contents of the file located at the URL provided in <var>device descriptor</var> obtained according to the rules

1198 defined in 'Section 2.11: Retrieving a description using HTTP' in [[!UPNP-DEVICEARCH11]]. If the value provided in <var>device descriptor</var> cannot be resolved as a URL on the current network or the <var>root device descriptor file</var> remains empty then the <a>HTTP Response</a> is invalid and the <a>user agent</a> MUST discard this response, abort any remaining steps and return.

1202 Let <var>advertised services</var> be a <a>list of all advertised services</a> obtained from the <var>root device descriptor file</var> containing the value of the first occurrence of the <code>&lt;serviceList&gt;</code> element as it is defined in 'Section 2.3: Device Description' in [[!UPNP-DEVICEARCH11]].

1215 Set <var>network service record</var>'s <code>id</code> property to the concatenated string value of <var>device identifier</var> with the <var>advertised service</var>'s <code>&lt;serviceId&gt;</code> sub-element.

1227 Set <var>network service record</var>'s <code>type</code> property to the concatenation of the string <code>upnp:</code> followed by the string value of the first occurrence of the <var>advertised service</var>'s <code>&lt;serviceType&gt;</code> sub-element.

1235 Set <var>network service record</var>'s <code>config</code> property to the string value of the contents of the first occurrence of the <code>&lt;device&gt;</code> element in the <var>root device descriptor file</var>.

1239 If <var>advertised service</var>'s <code>&lt;eventSubURL&gt;</code> sub-element is not empty, then set <var>network service record</var>'s <code>eventsUrl</code> property to the string value of the first occurrence of the <var>advertised service</var>'s <code>&lt;eventSubURL&gt;</code> sub-element. Otherwise, do not set <var>network service record</var>'s <code>eventsUrl</code> property.

1267 If the <var>existing service record</var>'s <code>deviceId</code> property does not match <var>device identifier</var> then skip any remaining sub-steps for the current <var>existing service record</var> and continue at the next available <var>existing service record</var>.

1280 <p>When the <a>user agent</a> is to <dfn>setup a UPnP Events Subscription</dfn>, it is to run the following steps with the current <var>network service record</var> object as defined in 'Section 4.1.2: SUBSCRIBE with NT and CALLBACK' in [[!UPNP-DEVICEARCH11]]:</p>

1292 Send a HTTP SUBSCRIBE request with a <em>NT</em> header with a string value of <code>upnp:event</code>, a <em>TIMEOUT</em> header with a user-agent defined timeout value (in the form <code>Second-XX</code> where <code>XX</code> is the user-agent defined timeout value in seconds) and a <em>CALLBACK</em> header

1293 with a string value of <var>callback URL</var> towards the <var>network service record</var>'s <code>eventsUrl</code> property.

1308 Let <var>timeout date</var> equal the sum of the current UTC date value plus the integer value of the first included <em>TIMEOUT</em> header (minus the leading string of <code>Second-</code>), if it exists.

1324 Send a HTTP SUBSCRIBE request with a <em>SID</em> header with the string value of <var>callback ID</var> and a user-agent defined <em>TIMEOUT</em> header (in the form <code>Second-XX</code> where <code>XX</code> is the user-agent defined timeout value in seconds) towards the <var>network service record</var>'s <code>eventsUrl</code> property.

1361 A <a>user agent</a> can <dfn>terminate an existing UPnP Events Subscription</dfn> at any time for any <var>active service</var> in the <a>list of authorized service records</a> by sending an HTTP UNSUBSCRIBE request - as defined in 'Section 4.1.4: Canceling a subscription with UNSUBSCRIBE' in [[!UPNP-DEVICEARCH11]] - with a HOST header set to that <var>active service</var>'s <code>eventsUrl</code> property and a SID header set to the <var>callback ID</var> obtained when the initial <a>setup a UPnP Events Subscription</a> action occurred.

1371 When the <a>user agent</a> detects that the user has dropped from their connected network then, for each <var>existing service record</var> in the <a>list of available service records</a>, the user agent

1391 Only when the user navigates away from the current browsing context can <a><code>NetworkService</code></a> objects be garbage-collected, its records in the <a>entry script origin's URL whitelist</a> be removed and its corresponding entry in the <a>list of authorized service records</a> be removed.

1431 Example: A Web page advertises that it is capable of interacting with and controlling multiple types of Home Media Server. The user can select their Home Media Server type from a drop-down list or known Media Servers, at which point the

1432 Web page sends a request to the user agent to connect with the associated service type (and, optionally, the associated event type) of the Home Media Server. The communiciation protocols supported by Home Media Servers typically vary

1433 between UPnP, JSON-RPC, Protocol Buffers or other messaging formats depending on the Home Media Server requested. The Web page is able to communicate with the user-selected Home Media

1434 Server in the messaging format supported by that Device, which, in this example is a simple key/value pair text format.

1453 Example: A Web page is capable of interacting with a specific profile of Local-networked Service. As such, it makes a request to the user agent to access those services, of which multiple matches

1454 are found. The user is capable of selecting one or more of the discovered services to share with the Web page. The Web page can then implement a drag-and-drop interface for the user to drag specific

1455 actions on to one or more of the authorized Local-networked Services.

1472 <p>This sample code exposes a button. When clicked, this button is disabled and the user is prompted to offer a network service. The user may also select multiple network services. When the user has authorized a network service to be connected to the web page then the web page issues a simple command to get a list of all the albums stored on the connected media player service.

1473 <p>The button is re-enabled only when the connected network service disconnects for whatever reason (the service becomes unavailable on the network, the user disconnects from their current network or the user revokes access to the service from the current web page). At this point the user can re-click the button to select a new network service to connect to the web page and the above steps are repeated.</p>

1474 <p>The provided service type identifier and service interaction used in this example is based on the well-defined service type and messaging format supported by the <a href="http://xbmc.org/about/">XBMC Media Server</a>. </p>

1537 This sample exposes a drop-down list containing a number of common Home-based audio devices. When the user selects an audio device from the list provided, they are prompted to authorize a network service

1538 based on the service type requested. The user may also select multiple network services matching the selected service type.

1539 In this example, the user selects their make as being <var>Sony</var> and their model as being <var>Bravia S1000</var> from which the Web page can derive a service type