- From: Richard Tibbett via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 11 Nov 2009 08:31:44 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/contacts
In directory hutz:/tmp/cvs-serv2737/contacts
Modified Files:
Overview.html
Log Message:
- Minor bug fixes to examples provided in Contact Interface.
- Addtion of Instant Messaging and Presence Protocal Extensions to Contact Interface.
- Added RFC4122 and RFC4770 to biblio.js for reference in Contacts API
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/contacts/Overview.html,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -d -r1.11 -r1.12
--- Overview.html 10 Nov 2009 20:02:10 -0000 1.11
+++ Overview.html 11 Nov 2009 08:31:42 -0000 1.12
@@ -21,7 +21,7 @@
<body>
<section id='abstract'>
<p>This specification defines an API that provides access to a user's unified address book. This specification provides a
- 1:1 mapping of [[RFC2426]] vCARD properties and values.</p>
+ 1:1 mapping of [[RFC2426]] vCard properties and values with the [[RFC4770]] Instant Messaging vCard extension.</p>
</section>
<section id='conformance'>
<p>
@@ -64,7 +64,8 @@
Adding a new contact.
</p>
<pre class='example sh_javascript_dom'>// Create the Contact object for the add function
-var contact = {id: '2345835829231', name: {formatted: 'Mr. Robert Smith Jr'}};
+// note: only the name.formatted value is required to create a new Contact
+var contact = {name: {formatted: 'Mr. Robert Smith Jr'}};
// Add the new contact to the address book
navigator.device.contacts.add( contact,
@@ -308,24 +309,25 @@
<section>
<h2><a>Contact</a> interface</h2>
- <p>The <a href="#contact-interface"><code>Contact</code></a> interface captures a single contact item and is based on a 1:1 mapping to the vCARD specification [[RFC2426]].</p>
+ <p>The <a href="#contact-interface"><code>Contact</code></a> interface captures a single contact item and is based on a 1:1 mapping to the vCARD specification [[RFC2426]] with the [[RFC4770]] Instant Messaging vCard extension.</p>
<p>Attributes of the <a href="#contact-interface"><code>Contact</code></a> interface that expect a singular value have singular spelling (e.g. <code>name</code>) and attributes that may have one or more values have plural spelling (e.g. <code>phones</code>) to make the distinction of these fields easier.</p>
- <p>Each resulting <a href="#contact-interface"><code>Contact</code></a> object instance MUST include a non-NULL <code>id</code> and <code>name.formatted</code> attribute. All other attributes are optional.</p>
+ <p>Each resulting <a href="#contact-interface"><code>Contact</code></a> instance MUST include a non-NULL <code>name.formatted</code> attribute. All other attributes are OPTIONAL.</p>
- <p>In the case that either the <code>id</code> and <code>name.formatted</code> attributes do not have a non-NULL value and an <a href="#contacts-interface"><code>Contacts</code></a> object <a href="#widl-Contacts-add">add()</a>, <a href="#widl-Contacts-remove">remove()</a> or a <a href="#contact-interface"><code>Contact</code></a> object <a href="#widl-Contact-update">update()</a> method is invoked, an <a href="#errorcallback-interface"><code>ErrorCallback</code></a> MUST be triggered consisting of a <a href="#contacterror-interface"><code>ContactError</code></a> object with an error <code>code</code> of <span class="todo">[...]</span>.</p>
+ <p>In the case that the <code>name.formatted</code> attribute does not have a non-NULL value and an <a href="#contacts-interface"><code>Contacts</code></a> object <a href="#widl-Contacts-add">add()</a>, <a href="#widl-Contacts-remove">remove()</a> or a <a href="#contact-interface"><code>Contact</code></a> object <a href="#widl-Contact-update">update()</a> method is invoked, an <a href="#errorcallback-interface"><code>ErrorCallback</code></a> MUST be triggered consisting of a <a href="#contacterror-interface"><code>ContactError</code></a> object with an error <code>code</code> of <span class="todo">[...]</span>.</p>
- <p class="note">Instant Messaging handles not yet included as this is not defined in [[RFC2426]].</p>
<dl title='[NoInterfaceObject] interface Contact' class='idl'>
<dt>
- attribute DOMString id
- </dt>
+ readonly attribute DOMString id
+ </dt>
<dd>
- <p>A globally unique identifier for the given <code>Contact</code> object.</p>
- <p>Each contact MUST include a non-empty <code>id</code> value.</p>
+ <p>A globally unique identifier for the given <code>Contact</code> object. Each <code>Contact</code> referenced from <code>Contacts</code> MUST include a non-empty <code>id</code> value.</p>
+ <p>An implementation MUST maintain this globally unique resource identifier when a Contact is added to, or present within, an Address Book.</p>
+ <p>An implementation MAY use an IANA registered identifier format. The value can also be a non-standard format.</p>
+ <p>It is RECOMMENDED that an implementation assign the id attribute as a <abbr name="Universally Unique IDentifier">UUID</abbr> URN as defined in [[RFC4122]].</p>
<p>[[RFC2426]] equivalent type: UID</p>
- <pre class="example sh_javascript">{id: '454354353454'}</pre>
+ <pre class="example sh_javascript">{id: 'urn:uuid:d13d4fd0-4ce9-1cef-b1f2-10a9c1446bf0'}</pre>
</dd>
<dt>
attribute ContactName name
@@ -386,7 +388,8 @@
<dd>
<p>To specify multiple email addresses for the contact.</p>
<p>[[RFC2426]] equivalent type: EMAIL</p>
- <pre class="example sh_javascript">{emails: [{type: 'work', address: 'john.q.quinlan@barfooinc.com'}, {type: 'home', address: 'jquinlan@mail.com'}]}</pre>
+ <pre class="example sh_javascript">{emails: [{types: ['work','pref'], address: 'john.q.quinlan@barfooinc.com'},
+ {types: ['home'], address: 'jquinlan@mail.com'}]}</pre>
</dd>
<dt>
attribute sequence<ContactAddress> addresses
@@ -395,13 +398,22 @@
<p>The address(es) associated with the contact.</p>
<p>[[RFC2426]] equivalent types: ADR, LABEL</p>
<pre class="example sh_javascript">addresses: [{formatted: '123 Main Street,\nMain Business Park,\nAny Town, CA,\n91921-1234\nUSA'
- types: ['dom','home','postal','parcel'],
+ types: ['dom','home','postal','parcel','pref'],
streetAddress: ['123 Main Street', 'Main Business Park'],
locality: 'Any Town',
region: 'CA',
postalCode: '91921-1234',
country: 'USA' }]}</pre>
- </dd>
+ </dd>
+ <dt>
+ attribute sequence<ContactIMPPAddress> impps
+ </dt>
+ <dd>
+ <p>The instant messaging and presence protocol address(es) associated with the contact.</p>
+ <p>[[RFC4770]] equivalent type: IMPP</p>
+ <pre class="example sh_javascript">impps: [{types: ['work', 'pref'], address:'im:jquinlan@foobarinc.com'},
+ {types: ['home'], address:'sip:jquinlan@foobarinc.com'}]}</pre>
+ </dd>
<dt>
attribute DOMString geo
</dt>
@@ -493,7 +505,7 @@
<dd>
<p>One or more electronic mail software programs that are used by the contact.</p>
<p>[[RFC2426]] equivalent type: MAILER</p>
- <pre class="example sh_javascript">{mailer: ['Pigeon Mail 5.0']}</pre>
+ <pre class="example sh_javascript">{mailers: ['Pigeon Mail 5.0']}</pre>
</dd>
<dt>
attribute sequence<DOMString> notes
@@ -501,7 +513,7 @@
<dd>
<p>A free-text field that allows supplemental information or a comment to be associated to the contact.</p>
<p>[[RFC2426]] equivalent type: NOTE</p>
- <pre class="example sh_javascript">{note: 'This contact prefers, if possible, mailing list based discussion.'}</pre>
+ <pre class="example sh_javascript">{notes: ['This contact prefers, if possible, mailing list based discussion.']}</pre>
</dd>
<dt>
attribute sequence<ContactOrganisation> organisations
@@ -517,7 +529,7 @@
<dd>
<p>The role, occupation or business category of the contact.</p>
<p>[[RFC2426]] equivalent type: ROLE</p>
- <pre class="example sh_javascript">{role: 'Engineer'}</pre>
+ <pre class="example sh_javascript">{roles: ['Engineer']}</pre>
</dd>
<dt>
attribute sequence<ContactData> sounds
@@ -543,7 +555,7 @@
<dd>
<p>One or more telephone numbers associated with the contact.</p>
<p>[[RFC2426]] equivalent type: TEL</p>
- <pre class="example sh_javascript">{phones: [{types: ['home'], preferred: true, number: '+442088450343'},
+ <pre class="example sh_javascript">{phones: [{types: ['home','pref'], number: '+442088450343'},
{types: ['work'], number: '+442088450343}] }</pre>
</dd>
<dt>
@@ -672,17 +684,20 @@
</p>
<dl title='[NoInterfaceObject] interface ContactEmail' class='idl'>
<dt>
- attribute DOMString type
+ attribute sequence<DOMString> types
</dt>
<dd>
The type of the email address.
<p>The following constants are defined by [[RFC2426]].</p>
- <pre>'internet', 'x400', 'pref'</pre>
+ <pre>'internet', 'x400'</pre>
<p>A non-standard value MAY also be specified:</p>
<pre>e.g. 'home', 'work', 'mobile'</pre>
- <p>If no value is specified for the current object, one default value MUST be assigned to this attribute:</p>
+ <p> The following constant can be included to denote the user's preferred email address:</p>
+ <pre>'pref'</pre>
+
+ <p>If no value is specified for the current object, the following default value MUST be assigned to this attribute:</p>
<pre>'internet'</pre>
</dd>
<dt>
@@ -712,7 +727,10 @@
<dd>
A sequence of types of the mailing address.
<p>The following constants are defined by [[RFC2426]]:</p>
- <pre>'dom', 'intl', 'postal'. 'parcel', 'home', 'work', 'pref'</pre>
+ <pre>'dom', 'intl', 'postal'. 'parcel', 'home', 'work'</pre>
+
+ <p> The following constant can be included to denote the user's preferred address:</p>
+ <pre>'pref'</pre>
<p>If no value is specified for the current object, four default values MUST be assigned to this attribute:</p>
<pre>'intl', 'postal', 'parcel', 'work'</pre>
@@ -755,7 +773,33 @@
</dd>
</dl>
</section>
-
+
+ <section>
+ <h2><a>ContactIMPPAddress</a> interface</h2>
+ <p>
+ The <a>ContactIMPPAddress</a> interface describes a contact's Instant Messaging or Presence Protocal address.
+ </p>
+ <dl title='[NoInterfaceObject] interface ContactIMPPAddress' class='idl'>
+ <dt>
+ attribute sequence<DOMString> types
+ </dt>
+ <dd>
+ A sequence of types of the IMPP address.
+ <p>The following constants are defined by [[RFC4770]]:</p>
+ <pre>'home', 'work', 'mobile'. 'personal', 'business'</pre>
+
+ <p> The following constant can be included to denote the user's preferred IMPP address:</p>
+ <pre>'pref'</pre>
+ </dd>
+ <dt>
+ attribute DOMString address
+ </dt>
+ <dd>
+ The IMPP address as defined in [[RFC4770]].
+ </dd>
+ </dl>
+ </section>
+
<section>
<h2><a>ContactOrganisation</a> interface</h2>
<p>
@@ -790,7 +834,10 @@
The type(s) of the phone number.
<p>The following constants are defined by [[RFC2426]] and MUST be used for this attribute:</p>
<pre>'home', 'msg', 'work', 'pref', 'voice', 'fax', 'cell',
- 'video', 'pager', 'bbs', 'modem', 'car', 'isdn', 'pcs'</pre>
+ 'video', 'pager', 'bbs', 'modem', 'car', 'isdn', 'pcs'</pre>
+
+ <p>The following constant can be included to denote the user's preferred phone number:</p>
+ <pre>'pref'</pre>
<p>If no value is specified for the current object, one default value MUST assigned to this attribute:</p>
<pre>'voice'</pre>
@@ -801,13 +848,6 @@
<dd>
The phone number.
</dd>
- <dt>
- attribute boolean preferred
- </dt>
- <dd>
- <p><code>true</code> if the related phone number is the contact's preferred phone number.</p>
- <p>DEFAULT: <code>false</code></p>
- </dd>
</dl>
</section>
@@ -842,7 +882,7 @@
<p>A representation of, or a pointer to, the relevant data. This attribute MUST represent either:</p>
<ul>
- <li>A base64 encoded data stream, included as the value of this attribute. In this case the related <code>encoding</code> attribute MUST be set to 'b'.</li>
+ <li>A binary encoded data stream, included as the value of this attribute. In this case the related <code>encoding</code> attribute MUST be set to 'b'.</li>
<li>A URI, pointing to the data resource in an external location included as the value of this attribute. In this case the related <code>encoding</code> attribute MUST be set to NULL.</li>
</ul>
</dd>
Received on Wednesday, 11 November 2009 08:31:53 UTC