--- a/spec/Overview-respec.html Wed Mar 14 14:42:42 2012 -0700
+++ b/spec/Overview-respec.html Tue Apr 10 18:21:29 2012 -0700
@@ -287,6 +287,33 @@
<h2>API Description</h2>
<section>
+ <h3>Intent parameters dictionary</h3>
+ <p>
+ This object can be used in the object-literal constructor of the Intent
+ object. When using the object literal constructor, the <b>action</b> and
+ <b>type</b> fields are required; all others are optional.
+ </p>
+ <dl title='dictionary IntentParameters' class='idl'>
+ <dt>readonly attribute DOMString action</dt>
+ <dd>An opaque string indicating the action type of the intent. The
+ string MUST NOT be empty.</dd>
+ <dt>readonly attribute DOMString type</dt>
+ <dd>A string indicating the type of the data payload. The data payload
+ MUST be described by this parameter, which MUST NOT be empty.</dd>
+ <dt>readonly attribute any data</dt>
+ <dd>The data payload used MUST be an object upon which the structured
+ clone algorithm can be performed, including Transferables.</dd>
+ <dt>readonly attribute sequence&lt;Transferable&gt; transfer</dt>
+ <dd>The list of Transferables, for use in the structured clone
+ algorithm.</dd>
+ <dt>readonly attribute dictionary&lt;string&gt; extras</dt>
+ <dd>A key-value map of extra metadata to be sent with the intent</dd>
+ <dt>readonly attribute URL service</dt>
+ <dd>When present, this field marks the intent as an explicit intent. The
+ value MUST be an absolute URL.</dd>
+ </dl>
+ </section>
+ <section>
<h3>Intent object</h3>
<p>
The Intent object models a particular task which can be requested by
@@ -294,8 +321,8 @@
launch multiple Intents simultaneously. Specific Intent objects are
immutable once created.
</p>
- <dl title='[Constructor(in string action, in string type, in optional any
- data, in optional sequence&lt;Transferable&gt; transferList, in optional dictionary&lt;string&gt; extraData) raises DOMException] interface Intent' class='idl'>
+
+ <dl title='[Constructor(IntentParameters params)<br> Constructor(string action, string type, optional any data, optional sequence&lt;Transferable&gt; transferList) raises DOMException] interface Intent' class='idl'>
<dt>readonly attribute DOMString action</dt>
<dd>This is an opaque string. Chosen strings SHOULD be namespaced by a
URL namespace convention. The string MUST NOT be empty, or the
@@ -313,12 +340,11 @@
page.</b> Any ports used in the |transferList| of the constructor during invocation will be
delivered to the service page in the |ports| attribute. See
[[!http://dev.w3.org/html5/postmsg/]]</dd>
- <dt>string getExtra(in DOMString key)</dt>
+ <dt>string getExtra(DOMString key)</dt>
<dd>Retrieves the value (if any) from the extra data dictionary this
intent was constructed with.</dd>
- <dt>void postResult(in any data, in optional
- sequence<Transferable>)</dt>
+ <dt>void postResult(any data, optional sequence<Transferable>)</dt>
<dd><b>Only present when the Intent object is delivered to the
Service page.</b> The payload passed to this method will be returned to the onSuccess
callback registered by the client page in the startActivity call (if any).
@@ -326,14 +352,13 @@
performed. The Transferables array, if present, will specify
transferable elements in the |data| payload argument, as per
[[!HTML5]] [[!http://dev.w3.org/html5/postmsg/]]</dd>
- <dt>void postFailure(in any data)</dt>
+ <dt>void postFailure(any data)</dt>
<dd><b>Only present when the Intent object is delivered to the Service
page.</b> The payload passed to this method will be returned to the onFailure
callback registered by the client page in the startActivity call (if any).
The playload must be an object upon which the structured clone algorithm
can be performed, including Transferables. [[!HTML5]]</dd>
</dl>
-
<p>
Notes on the intent object: The transferList parameter is not available
post-creation. It becomes an internal implementation detail directing the
@@ -341,6 +366,10 @@
|data| and |transferList| arguments MUST be implemented following the W3C
Web Messaging spec [[!http://dev.w3.org/html5/postmsg/]].
</p>
+ <p>
+ The User Agent MUST perform the structured clone algorithm on creation
+ of the Intent object.
+ </p>
</section>
<section>
@@ -354,7 +383,7 @@
intent action and type. The user is then able to select which service should handle the intent.
</p>
<dl title='[NoInterfaceObject] interface Intents' class='idl'>
- <dt>void startActivity (in Intent intent, in optional callback onSuccess, in optional callback onFailure)</dt>
+ <dt>void startActivity (Intent intent, optional callback onSuccess, optional callback onFailure)</dt>
<dd>Called to invoke an intent service. The Intent object is described
above. The onSuccess handler, if any, will be called by the user agent if
the service is dispatched, processes the intent, and calls postResult on
@@ -383,7 +412,7 @@
<p>The callbacks passed to startActivity MUST provide these signatures:</p>
<dl title='[NoInterfaceObject] interface IntentSuccessCallback' class='idl'>
- <dt>void onSuccess (in optional any data, in optional MessagePort[] ports)</dt>
+ <dt>void onSuccess (optional any data, optional MessagePort[] ports)</dt>
<dd>The |data| passed will be the payload data from the structured
cloneable object passed to the postResult method of the delivered Intent.
The |ports| will be any ports in the payload, as resulting from the structured
@@ -392,7 +421,7 @@
</dl>
<dl title='interface IntentFailureCallback' class='idl'>
- <dt>void onFailure (in optional any data)
+ <dt>void onFailure (optional any data)
<dd>The |data| passed will be the payload data passed to the postFailure
method of the delivered Intent.</dd>
</dl>
@@ -412,17 +441,17 @@
<dd>The intent object as delivered to the service page (includes
postResult and postFailure methods).</dd>
</dl>
- <dl title='DOMWindow implements IntentProvider' class='idl'></dl>
+ <dl title='Window implements IntentProvider' class='idl'></dl>
<p>
This object will only be made available to Service pages when they are
loaded in the context of an intent invocation. Even if the same URL is
loaded in other situations, the User Agent MUST NOT make
- <code>DOMWindow</code> implement <code>IntentProvider</code>. Similarly, if
+ <code>Window</code> implement <code>IntentProvider</code>. Similarly, if
a Service page is registered, but the User Agent loads it and it does not
contain the declarative markup marking it as expecting to handle the Intent
the User Agent is delivering, the User Agent MUST NOT make
- <code>DOMWindow</code> implement <code>IntentProvider</code>.
+ <code>Window</code> implement <code>IntentProvider</code>.
</p>
<p>
The <code>window.intent</code> object MUST be made available across
@@ -636,10 +665,10 @@
of the <code>window.intent</code> object so that they return their
serializable payloads to the registered handlers the User Agent received
in the invoking <code>navigator.startActivity</code> call. If the user
- closes the service page before it has responded, the User Agent SHOULD
+ closes the service page before it has responded, the User Agent MUST
invoke the <code>onFailure</code> callback in the client page invocation,
if any. If the user cancels a service selection UI control the User Agent
- displays in the course of dispatching an intent, the User Agent SHOULD
+ displays in the course of dispatching an intent, the User Agent MUST
invoke the <code>onFailure</code> callback in the client page invocation,
if any.
</p>
@@ -680,6 +709,31 @@
services it knows can handle that intent type so that the user can
complete the activity.
</p>
+ <section>
+ <h3>Explicit Intents</h3>
+ <p>
+ When handling an Intent marked as explicit (that is, constructed with the
+ object literal constructor with a non-empty <b>service</b> field), the
+ expected User Agent behavior is that if this "service" attribute is
+ present, it SHOULD NOT display a service selection mechanism to the user.
+ Instead, the service url SHOULD be loaded directly to handle the intent.
+ (This is not a hard restriction. The User Agent MAY provide a way for the
+ user to intercept even an explicit invocation.)
+ </p>
+ <p>
+ During delivery, all restrictions are still in place. That is, the User
+ Agent MUST follow the above requirements on placing the
+ <code>window.intent</code> object in the scope of the page, and respect
+ any declarative metadata in that service page. If the user agent needs
+ information about the service (i.e. disposition, title, etc) for use
+ in preparing its UI, it MAY load the service URL and examine the page
+ for any declarative metadata.
+ </p>
+ <p>
+ The User Agent MAY ask the user if they wish to install this service,
+ just like for any other visit of the page.
+ </p>
+ </section>
</section>
<section>
--- a/spec/Overview.html Wed Mar 14 14:42:42 2012 -0700
+++ b/spec/Overview.html Tue Apr 10 18:21:29 2012 -0700
@@ -477,7 +477,7 @@
pre.sh_sourceCode .sh_attribute { color: #006400; }
</style><link href="http://www.w3.org/StyleSheets/TR/W3C-ED" rel="stylesheet" type="text/css" charset="utf-8"></head>
- <body style="display: inherit; "><div class="head"><p><a href="http://www.w3.org/"><img width="72" height="48" src="http://www.w3.org/Icons/w3c_home" alt="W3C"></a></p><h1 class="title" id="title">Web Intents</h1><h2 id="w3c-editor-s-draft-14-march-2012"><acronym title="World Wide Web Consortium">W3C</acronym> Editor's Draft 14 March 2012</h2><dl><dt>This version:</dt><dd><a href="http://dev.w3.org/2011/webapps/TODO.html">http://dev.w3.org/2011/webapps/TODO.html</a></dd><dt>Latest published version:</dt><dd><a href="http://www.w3.org/TR/web-intents/">http://www.w3.org/TR/web-intents/</a></dd><dt>Latest editor's draft:</dt><dd><a href="http://dev.w3.org/2011/webapps/TODO.html">http://dev.w3.org/2011/webapps/TODO.html</a></dd><dt>Previous version:</dt><dd>none</dd><dt>Editors:</dt><dd><span>Greg Billock</span>, <a href="http://google.com/">Google</a></dd>
+ <body style="display: inherit; "><div class="head"><p><a href="http://www.w3.org/"><img width="72" height="48" src="http://www.w3.org/Icons/w3c_home" alt="W3C"></a></p><h1 class="title" id="title">Web Intents</h1><h2 id="w3c-editor-s-draft-11-april-2012"><acronym title="World Wide Web Consortium">W3C</acronym> Editor's Draft 11 April 2012</h2><dl><dt>This version:</dt><dd><a href="http://dev.w3.org/2011/webapps/TODO.html">http://dev.w3.org/2011/webapps/TODO.html</a></dd><dt>Latest published version:</dt><dd><a href="http://www.w3.org/TR/web-intents/">http://www.w3.org/TR/web-intents/</a></dd><dt>Latest editor's draft:</dt><dd><a href="http://dev.w3.org/2011/webapps/TODO.html">http://dev.w3.org/2011/webapps/TODO.html</a></dd><dt>Previous version:</dt><dd>none</dd><dt>Editors:</dt><dd><span>Greg Billock</span>, <a href="http://google.com/">Google</a></dd>
<dd><span>James Hawkins</span>, <a href="http://google.com/">Google</a></dd>
<dd><span>Paul Kinlan</span>, <a href="http://google.com/">Google</a></dd>
</dl><p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © 2012 <a href="http://www.w3.org/"><acronym title="World Wide Web Consortium">W3C</acronym></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute of Technology">MIT</acronym></a>, <a href="http://www.ercim.eu/"><acronym title="European Research Consortium for Informatics and Mathematics">ERCIM</acronym></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. <acronym title="World Wide Web Consortium">W3C</acronym> <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.</p><hr></div>
@@ -491,7 +491,7 @@
pages to create, receive, and reply to Web Intents messages, and the
procedures the User Agent carries out to facilitate that process.
</p>
- </div><div id="sotd" class="introductory section"><h2>Status of This Document</h2><p><em>This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current <acronym title="World Wide Web Consortium">W3C</acronym> publications and the latest revision of this technical report can be found in the <a href="http://www.w3.org/TR/"><acronym title="World Wide Web Consortium">W3C</acronym> technical reports index</a> at http://www.w3.org/TR/.</em></p><p>This document was published by the <a href="http://www.w3.org/2008/webapps/">Web Applications (WebApps) Working Group</a> as an Editor's Draft. If you wish to make comments regarding this document, please send them to <a href="mailto:public-web-intents@w3.org">public-web-intents@w3.org</a> (<a href="mailto:public-web-intents-request@w3.org?subject=subscribe">subscribe</a>, <a href="http://lists.w3.org/Archives/Public/public-web-intents/">archives</a>). All feedback is welcome.</p><p>Publication as an Editor's Draft does not imply endorsement by the <acronym title="World Wide Web Consortium">W3C</acronym> 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.</p><p>This document was produced by a group operating under the <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February 2004 <acronym title="World Wide Web Consortium">W3C</acronym> Patent Policy</a>. <acronym title="World Wide Web Consortium">W3C</acronym> maintains a <a href="TODO" rel="disclosure">public list of any patent disclosures</a> 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 <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential Claim(s)</a> must disclose the information in accordance with <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section 6 of the <acronym title="World Wide Web Consortium">W3C</acronym> Patent Policy</a>.</p></div><div id="toc" class="section"><h2 class="introductory">Table of Contents</h2><ul class="toc"><li class="tocline"><a href="#introduction" class="tocxref"><span class="secno">1. </span>Introduction</a><ul class="toc"><li class="tocline"><a href="#example" class="tocxref"><span class="secno">1.1 </span>Example</a></li><li class="tocline"><a href="#normative-parts" class="tocxref"><span class="secno">1.2 </span>Normative parts</a></li></ul></li><li class="tocline"><a href="#terminology" class="tocxref"><span class="secno">2. </span>Terminology</a><ul class="toc"><li class="tocline"><a href="#actors" class="tocxref"><span class="secno">2.1 </span>Actors</a></li><li class="tocline"><a href="#life-cycle-of-intents" class="tocxref"><span class="secno">2.2 </span>Life cycle of Intents</a></li></ul></li><li class="tocline"><a href="#api-description" class="tocxref"><span class="secno">3. </span>API Description</a><ul class="toc"><li class="tocline"><a href="#intent-object" class="tocxref"><span class="secno">3.1 </span>Intent object</a><ul class="toc"><li class="tocline"><a href="#attributes" class="tocxref"><span class="secno">3.1.1 </span>Attributes</a></li><li class="tocline"><a href="#methods" class="tocxref"><span class="secno">3.1.2 </span>Methods</a></li></ul></li><li class="tocline"><a href="#invocation-api" class="tocxref"><span class="secno">3.2 </span>Invocation API</a><ul class="toc"><li class="tocline"><a href="#methods-1" class="tocxref"><span class="secno">3.2.1 </span>Methods</a></li></ul></li><li class="tocline"><a href="#delivery-and-response-api" class="tocxref"><span class="secno">3.3 </span>Delivery and Response API</a><ul class="toc"><li class="tocline"><a href="#attributes-1" class="tocxref"><span class="secno">3.3.1 </span>Attributes</a></li></ul></li><li class="tocline"><a href="#registration-markup" class="tocxref"><span class="secno">3.4 </span>Registration Markup</a><ul class="toc"><li class="tocline"><a href="#attributes-2" class="tocxref"><span class="secno">3.4.1 </span>Attributes</a></li></ul></li></ul></li><li class="tocline"><a href="#user-agent-behavior" class="tocxref"><span class="secno">4. </span>User Agent Behavior</a></li><li class="tocline"><a href="#use-cases-and-requirements" class="tocxref"><span class="secno">5. </span>Use Cases and Requirements</a><ul class="toc"><li class="tocline"><a href="#sharing" class="tocxref"><span class="secno">5.1 </span>Sharing</a></li><li class="tocline"><a href="#integration-with-local-web-apps" class="tocxref"><span class="secno">5.2 </span>Integration with local web apps</a></li><li class="tocline"><a href="#persistent-connections" class="tocxref"><span class="secno">5.3 </span>Persistent connections</a></li><li class="tocline"><a href="#integration-with-external-applications" class="tocxref"><span class="secno">5.4 </span>Integration with external applications</a></li><li class="tocline"><a href="#translating-existing-web-platform-features-to-intents" class="tocxref"><span class="secno">5.5 </span>Translating existing web platform features to intents</a></li><li class="tocline"><a href="#authentication" class="tocxref"><span class="secno">5.6 </span>Authentication</a></li></ul></li><li class="tocline"><a href="#acknowledgements" class="tocxref"><span class="secno">A. </span>Acknowledgements</a></li><li class="tocline"><a href="#references" class="tocxref"><span class="secno">B. </span>References</a><ul class="toc"><li class="tocline"><a href="#normative-references" class="tocxref"><span class="secno">B.1 </span>Normative references</a></li><li class="tocline"><a href="#informative-references" class="tocxref"><span class="secno">B.2 </span>Informative references</a></li></ul></li></ul></div>
+ </div><div id="sotd" class="introductory section"><h2>Status of This Document</h2><p><em>This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current <acronym title="World Wide Web Consortium">W3C</acronym> publications and the latest revision of this technical report can be found in the <a href="http://www.w3.org/TR/"><acronym title="World Wide Web Consortium">W3C</acronym> technical reports index</a> at http://www.w3.org/TR/.</em></p><p>This document was published by the <a href="http://www.w3.org/2008/webapps/">Web Applications (WebApps) Working Group</a> as an Editor's Draft. If you wish to make comments regarding this document, please send them to <a href="mailto:public-web-intents@w3.org">public-web-intents@w3.org</a> (<a href="mailto:public-web-intents-request@w3.org?subject=subscribe">subscribe</a>, <a href="http://lists.w3.org/Archives/Public/public-web-intents/">archives</a>). All feedback is welcome.</p><p>Publication as an Editor's Draft does not imply endorsement by the <acronym title="World Wide Web Consortium">W3C</acronym> 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.</p><p>This document was produced by a group operating under the <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February 2004 <acronym title="World Wide Web Consortium">W3C</acronym> Patent Policy</a>. <acronym title="World Wide Web Consortium">W3C</acronym> maintains a <a href="TODO" rel="disclosure">public list of any patent disclosures</a> 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 <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential Claim(s)</a> must disclose the information in accordance with <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section 6 of the <acronym title="World Wide Web Consortium">W3C</acronym> Patent Policy</a>.</p></div><div id="toc" class="section"><h2 class="introductory">Table of Contents</h2><ul class="toc"><li class="tocline"><a href="#introduction" class="tocxref"><span class="secno">1. </span>Introduction</a><ul class="toc"><li class="tocline"><a href="#example" class="tocxref"><span class="secno">1.1 </span>Example</a></li><li class="tocline"><a href="#normative-parts" class="tocxref"><span class="secno">1.2 </span>Normative parts</a></li></ul></li><li class="tocline"><a href="#terminology" class="tocxref"><span class="secno">2. </span>Terminology</a><ul class="toc"><li class="tocline"><a href="#actors" class="tocxref"><span class="secno">2.1 </span>Actors</a></li><li class="tocline"><a href="#life-cycle-of-intents" class="tocxref"><span class="secno">2.2 </span>Life cycle of Intents</a></li></ul></li><li class="tocline"><a href="#api-description" class="tocxref"><span class="secno">3. </span>API Description</a><ul class="toc"><li class="tocline"><a href="#intent-parameters-dictionary" class="tocxref"><span class="secno">3.1 </span>Intent parameters dictionary</a><ul class="toc"><li class="tocline"><a href="#dictionary-intentparameters-members" class="tocxref"><span class="secno">3.1.1 </span>Dictionary <span class="idlType formerLink idlType"><code>IntentParameters</code></span> Members</a></li></ul></li><li class="tocline"><a href="#intent-object" class="tocxref"><span class="secno">3.2 </span>Intent object</a><ul class="toc"><li class="tocline"><a href="#attributes" class="tocxref"><span class="secno">3.2.1 </span>Attributes</a></li><li class="tocline"><a href="#methods" class="tocxref"><span class="secno">3.2.2 </span>Methods</a></li></ul></li><li class="tocline"><a href="#invocation-api" class="tocxref"><span class="secno">3.3 </span>Invocation API</a><ul class="toc"><li class="tocline"><a href="#methods-1" class="tocxref"><span class="secno">3.3.1 </span>Methods</a></li></ul></li><li class="tocline"><a href="#delivery-and-response-api" class="tocxref"><span class="secno">3.4 </span>Delivery and Response API</a><ul class="toc"><li class="tocline"><a href="#attributes-1" class="tocxref"><span class="secno">3.4.1 </span>Attributes</a></li></ul></li><li class="tocline"><a href="#registration-markup" class="tocxref"><span class="secno">3.5 </span>Registration Markup</a><ul class="toc"><li class="tocline"><a href="#attributes-2" class="tocxref"><span class="secno">3.5.1 </span>Attributes</a></li></ul></li></ul></li><li class="tocline"><a href="#user-agent-behavior" class="tocxref"><span class="secno">4. </span>User Agent Behavior</a><ul class="toc"><li class="tocline"><a href="#explicit-intents" class="tocxref"><span class="secno">4.1 </span>Explicit Intents</a></li></ul></li><li class="tocline"><a href="#use-cases-and-requirements" class="tocxref"><span class="secno">5. </span>Use Cases and Requirements</a><ul class="toc"><li class="tocline"><a href="#sharing" class="tocxref"><span class="secno">5.1 </span>Sharing</a></li><li class="tocline"><a href="#integration-with-local-web-apps" class="tocxref"><span class="secno">5.2 </span>Integration with local web apps</a></li><li class="tocline"><a href="#persistent-connections" class="tocxref"><span class="secno">5.3 </span>Persistent connections</a></li><li class="tocline"><a href="#integration-with-external-applications" class="tocxref"><span class="secno">5.4 </span>Integration with external applications</a></li><li class="tocline"><a href="#translating-existing-web-platform-features-to-intents" class="tocxref"><span class="secno">5.5 </span>Translating existing web platform features to intents</a></li><li class="tocline"><a href="#authentication" class="tocxref"><span class="secno">5.6 </span>Authentication</a></li></ul></li><li class="tocline"><a href="#acknowledgements" class="tocxref"><span class="secno">A. </span>Acknowledgements</a></li><li class="tocline"><a href="#references" class="tocxref"><span class="secno">B. </span>References</a><ul class="toc"><li class="tocline"><a href="#normative-references" class="tocxref"><span class="secno">B.1 </span>Normative references</a></li><li class="tocline"><a href="#informative-references" class="tocxref"><span class="secno">B.2 </span>Informative references</a></li></ul></li></ul></div>
<div id="introduction" class="section">
<!--OddPage--><h2><span class="secno">1. </span>Introduction</h2>
@@ -678,16 +678,38 @@
<div id="api-description" class="section">
<!--OddPage--><h2><span class="secno">3. </span>API Description</h2>
+ <div id="intent-parameters-dictionary" class="section">
+ <h3><span class="secno">3.1 </span>Intent parameters dictionary</h3>
+ <p>
+ This object can be used in the object-literal constructor of the Intent
+ object. When using the object literal constructor, the <b>action</b> and
+ <b>type</b> fields are required; all others are optional.
+ </p>
+ <pre class="idl"><span class="idlDictionary" id="idl-def-IntentParameters">dictionary <span class="idlDictionaryID">IntentParameters</span> {
+<span class="idlMember"> <span class="idlMemberType"><a>readonly attribute DOMString</a></span> <span class="idlMemberName"><a href="#widl-IntentParameters-action">action</a></span>;</span>
+<span class="idlMember"> <span class="idlMemberType"><a>readonly attribute DOMString</a></span> <span class="idlMemberName"><a href="#widl-IntentParameters-type">type</a></span>;</span>
+<span class="idlMember"> <span class="idlMemberType"><a>readonly attribute any</a></span> <span class="idlMemberName"><a href="#widl-IntentParameters-data">data</a></span>;</span>
+<span class="idlMember"> <span class="idlMemberType"><a>readonly attribute sequence<Transferable></a></span> <span class="idlMemberName"><a href="#widl-IntentParameters-transfer">transfer</a></span>;</span>
+<span class="idlMember"> <span class="idlMemberType"><a>readonly attribute dictionary<string></a></span> <span class="idlMemberName"><a href="#widl-IntentParameters-extras">extras</a></span>;</span>
+<span class="idlMember"> <span class="idlMemberType"><a>readonly attribute URL</a></span> <span class="idlMemberName"><a href="#widl-IntentParameters-service">service</a></span>;</span>
+};</span>
+</pre><div id="dictionary-intentparameters-members" class="section"><h4><span class="secno">3.1.1 </span>Dictionary <a class="idlType" href="#idl-def-IntentParameters"><code>IntentParameters</code></a> Members</h4><dl class="dictionary-members"><dt id="widl-IntentParameters-action"><code>action</code> of type <span class="idlMemberType"><a>readonly attribute DOMString</a></span></dt><dd>An opaque string indicating the action type of the intent. The
+ string <em class="rfc2119" title="must not">must not</em> be empty.</dd><dt id="widl-IntentParameters-data"><code>data</code> of type <span class="idlMemberType"><a>readonly attribute any</a></span></dt><dd>The data payload used <em class="rfc2119" title="must">must</em> be an object upon which the structured
+ clone algorithm can be performed, including Transferables.</dd><dt id="widl-IntentParameters-extras"><code>extras</code> of type <span class="idlMemberType"><a>readonly attribute dictionary&lt;string&gt;</a></span></dt><dd>A key-value map of extra metadata to be sent with the intent</dd><dt id="widl-IntentParameters-service"><code>service</code> of type <span class="idlMemberType"><a>readonly attribute URL</a></span></dt><dd>When present, this field marks the intent as an explicit intent. The
+ value <em class="rfc2119" title="must">must</em> be an absolute URL.</dd><dt id="widl-IntentParameters-transfer"><code>transfer</code> of type <span class="idlMemberType"><a>readonly attribute sequence&lt;Transferable&gt;</a></span></dt><dd>The list of Transferables, for use in the structured clone
+ algorithm.</dd><dt id="widl-IntentParameters-type"><code>type</code> of type <span class="idlMemberType"><a>readonly attribute DOMString</a></span></dt><dd>A string indicating the type of the data payload. The data payload
+ <em class="rfc2119" title="must">must</em> be described by this parameter, which <em class="rfc2119" title="must not">must not</em> be empty.</dd></dl></div>
+ </div>
<div id="intent-object" class="section">
- <h3><span class="secno">3.1 </span>Intent object</h3>
+ <h3><span class="secno">3.2 </span>Intent object</h3>
<p>
The Intent object models a particular task which can be requested by
handled by client pages. It is left up to the client page whether to
launch multiple Intents simultaneously. Specific Intent objects are
immutable once created.
</p>
- <pre class="idl"><span class="idlInterface" id="idl-def-Intent">[<span class="extAttr">Constructor(in string action, in string type, in optional any
- data, in optional sequence<Transferable> transferList, in optional dictionary<string> extraData) raises DOMException</span>]
+
+ <pre class="idl"><span class="idlInterface" id="idl-def-Intent">[<span class="extAttr">Constructor(IntentParameters params)<br> Constructor(string action, string type, optional any data, optional sequence<Transferable> transferList) raises DOMException</span>]
interface <span class="idlInterfaceID">Intent</span> {
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>DOMString</a></span> <span class="idlAttrName"><a href="#widl-Intent-action">action</a></span>;</span>
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>DOMString</a></span> <span class="idlAttrName"><a href="#widl-Intent-type">type</a></span>;</span>
@@ -697,7 +719,7 @@
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-Intent-postResult-void-any-data--sequence-Transferable">postResult</a></span> (<span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">data</span></span>, <span class="idlParam">optional <span class="idlParamType"><a></a></span> <span class="idlParamName">sequence<transferable></transferable></span></span>);</span>
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-Intent-postFailure-void-any-data">postFailure</a></span> (<span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">data</span></span>);</span>
};</span>
-</pre><div id="attributes" class="section"><h4><span class="secno">3.1.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-Intent-action"><code>action</code> of type <span class="idlAttrType"><a>DOMString</a></span>, readonly</dt><dd>This is an opaque string. Chosen strings <em class="rfc2119" title="should">should</em> be namespaced by a
+</pre><div id="attributes" class="section"><h4><span class="secno">3.2.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-Intent-action"><code>action</code> of type <span class="idlAttrType"><a>DOMString</a></span>, readonly</dt><dd>This is an opaque string. Chosen strings <em class="rfc2119" title="should">should</em> be namespaced by a
URL namespace convention. The string <em class="rfc2119" title="must not">must not</em> be empty, or the
constructor <em class="rfc2119" title="must">must</em> throw an exception.</dd><dt id="widl-Intent-data"><code>data</code> of type <span class="idlAttrType"><a>any</a></span>, readonly</dt><dd>The object used <em class="rfc2119" title="must">must</em> be an object upon which the structured clone
algorithm can be performed, including Transferables, or the constructor <em class="rfc2119" title="must">must</em>
@@ -706,7 +728,7 @@
delivered to the service page in the |ports| attribute. See
[[!http://dev.w3.org/html5/postmsg/]]</dd><dt id="widl-Intent-type"><code>type</code> of type <span class="idlAttrType"><a>DOMString</a></span>, readonly</dt><dd>The data payload <em class="rfc2119" title="must">must</em> be described by the type parameter.
Recommended type strings are MIME strings or self-documenting urls. The
- string <em class="rfc2119" title="must not">must not</em> be empty, or the constructor <em class="rfc2119" title="must">must</em> throw an exception.</dd></dl></div><div id="methods" class="section"><h4><span class="secno">3.1.2 </span>Methods</h4><dl class="methods"><dt id="widl-Intent-getExtra-string-DOMString-key"><code>getExtra</code></dt><dd>Retrieves the value (if any) from the extra data dictionary this
+ string <em class="rfc2119" title="must not">must not</em> be empty, or the constructor <em class="rfc2119" title="must">must</em> throw an exception.</dd></dl></div><div id="methods" class="section"><h4><span class="secno">3.2.2 </span>Methods</h4><dl class="methods"><dt id="widl-Intent-getExtra-string-DOMString-key"><code>getExtra</code></dt><dd>Retrieves the value (if any) from the extra data dictionary this
intent was constructed with.<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">key</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr></table><div><em>Return type: </em><code><a>string</a></code></div></dd><dt id="widl-Intent-postFailure-void-any-data"><code>postFailure</code></dt><dd><b>Only present when the Intent object is delivered to the Service
page.</b> The payload passed to this method will be returned to the onFailure
callback registered by the client page in the startActivity call (if any).
@@ -718,7 +740,6 @@
performed. The Transferables array, if present, will specify
transferable elements in the |data| payload argument, as per
[<cite><a class="bibref" rel="biblioentry" href="#bib-HTML5">HTML5</a></cite>] [[!http://dev.w3.org/html5/postmsg/]]<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">data</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr><tr><td class="prmName">sequence<Transferable></td><td class="prmType"><code><a></a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc"></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></div>
-
<p>
Notes on the intent object: The transferList parameter is not available
post-creation. It becomes an internal implementation detail directing the
@@ -726,10 +747,14 @@
|data| and |transferList| arguments <em class="rfc2119" title="must">must</em> be implemented following the <acronym title="World Wide Web Consortium">W3C</acronym>
Web Messaging spec [[!http://dev.w3.org/html5/postmsg/]].
</p>
+ <p>
+ The User Agent <em class="rfc2119" title="must">must</em> perform the structured clone algorithm on creation
+ of the Intent object.
+ </p>
</div>
<div id="invocation-api" class="section">
- <h3><span class="secno">3.2 </span>Invocation API</h3>
+ <h3><span class="secno">3.3 </span>Invocation API</h3>
<p>
The client invokes an intent by constructing an Intent object as above and invoking
the <code>navigator.startActivity</code> function on it. The callbacks
@@ -742,7 +767,7 @@
interface <span class="idlInterfaceID">Intents</span> {
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-Intents-startActivity-void-Intent-intent-callback-onSuccess-callback-onFailure">startActivity</a></span> (<span class="idlParam"><span class="idlParamType"><a href="#idl-def-Intent" class="idlType"><code>Intent</code></a></span> <span class="idlParamName">intent</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>callback</a></span> <span class="idlParamName">onSuccess</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>callback</a></span> <span class="idlParamName">onFailure</span></span>);</span>
};</span>
-</pre><div id="methods-1" class="section"><h4><span class="secno">3.2.1 </span>Methods</h4><dl class="methods"><dt id="widl-Intents-startActivity-void-Intent-intent-callback-onSuccess-callback-onFailure"><code>startActivity</code></dt><dd>Called to invoke an intent service. The Intent object is described
+</pre><div id="methods-1" class="section"><h4><span class="secno">3.3.1 </span>Methods</h4><dl class="methods"><dt id="widl-Intents-startActivity-void-Intent-intent-callback-onSuccess-callback-onFailure"><code>startActivity</code></dt><dd>Called to invoke an intent service. The Intent object is described
above. The onSuccess handler, if any, will be called by the user agent if
the service is dispatched, processes the intent, and calls postResult on
the Intent object it receives. The handler will be invoked with one
@@ -785,7 +810,7 @@
</div>
<div id="delivery-and-response-api" class="section">
- <h3><span class="secno">3.3 </span>Delivery and Response API</h3>
+ <h3><span class="secno">3.4 </span>Delivery and Response API</h3>
<p>
When the User Agent loads a Service page to handle an Intent invocation, it
will place a <code>window.intent</code> object in the scope of the page.
@@ -795,19 +820,19 @@
interface <span class="idlInterfaceID">IntentProvider</span> {
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a href="#idl-def-Intent" class="idlType"><code>Intent</code></a></span> <span class="idlAttrName"><a href="#widl-IntentProvider-intent">intent</a></span>;</span>
};</span>
-</pre><div id="attributes-1" class="section"><h4><span class="secno">3.3.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-IntentProvider-intent"><code>intent</code> of type <span class="idlAttrType"><a href="#idl-def-Intent" class="idlType"><code>Intent</code></a></span>, readonly</dt><dd>The intent object as delivered to the service page (includes
+</pre><div id="attributes-1" class="section"><h4><span class="secno">3.4.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-IntentProvider-intent"><code>intent</code> of type <span class="idlAttrType"><a href="#idl-def-Intent" class="idlType"><code>Intent</code></a></span>, readonly</dt><dd>The intent object as delivered to the service page (includes
postResult and postFailure methods).</dd></dl></div>
- <pre class="idl"><span class="idlImplements"><a>DOMWindow</a> implements <a href="#idl-def-IntentProvider" class="idlType"><code>IntentProvider</code></a>;</span></pre><div class="idlImplementsDesc"><p>All instances of the <code><a>DOMWindow</a></code> type are defined to also implement the <a href="#idl-def-IntentProvider" class="idlType"><code>IntentProvider</code></a> interface.</p></div>
+ <pre class="idl"><span class="idlImplements"><a>Window</a> implements <a href="#idl-def-IntentProvider" class="idlType"><code>IntentProvider</code></a>;</span></pre><div class="idlImplementsDesc"><p>All instances of the <code><a>Window</a></code> type are defined to also implement the <a href="#idl-def-IntentProvider" class="idlType"><code>IntentProvider</code></a> interface.</p></div>
<p>
This object will only be made available to Service pages when they are
loaded in the context of an intent invocation. Even if the same URL is
loaded in other situations, the User Agent <em class="rfc2119" title="must not">must not</em> make
- <code>DOMWindow</code> implement <code>IntentProvider</code>. Similarly, if
+ <code>Window</code> implement <code>IntentProvider</code>. Similarly, if
a Service page is registered, but the User Agent loads it and it does not
contain the declarative markup marking it as expecting to handle the Intent
the User Agent is delivering, the User Agent <em class="rfc2119" title="must not">must not</em> make
- <code>DOMWindow</code> implement <code>IntentProvider</code>.
+ <code>Window</code> implement <code>IntentProvider</code>.
</p>
<p>
The <code>window.intent</code> object <em class="rfc2119" title="must">must</em> be made available across
@@ -850,7 +875,7 @@
</div>
<div id="registration-markup" class="section">
- <h3><span class="secno">3.4 </span>Registration Markup</h3>
+ <h3><span class="secno">3.5 </span>Registration Markup</h3>
<p>
Service pages declaratively mark themselves (or other on-domain pages)
as providing handling functionality for particular intent actions and types
@@ -872,7 +897,7 @@
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>string</a></span> <span class="idlAttrName"><a href="#widl-HTMLIntentElement-title">title</a></span>;</span>
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>string</a></span> <span class="idlAttrName"><a href="#widl-HTMLIntentElement-disposition">disposition</a></span>;</span>
};</span>
-</pre><div id="attributes-2" class="section"><h4><span class="secno">3.4.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-HTMLIntentElement-action"><code>action</code> of type <span class="idlAttrType"><a>string</a></span>, readonly</dt><dd>An opaque string indicating the behavior class the service supports.
+</pre><div id="attributes-2" class="section"><h4><span class="secno">3.5.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-HTMLIntentElement-action"><code>action</code> of type <span class="idlAttrType"><a>string</a></span>, readonly</dt><dd>An opaque string indicating the behavior class the service supports.
It is recommended that users use a fully qualified URI.
If the <code>action</code> attribute is missing, the intent Service is
assumed to handle display of the provided type(s) in the <code>type</code>
@@ -1017,10 +1042,10 @@
of the <code>window.intent</code> object so that they return their
serializable payloads to the registered handlers the User Agent received
in the invoking <code>navigator.startActivity</code> call. If the user
- closes the service page before it has responded, the User Agent <em class="rfc2119" title="should">should</em>
+ closes the service page before it has responded, the User Agent <em class="rfc2119" title="must">must</em>
invoke the <code>onFailure</code> callback in the client page invocation,
if any. If the user cancels a service selection UI control the User Agent
- displays in the course of dispatching an intent, the User Agent <em class="rfc2119" title="should">should</em>
+ displays in the course of dispatching an intent, the User Agent <em class="rfc2119" title="must">must</em>
invoke the <code>onFailure</code> callback in the client page invocation,
if any.
</p>
@@ -1061,6 +1086,31 @@
services it knows can handle that intent type so that the user can
complete the activity.
</p>
+ <div id="explicit-intents" class="section">
+ <h3><span class="secno">4.1 </span>Explicit Intents</h3>
+ <p>
+ When handling an Intent marked as explicit (that is, constructed with the
+ object literal constructor with a non-empty <b>service</b> field), the
+ expected User Agent behavior is that if this "service" attribute is
+ present, it <em class="rfc2119" title="should not">should not</em> display a service selection mechanism to the user.
+ Instead, the service url <em class="rfc2119" title="should">should</em> be loaded directly to handle the intent.
+ (This is not a hard restriction. The User Agent <em class="rfc2119" title="may">may</em> provide a way for the
+ user to intercept even an explicit invocation.)
+ </p>
+ <p>
+ During delivery, all restrictions are still in place. That is, the User
+ Agent <em class="rfc2119" title="must">must</em> follow the above requirements on placing the
+ <code>window.intent</code> object in the scope of the page, and respect
+ any declarative metadata in that service page. If the user agent needs
+ information about the service (i.e. disposition, title, etc) for use
+ in preparing its UI, it <em class="rfc2119" title="may">may</em> load the service URL and examine the page
+ for any declarative metadata.
+ </p>
+ <p>
+ The User Agent <em class="rfc2119" title="may">may</em> ask the user if they wish to install this service,
+ just like for any other visit of the page.
+ </p>
+ </div>
</div>
<div id="use-cases-and-requirements" class="section">