--- a/spec/Overview-respec.html Tue Jan 31 14:49:31 2012 -0800
+++ b/spec/Overview-respec.html Wed Mar 14 12:26:42 2012 -0700
@@ -294,7 +294,8 @@
launch multiple Intents simultaneously. Specific Intent objects are
immutable once created.
</p>
- <dl title='[Constructor(in string action, in string type, in any data) raises DOMException] interface Intent' class='idl'>
+ <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'>
<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
@@ -307,13 +308,19 @@
<dd>The object used MUST be an object upon which the structured clone
algorithm can be performed, including Transferables, or the constructor MUST
throw an exception.</dd>
+ <dt>string getExtra(in 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)</dt>
+ <dt>void postResult(in any data, in 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).
The payload must be an object upon which the structured clone algorithm can be
- performed, including Transferables. [[!HTML5]] </dd>
+ 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>
<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
@@ -321,7 +328,15 @@
The playload must be an object upon which the structured clone algorithm
can be performed, including Transferables. [[!HTML5]]</dd>
</dl>
- </section>
+
+ <p>
+ Notes on the intent object: The transferList parameter is not available
+ post-creation. It becomes an internal implementation detail directing the
+ User Agent to interpret some fields of the |data| argument as Transferable. The
+ |data| and |transferList| arguments MUST be implemented following the W3C
+ Web Messaging spec [[!http://dev.w3.org/html5/postmsg/]].
+ </p>
+ </section>
<section>
<h3>Invocation API</h3>
@@ -334,7 +349,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 onSuccess, in optional onFailure)</dt>
+ <dt>void startActivity (in Intent intent, in optional callback onSuccess, in 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
@@ -358,6 +373,26 @@
The invocation API is implemented by the <code>window.navigator</code> object.
</p>
<dl title='Navigator implements Intents' class='idl'></dl>
+
+ <section>
+ <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>
+ <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
+ clone algorithm with Transferables, as in the Web Messaging spec.
+ [[!http://dev.w3.org/html5/postmsg/]]
+ </dl>
+
+ <dl title='interface IntentFailureCallback' class='idl'>
+ <dt>void onFailure (in optional any data)
+ <dd>The |data| passed will be the payload data passed to the postFailure
+ method of the delivered Intent.</dd>
+ </dl>
+ </section>
+
</section>
<section>
@@ -387,7 +422,7 @@
<p>
The <code>window.intent</code> object MUST be made available across
same-origin redirects of the service page. It MUST NOT be available if
- redirects cross a same-origin boundary.
+ redirects cross an origin boundary.
</p>
<p>
So the following redirect sequence
@@ -417,9 +452,9 @@
In other words, in the browsing context in which the Intent is originally
delivered, the intent data MUST be available to pages in a redirect or
navigation sequence when they are in the same origin as that to which it was originally
- delivered, but MUST NOT be available to any other pages. This allows Service
- pages to delegate handling, to redirect to login screens, and so forth, but
- does not make the Intent data available to any such pages encountered which
+ delivered (and have the enabling markup), but MUST NOT be available to any other pages.
+ This allows Service pages to delegate handling, to redirect to login screens,
+ and so forth, but does not make the Intent data available to any such pages encountered which
are not in the same origin.
</p>
</section>
@@ -427,17 +462,17 @@
<section>
<h3>Registration Markup</h3>
<p>
- Service pages declaratively mark themselves as providing handling
- functionality for particular intent actions and types. A User Agent MUST NOT
- deliver an Intent to a page which does not include markup describing what
- intents it can handle which matches the intent being delivered. The algorithm
- for matching intents is that the action string provided in invocation and
- registration must match exactly, and the type strings must match exactly
- except for possible [[!RFC2046]] MIME subtype wildcards. MIME parameters
- specified in the Service page markup will be checked and must match exactly,
- except for MIME-formatted strings with MIME subtype wildcards. MIME
- parameters which are included in the intent and which are not specified do
- not impact delivery.
+ Service pages declaratively mark themselves (or other on-domain pages)
+ as providing handling functionality for particular intent actions and types.
+ A User Agent MUST NOT deliver an Intent to a web app service page which
+ does not include markup describing what intents it can handle which matches
+ the intent being delivered. The algorithm for matching intents is that the
+ action string provided in invocation and registration must match exactly,
+ and the type strings must match exactly except for possible [[!RFC2046]]
+ MIME subtype wildcards. MIME parameters specified in the Service page markup
+ will be checked and must match exactly, except for MIME-formatted strings
+ with MIME subtype wildcards. MIME parameters which are included in the
+ intent and which are not specified do not impact delivery.
<pre>
<!ENTITY % Disposition "{window|inline}">
@@ -452,6 +487,24 @@
</pre>
</p>
<p>
+ If the <code>action</code> attribute is missing, the intent Service is
+ assumed to handle display of the provided type(s) in that attribute.
+ </p>
+ <p>
+ If the <code>type</code> attribute is missing, the intent Service is
+ assumed to be registered specifically for a <code>text/plain</code> type.
+ </p>
+ <p>
+ If the <code>href</code> attribute is missing, the intent Service is
+ assumed to be registering for the URL of the page on which the tag is found.
+ (That is, "this page.")
+ </p>
+ <p>
+ If the <code>title</code> attribute is missing, the User Agent SHOULD
+ utilize the title of the registered Service page to guide the user-visible
+ indicator of that Service during Selection.
+ </p>
+ <p>
The <code>disposition</code> attribute allows a service to choose which
context to be opened in. The User Agent MUST NOT allow the Client page any
ability to change the disposition. The <code>window</code> disposition means
@@ -462,30 +515,60 @@
under the control of the client page.
</p>
<p>
- The User Agent MUST not obey any registration markup which is not
+ <i>This section should not be construed as limiting the ability of the User
+ Agent to manage registration of non-web services. That is, the User Agent
+ may handle intent invocations locally, using extensions, or with
+ third-party system services. This section solely governs how web-app service pages
+ register and unregister with the User Agent.</i>
+ </p>
+ <h4>Same-origin registration</h4>
+ <p>
+ The User Agent MUST NOT obey any registration markup which is not
same-origin. That is, a page may only register <code>href</code> attributes
for other service handlers on its same origin. A page may register itself
- as a Service handler, by leaving this attribute empty.
+ as a Service handler, by leaving the |href| attribute empty.
</p>
<p>
- If the <code>title</code> attribute is missing, the User Agent SHOULD
- utilize the title of the registered Service page to guide the user-visible
- indicator of that Service during Selection.
+ For cross-page registration, when the |href| attribute points to a different
+ resource, the User Agent SHOULD interpret intent registrations additively.
+ That is, an intent descriptor from the tag would be added to the registry
+ if it is not present (if the user approves the addition).
</p>
- <p>
- If the <code>action</code> attribute is missing, the intent Service is
- assumed to handle display of the provided type(s) in that attribute.
- </p>
- <p>
- If the <code>type</code> attribute is missing, the intent Service is
- assumed to be registered specifically for a <code>text/plain</code> type.
- </p>
+ <h4>Unregistering</h4>
<p>
The User Agent SHOULD treat any registration markup which has both
<code>action</code> and <code>type</code> attributes missing as if the
- markup specified no intent capability on the page. That is, a page may
- unregister itself quietly by removing the tag altogether, or explicitly
- by keeping the tag present, but empty.
+ markup specified no intent capability on the |href| page. That is, a page may
+ unregister itself quietly by removing all intent tags, or explicitly
+ by keeping the tag present, but empty. This explicit unregistration SHOULD
+ be supported for same-origin pages as well.
+ </p>
+ <p>
+ The intent tags on the service handler page itself SHOULD be interpreted by
+ the User Agent as authoritative. That is, if the User Agent loads a service
+ page, and sees that not all intent descriptors it believes will be handled
+ by the page are actually handled, it would replace the currently-registered
+ set with the new set declared by the page.
+ </p>
+ <h4>HTTP Error Codes on Service Pages</h4>
+ <p>
+ If a registered service page is retrieved and has a non-20x error code
+ [[!HTTP11]], the User Agent SHOULD take the following actions:</p>
+ <p>
+ 30x: redirect to the indicated page. If the page is on-domain, and has
+ intent markup, the intent will be re-delivered. If the redirect is permanent
+ (301), the User Agent MAY update its service registration records to reflect
+ that.
+ </p>
+ <p>
+ 40x: indicate to the user that the page cannot be loaded, along with any
+ remediation capabilities (i.e. authentication for 403 or payments for 402).
+ In the case of error 410, the User Agent SHOULD unregister the handler from
+ its internal registry.
+ </p>
+ <p>
+ 50x: indicate to the user that the page cannot be loaded.
+ </p>
</p>
</section>
@@ -511,7 +594,7 @@
The User Agent MAY provide additional mechanisms for web intents service
registration. For example, by external applications, through a separate
API, as a result of a permissions bundle in a downloaded web application,
- or pre-bundled.
+ or pre-bundled. (TODO: add example of a local network service)
</p>
<p>
For intents invoked by client web applications, the User Agent MUST