--- a/wi-addendum-local-services/Overview.html Tue Jul 10 11:37:21 2012 -0400
+++ b/wi-addendum-local-services/Overview.html Tue Jul 10 14:05:46 2012 -0400
@@ -576,583 +576,4 @@
</p>
</section>
</body>
-</html>=======
-<!DOCTYPE html>
-<html>
- <head>
- <title>Web Intents Addendum - Local Services</title>
- <meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
- <!--
- === NOTA BENE ===
- For the three scripts below, if your spec resides on dev.w3 you can check them
- out in the same tree and use relative links so that they'll work offline,
- -->
- <script src='http://www.w3.org/Tools/respec/respec-w3c-common' class='remove'></script>
- <script class='remove'>
- var respecConfig = {
- // specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
- specStatus: "ED",
-
- // the specification's short name, as in http://www.w3.org/TR/short-name/
- shortName: "Web Intents-UPnP addendum",
-
- // if your specification has a subtitle that goes below the main
- // formal title, define it here
- // subtitle : "an excellent document",
-
- // if you wish the publication date to be other than today, set this
- // publishDate: "2009-08-06",
-
- // if the specification's copyright date is a range of years, specify
- // the start date here:
- // copyrightStart: "2005"
-
- // if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
- // and its maturity status
- // previousPublishDate: "1977-03-15",
- // previousMaturity: "WD",
-
- // if there a publicly available Editor's Draft, this is the link
- // edDraftURI: "http://dev.w3.org/2009/dap/ReSpec.js/documentation.html",
-
- // if this is a LCWD, uncomment and set the end of its review period
- // lcEnd: "2009-08-05",
-
- // if you want to have extra CSS, append them to this list
- // it is recommended that the respec.css stylesheet be kept
- extraCSS: ["http://dev.w3.org/2009/dap/ReSpec.js/css/respec.css"],
-
- // editors, add as many as you like
- // only "name" is required
- editors: [
- { name: "Claes Nilsson",
- company: "Sony Mobile", companyURL: "http://www.sonymobile.com/se/" },
- ],
-
- // authors, add as many as you like.
- // This is optional, uncomment if you have authors as well as editors.
- // only "name" is required. Same format as editors.
-
- //authors: [
- // { name: "Your Name", url: "http://example.org/",
- // company: "Your Company", companyURL: "http://example.com/" },
- //],
-
- //
- edDraftURI: "http://w3c-test.org/dap/wi-addendum-local-services/",
-
- // name of the WG
- wg: "DAP/Web Apps Web Intents task force",
-
- // URI of the public WG page
- wgURI: "http://www.w3.org/2009/dap/",
-
- // name (without the @w3c.org) of the public mailing to which comments are due
- wgPublicList: "public-web-intents",
-
- // URI of the patent status for this WG, for Rec-track documents
- // !!!! IMPORTANT !!!!
- // This is important for Rec-track documents, do not copy a patent URI from a random
- // document unless you know what you're doing. If in doubt ask your friendly neighbourhood
- // Team Contact.
- wgPatentURI: "",
- };
- </script>
- </head>
- <body>
- <section id='abstract'>
- 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.
- </section>
-
- <section class='informative'>
- <h2>Introduction</h2>
- <p>
- 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:
- </p>
- <ol>
- <li>Web Intents Services register their intention to handle an action for the user </li>
- <li>A web application requests to start an action (share, edit, pick, view, ...)</li>
- <li>The user selects which service to handle the action</li>
- </ol>
- <p>
- 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.
- </p>
- <p>
- 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.
- </p>
- <p>
- 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.
- </p>
- <pre class="example sh_javascript_dom">
-
- // 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);});
- </pre>
- <p>
- 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.
- </p>
-
- <ol>
- <li>Triggered by navigator.startActivity the User Agent will start local network discovery of Web Intents Services.</li>
- <li>Replies from Web Intents enabled devices contain a URL to a Web Intents document, containing Web Intents Service registration
- markup, in the device. </li>
- <li>The Web Intents documents are retrieved by the User Agent and the dynamically registered Services are visible in the Web Intents Service picker. </li>
- <li>User selects Service.</li>
- <li>User Agent retrieves the Service page from the the Web Intents local network device and invokes it. </li>
- <li>The Service page handles the intent. </li>
- <li>When handling the intent is finished, the Service page issues window.intent.postResult and closes itself. </li>
- </ol>
-
- </section>
-
- <section id="conformance">
- <p>
- This specification defines conformance criteria that apply to:
- <ul>
- <li><dfn>UPnP enabled User Agent</dfn>: A <a>UPnP enabled User Agent</a> MUST support Web Intents [[!WEBINTENTS]] and the conformance criteria
- stated in this specification. </li>
- <li><dfn>UPnP enabled device</dfn>: A <a>UPnP enabled device</a> MUST support [[!UPNP-DEVICEARCH]] and the conformance criteria
- stated in this specification. </li>
- </ul>
-
- <p>
- TBD definitions of User Agents and devices for other local discovery and communication technologies...
- </p>
- </p>
- <p>
- 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.
- </p>
- <section>
- <h2>Dependencies</h2>
- <p>
- This specification relies on the following specifications:
-
- <dl>
- <dt>Web Intents</dt>
- <dd>This addendum specification is dependent on and defines optional extensions to the basic Web Intents specification, [[!WEBINTENTS]]. </dd>
- <dt>UPnP Device Architecture 1.0</dt>
- <dd>This addendum specification is dependent on and defines vendor specific extensions to the UPnP Device Architecture 1.0 specification, [[!UPNP-DEVICEARCH]] </dd>
- </dl>
-
- </p>
- </section>
- </section>
-
- <section>
- <h2>Terminology</h2>
- <p>
- Web Intents related terms are used according to section "Terminology" in [[!WEBINTENTS]].
- </p>
-
- <section>
- <h3>UPnP related terms</h3>
- <p>
- UPnP related terms are used according to [[!UPNP-DEVICEARCH]].
- </p>
- <p>
- The <a>UPnP enabled User Agent</a> has the role of a <dfn id="dfn-registration">control point</dfn> according to UPnP terminology.
- </p>
- <p>
- The <a>UPnP enabled device</a> discovered by the <a>UPnP enabled User Agent</a> has the roles of <dfn id="dfn-registration">device</dfn> according to UPnP terminology.
- </p>
- </section>
-
- <section>
- <h3>mDNS related terms</h3>
- <p>
- TBD...
- </p>
- </section>
-
-
- </section>
-
- <section>
-
- <h2>UPnP adaptation</h2>
-
- <section>
-
- <h3><a>UPnP enabled device</a></h3>
-
- <p>
- The <a>UPnP enabled device</a> <em class="rfc2119" title="must">must</em> support this section.
- </p>
-
- <section>
-
- <h4>UPnP Web Intents serviceType</h4>
-
- <p>
- The <a>UPnP enabled device</a> <em class="rfc2119" title="must">must</em> support the UPnP service which serviceType is the <code>urn:schemas-webintents-org:service:WebIntents:1</code>
- as a vendor specific serviceType according to [[!UPNP-DEVICEARCH]]. It is vendor dependent how the <a>UPnP enabled device</a> implements the serviceType,
- i.e. a device description of any deviceType could include this serviceType.
- </p>
-
- <p>
- The Web Intents serviceType <em class="rfc2119" title="must">must</em> have a dummy state variable, <code>X_State</code> of <code>ui4</code> data type to comform to [[!UPNP-DEVICEARCH]]
- which requires one or more state variables in a serviceType. The <code>X_State</code> state variable is not used with a value and is never evented.
- </p>
- <p>
- The Web Intents serviceType has no standard action.
- </p>
-
- <p>
- See below for the UPnP Service description document of the Web Intents serviceType.
- </p>
-
- <p align="left"><img src="Example_device_and_service_description_pages/Slide2.png" alt="Service description page" width="600" height="600" ><br>
- (<a href="Example_device_and_service_description_pages/Slide2.png">View as PNG</a>)
- </p>
-
-
- </section>
-
- <section>
-
- <h4>Web Intents specific SSDP headers</h4>
-
- <p>
- The <a>UPnP enabled device</a> <em class="rfc2119" title="must">must</em> 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:<code>urn:schemas-webintents-org:service:WebIntents:1</code>
- </p>
-
- <ul>
- <li>
- <code>location.webintents.org</code>: <em class="rfc2119" title="required">required</em>. States the location to the Web Intents document in the <a>UPnP enabled device</a>.
- If the value of this header is a relative URL the base URL is the base URL of the <code>LOCATION</code> header.
- </li>
- <li>
- <code>action.webintents.org</code>: <em class="rfc2119" title="optional">optional</em>. If supported, states the Web Intents
- <code>action</code> of the supported Web Intents Services and <em class="rfc2119" title="must">must</em>
- match the <code>action</code> attributes of the Service registration markup in the Web Intents document. To support more than
- one Web Intents <code>action</code> the action strings <em class="rfc2119" title="must">must</em> be separated with
- one or more commas. Commas included in action strings <em class="rfc2119" title="must">must</em> be percent-encoded as
- defined in [[!RFC3986]], section-2.1.
- <br /> <br />
- This header allows the <a>UPnP enabled User Agent</a> to filter received SSDP messages so that the <a>UPnP enabled User Agent</a>s only have to
- retrieve Web Intents documents for matching Web Intents Actions.
- </li>
- </ul>
-
- </section>
-
- <section>
-
- <h4>Web Intents document</h4>
-
- <p>
- The <a>UPnP enabled device</a> <em class="rfc2119" title="must">must</em> store Web Intents documents for the Web Intents Services the <a>UPnP enabled device</a> 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.
- </p>
-
- </section>
-
- <section>
-
- <h4>Web Intents Service pages</h4>
-
- <p>
- The <a>UPnP enabled device</a> <em class="rfc2119" title="must">must</em> store a Web Intents Service page for each Service that is
- referred in Web Intents documents through <code>href</code> attributes in the registration markup.
- </p>
- <p>
- Service pages contain Service handler code and fulfills the rules for Web Intents Services as defined by [[!WEBINTENTS]].
- </p>
-
- </section>
-
- </section>
-
- <section>
-
- <h3><a>UPnP enabled User Agent</a></h3>
-
- <p>
- The <a>UPnP enabled User Agent</a> <em class="rfc2119" title="must">must</em> support discovery of <a>UPnP enabled device<a>s 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.
- </p>
-
- <p>
- The sections below describe typical steps using these methods.
- </p>
- <section class='informative'>
- <h4>Dynamic Service registration based on M-SEARCH</h4>
- <p>
- The section describes the discovery process based on standard UPnP M-SEARCH multicast request.
- </p>
-
- <p>
- When the navigator.startActivity method [[!WEBINTENTS]] is called, the <a>UPnP enabled User Agent</a> runs the following steps:
- </p>
-
- <ol class="rule">
- <li>
- Send a multicast request with the method M-SEARCH in the format specified by [[!UPNP-DEVICEARCH]].
- <br />
- The <code>ST</code> header is set to: <code>urn:schemas-webintents-org:service:WebIntents:1</code>
- </li>
- <br />
- <li>
- For each matching M-SEARCH response, i.e. the response ST header is <code>urn:schemas-webintents-org:service:WebIntents:1</code> and the <code>action.webintents.org</code>
- header, if present, matches the Action of the invoked intent,
- the <a>UPnP enabled User Agent</a> attempts to retrieve the Web Intents document from the discovered <a>UPnP enabled device</a>.
- The value of the <code>location.webintents.org</code> header is the location for the Web Intents document.
- If this value is a relative URL the <a>UPnP enabled User Agent</a> uses the base URL of the <code>LOCATION</code> header as base URL for the location of the
- Web Intents document.
- <br /> <br />
- If the <a>UPnP enabled User Agent</a> fails to retrieve the Web Intents document it silently disregards the discovered Service.
- <br /> <br />
- If the <code>action.webintents.org</code> header is present and does not match the <code>action</code> attributes of the Services registered in the retrieved Web Intents
- document the <a>UPnP enabled User Agent</a> silently disregards the discovered Service.
- </li>
- <br />
- <li>
- It is expected that the Web Intents document contains registration markup and the <a>UPnP enabled User Agent</a> interprets this
- registration markup according to the rules for registration defined by [[!WEBINTENTS]] and register the Services accordingly.
- </li>
- <br />
- <li>
- The <a>UPnP enabled User Agent</a> makes each dynamically registered Service available for selection
- by the user, typically by making them visible and selectable in a Web Intents Service picker.
- </li>
- <br />
- <li>
- Based on user selection of a dynamically registered Service the <a>UPnP enabled User Agent</a> loads the
- Service handler code as defined by the <code>href</code> attribute in the registration markup for this Service according to the rules for
- loading Service pages defined in [[!WEBINTENTS]].
- </li>
-
- </ol>
-
- </section>
-
- <section class='informative'>
- <h4>Dynamic Service registration based on NOTIFY</h4>
- <p>
- This section describes the discovery process based on standard UPnP Advertisement with NOTIFY message.
- </p>
-
- <p>
- The <a>UPnP enabled User Agent</a> <em class="rfc2119" title="may">may</em> continously listen and act on advertisments according to the following steps:
- </p>
- <ol class="rule">
-
- <li>
- The <a>UPnP enabled User Agent</a> maintains a list of announced services based on received SSDP NOTIFY messages
- with <code>NT</code> header equal to <code>urn:schemas-webintents-org:service:WebIntents:1</code>.
- </li>
- <br />
- <li>
- When the navigator.startActivity method [[!WEBINTENTS]] is called the <a>UPnP enabled User Agent</a> checks the list
- of of announced services for a service with an <code>action.webintents.org</code> header that matches the Action of the invoked intent.
- </li>
- <br />
- <li>
- For each match the <a>UPnP enabled User Agent</a> attempts to retrieve the Web Intents document document from the discovered <a>UPnP enabled device</a>. The <a>UPnP enabled User Agent</a>
- may also attempt to retrieve the Web Intents document for announced services without an <code>action.webintents.org</code> header.
- The location of the Web Intents document is the value of the <code>location.webintents.org</code> header. If this value is a relative URL the
- base URL is the base URL of the <code>LOCATION</code> header.
- <br /> <br />
- If the <a>UPnP enabled User Agent</a> fails to retrieve the Web Intents document it silently disregards the discovered Service.
- <br /> <br />
- If the <code>action.webintents.org</code> header does not match the <code>action</code> attribute in the retrieved Web Intents document
- the <a>UPnP enabled User Agent</a> silently disregards the discovered Service.
- </li>
- <br />
- <li>
- It is expected that the Web Intents document contains registration markup and the <a>UPnP enabled User Agent</a> interprets the
- Web Intents document according to the rules for registration defined by [[!WEBINTENTS]] and register the Services accordingly.
- </li>
- <br />
- <li>
- The <a>UPnP enabled User Agent</a> makes each dynamically registered Service available for selection
- by the user, typically by making them visible and selectable in a Web Intents Service picker.
- </li>
- <br />
- <li>
- Based on user selection of a dynamically registered Service the <a>UPnP enabled User Agent</a> loads the
- Service handler code as defined by the <code>href</code> attribute in the registration markup for this Service according to the rules for
- loading Service pages defined in [[!WEBINTENTS]].
- </li>
- </ol>
-
- <p class="note">
- 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..
- </p>
-
- </section>
-
- <section class='informative'>
- <h4>Support for Web Intents and UPnP</h4>
- <p>
- In addition to the normative statements defined in this specification it is assumed that <a>UPnP enabled User Agent</a>s that comply to this specification
- support Web Intents according to [[!WEBINTENTS]] and UPnP Discovery, Description and Control according to [[!UPNP-DEVICEARCH11]].
- However, it is implementation dependent whether this is supported natively in the User Agent or supported through some external component,
- e.g. an in-device web server.
- </p>
- </section>
-
- <section class='informative'>
-
- <h4>Service availability management</h4>
-
- <p>
- The <a>UPnP enabled User Agent</a> must manage the availability of UPnP services. For example detect when contact with a <a>UPnP enabled device</a> 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 must be considered and long lasting "keep alive" sessions" should be avoided.
- </p>
-
- </section>
-
- </section>
-
-
-
- </section>
-
- <section>
-
- <h2>mDNS adaptation</h2>
-
- <p>
-
- This section describes how the User Agent handles Web Intents Services provided by local devices supporting mDNS.
- </p>
-
- <p>
- TBD....
- </p>
-
-
- </section>
-
-
- <section class='informative'>
- <h2>APIs / protocols Client - Service </h2>
- <p>
- 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.
- </p>
-
- <p>
- Examples:
- </p>
- <ul>
- <li>
- A Client application invoking a "View" intent provides, as intent payload data, a link to a video to be displayed at the remote <a>UPnP enabled device</a>.
- The Service application takes full control of the video playback by providing control buttons and sends UPnP commands to the remote device.
- So in this case there the simple "API" just gives the link to the video to play.
- </li>
- <li>
- Some use cases require a longer lasting relation between the Client and Service applications. By using the MessagePort[] attribute of the intent object
- a message channel can be established between the Client and Service page. This message channel can be used to run Service specific protocols,
- for example a protocol that allows the Client application to send simple video playback control commands to a Service application.
- </li>
- </ul>
-
- </section>
-
- <section class='informative appendix'>
- <h2>Examples and scenarios</h2>
- <section>
- <h3>View and control video on remote device through Service page control buttons</h3>
- <p>
- 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.
- </p>
-
- <p align="left"><img src="Example_scenario_1/Slide1.png" alt="Example scenario 1/Slide1" width="700" height="700" ><br>
- (<a href="Example_scenario_1/Slide1.png">View as PNG</a>)
- </p>
-
- <p align="left"><img src="Example_scenario_1/Slide2.png" alt="Example scenario 1/Slide2" width="700" height="700" ><br>
- (<a href="Example_scenario_1/Slide2.png">View as PNG</a>)
- </p>
-
- <p align="left"><img src="Example_scenario_1/Slide3.png" alt="Example scenario 1/Slide3" width="700" height="700" ><br>
- (<a href="Example_scenario_1/Slide3.png">View as PNG</a>)
- </p>
- </section>
-
- <section>
- <h3>View and control video on remote device through Client page control buttons</h3>
- <p>
- 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.
- </p>
-
- <p class="issue">
- 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.
- </p>
-
- <p align="left"><img src="Example_scenario_2/Slide1.png" alt="Example scenario 2/Slide1" width="700" height="700" ><br>
- (<a href="Example_scenario_2/Slide1.png">View as PNG</a>)
- </p>
-
- <p align="left"><img src="Example_scenario_2/Slide2.png" alt="Example scenario 2/Slide2" width="700" height="700" ><br>
- (<a href="Example_scenario_2/Slide2.png">View as PNG</a>)
- </p>
-
- <p align="left"><img src="Example_scenario_2/Slide3.png" alt="Example scenario 2/Slide3" width="700" height="700" ><br>
- (<a href="Example_scenario_2/Slide3.png">View as PNG</a>)
- </p>
-
- <p align="left"><img src="Example_scenario_2/Slide4.png" alt="Example scenario 2/Slide4" width="700" height="700" ><br>
- (<a href="Example_scenario_2/Slide4.png">View as PNG</a>)
- </p>
- </section>
-
-
-
- <section>
- <h3>Example of Web Intents document</h3>
-
- <p align="left"><img src="Example1_registration_page/Slide1.png" alt="Example1 registration page" width="280" height="280" ><br>
- (<a href="Example1_registration_page/Slide1.png">View as PNG</a>)
- </p>
- </section>
-
- <section>
- <h3>Example of UPnP Device description document</h3>
- <p align="left"><img src="Example_device_and_service_description_pages/Slide1.png" alt="Example device and service description pages/Slide1" width="600" height="600" ><br>
- (<a href="Example_device_and_service_description_pages/Slide1.png">View as PNG</a>)
- </p>
- </section>
-
- </section>
-
- <section class='appendix'>
- <h3>Acknowledgements</h3>
- <p>
- Many thanks to Sony Mobile colleagues Anders Isberg, Anders Edenbrandt and Björn Ekberg
- for all support.
- <br /> <br />
- Many thanks to Robin Berjon for making our lives so much easier with his cool specification editing tool.
- </p>
- </section>
- </body>
</html>