- From: Robin Berjon via cvs-syncmail <cvsmail@w3.org>
- Date: Mon, 05 Oct 2009 17:14:05 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/contacts
In directory hutz:/tmp/cvs-serv16638/contacts
Modified Files:
Overview.html
Log Message:
Contacts pass one; some fixes
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/contacts/Overview.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- Overview.html 30 Sep 2009 15:24:54 -0000 1.5
+++ Overview.html 5 Oct 2009 17:14:03 -0000 1.6
@@ -3,10 +3,7 @@
<head>
<title>The Contacts API</title>
<meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
- <script src='../ReSpec.js/js/simple-node.js' class='remove'></script>
- <script src='../ReSpec.js/js/shortcut.js' class='remove'></script>
<script src='../ReSpec.js/js/respec.js' class='remove'></script>
- <script src='../ReSpec.js/bibref/biblio.js' class='remove'></script>
<script class='remove'>
var respecConfig = {
specStatus: "ED",
@@ -21,44 +18,37 @@
</head>
<body>
<section id='abstract'>
- This is the abstract for your specification.
+ This specification defines an API that provides access to the device's address book.
</section>
- <section id='conformance'></section>
-
<section>
- <h2>Requirements</h2>
+ <h2>Introduction</h2>
<p>
- The Contacts API:
- </p>
- <ul>
- <li>MUST enable listing all available address books on the device</li>
- <li>MUST enable listing all contacts in the address book(s)</li>
- <li>MUST enable reading the details for a contact</li>
- <li>SHOULD enable creating a new contact</li>
- <li>SHOULD enable updating a contact</li>
- <li>SHOULD enable deleting a contact</li>
- <li>SHOULD enable filtering the list of contacts to search for a subset</li>
- <li>MUST support asynchronous, cancellable operation when methods may take a long time to complete</li>
- </ul>
- <p class='issue'>
- Are there convincing use cases for supporting multiple address books in v1 (as opposed to just
- a default one, and maybe exposing more later)?
+ Rather than each application having its own address book for its own purposes (email, phone,
+ driving directions) it is more practical for the user to have a single address book which
+ multiple applications share. That is what this specification exposes.
</p>
- <p class='issue'>
- Do we need support for groups (currently not listed) in v1?
+ <p>
+ The requirements for this set of interfaces are listed in the Device API Requirements
+ document [[DAP-REQS]].
</p>
</section>
-
+ <section id='conformance'>
+ <p>
+ This specification defines conformance criteria that apply to a single product:
+ <dfn>user agents</dfn> that implement the interfaces that it contains.
+ </p>
+ </section>
+
<section>
<h2>The <a>AddressBook</a> interface</h2>
<p>
The <a>AddressBook</a> interface exposes an interface to a database collecting addresses,
such that they may be created, found, read, updated, and deleted.
</p>
- <dl title='interface AddressBook' class='idl'>
- <dt>void addContact ()</dt>
+ <dl title='[NoInterfaceObject] interface AddressBook' class='idl'>
+ <dt>void add ()</dt>
<dd>
Adds a contact to the address book.
<dl class='parameters'>
@@ -68,7 +58,17 @@
</dd>
</dl>
</dd>
- <dt>sequence<Contact> findContacts ()</dt>
+ <dt>void remove ()</dt>
+ <dd>
+ Removes a contact from the address book.
+ <dl class='parameters'>
+ <dt>Contact contact</dt>
+ <dd>
+ The contact that is being removed.
+ </dd>
+ </dl>
+ </dd>
+ <dt>sequence<Contact> find ()</dt>
<dd>
Uses a filter in order to find corresponding contacts in the address book.
<dl class='parameters'>
@@ -86,7 +86,7 @@
<p>
The <a>Contact</a> interface captures a single contact item.
</p>
- <dl title='interface Contact' class='idl'>
+ <dl title='[NoInterfaceObject] interface Contact' class='idl'>
<dt>attribute sequence<DOMString> givenNames</dt>
<dd>
The contact's given names.
@@ -116,17 +116,61 @@
<dd>
The addresses of the contact.
</dd>
- <dt>attribute sequence<DOMString> phones</dt>
+ <dt>attribute sequence<PhoneNumber> phones</dt>
<dd>
The phones of the contact.
</dd>
- <dt>attribute sequence<DOMString> emails</dt>
+ <dt>attribute sequence<EmailAddress> emails</dt>
<dd>
- The email of the contact.
+ The emails of the contact.
+ </dd>
+ <dt>attribute sequence<URIAddress> uris</dt>
+ <dd>
+ The URIs of the contact.
+ </dd>
+ <dt>attribute sequence<IMHandle> ims</dt>
+ <dd>
+ The IMs of the contact.
+ </dd>
+ <dt>attribute File photo</dt>
+ <dd>
+ A picture of the contact.
+ </dd>
+ <dt>attribute DOMString prefix</dt>
+ <dd>
+ <p>
+ The prefix for the contact's name.
+ </p>
+ <p class='issue'>
+ Should this be called "honorific"?
+ </p>
+ </dd>
+ <dt>attribute DOMString suffix</dt>
+ <dd>
+ The suffix for the contact's name.
+ </dd>
+ <dt>attribute DOMString jobTitle</dt>
+ <dd>
+ The contact's job title.
+ </dd>
+ <dt>attribute Date birthday</dt>
+ <dd>
+ The contact's birthday.
+ </dd>
+ <dt>attribute DOMString phoneticName</dt>
+ <dd>
+ The contact's phonetic name.
</dd>
<dt>void save ()</dt>
<dd>
Saves the modified contact to the address book.
+ <dl class='exception' title='ContactsException'>
+ <dt>NO_BOOK_ERR</dt>
+ <dd>
+ The contact does not belong to an address book at this point in time and therefore
+ cannot be saved.
+ </dd>
+ </dl>
</dd>
<dt>DOMString getFullName ()</dt>
<dd>
@@ -136,16 +180,226 @@
</dl>
</section>
+ <section>
+ <h2>The <a>Address</a> interface</h2>
+ <p>
+ The <a>Address</a> interface is used to describe a physical street address.
+ </p>
+ <dl title='[NoInterfaceObject] interface Address' class='idl'>
+ <dt>attribute DOMString street</dt>
+ <dd>
+ The address's street.
+ </dd>
+ <dt>attribute DOMString postalCode</dt>
+ <dd>
+ The address's postal code.
+ </dd>
+ <dt>attribute DOMString city</dt>
+ <dd>
+ The address's city.
+ </dd>
+ <dt>attribute DOMString region</dt>
+ <dd>
+ The address's region or state.
+ </dd>
+ <dt>attribute DOMString countryCode</dt>
+ <dd>
+ <p>
+ The address's ISO country code.
+ </p>
+ <p class='issue'>
+ This may not be or even guessable if the original address only stores the
+ country as a user-provided string.
+ </p>
+ </dd>
+ <dt>attribute DOMString country</dt>
+ <dd>
+ The address's country, as a human-readable string.
+ </dd>
+ <dt>attribute DOMString building</dt>
+ <dd>
+ The address's building.
+ </dd>
+ <dt>attribute DOMString floor</dt>
+ <dd>
+ The address's floor.
+ </dd>
+ <dt>attribute DOMString accessCode</dt>
+ <dd>
+ The access code for that address.
+ </dd>
+ </dl>
+ </section>
+
+ <section>
+ <h2>The <a>PhoneNumber</a> interface</h2>
+ <p>
+ The <a>PhoneNumber</a> interface describes a phone number.
+ </p>
+ <dl title='[NoInterfaceObject] interface PhoneNumber' class='idl'>
+ <dt>attribute DOMString number</dt>
+ <dd>
+ The phone number.
+ </dd>
+ <dt>attribute DOMString type</dt>
+ <dd>
+ The type of the phone number (e.g. mobile, home, work, etc.).
+ </dd>
+ </dl>
+ </section>
+
+ <section>
+ <h2>The <a>EmailAddress</a> interface</h2>
+ <p>
+ The <a>EmailAddress</a> interface describes an email address.
+ </p>
+ <dl title='[NoInterfaceObject] interface EmailAddress' class='idl'>
+ <dt>attribute DOMString address</dt>
+ <dd>
+ The email address.
+ </dd>
+ <dt>attribute DOMString type</dt>
+ <dd>
+ The type of the email address (e.g. mobile, home, work, etc.).
+ </dd>
+ </dl>
+ </section>
+
+ <section>
+ <h2>The <a>URIAddress</a> interface</h2>
+ <p>
+ The <a>URIAddress</a> interface describes a URI.
+ </p>
+ <dl title='[NoInterfaceObject] interface URIAddress' class='idl'>
+ <dt>attribute DOMString address</dt>
+ <dd>
+ The URI.
+ </dd>
+ <dt>attribute DOMString type</dt>
+ <dd>
+ The type of the URI (e.g. blog, work, etc.).
+ </dd>
+ </dl>
+ </section>
+
+ <section>
+ <h2>The <a>IMHandle</a> interface</h2>
+ <p>
+ The <a>IMHandle</a> interface describes an IM handle.
+ </p>
+ <dl title='[NoInterfaceObject] interface IMHandle' class='idl'>
+ <dt>attribute DOMString address</dt>
+ <dd>
+ The IM handle.
+ </dd>
+ <dt>attribute DOMString type</dt>
+ <dd>
+ The type of the IM handle (e.g. home, work, etc.).
+ </dd>
+ <dt>attribute DOMString network</dt>
+ <dd>
+ The network of the IM handle (e.g. Jabber, IRC, iChat, etc.).
+ </dd>
+ </dl>
+ </section>
+
+ <section>
+ <h2>The <a>ContactFilter</a> interface</h2>
+ <p>
+ The <a>ContactFilter</a> interface captures a filter that enables simple searches
+ within the address book. Fields that are set to <code>null</code> are considered to match anything.
+ </p>
+ <dl title='[NoInterfaceObject] interface ContactFilter' class='idl'>
+ <dt>attribute DOMString givenName</dt>
+ <dd>
+ The given name that is being looked for.
+ </dd>
+ <dt>attribute DOMString familyName</dt>
+ <dd>
+ The family name that is being looked for.
+ </dd>
+ <dt>attribute DOMString nickname</dt>
+ <dd>
+ The nickname that is being looked for.
+ </dd>
+ <dt>attribute DOMString companyName</dt>
+ <dd>
+ The company name that is being looked for.
+ </dd>
+ <dt>attribute boolean isCompany</dt>
+ <dd>
+ True if a company is being looked for.
+ </dd>
+ <dt>attribute Address address</dt>
+ <dd>
+ The addresses that is being looked for, with its fields set to <code>null</code> where they
+ are expected to match anything.
+ </dd>
+ <dt>attribute DOMString phone</dt>
+ <dd>
+ The phone number that is being looked for.
+ </dd>
+ <dt>attribute DOMString email</dt>
+ <dd>
+ The email address that is being looked for.
+ </dd>
+ <dt>attribute DOMString uri</dt>
+ <dd>
+ The URI that is being looked for.
+ </dd>
+ <dt>attribute DOMString im</dt>
+ <dd>
+ The IM that is being looked for.
+ </dd>
+ <dt>attribute DOMString prefix</dt>
+ <dd>
+ The prefix that is being looked for.
+ </dd>
+ <dt>attribute DOMString suffix</dt>
+ <dd>
+ The suffix that is being looked for.
+ </dd>
+ <dt>attribute DOMString jobTitle</dt>
+ <dd>
+ The job title that is being looked for.
+ </dd>
+ <dt>attribute Date birthday</dt>
+ <dd>
+ <p>
+ The birthday that is being looked for.
+ </p>
+ <p class='issue'>
+ We probably want to look by day/month, not by year here.
+ </p>
+ </dd>
+ <dt>attribute DOMString phoneticName</dt>
+ <dd>
+ The phonetic name that is being looked for.
+ </dd>
+ </dl>
+ </section>
+
+ <section>
+ <h2>The ContactsException exception</h2>
+ <p>
+ The <a>ContactsException</a> exception class encapsulates all errors in the manipulation
+ of objects in the Contacts API.
+ </p>
+ <dl title='[NoInterfaceObject] exception ContactsException' class='idl'>
+ <dt>const unsigned short NO_BOOK_ERR = 0</dt>
+ <dd>
+ An object was manipulated in a way that requires it to belong to an address
+ book, but it hasn't been added to one yet.
+ </dd>
+ </dl>
+ </section>
+
<section class='appendix'>
<h2>Features for Future Consideration</h2>
<p>
- This is a list of features that have been discussed with respect to this version of the
- API but for which it has been decided that if they are included it will be in a future
- revision.
+ The requirements document contains a list of features that were considered for this version
+ but deferred to future work [[DAP-REQS]].
</p>
- <ul>
- <li>...</li>
- </ul>
</section>
<section class='appendix'>
Received on Monday, 5 October 2009 17:14:12 UTC