The Device APIs Working Group is currently not progressing the approach outlined in this draft. Please treat this document with caution and do not reference it or use it as the basis for implementation. The domain covered by this document is still within the scope of the Working Group as defined in its Charter. The Working Group may resume this work or adopt an alternative approach depending on the interest of WG members and implementers.

This specification is an addendum to Web Intents, [[!WEBINTENTS]], that defines how Web Intents enabled User Agents can discover and communicate with local Web Intents Services.

Introduction

Web Intents,[[!WEBINTENTS]], is a service discovery and light-weight RPC mechanism for web applications. The concept enables rich integration between web applications. A typical Web Intents scenario is:

  1. Web Intents Services register their intention to handle an action for the user
  2. A web application requests to start an action (share, edit, pick, view, ...)
  3. The user selects which service to handle the action
  4. The selected service executes the action

A Web Intents Service is represented by a web page that declaratively marks itself as providing handling functionality for particular intents. Users register Web Intents Services by visiting web pages that contain registration markup. However, the strength of Web Intents is the ability to provide web applications with access to Services residing not only in the cloud but also in local environments.

This specification defines optional extensions to Web Intents enabled User Agents to discover and dynamically register local Web Intents Services. Note that all details of the specific low level protocols used to discover and communicate with the local services are hidden to the Client Web Applications.

The following code illustrates how a web application containing links to videos, can initiate video playback by creating and invoking a "video intent" as defined in [[!WEBINTENTS]]. This code is the same irrespective of whether the Service executing the intent action is a cloud based Service or a local Service. 

      
        // Create a new intent
var intent = new Intent( "http://webintents.org/view","video/mp4",{ "src":videoCanvas.src, "img": videoCanvas.poster});
					
// Start intents picker 
navigator.startActivity(intent,
  // On Result
  function(intentData) {console.log("player.html: On Result" + intentData);}, 
  // On Failure
  function(intentData) {console.log("player.html: On Failure" + intentData);});

The example below briefly describes the steps taken when a Service on a local network, e.g. UPnP or mDNS, device is discovered and selected by the user.

  1. Triggered by navigator.startActivity the User Agent will start local network discovery of Web Intents Services.
  2. Replies from Web Intents enabled devices contain a URL to a Web Intents document, containing Web Intents Service registration markup, in the device.
  3. The Web Intents documents are retrieved by the User Agent and the dynamically registered Services are visible in the Web Intents Service picker.
  4. User selects Service.
  5. User Agent retrieves the Service page from the the Web Intents local network device and invokes it.
  6. The Service page handles the intent.
  7. When handling the intent is finished, the Service page issues window.intent.postResult and closes itself.

This specification defines conformance criteria that apply to:

Implementations that use ECMAScript to implement the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]], as this specification uses that specification and terminology.

Dependencies

This specification relies on the following specifications:

Web Intents
This addendum specification is dependent on and defines optional extensions to the basic Web Intents specification, [[!WEBINTENTS]].
UPnP Device Architecture 1.0
This addendum specification is dependent on and defines vendor specific extensions to the UPnP Device Architecture 1.0 specification, [[!UPNP-DEVICEARCH]].
IANA Service Name and Transport Protocol Port Number Registry
This addendum specification adds new entry on it, [[!IANA-SRVPORT-REG]].
DNS-SD
This addendum specification is dependent on it, [[!DNS-SD]].
mDNS
This addendum specification is dependent on it, [[!MDNS]].

Terminology

Web Intents related terms are used according to section "Terminology" in [[!WEBINTENTS]].

UPnP related terms

UPnP related terms are used according to [[!UPNP-DEVICEARCH]].

The UPnP enabled User Agent has the role of a control point according to UPnP terminology.

The Web Intents enabled UPnP device discovered by the UPnP enabled User Agent has the roles of device according to UPnP terminology.

mDNS related terms

The mDNS enabled User Agent has the role of a DNS client with capability of [[!DNS-SD]].

The Web Intents enabled mDNS device discovered by the mDNS enabled User Agent has the roles of service according to [[!MDNS]] and [[!DNS-SD]].

UPnP adaptation

Web Intents enabled UPnP device

The Web Intents enabled UPnP device must support this section.

UPnP Web Intents serviceType

The Web Intents enabled UPnP device must support one UPnP service which serviceType is the urn:schemas-webintents-org:service:WebIntents:1 as a vendor specific serviceType according to [[!UPNP-DEVICEARCH]]. It is vendor dependent how the Web Intents enabled UPnP device implements the serviceType, i.e. a device description of any deviceType could include this serviceType.

The Web Intents serviceType must have a dummy state variable, X_State of boolean data type to comform to [[!UPNP-DEVICEARCH]] which requires one or more state variables in a serviceType. The X_State state variable is not used with a value and is never evented.

The Web Intents serviceType has no standard action.

See below for the UPnP Service description document of the Web Intents serviceType.

Service description page
(View as PNG)

Web Intents specific SSDP headers

The Web Intents enabled UPnP device must support SSDP discovery process based on standard UPnP Discovery extended with 2 additional SSDP headers for M-SEARCH response and NOTIFY when ST/NT headers are:urn:schemas-webintents-org:service:WebIntents:1

  • location.webintents.org: required. States the location to the Web Intents document in the Web Intents enabled UPnP device. If the value of this header is a relative URL the base URL is the base URL of the LOCATION header.
  • action.webintents.org: optional. If supported, states the Web Intents action of the supported Web Intents Services and must match the action attributes of the Service registration markup in the Web Intents document. Each action string must be surrounded by double-quotes and if more than one Web Intents action is defined the action strings must be separated with comma.

    This header allows the UPnP enabled User Agent to filter received SSDP messages so that the UPnP enabled User Agent only has to retrieve Web Intents documents for matching Web Intents Actions.

    Examples of action.webintents.org headers:
    • action.webintents.org:"view"
    • action.webintents.org:"http://intents.w3.org/experimental-discover"
    • action.webintents.org:"http://intents.sony.net/local-discover","view"
    • action.webintents.org:"http://intents.w3.org/experimental-discover","http://intents.w3.org/experimental-view"

Web Intents document

The Web Intents enabled UPnP device must host Web Intents documents for the Web Intents Services the Web Intents enabled UPnP device supports. Web Intents documents are html pages that contain Web Intents Service registration markup according to the rules for Web Intents Service registration defined by [[!WEBINTENTS]]. They may also contain Service handler code for Services registered within the same document.

Web Intents Service pages

The Web Intents enabled UPnP device must host a Web Intents Service page for each Service that is referred in Web Intents documents through href attributes in the registration markup.

Service pages contain Service handler code and fulfills the rules for Web Intents Services as defined by [[!WEBINTENTS]].

UPnP enabled User Agent

The UPnP enabled User Agent must support discovery of Web Intents enabled UPnP devices through SSDP Discovery or through Advertisement or through both methods according to [[!UPNP-DEVICEARCH]] and according to the Web Intents serviceType and Web Intents specific SSDP headers defined in this specification, section 4.1.

The sections below describe typical steps using these methods.

Dynamic Service registration based on M-SEARCH

The section describes the discovery process based on standard UPnP M-SEARCH multicast request.

When the navigator.startActivity method [[!WEBINTENTS]] is called, the UPnP enabled User Agent runs the following steps:

  1. Send a multicast request with the method M-SEARCH in the format specified by [[!UPNP-DEVICEARCH]].
    The ST header is set to: urn:schemas-webintents-org:service:WebIntents:1
  2. For each matching M-SEARCH response, i.e. the response ST header is urn:schemas-webintents-org:service:WebIntents:1 and the action.webintents.org header, if present, matches the Action of the invoked intent, the UPnP enabled User Agent attempts to retrieve the Web Intents document from the discovered Web Intents enabled UPnP device. The value of the location.webintents.org header is the location for the Web Intents document. If this value is a relative URL the UPnP enabled User Agent uses the base URL of the LOCATION header as base URL for the location of the Web Intents document.

    If the UPnP enabled User Agent fails to retrieve the Web Intents document it silently disregards the received M-SEARCH response.

    If the action.webintents.org header is present and does not match the action attributes of the Services registered in the retrieved Web Intents document the UPnP enabled User Agent silently disregards the the received M-SEARCH response.
  3. It is expected that the Web Intents document contains registration markup and the UPnP enabled User Agent interprets this registration markup according to the rules for registration defined by [[!WEBINTENTS]] and register the Services accordingly. The Web Intents document is not displayed to the user and for security reasons it is recommended that the UPnP enabled User Agent during the Service registration process just interprets the registration markup and other related "safe" elements such as favicon.
  4. The UPnP enabled User Agent makes each dynamically registered Service, that matches the Action of the invoked intent, available for selection by the user, typically by making them visible and selectable in a Web Intents Service picker.
  5. Based on user selection of a dynamically registered Service the UPnP enabled User Agent loads the Service handler code as defined by the href attribute in the registration markup for this Service according to the rules for loading Service pages defined in [[!WEBINTENTS]].

Dynamic Service registration based on NOTIFY

This section describes the discovery process based on standard UPnP Advertisement with NOTIFY message.

The UPnP enabled User Agent may continuously listen to and act on advertisments according to the following steps:

  1. The UPnP enabled User Agent maintains a list of announced UPnP services based on received SSDP NOTIFY messages with NT header equal to urn:schemas-webintents-org:service:WebIntents:1.
  2. When the navigator.startActivity method [[!WEBINTENTS]] is called the UPnP enabled User Agent checks the list of of announced services and attempts to retrieve the Web Intents document from the discovered Web Intents enabled UPnP device in the following cases:
    • The received NOTIFY message contains an action.webintents.org header and this header matches the Action of the invoked intent.
    • The received NOTIFY message does not contain an action.webintents.org header.

    The location of the Web Intents document is the value of the location.webintents.org header. If this value is a relative URL the base URL is the base URL of the LOCATION header.

    If the UPnP enabled User Agent fails to retrieve the Web Intents document it silently disregards the received NOTIFY message.

    If the action.webintents.org header does not match the action attribute in the retrieved Web Intents document the UPnP enabled User Agent silently disregards the received NOTIFY message.
  3. It is expected that the Web Intents document contains registration markup and the UPnP enabled User Agent interprets the Web Intents document according to the rules for registration defined by [[!WEBINTENTS]] and register the Services accordingly. The Web Intents document is not displayed to the user and for security reasons it is recommended that the UPnP enabled User Agent during the Service registration process just interprets the registration markup and other related "safe" elements such as favicon.
  4. The UPnP enabled User Agent makes each dynamically registered Service, that matches the Action of the invoked intent, available for selection by the user, typically by making them visible and selectable in a Web Intents Service picker.
  5. Based on user selection of a dynamically registered Service the UPnP enabled User Agent loads the Service handler code as defined by the href attribute in the registration markup for this Service according to the rules for loading Service pages defined in [[!WEBINTENTS]].

Power consumption in battery powered devices should be considered. If power consumption is severe continuously listening to SSDP advertisement in the background should not be used..

Support for Web Intents and UPnP

In addition to the normative statements defined in this specification a UPnP enabled User Agent that complies to this specification supports Web Intents according to [[!WEBINTENTS]] and UPnP Discovery and Description according to [[!UPNP-DEVICEARCH]].

Service availability management

The UPnP enabled User Agent should manage the availability of UPnP services. For example detect when contact with a Web Intents enabled UPnP device is lost through standard UPnP life cycle management and remove a previously discovered and registered Service from the Service picker. However, for battery powered devices power consumption should be considered and long lasting "keep alive" sessions" should be avoided.

mDNS (DNS-SD) adaptation

This section describes how the User Agent handles Web Intents Services provided by local devices supporting mDNS and DNS-SD.

Web Intents enabled mDNS device

The Web Intents enabled mDNS device must support this section.

Web Intents service type for DNS-SD

The Web Intents enabled mDNS device must support [[!DNS-SD]] with a SRV record of the webintents service type.

A service type webintents should be registered in [[!IANA-SRVPORT-REG]].

The TXT record for the webintents service must have following parameters:

  • location: required. States the location to the Web Intents document in the Web Intents enabled mDNS device. The value of this header is path to be concatenated with a host of the Web Intents enabled mDNS device to determine the location. The definition of the Web Intents document is the same as for UPnP.
  • action: optional. If supported, states the Web Intents action of the supported Web Intents Services and must match the action attributes of the Service registration markup in the Web Intents document. To support more than one Web Intents action the action strings must be separated with comma. Commas included in action strings must be percent-encoded as defined in [[!RFC3986]], section-2.1.
    This allows the mDNS enabled User Agent to filter received mDNS messages so that the mDNS enabled User Agent only has to retrieve Web Intents documents for matching Web Intents Actions.

mDNS enabled User Agent

The mDNS enabled User Agent must support discovery of Web Intents enabled mDNS devices through mDNS and DNS-SD according to [[!MDNS]], [[!DNS-SD]] and according to the Web Intents specific DNS records defined in this specification, section 5.1.

Dynamic Service registration

When the navigator.startActivity method [[!WEBINTENTS]] is called, the mDNS enabled User Agent typically runs the following steps:

  1. Send a multicast PTR query of the _webintents._tcp.local in the format specified by [[!MDNS]] and [[!DNS-SD]].
  2. For each response, send a unicast TXT query of the webintents service instance in the PTR answer.

    This step can be omitted in case that the Web Intents enabled mDNS device attaches a TXT answer with the previous answer.

  3. For each matching response, i.e. the response TXT record does not have an action parameter or does have an action parameter matching the Action of the invoked intent, send a unicast request with a SRV query of the webintens service instance.

    This step can be omitted in case that the Web Intents enabled mDNS device attaches a SRV answer with the previous answer.

  4. For each response, send a unicast A and/or AAAA query of the host name in the SRV answer.

    This step can be omitted in case that the Web Intents enabled mDNS device attaches an A and/or AAAA answer with the previous answer.

  5. The mDNS enabled User Agent attempts to retrieve the Web Intents document from the discovered Web Intents enabled mDNS device. The destination URL consists of an IP address in the A or AAAA answer, a port number in the SRV record and an absolute path in the location parameter of the TXT record.

    If the mDNS enabled User Agent fails to retrieve the Web Intents document it silently disregards the received response.

    If the action parameter is present and does not match the action attributes of the Services registered in the retrieved Web Intents document the mDNS enabled User Agent silently disregards the the received response.

    Note that following steps are identical to those of UPnP described in 4.2.
  6. It is expected that the Web Intents document contains registration markup and the mDNS enabled User Agent interprets this registration markup according to the rules for registration defined by [[!WEBINTENTS]] and register the Services accordingly. The Web Intents document is not displayed to the user and for security reasons it is recommended that the mDNS enabled User Agent during the Service registration process just interprets the registration markup and other related "safe" elements such as favicon.
  7. The mDNS enabled User Agent makes each dynamically registered Service, that matches the Action of the invoked intent, available for selection by the user, typically by making them visible and selectable in a Web Intents Service picker.
  8. Based on user selection of a dynamically registered Service the mDNS enabled User Agent loads the Service handler code as defined by the href attribute in the registration markup for this Service according to the rules for loading Service pages defined in [[!WEBINTENTS]].

Sample Records

See below for the example records for Web Intents. An mDNS enabled User Agent looking for devices supporting http://webintents.org/view Web Intents can understand that it is possible to get a Web Intents document for "LivingRoomTV" at http://192.168.1.47:3619/webintents.html.

APIs / protocols Client - Service

The APIs / protocols for interaction between Client and Service pages are not defined by this specification. It is assumed that Web Intents based APIs and protocols will be standardized by W3C and that these will be applicable for Client and Service applications running on User Agents that comply to this specification. Different use cases will require different ways of interaction patterns between Client and Service.

Examples:

Examples and scenarios

View and control video on remote device through Service page control buttons

The following scenario describes how a Client page uses Web Intents to discover a remote video view service. The Service page contains the UI for controlling the video playback.

Example scenario 1/Slide1
(View as PNG)

Example scenario 1/Slide2
(View as PNG)

Example scenario 1/Slide3
(View as PNG)

View and control video on remote device through Client page control buttons

The following scenario describes how a Client page uses Web Intents to discover a remote video view service. The UI stays in the Client page, which contains the UI controls for the video playback. This means that there is a need for continuous communication between the Client page and the Service page, which is "hidden", i.e. it has no UI. The Client page creates a messaging channel and sends the messaging channel port to the Service page trhrough the intent invocation. A high level "TV control" protocol, supporting commands such as "play", "pause" and "stop, runs on top of the messaging channel.

In this example the assumption is that he Client invokes an intent to discover a Service that supports a specified protocol running on top of the message channel So the "discover" intent Action is used and Type is set to the specific protocol used to communicate with the Service.

This scenario assumes the possibility to have hidden/background Service pages or Service pages that are visible inline the Client page. Currently [[!WEBINTENTS]] does not allow this but W3C DAP Action http://www.w3.org/2009/dap/track/actions/519 should add a proposal for a hidden disposition.

Example scenario 2/Slide1
(View as PNG)

Example scenario 2/Slide2
(View as PNG)

Example scenario 2/Slide3
(View as PNG)

Example scenario 2/Slide4
(View as PNG)

Example of Web Intents document

Example1 registration page
(View as PNG)

Example of UPnP Device description document

Example device and service description pages/Slide1
(View as PNG)

Acknowledgements

Many thanks to Sony colleagues Anders Isberg, Naoyuki Sato, Tatsuya Igarashi, Anders Edenbrandt and Björn Ekberg for all support.

Many thanks to Robin Berjon for making our lives so much easier with his cool specification editing tool.