- From: Richard Tibbett via cvs-syncmail <cvsmail@w3.org>
- Date: Tue, 03 Aug 2010 10:51:37 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/contacts
In directory hutz:/tmp/cvs-serv15901/contacts
Modified Files:
Overview.html
Added Files:
Writer.html
Log Message:
Split reading from writing according to the resolution made at the London F2F (Jul-2010): http://lists.w3.org/Archives/Public/public-device-apis/2010Jul/att-0094/minutes-2010-07-15.html#item06
--- NEW FILE: Writer.html ---
<!DOCTYPE html>
<html>
<head>
<title>
Contacts Writer API
</title>
<meta
http-equiv='Content-Type'
content='text/html;charset=utf-8'>
<script
type="text/javascript"
src='../ReSpec.js/js/respec.js'
class='remove'>
</script>
<script
type="text/javascript"
src='../ReSpec.js/js/sh_main.min.js'
class='remove'>
</script>
<script
type="text/javascript"
class='remove'>
var respecConfig = {
specStatus: "ED",
shortName: "contacts-api",
editors: [{name: "Richard Tibbett", company: "Invited Expert"}],
//publishDate: "2010-07-01",
// previousPublishDate: "2010-01-21",
edDraftURI: "http://dev.w3.org/2009/dap/contacts/Writer.html",
// lcEnd: "2009-08-05",
};
</script>
<script
type="text/javascript"
src='../common/config.js'
class='remove'>
</script>
</head>
<body>
<section
id='abstract'>
<p>
The Contacts API defines the high-level interfaces required to provide access to a user's unified address book.
</p>
</section>
<section
id='sotd'>
<p>
This document represents the early consensus of the group on the scope and features of the proposed Contacts API. Issues and
editors note in the document highlight some of the points on which the group is still working and would particularly like to get
feedback.
</p>
</section>
<section
id='conformance'>
<p>
This specification defines conformance criteria that apply to a single product: the <dfn>user agent</dfn> that implements the
interfaces that it contains.
</p>
<p>
Implementations that use ECMAScript to implement the APIs defined in this specification must implement them in a manner consistent
with the ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]], as this specification uses that specification and
terminology.
</p>
</section>
<section
class="informative">
<h2>
Introduction
</h2>
<p>
Every operating system and a large number of web-based service providers have different ways of representing address book
information. Most users are required to maintain a plurality of contact lists which leads to multiple copies of address book data.
The multiplicity of address books that a user is required to maintain often leads to disjointed and inconsistent information being
stored across a user's address book providers.
</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 3rd parties users are, more often
than not, required to hand over access to their whole address book. Users are implicitly required to trust 3rd 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 3rd 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 centre 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>
The API itself is agnostic of any underlying address book sources and storage. A conforming implementation is required to implement
all fields defined in this specification.
</p>
<section>
<h2>
Usage Examples
</h2>
<p>
The following code extracts illustrate how to search, add, remove and update contact information in a given address book:
</p>
<div>
<p>
Creating a new contact.
</p>
</div>
<pre
class='example sh_javascript_dom'>
// Create new contact
var myContact = navigator.service.contacts.create({displayName: 'Robert'}});
// Add additional contact attributes as required...
// myContact.nicknames.push('bobby');
</pre>
<div>
<p>
Saving a new contact in the underlying addressbook.
</p>
</div>
<pre
class='example sh_javascript_dom'>
// previous example follow-on...
function successContactCallback(contact) {
// do something with resulting contact object
alert(contact.displayName);
// ...
}
// Save new contact
myContact.save(successContactCallback, generalErrorCB);
</pre>
<div>
<p>
Editing an existing contact.
</p>
</div>
<pre
class='example sh_javascript_dom'>
// previous example follow-on...
// e.g. add a new phone number
myContact.phoneNumbers.push({type: 'home', value: '+440000000002'});
// Update existing contact
myContact.save(successContactCallback, generalErrorCB);
</pre>
<div>
<p>
Removing an existing contact.
</p>
</div>
<pre
class='example sh_javascript_dom'>
// previous example follow-on...
// Remove existing contact
myContact.remove(successContactCallback, generalErrorCB);
</pre>
</section>
</section>
<section>
<h2>
Security and Privacy Considerations
</h2>
<p
class='note'>
The overall architecture for addressing privacy in DAP is still under construction. As it is finalized, there may be changes made
to this API to reflect requirements or support for privacy-related functionality.
</p>
<p>
The API defined in this specification can be used to create, find, save and remove contact information from a user's address
book(s). All API methods disclose 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.
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 creatable, retrivable, updateable or removable 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 create, find, save or delete 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.
</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 create, find, save or remove 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 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 creation, retrieval, update and/or removal of contact information.
</p>
</section>
<section>
<h2>
Privacy considerations for recipients of contact information
</h2>
<p>
Recipients MUST only request contact information when necessary. Recipients MUST only use the contact information for the task
for which it was provided to them. Recipients MUST dispose of contact information once that task is completed, unless expressly
permitted to retain it by the user. Recipients MUST 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 MUST 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 MUST clearly and conspicuously disclose the fact that they are collecting contact data, the purpose for the
collection, how long the data is retained, how the data is secured, how the data is shared if it is shared, how users can access,
update and delete the data, and any other choices that users have with respect to the data. This disclosure MUST include an
explanation of any exceptions to the guidelines listed above.
</p>
</section>
<section
class='informative'>
<h2>
Additional implementation considerations
</h2>
<p>
Further to the requirements listed in the previous section, implementors of the Contacts API are also advised to consider the
following aspects that can negatively affect the privacy of their users: in certain cases, users can inadvertently grant
permission to the User Agent to disclose their contacts to Web sites. In other cases, the content hosted at a certain URL changes
in such a way that the previously granted contact permissions no longer apply as far as the user is concerned. Or the users might
simply change their minds.
</p>
<p>
Predicting or preventing these situations is inherently difficult. Mitigation and in-depth defensive measures are an
implementation responsibility and not prescribed by this specification. However, in designing these measures, implementers are
advised to enable user awareness of contact sharing, and to provide easy access to interfaces that enable revocation of
permissions.
</p>
</section>
</section>
<section>
<h2>
API Description
</h2>
<section>
<h2>
<a>ContactsWriter</a> interface
</h2>
<p>
The <a>ContactsWriter</a> interface exposes a database collecting contacts information, such that they may be created, updated, and deleted.
</p>
<dl
title='[NoInterfaceObject] interface ContactsWriter : Contacts'
class='idl'>
<dt>
Contact create ()
</dt>
<dd>
Create a new <code>Contact</code> object.
<p>
This method takes one argument. When called, it returns a <a
href='#contact-interface'><code>Contact</code></a> object.
</p>
<p>
The newly created <a
href='#contact-interface'><code>Contact</code></a> object MUST NOT be stored in the user's address book as a result of
calling this method. The <a
href='#contact-interface'><code>Contact</code></a> <a
href='#widl-Contact-save'>save()</a> method MUST be called on the response of this method to store the new <a
href='#contact-interface'><code>Contact</code></a> object in the user's address book.
</p>
<dl
class='parameters'>
<dt>
ContactProperties attributes
</dt>
<dd>
The attributes to assign to the resulting object.
</dd>
</dl>
</dd>
</dl>
</section>
<section>
<h2>
<a>ContactWriter</a> interface
</h2>
<p>
The <a
href="#contact-interface"><code>ContactWriter</code></a> interface captures a single contact item. This interface extends <a
href='#contactproperties-interface'><code>ContactProperties</code></a> attributes.
</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.
</p>
<p>
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>
<dl
title='[NoInterfaceObject] interface ContactWriter : Contact'
class='idl'>
<dt>
Contact clone ()
</dt>
<dd>
<p>
Create a deep clone copy of the current object minus the current object's <a
href='#widl-Contact-id'><code>id</code></a> attribute.
</p>
<p>
The resulting object MUST be provided with a newly generated <a
href='#widl-Contact-id'><code>id</code></a> attribute to distiguish the cloned object from the original object.
</p>
</dd>
<dt>
PendingOp save ()
</dt>
<dd>
<p>
Add or update (as appropriate) the current <a
href="#contact-interface"><code>Contact</code></a> object to the <a
href="#contacts-interface"><code>Contacts</code></a>.
</p>
<p>
This method takes one or two arguments. When called, it immediately returns a <code>PendingOp</code> object, as defined in
[[!CORE-DEVICE]], and then asynchronously starts a <dfn>save contact process</dfn> defined as follows:
</p>
<ol>
<li>
If a current find(), save() or remove() 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.
</li>
<li>
If the current <a
href='#widl-Contact-id'><code>Contact.id</code></a> value is not recognized in <a
href='#contacts-interface'><code>Contacts</code></a> or a <a
href='#widl-Contact-id'><code>Contact.id</code></a> value has not been set, create and set a new <a
href='#widl-Contact-id'><code>Contact.id</code></a> value and add the current object as a new object to <a
href='#contacts-interface'><code>Contacts</code></a>.
</li>
<li>
If the <a
href='#widl-Contact-id'><code>Contact.id</code></a> already exists in <a
href='#contacts-interface'><code>Contacts</code></a> then update the existing object in <a
href='#contacts-interface'><code>Contacts</code></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.
</li>
</ol>
<dl
class='parameters'>
<dt>
ContactSuccessCB successCB
</dt>
<dd>
Function to call when the asynchronous operation completes
</dd>
<dt>
optional ContactErrorCB? errorCB
</dt>
<dd>
Function to call when the asynchronous operation fails.
</dd>
</dl>
</dd>
<dt>
PendingOp remove ()
</dt>
<dd>
<p>
Remove the current contact from the address book.
</p>
<p>
In the case that the current <a
href='#widl-Contact-id'><code>id</code></a> attribute is <code>null</code> and this method is invoked, a <a
href='#contacterrorcb-interface'><code>ContactErrorCB</code></a> MUST be triggered as part of the <a>remove contact
process</a>. This error MUST consist of a <a
href="#contacterror-interface"><code>ContactError</code></a> object with a <code>code</code> of <a
href='#widl-ContactError-NOT_FOUND_ERROR'><code>NOT_FOUND_ERROR</code></a>.
</p>
<p>
This method takes one or two arguments. When called, it immediately returns a <code>PendingOp</code> object, as defined in
[[!CORE-DEVICE]], and then asynchronously starts a <dfn>remove contact process</dfn> defined as follows:
</p>
<ol>
<li>
If a current find(), save() or remove() 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.
</li>
<li>
Remove the current object from <a
href='#contacts-interface'><code>Contacts</code></a>.
</li>
<li>
If the removal of the current object from <a
href='#contacts-interface'><code>Contacts</code></a> was successful, set the current object's <a
href='#widl-Contact-id'><code>Contact.id</code></a> value to <code>null</code>.
</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.
</li>
</ol>
<dl
class='parameters'>
<dt>
ContactSuccessCB successCB
</dt>
<dd>
Function to call when the asynchronous operation completes
</dd>
<dt>
optional ContactErrorCB? errorCB
</dt>
<dd>
Function to call when the asynchronous operation fails.
</dd>
</dl>
</dd>
</dl>
</section>
<section>
<h2>
<a>ContactSuccessCB</a> interface
</h2>
<!-- interface intro here -->
<dl
title='[Callback=FunctionOnly, NoInterfaceObject] interface ContactSuccessCB'
class='idl'>
<dt>
void onSuccess ()
</dt>
<dd>
<!-- interface description here -->
<dl
class='parameters'>
<dt>
Contact contactObj
</dt>
<dd>
The Contact object resulting from the given <a
href='#contact-interface'><code>Contact</code></a> <a
href='#widl-Contact-save'>save()</a> or <a
href='#contact-interface'><code>Contact</code></a> <a
href='#widl-Contact-remove'>remove()</a> method.
</dd>
</dl>
</dd>
</dl>
</section>
<section>
<h2>
<a>ContactErrorCB</a> interface
</h2>
<!-- interface intro here -->
<dl
title='[Callback=FunctionOnly, NoInterfaceObject] interface ContactErrorCB'
class='idl'>
<dt>
void onError ()
</dt>
<dd>
<!-- interface description here -->
<dl
class='parameters'>
<dt>
ContactError error
</dt>
<dd>
The Contact API related error object.
</dd>
</dl>
</dd>
</dl>
</section>
<section>
<h2>
<a>ContactError</a> interface
</h2>
<p>
The <a
href='#contacterror-interface'><code>ContactError</code></a> interface encapsulates all errors in the manipulation of <a
href='#contact-interface'><code>Contact</code></a> objects in the Contacts API.
</p>
<dl
title='[NoInterfaceObject] interface ContactError'
class='idl'>
<dt>
const unsigned short UNKNOWN_ERROR = 0
</dt>
<dd>
An unknown error occurred.
</dd>
<dt>
const unsigned short INVALID_ARGUMENT_ERROR = 1
</dt>
<dd>
An invalid parameter was provided when the requested method was invoked.
</dd>
<dt>
const unsigned short NOT_FOUND_ERROR = 2
</dt>
<dd>
If no response information can be provided from the requested method.
</dd>
<dt>
const unsigned short TIMEOUT_ERROR = 3
</dt>
<dd>
The requested method timed out before it could be completed.
</dd>
<dt>
const unsigned short PENDING_OPERATION_ERROR = 4
</dt>
<dd>
If the <a>user agent</a> is currently waiting for a callback on a current find(), save() or remove() operation, as defined in
this specification.
</dd>
<dt>
const unsigned short IO_ERROR = 5
</dt>
<dd>
An error occurred in communication with the underlying implementation that meant the requested method could not complete.
</dd>
<dt>
const unsigned short NOT_SUPPORTED_ERROR = 6
</dt>
<dd>
The requested method is not supported by the current implementation.
</dd>
<dt>
const unsigned short PERMISSION_DENIED_ERROR = 20
</dt>
<dd>
Access to the requested method was denied at the implementation or by the user.
</dd>
<dt>
readonly attribute unsigned short code
</dt>
<dd>
An error code assigned by an implementation when an error has occurred in Contacts API processing.
</dd>
</dl>
</section>
</section>
<!-- end api description section -->
<section
class="informative appendix">
<h2>
User Interaction Guidelines
</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, saved or removed from their unified address book. This annex provides some examples of a conformant user experience that
this specification enables.
</p>
<section>
<h3>
Contact Writebacks
</h3>
<section>
<h4>
Saving a Contact to the Address Book
</h4>
<p
class="note">
Include Contact creation/modification writeback mockup.
</p>
</section>
<section>
<h4>
Removing a Contact from the Address Book
</h4>
<p
class="note">
Include Contact deletion writeback mockup.
</p>
</section>
</section>
</section>
</body>
</html>
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/contacts/Overview.html,v
retrieving revision 1.67
retrieving revision 1.68
diff -u -d -r1.67 -r1.68
--- Overview.html 5 Jul 2010 15:36:58 -0000 1.67
+++ Overview.html 3 Aug 2010 10:51:35 -0000 1.68
@@ -128,64 +128,6 @@
{filter: 'Bob'}
);
</pre>
- <div>
- <p>
- Creating a new contact.
- </p>
- </div>
-<pre
- class='example sh_javascript_dom'>
-// Create new contact
-var myContact = navigator.service.contacts.create({displayName: 'Robert'}});
-
-// Add additional contact attributes as required...
-// myContact.nicknames.push('bobby');
-</pre>
- <div>
- <p>
- Saving a new contact in the underlying addressbook.
- </p>
- </div>
-<pre
- class='example sh_javascript_dom'>
-// previous example follow-on...
-
-function successContactCallback(contact) {
- // do something with resulting contact object
- alert(contact.displayName);
- // ...
-}
-
-// Save new contact
-myContact.save(successContactCallback, generalErrorCB);
-</pre>
- <div>
- <p>
- Editing an existing contact.
- </p>
- </div>
-<pre
- class='example sh_javascript_dom'>
-// previous example follow-on...
-
-// e.g. add a new phone number
-myContact.phoneNumbers.push({type: 'home', value: '+440000000002'});
-
-// Update existing contact
-myContact.save(successContactCallback, generalErrorCB);
-</pre>
- <div>
- <p>
- Removing an existing contact.
- </p>
- </div>
-<pre
- class='example sh_javascript_dom'>
-// previous example follow-on...
-
-// Remove existing contact
-myContact.remove(successContactCallback, generalErrorCB);
-</pre>
</section>
</section>
<section>
@@ -321,33 +263,6 @@
title='[NoInterfaceObject] interface Contacts'
class='idl'>
<dt>
- Contact create ()
- </dt>
- <dd>
- Create a new <code>Contact</code> object.
- <p>
- This method takes one argument. When called, it returns a <a
- href='#contact-interface'><code>Contact</code></a> object.
- </p>
- <p>
- The newly created <a
- href='#contact-interface'><code>Contact</code></a> object MUST NOT be stored in the user's address book as a result of
- calling this method. The <a
- href='#contact-interface'><code>Contact</code></a> <a
- href='#widl-Contact-save'>save()</a> method MUST be called on the response of this method to store the new <a
- href='#contact-interface'><code>Contact</code></a> object in the user's address book.
- </p>
- <dl
- class='parameters'>
- <dt>
- ContactProperties attributes
- </dt>
- <dd>
- The attributes to assign to the resulting object.
- </dd>
- </dl>
- </dd>
- <dt>
PendingOp find ()
</dt>
<dd>
@@ -442,130 +357,6 @@
See [[[!POCO-SCHEMA]] Section 7.2.1. <code>id</code>] for additional definition of this attribute.
</p>
</dd>
- <dt>
- Contact clone ()
- </dt>
- <dd>
- <p>
- Create a deep clone copy of the current object minus the current object's <a
- href='#widl-Contact-id'><code>id</code></a> attribute.
- </p>
- <p>
- The resulting object MUST be provided with a newly generated <a
- href='#widl-Contact-id'><code>id</code></a> attribute to distiguish the cloned object from the original object.
- </p>
- </dd>
- <dt>
- PendingOp save ()
- </dt>
- <dd>
- <p>
- Add or update (as appropriate) the current <a
- href="#contact-interface"><code>Contact</code></a> object to the <a
- href="#contacts-interface"><code>Contacts</code></a>.
- </p>
- <p>
- This method takes one or two arguments. When called, it immediately returns a <code>PendingOp</code> object, as defined in
- [[!CORE-DEVICE]], and then asynchronously starts a <dfn>save contact process</dfn> defined as follows:
- </p>
- <ol>
- <li>
- If a current find(), save() or remove() 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.
- </li>
- <li>
- If the current <a
- href='#widl-Contact-id'><code>Contact.id</code></a> value is not recognized in <a
- href='#contacts-interface'><code>Contacts</code></a> or a <a
- href='#widl-Contact-id'><code>Contact.id</code></a> value has not been set, create and set a new <a
- href='#widl-Contact-id'><code>Contact.id</code></a> value and add the current object as a new object to <a
- href='#contacts-interface'><code>Contacts</code></a>.
- </li>
- <li>
- If the <a
- href='#widl-Contact-id'><code>Contact.id</code></a> already exists in <a
- href='#contacts-interface'><code>Contacts</code></a> then update the existing object in <a
- href='#contacts-interface'><code>Contacts</code></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.
- </li>
- </ol>
- <dl
- class='parameters'>
- <dt>
- ContactSuccessCB successCB
- </dt>
- <dd>
- Function to call when the asynchronous operation completes
- </dd>
- <dt>
- optional ContactErrorCB? errorCB
- </dt>
- <dd>
- Function to call when the asynchronous operation fails.
- </dd>
- </dl>
- </dd>
- <dt>
- PendingOp remove ()
- </dt>
- <dd>
- <p>
- Remove the current contact from the address book.
- </p>
- <p>
- In the case that the current <a
- href='#widl-Contact-id'><code>id</code></a> attribute is <code>null</code> and this method is invoked, a <a
- href='#contacterrorcb-interface'><code>ContactErrorCB</code></a> MUST be triggered as part of the <a>remove contact
- process</a>. This error MUST consist of a <a
- href="#contacterror-interface"><code>ContactError</code></a> object with a <code>code</code> of <a
- href='#widl-ContactError-NOT_FOUND_ERROR'><code>NOT_FOUND_ERROR</code></a>.
- </p>
- <p>
- This method takes one or two arguments. When called, it immediately returns a <code>PendingOp</code> object, as defined in
- [[!CORE-DEVICE]], and then asynchronously starts a <dfn>remove contact process</dfn> defined as follows:
- </p>
- <ol>
- <li>
- If a current find(), save() or remove() 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.
- </li>
- <li>
- Remove the current object from <a
- href='#contacts-interface'><code>Contacts</code></a>.
- </li>
- <li>
- If the removal of the current object from <a
- href='#contacts-interface'><code>Contacts</code></a> was successful, set the current object's <a
- href='#widl-Contact-id'><code>Contact.id</code></a> value to <code>null</code>.
- </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.
- </li>
- </ol>
- <dl
- class='parameters'>
- <dt>
- ContactSuccessCB successCB
- </dt>
- <dd>
- Function to call when the asynchronous operation completes
- </dd>
- <dt>
- optional ContactErrorCB? errorCB
- </dt>
- <dd>
- Function to call when the asynchronous operation fails.
- </dd>
- </dl>
- </dd>
</dl>
</section>
<section>
@@ -1132,35 +923,6 @@
</section>
<section>
<h2>
- <a>ContactSuccessCB</a> interface
- </h2>
- <!-- interface intro here -->
- <dl
- title='[Callback=FunctionOnly, NoInterfaceObject] interface ContactSuccessCB'
- class='idl'>
- <dt>
- void onSuccess ()
- </dt>
- <dd>
- <!-- interface description here -->
- <dl
- class='parameters'>
- <dt>
- Contact contactObj
- </dt>
- <dd>
- The Contact object resulting from the given <a
- href='#contact-interface'><code>Contact</code></a> <a
- href='#widl-Contact-save'>save()</a> or <a
- href='#contact-interface'><code>Contact</code></a> <a
- href='#widl-Contact-remove'>remove()</a> method.
- </dd>
- </dl>
- </dd>
- </dl>
- </section>
- <section>
- <h2>
<a>ContactErrorCB</a> interface
</h2>
<!-- interface intro here -->
@@ -1788,33 +1550,6 @@
href="#security-and-privacy-considerations">Security and Privacy Considerations</a> section expects that the user should easily
be able to review and revoke permissions to web applications at a later date.
</p>
- <p
- class="note">
- Include permission review/revocation mockup?
- </p>
- </section>
- <section>
- <h3>
- Contact Writebacks
- </h3>
- <section>
- <h4>
- Saving a Contact to the Address Book
- </h4>
- <p
- class="note">
- Include Contact creation/modification writeback mockup.
- </p>
- </section>
- <section>
- <h4>
- Removing a Contact from the Address Book
- </h4>
- <p
- class="note">
- Include Contact deletion writeback mockup.
- </p>
- </section>
</section>
</section>
<section
Received on Tuesday, 3 August 2010 10:51:40 UTC