Copyright © 2012 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This specification defines a mechanism for an HTML document to discover and subsequently communicate with HTTP-based services advertised via common discovery protocols within the current network.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This document represents the early consensus of the group on the scope and features of the proposed API.
This document was published by the Device APIs Working Group as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-device-apis@w3.org (subscribe, archives). All feedback is welcome.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This section is non-normative.
To enable Web pages to connect and communicate with Local-networked Services provided over HTTP, this
specification introduces the NavigatorNetworkService
interface.
Using this API 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, is expected before the web page is able to interact with any Local-networked Services.
A web page creates a request to obtain connectivity to services running in the network by specifying a well-known discovery service type that it wishes to interact with.
The user agent, having captured all advertised services on the network from the Service Discovery mechanisms included in this recommendation, attempts to match the requested service type to a discovered service according to the processing described herein.
If a service connectivity request is successful then the Web page is provided with the necessary information to communicate with the authorized Local-networked Service. If the request fails then the Web page will receive an error callback containing an error code describing the cause of Local-networked Service connectivity failure.
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 authorized via the provided API. The Web page, once connected, can also receive service-pushed events, in the messaging format supported by the Local-networked Device, if such event subscription functionality is provided by the connected Local-networked Service.
Example of requesting a DNS-SD advertised service:
function showServices( services ) { // Show a list of all the services provided to the web page for(var i = 0, l = services.length; i < l; i++) console.log( services[i].name ); } navigator.getNetworkServices('zeroconf:_boxee-jsonrpc._tcp', showServices);
Example of requesting a UPnP advertised service, also handling error conditions:
function showServices( services ) { // Show a list of all the services provided to the web page for(var i = 0, l = services.length; i < l; i++) console.log( services[i].name ); } function error( e ) { console.log( "Error occurred: " + e.code ); } navigator.getNetworkServices('upnp:urn:schemas-upnp-org:service:ContentDirectory:1', showServices, error);
Example of requesting either a DNS-SD or UPnP advertised service:
function showServices( services ) { // Show a list of all the services provided to the web page (+ service type) for(var i = 0, l = services.length; i < l; i++) console.log( services[i].name + '(' + services[i].type + ')' ); } navigator.getNetworkServices([ 'zeroconf:_boxee-jsonrpc._tcp', 'upnp:urn:schemas-upnp-org:service:ContentDirectory:1' ], showServices);
For more detailed examples see the Examples section.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].
Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.
Some conformance requirements are phrased as requirements on attributes, methods or objects. Such requirements are to be interpreted as requirements on user agents.
Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)
The only conformance class defined by this specification is a user agent.
User agents may impose implementation-specific limits on otherwise unconstrained inputs, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.
When support for a feature is disabled (e.g. as an emergency measure to mitigate a security problem, or to aid in development, or for performance reasons), user agents must act as if they had no support for the feature whatsoever, and as if the feature was not mentioned in this specification. For example, if a particular feature is accessed via an attribute in a Web IDL interface, the attribute itself would be omitted from the objects that implement that interface - leaving the attribute on the object but making it return null or throw an exception is insufficient.
The construction "a Foo
object", where Foo
is actually an interface, is sometimes
used instead of the more accurate "an object implementing the interface Foo
".
The term DOM is used to refer to the API set made available to scripts in Web applications, and does not
necessarily imply the existence of an actual Document
object or of any other Node
objects as defined in the DOM Core specifications. [DOM4]
An IDL attribute is said to be getting when its value is being retrieved (e.g. by author script), and is said to be setting when a new value is assigned to it.
A valid service type is a string that begins with upnp:
or zeroconf:
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.
A valid service type provided in the type
attribute of the getNetworkServices()
method will be matched against the
services currently contained in the list of available service records according to the algorithms
defined in this specification.
A user-agent generated callback url is a Local-network accessible URL endpoint that a user agent generates and maintains for receiving HTTP NOTIFY requests from UPnP Event sources. It is only required when the user agent implements UPnP Service Discovery as defined in this specification.
[Supplemental, NoInterfaceObject] interface NavigatorNetworkService { // Obtain a Local-networked Service void getNetworkServices( in any type, in NavigatorNetworkServiceSuccessCallback successCallback, in optional NavigatorNetworkServiceErrorCallback errorCallback ); }; Navigator implements NavigatorNetworkService; [Callback=FunctionOnly, NoInterfaceObject] interface NavigatorNetworkServiceSuccessCallback { void handleEvent( in NetworkServices services ); }; [NoInterfaceObject] interface NavigatorNetworkServiceError { const unsigned short PERMISSION_DENIED_ERR = 1; const unsigned short UNKNOWN_TYPE_PREFIX_ERR = 2; readonly attribute unsigned short code; }; [Callback=FunctionOnly, NoInterfaceObject] interface NavigatorNetworkServiceErrorCallback { void handleEvent( in NavigatorNetworkServiceError error ); };
navigator
.
getNetworkServices
( type , successCallback [, errorCallback ] )
Prompts the user to select one or more discovered network services that have advertised support for the requested service type.
The type argument contains one or more valid service type tokens that the web page would like to interact with.
If the user accepts, the successCallback is invoked, with one or more NetworkService
objects as its argument.
If the user declines, the errorCallback (if any) is invoked.
When the getNetworkServices(type, successCallback[,
errorCallback])
method is called, the user agent must run the
following steps:
Function
, with a new NavigatorNetworkServiceError
object whose code
attribute has the numeric value 2
(UNKNOWN_TYPE_PREFIX_ERR
) as
its argument, abort any remaining steps and return.
type
attribute equals the requested control type then let
matched service equal the value of available service and continue at the step
labeled attach below.
NetworkService
object, mapping the parameters of matched
service to this new object where possible.
Function
, with a new NavigatorNetworkServiceError
object whose code
attribute has the numeric value 1
(PERMISSION_DENIED_ERR
) as its
argument, abort any remaining steps and return.
Function
, with a new NavigatorNetworkServiceError
object whose code
attribute has the numeric value 1
(PERMISSION_DENIED_ERR
) as its
argument, abort any remaining steps and return.
NetworkService
objects representing the user-authorized subset of
services found.
If the user grants permission to access one or more networked services then the user agent should include an "ongoing local-network communication" indicator.
If the user denies permission, then the user agent must queue a task to invoke errorCallback, if it is provided and is an
object of type Function
, with a new NavigatorNetworkServiceError
object whose code
attribute has the numeric value 1
(PERMISSION_DENIED_ERR
) as its
argument, abort any remaining steps and return.
If the user never responds, this algorithm stalls on this step.
NetworkService
objects for which the user granted permission.
url
parameter to the entry script origin's
URL whitelist.
type
parameter begins with the DOMString "upnp:
"
and the service's eventsUrl
parameter is not empty then setup a UPnP Events
Subscription for service.
NetworkServices
object.
servicesAvailable
attribute to the number of
services currently found in the list of available service records whose type
property
matches any of the tokens requested in requested control types.
The task source for these tasks is the user interaction task source.
When a NetworkService
object is provided to a Web page, the
user agent must add the url
property to the entry script
origin's URL whitelist. This list enables the Web page to override and initiate cross-site resource
requests towards these URLs, and any sub-resources of these URLs, within the current entry script's origin via various existing mechanisms (e.g. Web Sockets, Server-Sent Events,
Web Messaging, XMLHttpRequest).
If the user navigates away from the current browsing context, the user agent must remove all previously whitelisted urls from the entry script origin's URL whitelist. 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:
getNetworkServices()
method at any point in its
execution.
code
Returns the current error's error code. At the current time, this will be 1
or
2
, for which the corresponding error constants PERMISSION_DENIED_ERR
and UNKNOWN_TYPE_PREFIX_ERR
are
defined.
The code
attribute of a NavigatorNetworkServiceError
object must return the code for the error, which will be one of the following:
PERMISSION_DENIED_ERR
(numeric value 1)
UNKNOWN_TYPE_PREFIX_ERR
(numeric value 2)
The NetworkServices
interface is the top-level response object from
a call to getNetworkServices()
and provides access
to a set of user-authorized NetworkService
objects for the given
request.
[NoInterfaceObject] interface NetworkServices { readonly attribute unsigned long length; getter NetworkService (unsigned long index); NetworkService? getServiceById(DOMString id); readonly attribute unsigned long servicesAvailable; // event handler attributes attribute EventHandler onserviceavailable; attribute EventHandler onserviceunavailable; }; NetworkServices implements EventTarget;
length
Returns the current number of services belonging in the respective object's list of authorized service records.
servicesAvailable
Returns the current number of services matching one of the app-requested valid service type tokens in the list of available service records.
The length
attribute must
return the number of services represented in the object's corresponding list of authorized service
records at the time of getting.
The servicesAvailable
attribute
must return the number of services in the list of available service records
whose type
attribute matches any of the valid service type tokens that was initially
used to create the current NetworkServices
object.
services
[ index ]
Returns the specified NetworkService
object.
services
. getServiceById
( id )
Returns the NetworkService
object with the given identifier,
or null if no service has that identifier.
A NetworkServices
object represents the current list of one or
more current authorized services - the list of authorized service records. Each item in the list of
authorized service records is represented by a NetworkService
object. The list of authorized service records is immutable meaning that it cannot be
modified for the lifetime of a NetworkServices
object.
Each service in a NetworkServices
object thus has an index; the
first has the index 0, and each subsequent service is numbered one higher than the previous one.
The supported property indices of NetworkServices
objects at any instant are the numbers from zero to
the number of items in the list of authorized service records represented by the respective object
minus one, if any services are represented in the list of authorized service records.
To determine the value of an indexed property for a given index index in a
NetworkServices
object's list of authorized service
records, the user agent must return the NetworkService
object that represents the indexth service in
the list of authorized service records.
The getServiceById(id)
method must return the first NetworkService
object in the
list of authorized service records represented by the respective object whose id
attribute is equal to the value of the id argument.
When no services in the list of authorized service records match the given argument, the method
must return null.
Services available within the local network can connect and disconnect at different times during the
execution of a web page. A user agent can inform a web page when the state of networked services
matching the requested valid service type change. Web pages can use this information to enable in-page
experiences for communicating the state of networked services with the ability to change the particular
service or set of services the page is connected to by re-invoking the getNetworkServices()
method.
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 NetworkServices
interface:
Event handler | Event handler event type |
---|---|
onserviceavailable
|
serviceavailable
|
onserviceunavailable
|
serviceunavailable
|
The NetworkService
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.
[NoInterfaceObject] interface NetworkService { readonly attribute DOMString id; readonly attribute DOMString name; readonly attribute DOMString type; readonly attribute DOMString url; readonly attribute DOMString config; readonly attribute boolean online; // event handler attributes attribute EventHandler onserviceonline; attribute EventHandler onserviceoffline; attribute EventHandler onnotify; }; NetworkService implements EventTarget;
id
A unique identifier for the given user-selected service instance.
name
The name of the user-selected service.
type
The valid service type token value of the user-selected service.
url
The control URL endpoint (including any required port information) of the user-selected control service that has been added to the entry script origin's URL whitelist.
config
The configuration information associated with the service depending on the requested service type.
The id
attribute is a unique identifier for the service.
The same service provided at different times or on different objects must have the same
id
value.
The name
attribute represents a human-readable title for
the service.
The type
attribute reflects the value of the valid
service type of the service.
The url
attribute is an absolute URL pointing to the root HTTP endpoint for the service that has been
added to the entry script origin's URL whitelist. 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).
The config
attribute provides the raw configuration
information extracted from the given network service.
online
Returns true
if the service is reporting that it is accessible on the local network or
false
if the service is reporting that it is no longer accessible (temporarily or
permanently) on the local network.
The online
attribute indicates whether the service is
reporting itself as being either online, and therefore accessible on the local network, in which
case this attribute will return true
or, offline, and therefore not accessible on the
local network, either temporarily or permanently, in which case this attribute will return
false
. This attribute must default to true
.
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 NetworkService
interface:
Event handler | Event handler event type |
---|---|
onnotify
|
notify
|
onserviceonline
|
serviceonline
|
onserviceoffline
|
serviceoffline
|
A user agent conforming to this specification may implement SSDP [UPNP-DEVICEARCH11] and Zeroconf [DNS-SD] + [MDNS] service discovery mechanisms to enable Web pages to request and connect with HTTP services running on networked devices, discovered via either mechanism, through this API. When a user agent implements either of these service discovery mechanisms, then it must conform to the corresponding algorithms provided in this section of the specification.
This section presents how the results of these two service discovery 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 NetworkService
objects.
It is expected that user agents will perform these service discovery mechanisms asynchronously and periodically update the list of networked devices as required. The timing of any service discovery mechanisms is an implementation detail left to the discretion of the implementer (e.g. once on user agent start-up, every X seconds during user agent execution or on invocation of this API from a Web page).
The list of available service records 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. 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 services changes according to the rules defined in this specification.
The list of authorized service records is a single dynamic internal lookup table within user agents
that is used to track the current services that are being shared with web pages at any given time from the
list of available service records. Each record in the list of authorized service records is
associated with a services manager object that is assigned as part of the getNetworkServices()
algorithm.
The rule for adding an available service is the process of adding a new service or updating an existing service in the list of available service records that is generally available on the user's current network. This rule takes one argument, network service record, and consists of running the following steps:
true
.
id
property does not equal network
service record's id
property then abort any remaining sub-steps and continue at the next
available existing service record.
false
.
true
then add network service
record to the list of available service records as a new entry.
type
property does not equal the current
active service's type
attribute then abort any remaining sub-steps for this
active service and continue at the next available active service.
true
then increment the
servicesAvailable
attribute of the
services manager associated with the current active service object by
1
and then queue a task to dispatch a newly created event with the name serviceavailable
that uses the Event
interface, which does not bubble, is not cancellable, and
has no default action, at the services manager associated with the current active
service object.
online
attribute
to true
and then queue a task to dispatch a newly created event with the name serviceonline
that uses the Event
interface, which does not bubble, is not cancellable, and
has no default action, at the current active service object.
The rule for removing an available service is the general process of removing a service from the list of available service records that has left the user's current network or has otherwise expired. This rule takes one argument, service identifier, and consists of running the following steps:
id
property does not match service
identifier then skip any remaining sub-steps for the current existing service record and
continue at the next available existing service record.
type
property begins with the DOMString
"upnp:
" and existing service record's eventsURL
property is set then
run the rule to terminate an existing UPnP Events Subscription, if one is currently active (as a
result of having previously called setup a UPnP Events Subscription against the current
existing service record).
type
property does not equal the current
active service's type
attribute then abort any remaining sub-steps for this
active service and continue at the next available active service.
servicesAvailable
attribute of the services manager associated with the current active service
object by 1
and then queue a task to dispatch a newly created event with the name serviceunavailable
that uses the Event
interface, which does not bubble, is not cancellable,
and has no default action, at the services manager associated with the current
active service object.
online
attribute to false
and then queue a task to dispatch a newly created event with the name serviceoffline
that uses the Event
interface, which does not bubble, is not cancellable,
and has no default action, at the current active service object.
User agents should expire a service record from the list of available service
records when its expiryTimestamp
attribute exceeds the current UTC timestamp. When this
condition is met the user agent should run the rule for removing an available service, passing in
the expired service record's id
attribute as the only argument.
For each DNS response received from a user-agent-initiated Multicast DNS Browse for PTR records with the name _services._dns-sd._udp
on the resolved
recommended automatic browsing domain [MDNS], the user agent must run the
following steps:
id
, name
, type
, url
, config
,
expiryTimestamp
.
id
property to the value of the full PTR Service
Instance Name [MDNS].
name
property to the value of the PTR Service
Instance Name's Instance component [MDNS].
type
property to the concatenation of the string
zeroconf:
followed be the value of the PTR Service Instance Name's Service
component [MDNS].
url
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].
config
property to the string value of the
contents of the first DNS-SD TXT record associated with the service mDNS response as defined
in [DNS-SD].
expiryTimestamp
property to the value of the
current date, in UTC timestamp format, plus a value of 120
seconds.
A user agent that implements UPnP service discovery must issue an advertisement for UPnP root devices against the user's current local network according to the full normative text and timing provided in 'Section 1.3.2: Search request with M-SEARCH' detailed in [UPNP-DEVICEARCH11].
The user agent must issue all advertisements for UPnP root devices with a HTTP request line equal
to M-SEARCH * HTTP/1.1
, with a HOST header equal to the reserved multicast address and port of
239.255.255.250:1900
, a MAN header equal to ssdp:discover
, an ST header equal to
upnp:rootdevice
and a user-agent defined MX header equal to a maximum UPnP advertisement
response wait time value between 1
and 5
seconds.
The user agent must listen for incoming requests and process any incoming responses to
any advertisement for UPnP root devices on the standard UPnP address and port, on all
current local network interface addresses with the port 1900
, according to the rules defined in
this section.
For each HTTP Response following an initial advertisement for UPnP root devices sent on a standard UPnP address and port the user agent must run the following steps:
upnp:rootdevice
, then the HTTP Response is
invalid and the user agent must discard this response, abort any remaining steps
and return.
For each HTTP Request received on a standard UPnP address and port the user agent must run the following steps:
upnp:rootdevice
, then
the HTTP Request is a malformed UPnP Request and the user agent must return
a 400 Bad Request response, discard this request, abort any remaining steps and return.
ssdp:alive
or
ssdp:update
then the user agent must run the rule for obtaining a UPnP
Device Description File passing in the first occurrence of LOCATION from ssdp
device as the device descriptor URL argument and the first occurrence of USN from
ssdp device as the device identifier argument and the first occurrence of
CACHE-CONTROL from ssdp device as the device expiry.ssdp:byebye
then the
user agent must run the rule for removing all services from a registered UPnP
Device passing in the first occurrence of USN from ssdp device as the device
identifier argument.
The rule for obtaining a UPnP Device Description File is the process of obtaining the contents of a standard UPnP Device Description [UPNP-DEVICEARCH11] from a URL-based resource. This rule takes three arguments - device descriptor URL, device identifier and device expiry - and when called the user agent must run the following steps:
<deviceList>
element then
for each <device>
element within <deviceList>
- herein known as an
embedded device descriptor file - the user agent must run the rule for
processing a UPnP Device Description File, passing in the current embedded device descriptor
file as the device descriptor file argument, along with the common device
identifier and device expiry arguments.
The rule for processing a UPnP Device Description File is the process of parsing the contents of a standard UPnP Device Description [UPNP-DEVICEARCH11] and registering the UPnP services contained therein within the list of available service records.
The rule for processing a UPnP Device Description File takes three arguments - device descriptor file, device identifier and device expiry - and when called the user agent must run the following steps:
<serviceList>
element as it is defined in 'Section 2.3: Device Description' in [UPNP-DEVICEARCH11].
<service>
element - known as an advertised service - in
advertised services run the following steps:
id
, deviceId
, name
, type
, url
,
eventsUrl
, config
, expiryTimestamp
.
id
property to the concatenated string value of
device identifier with the advertised service's <serviceId>
sub-element.
deviceId
property to the value of device
identifier.
name
property to the string value of the first
occurrence of the advertised service's <serviceId>
sub-element.
type
property to the concatenation of the string
upnp:
followed by the string value of the first occurrence of the advertised
service's <serviceType>
sub-element.
url
property to the string value of the first
occurrence of the advertised service's <controlURL>
sub-element.
config
property to the string value of the
contents of the first occurrence of the <device>
element in the device descriptor
file.
<eventSubURL>
sub-element is not empty, then
set network service record's eventsUrl
property to the string value of the first
occurrence of the advertised service's <eventSubURL>
sub-element.
Otherwise, do not set network service record's eventsUrl
property.
expiryTimestamp
property to the value of the
current date, in UTC timestamp format, plus the value of device expiry.
The rule for removing all services from a registered UPnP Device is the process of removing all services associated with a device from the list of available service records that has left the user's current network or has otherwise timed out or expired. This rule takes one argument, device identifier, and consists of running the following steps:
deviceId
property does not match device
identifier then skip any remaining sub-steps for the current existing service record and
continue at the next available existing service record.
id
property as the only argument.
When the user agent is to setup a UPnP Events Subscription, it is to run the following steps with the current network service record object as defined in 'Section 4.1.2: SUBSCRIBE with NT and CALLBACK' in [UPNP-DEVICEARCH11]:
eventsUrl
property is empty then the user
agent must abort these steps.
upnp:event
, a
TIMEOUT header with a user-agent defined timeout value (in the form Second-XX
where
XX
is the user-agent defined timeout value in seconds) and a CALLBACK header with a
string value of callback URL towards the network service record's
eventsUrl
property.
Second-
), if it exists.
Second-XX
where
XX
is the user-agent defined timeout value in seconds) towards the network service
record's eventsUrl
property.
Event
interface with the name notify
, which does not bubble, is not cancellable, and has no
default action.
data
attribute of notification event have the DOMString value of
content clone.
NetworkService
object.
A user agent can terminate an existing UPnP Events Subscription at any time for any
active service in the list of authorized service records by sending an HTTP UNSUBSCRIBE
request - as defined in 'Section 4.1.4: Cancelling a subscription with UNSUBSCRIBE' in [UPNP-DEVICEARCH11]
- with a HOST header set to that active service's eventsUrl
property and a SID header
set to the callback ID obtained when the initial setup a UPnP Events Subscription action
occurred.
When the user agent detects that the user has dropped from their connected network then, for each
existing service record in the list of available service records, the user agent
must run the general rule for removing an available service passing in each
existing service record's id
property as the only argument for each call.
When the user agent detects that the user has connected to a new network or reconnected to an existing network, then it should restart its discovery mechanisms as defined in the Service Discovery section of this specification, maintaining the existing list of authorized service records currently in use.
The following events are dispatched on the NetworkServices
and/or
NetworkService
objects:
Event name | Interface | Dispatched when... |
---|---|---|
serviceavailable
|
Event
|
When a new service that matches one of the requested type tokens is found in the current network. |
serviceunavailable
|
Event
|
When an existing service that matches one of the requested type tokens gracefully leaves or expires from the current network. |
serviceonline
|
Event
|
When a current service renews its service registration within the current network. |
serviceoffline
|
Event
|
When a current service gracefully leaves or otherwise expires from the current network. |
notify
|
Event
|
When a valid UPnP Events Subscription Message is received on a user-agent generated callback url for a current service. This event never fires for Zeroconf-based services. |
Only when the user navigates away from the current browsing context can NetworkService
objects be garbage-collected, its records in the entry script origin's URL whitelist be removed and its
corresponding entry in the list of authorized service records be removed according to passing each
expired object identifier through the rule for removing an available service.
This section covers what the requirements are for this API, as well as illustrates some use cases.
This section is non-normative.
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.
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.
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 XBMC Media Server.
<input type="button" value="Start" onclick="start()" id="startBtn"/> <div id="debugconsole"></div> <script> var startBtn = document.getElementById('startBtn'), debug = document.getElementById('debugconsole'); function start() { if(navigator.getNetworkServices) { navigator.getNetworkServices('zeroconf:_xbmc-jsonrpc._tcp', gotXBMCService, error); startBtn.disabled = true; } else { debug.innerHTML += "<br>Service Discovery not supported!"; } } function gotXBMCService(services) { // Listen for service disconnect messages services[0].addEventListener('serviceoffline', function ( e ) { debug.innerHTML += "<br>" + services[0].name + " disconnected."; startBtn.disabled = false; }, false); // Send a service message to get albums list (and process the service response) var svcXhr = new XMLHttpRequest(); svcXhr.open("POST", services[0].url + "/getAlbums"); // services[0].url and its sub-resources have been // whitelisted for cross-site XHR use in this // current browsing context. svcXhr.setRequestHeader('Content-Type', 'application/json-rpc'); svcXhr.addEventListener('readystatechange', function ( response ) { if( response.readyState != 4 || response.status != 200 ) return; debug.innerHTML += "<br>" + services[0].name + " response received: "; debug.textContent += JSON.parse(response.responseText); }, false); var svcMsg = [ { "jsonrpc": "2.0", "method": "AudioLibrary.GetAlbums", "params": { "genreid": -1, "artistid": -1, "start": -1, "end": -1 }, "id": "1" } ]; svcXhr.send(JSON.stringify(svcMsg)); debug.innerHTML += "<br>" + services[0].name + " request sent: "; debug.textContent += JSON.stringify(svcMsg); } function error( err ) { debug.innerHTML += "<br>An error occurred obtaining a local network service."; startBtn.disabled = false; } </script>
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 based on the
service type requested. The user may also select multiple network services matching the selected service
type. In this example, the user selects their make as being Sony and their model as being
Bravia S1000 from which the Web page can derive a service type
(urn:schemas-upnp-org:service:RenderingControl:1).
Once the user has authorized the device, the web page sends a simple mute command according to the messaging
format supported by the device.
<select name="make" id="make"> <option selected="selected" disabled="disabled">Select make</option> <option>Sony</option> <option>Philips</option> <option>Alba</option> </select> <select name="model" id="model"></select> <div id="debugconsole"></div> <script> var debug = document.getElementById('debugconsole'); var models = { "Sony": [ {"name": "Bravia TV S1000", "type": "upnp", "service": "urn:schemas-upnp-org:service:RenderingControl:1" }, {"name": "Bravia TV S2000", "type": "zeroconf", "service": "_mediarenderer._http._tcp" }, {"name": "HiFi WD10", "type": "upnp", "service": "urn:schemas-upnp-org:service:RenderingControl:1" } ], "Philips": [ /* ... */ ], "Alba": [ /* ... */ ] }; var makeEl = document.getElementById("make"), modelEl = document.getElementById("model"); makeEl.addEventListener('change', function() { modelEl.innerHTML = ""; // reset var defaultOption = document.createElement("option"); defaultOption.textContent = "Select model"; defaultOption.setAttribute("disabled", "disabled"); defaultOption.setAttribute("selected", "selected"); modelEl.appendChild(defaultOption); for(var i = 0, l = models[makeEl.value].length; i < l; i++) { var option = document.createElement("option"); option.textContent = models[makeEl.value][i]["name"]; option.setAttribute("value", models[makeEl.value][i]["type"] + ":" + models[makeEl.value][i]["service"]); modelEl.appendChild(option); } }, false); modelEl.addEventListener('change', function() { if(navigator.getNetworkServices && modelEl.value == "upnp:urn:schemas-upnp-org:service:RenderingControl:1") { navigator.getNetworkServices(modelEl.value, successCallback, errorCallback); } else if (modelEl.value == "zeroconf:_mediarenderer._http._tcp") { debug.innerHTML += "<br>Service type is not implemented by this application."; } else { debug.innerHTML += "<br>Service Discovery is not supported!"; } }, false); </script> <script> function successCallback( services ) { // Listen for service push notification messages services[0].addEventListener('notify', function ( msg ) { debug.innerHTML += "<br>" + services[0].name + " event received: "; debug.textContent += msg.data; }, false); // Send a control signal to mute the service audio var svcXhr = new XMLHttpRequest(); svcXhr.open("POST", services[0].url); // services[0].url and its // sub-resources have been whitelisted for // cross-site XHR use in this current // browsing context. svcXhr.setRequestHeader('SOAPAction', 'urn:schemas-upnp-org:service:RenderingControl:1#SetMute'); svcXhr.setRequestHeader('Content-Type', 'text/xml; charset="utf-8";'); svcXhr.onreadystatechange = function ( response ) { if( response.readyState != 4 || response.status != 200 ) return; debug.innerHTML += "<br>" + services[0].name + " response received: "; debug.textContent += response.responseXML; } // Service messaging to mute the provided service var svcMsg = '<?xml version="1.0" encoding="utf-8"?>' + '<s:Envelope s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" ' + 'xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">' + '<s:Body>' + '<u:SetMute xmlns:u="urn:schemas-upnp-org:service:RenderingControl:1">' + '<InstanceID>0</InstanceID>' + '<Channel>Master</Channel>' + '<DesiredMute>true</DesiredMute>' + '</u:SetMute>' + '</s:Body>' + '</s:Envelope>'; svcXhr.send(svcMsg); debug.innerHTML += "<br>" + services[0].name + " request sent: "; debug.textContent += svcMsg; } function errorCallback( error ) { debug.innerHTML += "<br>An error occurred: " + error.code; } </script>
Thanks are expressed by the editor to the following individuals for their feedback on this specification to
date (in alphabetical order):
Gar Bergstedt, Lars-Erik Bolstad, Cathy Chan, Hari G Kumar, Bob Lund, Giuseppe Pascale, Marcin Simonides,
Clarke Stevens, Christian Söderström, Mark Vickers.
Thanks are also expressed by the editor to the following organizations and groups for their support in
producing this specification to date (in alphabetical order):
CableLabs, Opera Software ASA, W3C Device APIs Working Group, W3C Web and TV Interest Group.