--- a/spec/Overview-respec.html Tue Jul 17 08:25:12 2012 -0700
+++ b/spec/Overview-respec.html Mon Jul 30 08:17:29 2012 -0700
@@ -160,7 +160,7 @@
<title>Image Meme Editor</title>
</head>
<body>
- <intent action="http://webintents.org/edit" type="text/uri-list;type=image/* image/*"></intent>
+ <intent action="http://webintents.org/edit" type="text/uri-list image/*"></intent>
<script>
window.addEventListener("load", function() {
if (window.intent) {
@@ -215,8 +215,8 @@
<section>
<h3>Life cycle of Intents and Services</h3>
<p>
- <dfn>Registration</dfn> is how a Service page informs the User Agent
- that it is capable of handling Intents.
+ <dfn>Registration</dfn> is how a web page page informs the User Agent
+ that it (or another same-origin Service page) is capable of handling Intents.
</p>
<p>
<dfn>Invocation</dfn> refers to the API by which a Client page
@@ -273,17 +273,17 @@
<dd>When present, this field marks the intent as an explicit intent. The
value MUST be an absolute URL.</dd>
<dt>sequence<URL> suggestions</dt>
- <dd>When present, this field provides a list of (absolute) suggested Service URLs
- of which the Client is aware and which can handle the intent.</dd>
+ <dd>When present, this field provides a list of suggested Service URLs,
+ each of which is an absolute URL that the Client is aware of and which
+ can handle the intent.</dd>
</dl>
</section>
<section>
<h3>Intent object</h3>
<p>
The Intent object models a particular task which can be requested to be
- handled by Services. It is left up to the client page whether to
- launch multiple Intents simultaneously. Specific Intent objects are
- immutable once created.
+ handled by Services. A Client page may invoke multiple Intents simultaneously.
+ Specific Intent objects are immutable once created.
</p>
<dl title='[Constructor(IntentParameters params),<br> Constructor(DOMString action, DOMString type, optional any data, optional sequence&lt;Transferable&gt; transferList)] interface Intent' class='idl'>
@@ -301,12 +301,11 @@
throw an exception.</dd>
<dt>readonly attribute MessagePort[] ports</dt>
<dd><b>Only present when the Intent object is delivered to the Service
- 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
+ page.</b> Any ports used in the <code>transferList</code> of the constructor during invocation will be
+ delivered to the service page in the <code>ports</code> attribute. See
[[!POSTMSG]]</dd>
- <dt>DOMString getExtra(DOMString key)</dt>
- <dd>Retrieves the value (if any) from the extra data dictionary this
- intent was constructed with.</dd>
+ <dt>readonly attribute any extras</dt>
+ <dd>Retrieves the extras metadata (if any) which this intent was constructed with.</dd>
<dt>void postResult(any data, optional sequence<Transferable> transferable)</dt>
<dd><b>Only present when the Intent object is delivered to the
@@ -314,7 +313,7 @@
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. The Transferables array, if present, will specify
- transferable elements in the |data| payload argument, as per
+ transferable elements in the <code>data</code> payload argument, as per
[[!HTML5]] [[!POSTMSG]]</dd>
<dt>void postFailure(any data)</dt>
<dd><b>Only present when the Intent object is delivered to the Service
@@ -326,8 +325,8 @@
<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
+ User Agent to interpret some fields of the <code>data</code> argument as Transferable. The
+ <code>data</code> and <code>transferList</code> arguments MUST be implemented following the W3C
Web Messaging spec [[!POSTMSG]].
</p>
<p>
@@ -375,12 +374,12 @@
<dl title='callback IntentSuccessCallback = void' class='idl'>
<dt>optional any data</dt>
<dd>
- The |data| passed will be the payload data from the structured
+ The <code>data</code> passed will be the payload data from the structured
cloneable object passed to the postResult method of the delivered Intent.
</dd>
<dt>optional MessagePort[] ports</dt>
<dd>
- The |ports| will be any ports in the payload, as resulting from the structured
+ The <code>ports</code> will be any ports in the payload, as resulting from the structured
clone algorithm with Transferables, as in the Web Messaging spec.
[[!POSTMSG]]
</dd>
@@ -388,7 +387,7 @@
<dl title='callback IntentFailureCallback = void' class='idl'>
<dt>optional any data</dt>
- <dd>The |data| passed will be the payload data passed to the postFailure
+ <dd>The <code>data</code> passed will be the payload data passed to the postFailure
method of the delivered Intent.</dd>
</dl>
</section>
@@ -462,7 +461,7 @@
<section>
<h3>Registration Markup</h3>
<p>
- Service pages declaratively mark themselves (or other same-origin pages)
+ Web pages declaratively mark themselves (or other same-origin Service pages)
as providing handling functionality for particular intent actions and types
using the <code><intent></code> tag.
A User Agent MUST NOT deliver an Intent to a web app service page which
@@ -527,7 +526,7 @@
<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 |href| page. That is, a page may
+ markup specified no intent capability on the <code>href</code> page. That is, a page may
unregister itself implicitly by removing all intent tags, or explicitly
by keeping the tag present, but without <code>action</code> or
<code>type</code> attributes. Such explicit unregistration SHOULD
@@ -641,33 +640,27 @@
to be passed between client to service and back from service to client.
This includes Blobs [[!BLOB]], MessagePorts, etc. The User Agent MAY inspect
the payload of intents and present specialized UI corresponding to
- well-known intent types. The User Agent MUST NOT categorically prohibit
+ well-known intent types. As an example, the User Agent may present
+ specialized messaging to the user indicating that an intent is of the
+ "share" type, or that the Client is asking them to pick an image.
+ </p>
+ <p>
+ The User Agent MAY act as a Client or a Service. For example, the User
+ Agent may implement particular affordances which directly launch Intents
+ that may be handled by registered Services, or present UI allowing its own
+ functionality to be used alongside other registered Services to handle
+ Intents. For instance, User Agents MAY also dispatch intents directly based
+ on data-specific controls derived from microdata in pages, or based on other
+ User Agent-level features.
+ </p>
+ <p>
+ The User Agent MUST NOT categorically prohibit
dispatch of unknown intent types. This is not meant to prohibit the User
Agent from performing filtering functions on intents, such as suppressing
unwanted intent invocations, intents as used as an attack vector, and
other mis-use.
</p>
<p>
- In the same way User Agents MAY dispatch Intents triggered by non-web
- mechanisms to web applications, User Agents MAY dispatch intents invoked by
- web applications to handlers which are not web applications. In those
- cases, the User Agent SHOULD provide a public API mechanism for external
- connection to the intent dispatch mechanism selected. For example, the
- User Agent may be able to run an Operating System command in
- response to an intent. The User Agent could provide a configuration
- interface such that the user can install handler applications, and a
- documented format in which intent payload data is translated to that
- application. In these cases, the requirement that User Agents pass
- any serializable object is relaxed for some kinds of handlers.
- </p>
- <p>
- User Agents MAY also dispatch intents directly based on data-specific controls
- derived from microdata in pages, or based on other User Agent-level
- features. For instance, if the user has services registered which handle
- text/vcard, then the User Agent may provide the user with a way to invoke
- particular intents that consume such data as it detects it in web pages.
- </p>
- <p>
If the user has no services registered for a particular type of intent,
the User Agent MAY display options from other sources of data about
services it knows can handle that intent type so that the user can
@@ -732,16 +725,16 @@
type</var> is not, continue to the next registration record.
<li>If the <var>service type</var> is a MIME type, and the <var>intent
type</var> is not, continue to the next registration record.
- <li>If both <var>service type</var> and <var>action type</var> are MIME types,
+ <li>If both <var>service type</var> and <var>intent type</var> are MIME types,
then check whether the MIME specifiers overlap. This is true if the
top-level and sublevel types match exactly, or if one or both are represented
by the MIME wild card ("*"). If any MIME parameters are present in the
- <var>service type</var> or the <var>action type</var>, they must be present in
+ <var>service type</var> or the <var>intent type</var>, they must be present in
both and match exactly. A MIME parameter present in only one of
- <var>service type</var> and <var>action type</var> does not disqualify the
- match. If the MIME types do not overlap, continue fo the next
+ <var>service type</var> and <var>intent type</var> does not disqualify the
+ match. If the MIME types do not overlap, continue to the next
registration record.</li>
- <li>If neither <var>service type</var> nor <var>action type</var> are MIME types,
+ <li>If neither <var>service type</var> nor <var>intent type</var> are MIME types,
then if they are different, continue to the next registration
record.</li>
</ol>
@@ -866,15 +859,15 @@
<p>
The user needs to have confidence that the Service will user the data
associated with the action for the purpose intended and not share or retain
- the data inappropriately. For this reason it is important that the user have
- control over Intents, in particular the selection mechanism which determines
- which Service will handle a particular Intent. This offers the possibility
- of user decision and control related to the choice of Service, allowing them
- to take into account expectations regarding the Service, including Service
- policies related to retention and secondary use. This relates to the privacy
- principles of control and consent [[DAP-PRIVACY-REQS]]. For this reason a user
- should be made aware of explicit intents and be able to view and change them;
- implementations should be encouraged to offer this functionality.
+ the data inappropriately [[WEBAPP-PRIVACY-BESTPRACTICES]]. For this reason
+ it is important that the user have control over Intents, in particular the
+ selection mechanism which determines which Service will handle a particular Intent.
+ This offers the possibility of user decision and control related to the choice of
+ Service, allowing them to take into account expectations regarding the Service,
+ including Service policies related to retention and secondary use. This relates
+ to the privacy principles of control and consent [[DAP-PRIVACY-REQS]]. For
+ this reason a user should be made aware of explicit intents and be able to view and
+ change them; implementations should be encouraged to offer this functionality.
The minimum data necessary for a Service should be included as Intent parameters,
corresponding to the privacy principle of minimization