- From: Richard Tibbett via cvs-syncmail <cvsmail@w3.org>
- Date: Tue, 21 Sep 2010 10:53:21 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/contacts
In directory hutz:/tmp/cvs-serv14794/contacts
Modified Files:
Overview.html
Log Message:
Initial proposal for HTML5-based Event Loops, Tasks and Task Queues for calling asynchronous find() callbacks.
http://lists.w3.org/Archives/Public/public-device-apis/2010Sep/0031.html
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/contacts/Overview.html,v
retrieving revision 1.87
retrieving revision 1.88
diff -u -d -r1.87 -r1.88
--- Overview.html 21 Sep 2010 08:49:37 -0000 1.87
+++ Overview.html 21 Sep 2010 10:53:19 -0000 1.88
@@ -37,7 +37,8 @@
class='remove'>
</script>
-<style type="text/css">
+<style
+ type="text/css">
/* ReSpec.js CSS optimizations (Richard Tibbett) */
div.example {
@@ -126,27 +127,29 @@
</p>
<p>
Providing address book information to these service providers means handing over all of your data and trusting these providers with
- the security and privacy of storing and sharing of your information. When sharing this data with third parties users are, more often
- than not, required to hand over access to their whole address book. Users are implicitly required to trust third parties with all of
- their data when, in reality, the user may only wish, or need, to share a subset of their address book information so that an
+ the security and privacy of storing and sharing of your information. When sharing this data with third parties users are, more
+ often than not, required to hand over access to their whole address book. Users are implicitly required to trust third parties with
+ all of their data when, in reality, the user may only wish, or need, to share a subset of their address book information so that an
application can fulfill its purpose.
</p>
<p>
This specification defines the concept of a user's unified address book - where address book data may be sourced from a
- plurality of sources - both online and locally. This specification then defines the interfaces on which third party applications can
- access a user's unified address book, with explicit user permission and filtering. The focus of this data sharing is on making
- the user aware of the data that they will share and putting them at the center of the data sharing process; free to select both the
- extent to which they share their address book information and the ability to restrict which pieces of information related to which
- contact gets shared.
+ plurality of sources - both online and locally. This specification then defines the interfaces on which third party applications
+ can access a user's unified address book, with explicit user permission and filtering. The focus of this data sharing is on
+ making the user aware of the data that they will share and putting them at the center of the data sharing process; free to select
+ both the extent to which they share their address book information and the ability to restrict which pieces of information related
+ to which contact gets shared.
</p>
<p>
A conforming implementation is required to implement all fields defined in this specification.
</p>
- <div class="example">
+ <div
+ class="example">
<p>
The following code illustrates how to obtain contact information from a user's address book:
</p>
-<pre class="sh_javascript">
+<pre
+ class="sh_javascript">
function successContactFindCallback(contacts) {
// do something with resulting contact objects
for (var i in contacts) alert(contacts[i].displayName);
@@ -168,6 +171,34 @@
);
</pre>
</div>
+ <section>
+ <h2>
+ Terminology
+ </h2>
+ <p>
+ The terms <dfn>document base URL</dfn>, <dfn>browsing context</dfn>, <dfn
+ title="event handler attribute">event handler attributes</dfn>, <dfn>event handler event type</dfn>, <dfn>task</dfn>, <dfn>task
+ source</dfn> and <dfn>task queues</dfn> are defined by the HTML5 specification [[!HTML5]].
+ </p>
+ <p>
+ The <a>task source</a> used by this specification is the <dfn><a
+ href="http://dev.w3.org/2009/dap/device/#the-pendingop-interface">PendingOp</a> task source</dfn>.
+ </p>
+
+ <p class="note">
+ PendingOp needs updating in [[!CORE-DEVICE]] to show that it is a valid <a>task source</a>.
+ </p>
+ <p>
+ To <dfn>dispatch a <code><dfn>success</dfn> event</code></dfn> means that an event with the name <code>success</code>, which does
+ not bubble and is not cancelable, and which uses the <code>Event</code> interface, is to be dispatched at the <a
+ href="#contactfindcb-interface"><code>ContactFindCB</code></a> object.
+ </p>
+ <p>
+ To <dfn>dispatch an <code><dfn>error</dfn> event</code></dfn> means that an event with the name <code>error</code>, which does
+ not bubble and is not cancelable, and which uses the <code>Event</code> interface, is to be dispatched at the <a
+ href="#contacterrorcb-interface"><code>ContactErrorCB</code></a> object.
+ </p>
+ </section>
</section>
<section>
<h2>
@@ -179,54 +210,58 @@
to this API to reflect requirements or support for privacy-related functionality.
</p>
<p>
- The API defined in this specification can be used to find contact information from a user's address
- book(s). This discloses information related to a user's contacts such as their phone number(s), email address(es) and
- other personally identifying information. The distribution of this information could potentially compromise the user's privacy, or the user’s contacts privacy.
- A conforming implementation of this specification MUST provide a mechanism that protects the user's privacy and this mechanism
- should ensure that no contact information is retrievable without the user's express
- permission.
+ The API defined in this specification can be used to find contact information from a user's address book(s). This discloses
+ information related to a user's contacts such as their phone number(s), email address(es) and other personally identifying
+ information. The distribution of this information could potentially compromise the user's privacy, or the
+ user’s contacts privacy. A conforming implementation of this specification MUST provide a mechanism that
+ protects the user's privacy and this mechanism should ensure that no contact information is retrievable without the user's
+ express permission.
</p>
<section>
<h2>
Privacy considerations for implementors of the Contacts API
</h2>
<p>
- A <a>user agent</a> MUST not retrieve contact information to Web sites without the express permission of the
- user. A <a>user agent</a> MUST acquire permission through a user interface, unless they have prearranged trust relationships with
- users, as described below. The user interface MUST include the URI of the document origin, as defined in [[HTML5]]. Those
- permissions that are acquired through the user interface and that are preserved beyond the current browsing session (i.e. beyond
- the time when the browsing context, as defined in [[HTML5]], is navigated to another URL) MUST be revocable and a <a>user
- agent</a> MUST respect revoked permissions.
+ A <a>user agent</a> MUST not retrieve contact information to Web sites without the express permission of the user. A <a>user
+ agent</a> MUST acquire permission through a user interface, unless they have prearranged trust relationships with users, as
+ described below. The user interface MUST include the <a>document base URL</a>. Those permissions that are acquired through the
+ user interface and that are preserved beyond the current browsing session (i.e. beyond the time when the <a>browsing context</a>
+ is navigated to another URL) MUST be revocable and a <a>user agent</a> MUST respect revoked permissions.
</p>
<p>
Obtaining the user's express permission to access one API method does not imply the user has granted permission for the same
Web site to access other methods provided by this API, or to access the same method with a different set of arguments, as part of
the same permission context. If a user has expressed permission for an implementation to, e.g. find a set of existing contacts,
- the implementation MUST seek the user's express permission if and when any additional <code>find</code> function
- is called on this API.
+ the implementation MUST seek the user's express permission if and when any additional <code>find</code> function is called on
+ this API.
</p>
<p>
A <a>user agent</a> may have prearranged trust relationships that do not require such user interfaces. For example, while a Web
- browser will present a user interface when a Web site performs an address book request, a Widget [[WIDGETS]] runtime MAY have a prearranged,
- delegated security relationship with the user and, as such, a suitable alternative security and privacy mechanism with which to
- authorize the retrieval of contact information.
+ browser will present a user interface when a Web site performs an address book request, a Widget [[WIDGETS]] runtime MAY have a
+ prearranged, delegated security relationship with the user and, as such, a suitable alternative security and privacy mechanism
+ with which to authorize the retrieval of contact information.
</p>
</section>
- <section class="informative">
+ <section
+ class="informative">
<h2>
Privacy considerations for recipients of contact information
</h2>
- <p>Web sites owners that retrieve contacts information using this API are denoted as recipients below.</p>
<p>
- Recipients should only request contact information when necessary, and only use the contact information for the task
- for which it was provided to them.</p>
- <p>Recipients should dispose of contact information once that task is completed, unless expressly
- permitted to retain it by the user. Recipients should also take measures to protect this information against unauthorized access.
- If contact information is stored, users should be allowed to update and delete this information.
+ Web sites owners that retrieve contacts information using this API are denoted as recipients below.
</p>
<p>
- The recipient of contact information should not retransmit the contact information without the user's express permission. Care
- should be taken when retransmitting and use of encryption is encouraged.
+ Recipients should only request contact information when necessary, and only use the contact information for the task for which it
+ was provided to them.
+ </p>
+ <p>
+ Recipients should dispose of contact information once that task is completed, unless expressly permitted to retain it by the
+ user. Recipients should also take measures to protect this information against unauthorized access. If contact information is
+ stored, users should be allowed to update and delete this information.
+ </p>
+ <p>
+ The recipient of contact information should not retransmit the contact information without the user's express permission.
+ Care should be taken when retransmitting and use of encryption is encouraged.
</p>
<p>
Recipients should clearly and conspicuously disclose the fact that they are collecting contact data, the purpose for the
@@ -310,23 +345,26 @@
Find contacts in the address book according to the <a>find contacts process</a> detailed below.
</p>
<p>
- This method takes two, three or four arguments. When called, it immediately returns a <code>PendingOp</code> object , as
+ This method takes two, three or four arguments. When called, it immediately returns a <code>PendingOp</code> object, as
defined in [[!CORE-DEVICE]], and then asynchronously starts a <dfn>find contacts process</dfn> defined as follows:
</p>
- <ol class="rule">
+ <ol
+ class="rule">
<li>
- If a current find() operation is pending a response, and the method was invoked with a
- non-<code>null</code> <code>errorCB</code> argument, invoke the <code>errorCB</code> with a <a
- href='#widl-ContactError-PENDING_OPERATION_ERROR'><code>PENDING_OPERATION_ERROR</code></a> code.
+ If there are any <a>tasks</a> from the <a
+ title="ContactEventTarget task source"><code>ContactEventTarget</code> task source</a> in one of the <a>task queues</a>
+ (i.e. an existing <code>find()</code> operation is still pending a response), and the current method was invoked with a
+ non-<code>null</code> <code>errorCB</code> argument, <a>dispatch an <code>error</code> event</a> with a <a
+ href='#widl-ContactError-PENDING_OPERATION_ERROR'><code>PENDING_OPERATION_ERROR</code></a> <code>code</code> value.
</li>
<li>
Search for contacts in the address book according to the rules defined in <a
href='#contact-search-processing'>Contact Search Processing</a>.
</li>
<li>
- If successful, invoke the associated <code>successCB</code>. If the attempt fails, and the method was invoked with a
- non-<code>null</code> <code>errorCB</code> argument, this method must invoke the <code>errorCB</code> with a <a
- href='#contacterror-interface'><code>ContactError</code></a> object as an argument.
+ If the attempt was successful, <a>dispatch a <code>success</code> event</a>. If the attempt fails, and the method was
+ invoked with a non-<code>null</code> <code>errorCB</code> argument, this method must <a>dispatch an <code>error</code>
+ event</a> with the <code>code</code> attribute set according to the type of failure that has occurred.
</li>
</ol>
<dl
@@ -338,7 +376,7 @@
The <a>search qualifier</a>.
</dd>
<dt>
- ContactFindSuccessCB successCB
+ ContactFindCB successCB
</dt>
<dd>
Function to call when the asynchronous operation completes
@@ -363,21 +401,29 @@
<h2>
<a>Contact</a> interface
</h2>
+ <p
+ class="note">
+ The attributes provided in this interface are under review and are likely to change as the recommendation progresses.
+ </p>
<p>
The <a
href="#contact-interface"><code>Contact</code></a> interface captures the properties of a contact object. All properties
- included in this interface have a corresponding definition in [[!POCO-SCHEMA]] and are intended to be direct mappings to attributes also defined in [[RFC2426]].
+ included in this interface have a corresponding definition in [[!POCO-SCHEMA]] and are intended to be direct mappings to
+ attributes also defined in [[RFC2426]].
</p>
<p>
All <a
href="#contact-interface"><code>Contact</code></a> objects MUST include all attributes supported by the implementation,
- regardless of whether these attributes have been assigned a non-<code>null</code> value or a <code>null</code> value.
- If a supported attribute has not been assigned a value by the user and/or implementation, then this attribute MUST still be
- present in the resulting <a
+ regardless of whether these attributes have been assigned a non-<code>null</code> value or a <code>null</code> value. If a
+ supported attribute has not been assigned a value by the user and/or implementation, then this attribute MUST still be present in
+ the resulting <a
href="#contact-interface"><code>Contact</code></a> object and MUST have a value of <code>null</code>.
</p>
<p>
- Additional attributes MAY be included according to the provisions detailed in <a href="#extended-contact-properties-and-parameters">Extended Contact Properties and Parameters</a>. If an extended attribute is supported by the current implementation and has not been assigned a value by the user and/or implementation, then this extended attribute MUST still be present in the resulting <a
+ Additional attributes MAY be included according to the provisions detailed in <a
+ href="#extended-contact-properties-and-parameters">Extended Contact Properties and Parameters</a>. If an extended attribute is
+ supported by the current implementation and has not been assigned a value by the user and/or implementation, then this extended
+ attribute MUST still be present in the resulting <a
href="#contact-interface"><code>Contact</code></a> object and MUST have a value of <code>null</code>.
</p>
<dl
@@ -809,7 +855,8 @@
</dt>
<dd>
<p>
- Return only contact records that have been updated on or after the given time, specified as an ECMAScript <code>Date</code> object.
+ Return only contact records that have been updated on or after the given time, specified as an ECMAScript <code>Date</code>
+ object.
</p>
<p>
This filter is applied to the <a
@@ -821,11 +868,10 @@
</section>
<section>
<h2>
- <a>ContactFindSuccessCB</a> interface
+ <a>ContactFindCB</a> interface
</h2>
- <!-- interface intro here -->
<dl
- title='[Callback=FunctionOnly, NoInterfaceObject] interface ContactFindSuccessCB'
+ title='[Callback=FunctionOnly, NoInterfaceObject] interface ContactFindCB : PendingOp'
class='idl'>
<dt>
void onSuccess ()
@@ -847,6 +893,39 @@
</dl>
</dd>
</dl>
+ <section>
+ <h3>
+ Event Handler Attributes
+ </h3>
+ <p>
+ The following is the <a>event handler attribute</a> (and its corresponding <a>event handler event type</a>) that MUST be
+ supported as DOM attribute by the <a
+ href="#contactfindcb-interface"><code>ContactFindCB</code></a> object.
+ </p>
+ <table
+ class='simple'>
+ <thead>
+ <tr>
+ <th>
+ <a>event handler attribute</a>
+ </th>
+ <th>
+ <a>event handler event type</a>
+ </th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>
+ <strong><code><strong>onSuccess</strong></code></strong>
+ </td>
+ <td>
+ <code>success</code>
+ </td>
+ </tr>
+ </tbody>
+ </table>
+ </section>
</section>
<section>
<h2>
@@ -854,7 +933,7 @@
</h2>
<!-- interface intro here -->
<dl
- title='[Callback=FunctionOnly, NoInterfaceObject] interface ContactErrorCB'
+ title='[Callback=FunctionOnly, NoInterfaceObject] interface ContactErrorCB : PendingOp'
class='idl'>
<dt>
void onError ()
@@ -872,6 +951,39 @@
</dl>
</dd>
</dl>
+ <section>
+ <h3>
+ Event Handler Attributes
+ </h3>
+ <p>
+ The following is the <a>event handler attribute</a> (and its corresponding <a>event handler event type</a>) that MUST be
+ supported as DOM attribute by the <a
+ href="#contacterrorcb-interface"><code>ContactErrorCB</code></a> object.
+ </p>
+ <table
+ class='simple'>
+ <thead>
+ <tr>
+ <th>
+ <a>event handler attribute</a>
+ </th>
+ <th>
+ <a>event handler event type</a>
+ </th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>
+ <strong><code><strong>onError</strong></code></strong>
+ </td>
+ <td>
+ <code>error</code>
+ </td>
+ </tr>
+ </tbody>
+ </table>
+ </section>
</section>
<section>
<h2>
@@ -907,8 +1019,7 @@
const unsigned short PENDING_OPERATION_ERROR = 3
</dt>
<dd>
- If the <a>user agent</a> is currently waiting for a callback on a current find() operation, as defined in
- this specification.
+ If the <a>user agent</a> is currently waiting for a callback on a current find() operation, as defined in this specification.
</dd>
<dt>
const unsigned short IO_ERROR = 4
@@ -991,9 +1102,10 @@
<h3>
Advanced Search Qualifiers
</h3>
- <p>We call <dfn>composed attributes</dfn> <a
- href="#contact-interface"><code>Contact</code></a> attributes of types <code>object</code>, <code>sequence</code>, <code>array</code> or <code>any</code> which
- contain information only available only through child attributes of that object.
+ <p>
+ We call <dfn>composed attributes</dfn> <a
+ href="#contact-interface"><code>Contact</code></a> attributes of types <code>object</code>, <code>sequence</code>,
+ <code>array</code> or <code>any</code> which contain information only available only through child attributes of that object.
</p>
<p>
A requesting application MUST be able to request both the full composed <a
@@ -1025,11 +1137,14 @@
this composed attribute an application would request e.g. <code>addresses.locality</code>, <code>addresses.region</code>, etc.
</p>
</section>
- <div class="example">
+ <div
+ class="example">
<p>
The following Contact search is initiated:
</p>
-<pre class="sh_javascript">
+<pre
+ class="sh_javascript">
+
navigator.service.contacts.find(['emails.value', 'name', 'friends'],
function(contacts) {
for(i in contacts) {
@@ -1041,7 +1156,8 @@
<p>
The above example logically implies:
</p>
- <ol class="rule">
+ <ol
+ class="rule">
<li>
Return only the valid <a
href="#contact-interface"><code>Contact</code></a> attributes requested in the provided <a>search qualifier</a>
@@ -1064,7 +1180,7 @@
href="#contacts-interface"><code>Contacts</code></a> <a
href="#widl-Contacts-find">find()</a> operation MUST return either an empty sequence or a single <a
href="#contact-interface"><code>Contact</code></a> object, accessible as part of the sequence returned in the <a
- href="#contactfindsuccesscb-interface"><code>ContactFindSuccessCB</code></a> callback function.
+ href="#contactfindcb-interface"><code>ContactFindCB</code></a> callback function.
</p>
<p>
If a <a
@@ -1075,7 +1191,7 @@
href="#widl-Contacts-find">find()</a> operation MUST return either an empty sequence, a single <a
href="#contact-interface"><code>Contact</code></a> object or <var>[X]</var> number of <a
href="#contact-interface"><code>Contact</code></a> objects, accessible as part of the sequence returned in the <a
- href="#contactfindsuccesscb-interface"><code>ContactFindSuccessCB</code></a> callback function.
+ href="#contactfindcb-interface"><code>ContactFindCB</code></a> callback function.
</p>
</section>
<section>
@@ -1104,7 +1220,7 @@
href='#contacts-interface'><code>Contacts</code></a> database, is a <a>partial value match</a> of the input
<code>filter</code> value, that <a
href='#contact-interface'><code>Contact</code></a> object MUST be returned as part of the resulting <a
- href='#contactfindsuccesscb-interface'><code>ContactFindSuccessCB</code></a>.
+ href='#contactfindcb-interface'><code>ContactFindCB</code></a>.
</p>
<p>
A conforming implementation MUST only allow the provided <a>search filter</a> to be applied to fields requested in the provided
@@ -1158,7 +1274,8 @@
title="filter">filter</var> is a DOMString object
</dt>
<dd>
- <ol class="rule">
+ <ol
+ class="rule">
<li>
Let <var
title="contactset">contactset</var> be the next enumerable Object in <var
@@ -1220,7 +1337,8 @@
title="contactset">contactset</var> is an Object object
</dt>
<dd>
- <ol class="rule">
+ <ol
+ class="rule">
<li>
Let <var
title="elementvalue">elementvalue</var> be the String value of the next enumerable property in <var
@@ -1256,11 +1374,13 @@
</p>
</dd>
</dl>
- <div class="example">
+ <div
+ class="example">
<p>
The following Contact search is initiated:
</p>
-<pre class="sh_javascript">
+<pre
+ class="sh_javascript">
navigator.service.contacts.find(['name', 'addresses.locality', 'addresses.country', 'phoneNumbers', 'emails'],
function(contacts) {
for(x in contacts) alert(contacts[x].name);
@@ -1273,7 +1393,8 @@
<p>
The above example logically implies:
</p>
- <ol class="rule">
+ <ol
+ class="rule">
<li>
Using ECMA-262 3rd Edition regular expression syntax and pseudo-code, the <a>search filter</a> provided can be represented
as:
@@ -1289,8 +1410,10 @@
All searches are case-insensitive and apply a <a>loose-matching policy</a> as defined in <a
href="#search-filters">Search Filters</a>.<br>
<br>
- As noted in <a href="#search-filters">Search Filters</a>, the <code>id</code> attribute is implicitly appended along with any <a>search filter</a> attributes provided, regardless
- of whether it was provided as a <a>search qualifier</a> from the requesting application.<br>
+ As noted in <a
+ href="#search-filters">Search Filters</a>, the <code>id</code> attribute is implicitly appended along with any <a>search
+ filter</a> attributes provided, regardless of whether it was provided as a <a>search qualifier</a> from the requesting
+ application.<br>
<br>
</li>
<li>
@@ -1307,32 +1430,37 @@
</section>
</section>
<section>
- <h2>Extended Contact Properties and Parameters</h2>
-
+ <h2>
+ Extended Contact Properties and Parameters
+ </h2>
<p>
- The properties and parameters defined on the <a id="#contact-interface"><code>Contact</code></a> interface MAY be extended by implementors of this specification.
+ The properties and parameters defined on the <a
+ id="#contact-interface"><code>Contact</code></a> interface MAY be extended by implementors of this specification.
</p>
-
<p>
- Non-standard, private properties and parameters SHOULD have a name starting with <code>X</code> (U+0058 LATIN CAPTIAL LETTER X). Extended properties and parameters can be defined bilaterally between <a title="user agent">user agents</a> without outside registration or standardization.
+ Non-standard, private properties and parameters SHOULD have a prefixed name starting with <code>X</code> (U+0058 LATIN CAPTIAL
+ LETTER X) or use a vendor-specific prefix. Extended properties and parameters can be defined bilaterally between <a
+ title="user agent">user agents</a> without outside registration or standardization.
</p>
-
<p>
- It is RECOMMENDED that authors define both a formal vCard grammar [[RFC2426]] and a WebIDL grammar [[WEBIDL]] for their proposed extension to ensure interoperability between vCard databases and other non-standard Contact databases and formats.
- It is also RECOMMENDED that authors provide documentation of their extension properties and parameters within the public domain.
+ It is RECOMMENDED that authors define both a formal vCard grammar [[RFC2426]] and a WebIDL grammar [[WEBIDL]] for their proposed
+ extension to ensure interoperability between vCard databases and other non-standard Contact databases and formats. It is also
+ RECOMMENDED that authors provide documentation of their extension properties and parameters within the public domain.
</p>
-
- <div class="example">
- <p>A new parameter is required by Company X to provide information related to a user's accounts registered across different networks and services.</p>
-
- <p>The [[WEBIDL]] syntax for this parameter is defined as follows:</p>
-
+ <div
+ class="example">
+ <p>
+ A new parameter is required by Company X to provide information related to a user's accounts registered across different
+ networks and services.
+ </p>
+ <p>
+ The [[WEBIDL]] syntax for this parameter is defined as follows:
+ </p>
<div
class='idl'
title='Contact implements ContactExtended'>
</div>
-
<dl
title='[NoInterfaceObject] interface ContactExtended'
class='idl'>
@@ -1343,39 +1471,38 @@
One or more user accounts. See [[[!POCO-SCHEMA]] Section 7.2.2. <code>accounts</code>].
</dd>
</dl>
-
- <dl
+ <dl
title='[NoInterfaceObject] interface ContactAccount'
- class='idl'>
- <dt>
+ class='idl'>
+ <dt>
attribute DOMString domain
- </dt>
- <dd>
- <p>
+ </dt>
+ <dd>
+ <p>
See [[[!POCO-SCHEMA]] Section 7.6. <code>domain</code>].
- </p>
- </dd>
- <dt>
+ </p>
+ </dd>
+ <dt>
attribute DOMString username
- </dt>
- <dd>
- <p>
+ </dt>
+ <dd>
+ <p>
See [[[!POCO-SCHEMA]] Section 7.6. <code>username</code>].
- </p>
- </dd>
- <dt>
+ </p>
+ </dd>
+ <dt>
attribute DOMString userid
- </dt>
- <dd>
- <p>
+ </dt>
+ <dd>
+ <p>
See [[[!POCO-SCHEMA]] Section 7.6. <code>userid</code>].
- </p>
- </dd>
- </dl>
-
- <p>The corresponding vCard [[RFC2426]] notation for this parameter is defined as follows:</p>
-
- <pre>
+ </p>
+ </dd>
+ </dl>
+ <p>
+ The corresponding vCard [[RFC2426]] notation for this parameter is defined as follows:
+ </p>
+<pre>
The following ABNF grammar extends the grammar found in [[RFC2426]] (Section 4).
<strong>X-ACCOUNT</strong>
@@ -1401,12 +1528,13 @@
ABNF:
X-ACCOUNT-param = ; no parameter allowed
- X-ACCOUNT-value = list-component 3(";" list-component)
+ X-ACCOUNT-value = list-component 3(";" list-component)
</pre>
-
- <p>This parameter will be used within the Contacts API as follows:
-
-<pre class="sh_javascript">
+ <p>
+ This parameter will be used within the Contacts API as follows:
+ </p>
+<pre
+ class="sh_javascript">
var contact = ...; // ...obtain individual contact object
for(var i in contact.Xaccounts) {
alert(contact.Xaccounts[i].domain); // thesocialnetwork.com
@@ -1414,17 +1542,13 @@
alert(contact.Xaccounts[i].userid); // 344aesq2
}
</pre>
-
- <p>This parameter will be used within the vCard format [[RFC2426]]] as follows:
-
+ <p>
+ This parameter will be used within the vCard format [[RFC2426]]] as follows:
+ </p>
<pre>
X-ACCOUNT;thesocialnetwork.com;;344aesq2
-</pre>
+</pre>
</div>
-
- <p class="note">
- TBD: Whether there is a role for <a href="http://tools.ietf.org/html/draft-george-vcarddav-vcard-extension-02">http://tools.ietf.org/html/draft-george-vcarddav-vcard-extension-02</a> here in relation to Portable Contacts <-> vCard alignment.
- </p>
</section>
<section
class="informative appendix">
@@ -1433,8 +1557,8 @@
</h2>
<p>
This specification is primarily intended to provide the user with the ability to view and control the contact information that may
- be shared from their unified address book. This annex provides some examples of a conformant user experience that
- this specification enables.
+ be shared from their unified address book. This annex provides some examples of a conformant user experience that this
+ specification enables.
</p>
<section>
<h3>
@@ -1443,9 +1567,10 @@
<p>
A website requests access to a user's address book with the following code:
</p>
-<div
- class='example'>
-<pre class="sh_javascript">
+ <div
+ class='example'>
+<pre
+ class="sh_javascript">
function successContactFindCallback(contacts) {
// do something with resulting contact objects
for (var i in contacts) alert(contacts[i].name);
@@ -1466,7 +1591,7 @@
{filter: 'Bob'}
);
</pre>
-</div>
+ </div>
<p>
As a result of executing this code, the <a>user agent</a> may provide a non-blocking <dfn>contact search notification</dfn> as
follows:
@@ -1480,8 +1605,8 @@
href="contacts_notification.png">View as PNG</a>)
</p>
<p>
- If an additional find() operation is called by the current web application before the user has clicked
- 'Select' or 'Cancel' on the current notification, an error will be invoked with a code of <a
+ If an additional find() operation is called by the current web application before the user has clicked 'Select' or
+ 'Cancel' on the current notification, an error will be invoked with a code of <a
href="#widl-ContactError-PERMISSION_DENIED_ERROR"><code>PENDING_OPERATION_ERROR</code></a> if that operation was defined with a
non-<code>null</code> <code>errorCB</code> parameter.
</p>
@@ -1507,8 +1632,8 @@
one or more contacts (as appropriate) from the user interface.
</p>
<p>
- If an additional find() operation is called by the current web application before the user has clicked
- 'Select' or 'Cancel' on the current notification, an error will be invoked with a code of <a
+ If an additional find() operation is called by the current web application before the user has clicked 'Select' or
+ 'Cancel' on the current notification, an error will be invoked with a code of <a
href="#widl-ContactError-PERMISSION_DENIED_ERROR"><code>PENDING_OPERATION_ERROR</code></a> if that operation was defined with a
non-<code>null</code> <code>errorCB</code> parameter.
</p>
@@ -1519,8 +1644,8 @@
</p>
<p>
If the user clicks 'Select', the <a
- href="#contactfindsuccesscb-interface"><code>ContactFindSuccessCB</code></a> associated to the current find() operation will be
- invoked with the contact information selected by the user provided as the only parameter.
+ href="#contactfindcb-interface"><code>ContactFindCB</code></a> associated to the current find() operation will be invoked with
+ the contact information selected by the user provided as the only parameter.
</p>
<p>
Further to this initial sharing of Contact information, the <a
Received on Tuesday, 21 September 2010 10:53:24 UTC