--- a/contacts/Overview.html Fri Jun 22 17:05:43 2012 +0200
+++ b/contacts/Overview.html Fri Jun 22 18:03:41 2012 +0200
@@ -224,118 +224,114 @@
</li>
<li>
If an error of any kind takes place in the service, then an error payload is returned (using
- <code>postFailure()</code>) matching the error data format defined below. This includes the
- case in which the user has selected zero contacts.
+ <code>postFailure()</code>) matching the error data format defined below. The <a>contact service</a>
+ MUST NOT treat the user selecting zero contacts or cancelling the service as error conditions.
</li>
</ul>
+ <section>
+ <h2>Intent Extras</h2>
+ <p>
+ The Pick Contact Intent can be instantiated with an <code>extras</code> field that adheres to the
+ following dictionary.
+ </p>
+ <section>
+ <h2>The <a>ContactIntentExtras</a> dictionary</h2>
+ <p>
+ The <a>ContactIntentExtras</a> dictionary describes the options that can be applied to contact searching.
+ </p>
+ <dl title='dictionary ContactIntentExtras' class='idl'>
+ <dt>DOMString? search</dt>
+ <dd>
+ A string which provides a hint to the <a>contact service</a> to facilitate contacts selection by the user.
+ The exact manner in which this hint is exploited is entirely up to the <a>contact service</a>.
+ </dd>
+ <dt>unsigned long? limit</dt>
+ <dd>
+ By default a <a>contact service</a> MAY return as many contacts as the user selects. If <code>limit</code>
+ is specified, the <a>contact service</a> MUST NOT return more than <code>limit</code> contacts. The
+ <a>contact service</a> SHOULD enforce this limitation in the user interface that it exposes.
+ </dd>
+ <dt>DOMString[] fields</dt>
+ <dd>
+ An array of field names corresponding to the name of the fields in the <a>Contact</a> dictionary that
+ the Web application is requesting from the <a>contact service</a>. The <a>contact service</a> MUST
+ NOT return defined fields on the contact objects that it provides other than those present in this
+ list. If a field name is provided that the <a>contact service</a> does not recognise as a field
+ of the <a>Contact</a> dictionary, then it MUST ignore it.
+ </dd>
+ </dl>
+ </section>
+ </section>
</section>
<section>
<h2>Data Format</h2>
<p>
- Upon successful invocation, the <a>contact service</a> MUST return an array of <a>Contact</a> objects.
+ Upon successful invocation, the <a>contact service</a> MUST return an array of <a>Contact</a> dictionaries.
</p>
<section>
- <h2><a>Contact</a> </h2>
+ <h2>The <a>Contact</a> dictionary</h2>
<p>
- The <a>Contact</a> interface captures the properties of a contact object. All properties included in this
- interface have a corresponding definition in [[POCO-SCHEMA]], [[RFC2426]] (aka vCard), and [[OMA-CAB]], thereby
- allowing the API to be supported across implementations supporting these various contact formats.
- </p>
- <p id="ta-ac" class="product-ua">
- All <a>Contact</a> objects MUST include all attributes supported by the implementation, regardless
- of whether these attributes have been assigned a <code>null</code> value or not. If a supported attribute has not been
- assigned a value by the user or the implementation, then this attribute MUST still be present in the
- resulting <a>Contact</a> object and MUST have a value of <code>null</code>.
+ The <a>Contact</a> dictionary captures the properties of a contact object. All properties included in this
+ interface have a corresponding definition in [[POCO-SCHEMA]], [[RFC2426]] (also known as vCard), and
+ [[OMA-CAB]], thereby allowing the data format to be supported across implementations supporting these
+ various contact representations.
</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 or the implementation, then this extended attribute MUST still be present in the resulting
- <a>Contact</a> object and MUST have a value of <code>null</code>.
+ <a href="#extended-contact-properties-and-parameters">Extended Contact Properties and Parameters</a>.
</p>
-
- <!-- XXX make this a dictionary -->
- <dl title='[NoInterfaceObject] interface Contact' class='idl'>
- <dt>readonly attribute DOMString id</dt>
- <dd>
- <p>
- A globally unique identifier for the given <a>Contact</a> object.
- </p>
- <p>
- An implementation MUST maintain this globally unique identifier when a <a>Contact</a> is added
- to an address book.
- </p>
- </dd>
- <dt>attribute DOMString? displayName</dt>
- <dd>
- <p>
- This attribute contains the name of this <a>Contact</a> in a form that is suitable for display
- to the user.
- </p>
- </dd>
- <dt>attribute ContactName? name</dt>
- <dd>
- <p>
- This attribute represents the full name of this <a>Contact</a> indicated by the name components
- associated with the <a>ContactName</a> object.
- </p>
- </dd>
- <dt>attribute DOMString? nickname</dt>
- <dd>
- <p>
- This attribute contains the nickname (or a casual name) for this <a>Contact</a>.
- </p>
- </dd>
- <dt>attribute ContactField[]? phoneNumbers</dt>
+ <dl title='dictionary Contact' class='idl'>
+ <dt>DOMString id</dt>
<dd>
- <p>
- This attribute captures one or more phone numbers associated with this <a>Contact</a>.
- </p>
- </dd>
- <dt>attribute ContactField[]? emails</dt>
- <dd>
- <p>
- This attribute represents one or more email addresses associated with this <a>Contact</a>.
- </p>
- </dd>
- <dt>attribute ContactAddress[]? addresses</dt>
- <dd>
- <p>
- This attribute represents one or more physical addresses associated with this <a>Contact</a>.
- </p>
- </dd>
- <dt>attribute ContactField[]? ims</dt>
- <dd>
- <p>
- This attribute represents one or more instant messaging identifiers associated with this
- <a>Contact</a>.
- </p>
+ A globally unique identifier for the given <a>Contact</a> object.
</dd>
- <dt>attribute ContactOrganization[]? organizations</dt>
- <dd>
- <p>
- This attribute represents one or more organizations associated with this <a>Contact</a>.
- </p>
- </dd>
- <dt>attribute Date? birthday</dt>
+ <dt>DOMString? displayName</dt>
<dd>
- <p>
- This attribute contains birthday of this <a>Contact</a>.
- </p>
- <p>
- The year value MAY be set to 0000 when the age of the <a>Contact</a> is private or the year is not
- available.
- </p>
+ This attribute contains the name of this <a>Contact</a> in a form that is suitable for display
+ to the user.
</dd>
- <dt>attribute DOMString? note</dt>
+ <dt>ContactName? name</dt>
<dd>
- <p>
- This attribute contains the personal notes (free-text) for this <a>Contact</a> that is managed by the
- user of the address book.
- </p>
+ This attribute represents the full name of this <a>Contact</a> indicated by the name components
+ associated with the <a>ContactName</a> dictionary.
</dd>
- <dt>attribute ContactField[]? photos</dt>
+ <dt>DOMString? nickname</dt>
+ <dd>
+ This attribute contains the nickname (or a casual name) for this <a>Contact</a>.
+ </dd>
+ <dt>ContactField[]? phoneNumbers</dt>
+ <dd>
+ This attribute captures one or more phone numbers associated with this <a>Contact</a>.
+ </dd>
+ <dt>ContactField[]? emails</dt>
+ <dd>
+ This attribute represents one or more email addresses associated with this <a>Contact</a>.
+ </dd>
+ <dt>ContactAddress[]? addresses</dt>
+ <dd>
+ This attribute represents one or more physical addresses associated with this <a>Contact</a>.
+ </dd>
+ <dt>ContactField[]? ims</dt>
+ <dd>
+ This attribute represents one or more instant messaging identifiers associated with this
+ <a>Contact</a>.
+ </dd>
+ <dt>ContactOrganization[]? organizations</dt>
+ <dd>
+ This attribute represents one or more organisations associated with this <a>Contact</a>.
+ </dd>
+ <dt>Date? birthday</dt>
+ <dd>
+ This attribute contains birthday of this <a>Contact</a>. The <a>contact service</a> MAY
+ set the year value to 0000 when the age of the <a>Contact</a> is private or the year is not
+ available.
+ </dd>
+ <dt>DOMString? note</dt>
+ <dd>
+ This attribute contains the personal notes (free-text) for this <a>Contact</a> that is managed by the
+ user of the address book.
+ </dd>
+ <dt>ContactField[]? photos</dt>
<dd>
<p>
This attribute represents one or more photos associated with this <a>Contact</a>.
@@ -346,476 +342,178 @@
to provide inline data.
</p>
<p class="note">
- This attribute SHOULD NOT be used to send down arbitrary photos taken by this user,
+ A <a>contact service</a> SHOULD NOT use this attribute to send down arbitrary photos taken by this user,
but specifically profile photos of the contact suitable for display when describing the
contact.
</p>
</dd>
- <dt>attribute DOMString[]? categories</dt>
+ <dt>DOMString[]? categories</dt>
<dd>
- <p>
- This attribute contains one or more user-defined categories/tags/labels associated with this
- <a>Contact</a>. e.g. "family", "favorite", "cryptozoologists".
- </p>
+ This attribute contains one or more user-defined categories/tags/labels associated with this
+ <a>Contact</a>. e.g. "family", "favourite", "cryptozoologists".
</dd>
- <dt>attribute ContactField[]? urls</dt>
+ <dt>ContactField[]? urls</dt>
<dd>
<p>
This attribute represents one or more URLs associated with this <a>Contact</a> e.g. personal web page,
blog.
</p>
- <p>
- The web resources MUST be specified using the <code>value</code> attribute of the
- <code>ContactField</code> object, and its <code>type</code> field may be set to "blog" or
- "profile".
- </p>
- </dd>
- </dl>
- </section>
-
- <section>
- <h2><a>ContactName</a> interface</h2>
-
- <p>
- The <a>ContactName</a> interface describes a contact's name.
- </p>
-
- <dl title='[NoInterfaceObject] interface ContactName' class='idl'>
- <dt>attribute DOMString? familyName</dt>
- <dd>
- <p>
- This attribute contains the family name (also referred to as the last name) of this <a>Contact</a>.
- </p>
- </dd>
- <dt>attribute DOMString? givenName</dt>
- <dd>
- <p>
- This attribute contains the given name (also referred to as the first name) of this <a>Contact</a>.
- </p>
- </dd>
- <dt>attribute DOMString? middleName</dt>
- <dd>
- <p>
- This attribute contains the middle name of this <a>Contact</a>.
- </p>
- </dd>
- <dt>attribute DOMString? honorificPrefix</dt>
- <dd>
- <p>
- This attribute contains the honorific prefix (or title) of this <a>Contact</a>. E.g. Mr., Dr., Ms.,
- Mrs.
- </p>
- </dd>
- <dt>attribute DOMString? honorificSuffix</dt>
- <dd>
- <p>
- This attribute contains the honorific suffix of this <a>Contact</a>. E.g. Jr., III, Sr.
- </p>
- </dd>
- </dl>
- </section>
-
- <section>
- <h2><a>ContactField</a> interface</h2>
-
- <p>
- The <a>ContactField</a> interface is a reusable component that is used to capture contact fields of the
- <a>Contact</a> interface that have some modicum of structure.
- </p>
-
- <dl title='[NoInterfaceObject] interface ContactField' class='idl'>
- <dt>attribute DOMString type</dt>
- <dd>
- <p>
- This attribute contains the type information for this <a>ContactField</a> and its content varies subject
- to the contact property this <a>ContactField</a> is representing. For example, if the <a>ContactField</a>
- is representing a <code>phoneNumber</code> property, the <code>type</code> attribute can be set to
- <code>home</code>, <code>mobile</code>; if the <a>ContactField</a> is representing the <code>ims</code>
- property, the type attribute could be set to <code>xmpp</code>, <code>irc</code>, <code>bbm</code>, etc.
- </p>
- </dd>
- <dt>attribute DOMString? value</dt>
- <dd>
- <p>
- This attribute contains the value for this <a>ContactField</a> and its content varies subject to the
- contact property this <a>ContactField</a> is representing. For example, if the <a>ContactField</a> is
- representing an <code>email</code>, the value attribute could be set to <code>JoeSmith@example.com</code>,
- and if the <a>ContactField</a> is representing a <code>url</code>, the value attribute can be set to
- <code>http://www.example.org/joesmith</code>, etc.
- </p>
- </dd>
- <dt>attribute boolean pref</dt>
- <dd>
- <p>
- This attribute indicates whether this instance of the <a>ContactField</a> is the
- preferred, or primary, value for the contact property this <a>ContactField</a> is
- representing in the <a>Contact</a> interface. By default, the value is <code>false</code>.
- </p>
- </dd>
- </dl>
- </section>
-
- <section>
- <h2><a>ContactAddress</a> interface</h2>
-
- <p>
- The <a>ContactAddress</a> interface is a reusable component that is used to capture addresses
- within the <a>Contact</a> interface.
- </p>
- <dl title='[NoInterfaceObject] interface ContactAddress' class='idl'>
- <dt>attribute boolean pref</dt>
- <dd>
- <p>
- This attribute indicates whether this instance of the <code>ContactAddress</code> is the preferred, or primary, value for the contact.
- By default, the value is <code>false</code>.
- </p>
- </dd>
- <dt>attribute DOMString? type</dt>
- <dd>
- <p>
- This attribute contains the type of address this object is representing (e.g. <code>work</code>, <code>home</code>, <code>premises</code>, etc).
- </p>
- </dd>
- <dt>attribute DOMString? streetAddress</dt>
- <dd>
- <p>
- This attribute contains the street address corresponding to this <a>ContactAddress</a>.
- </p>
- </dd>
- <dt>attribute DOMString? locality</dt>
- <dd>
- <p>
- This attribute contains the locality (or city) name corresponding to this <a>ContactAddress</a>.
- </p>
- </dd>
- <dt>attribute DOMString? region</dt>
- <dd>
- <p>
- This attribute contains the region (or state/province) name corresponding to this <a>ContactAddress</a>.
- </p>
- </dd>
- <dt>attribute DOMString? postalCode</dt>
- <dd>
- <p>
- This attribute contains the postal code (or zip) corresponding to this <a>ContactAddress</a>.
- </p>
- </dd>
- <dt>attribute DOMString? country</dt>
- <dd>
- <p>
- This attribute contains the country name corresponding to this <a>ContactAddress</a>.
- </p>
- </dd>
- </dl>
- </section>
-
- <section>
- <h2><a>ContactOrganization</a> interface</h2>
-
- <p>
- The <a>ContactOrganization</a> interface is a reusable component that is used to support contact
- organisations within the <a>Contact</a> interface.
- </p>
-
- <dl title='[NoInterfaceObject] interface ContactOrganization' class='idl'>
- <dt>attribute boolean pref</dt>
- <dd>
- <p>
- This attribute indicates whether this instance of the <code>ContactOrganization</code> is the preferred, or
- primary, value for the contact. By default, the value is <code>false</code>.
- </p>
- </dd>
- <dt>attribute DOMString? type</dt>
- <dd>
- <p>
- This attribute contains the type of organization this object is representing.
- </p>
- </dd>
- <dt>attribute DOMString? name</dt>
- <dd>
- <p>
- The name of the organisation.
- </p>
- </dd>
- <dt>attribute DOMString? department</dt>
- <dd>
- <p>
- The department within which this <a>Contact</a> works.
- </p>
- </dd>
- <dt>attribute DOMString? title</dt>
- <dd>
- <p>
- The job title that the <a>Contact</a> holds inside this organisation.
- </p>
</dd>
</dl>
</section>
<section>
- <h2><a>ContactFindOptions</a> interface</h2>
+ <h2>The <a>ContactName</a> dictionary</h2>
<p>
- The <a>ContactFindOptions</a> interface describes the options that can be applied to contact searching.
- When a <a>ContactFindOptions</a> parameter is provided to the <a>Contacts</a> <a href="#widl-Contacts-find-void-DOMStringArray-fields-ContactFindCB-successCB-ContactErrorCB-errorCB-ContactFindOptions-options">find()</a>
- operation, it should be processed according to the provisions detailed in
- <a href="#options-processing">Options Processing</a>.
+ The <a>ContactName</a> dictionary describes a contact's name in detail.
</p>
- <dl title='[NoInterfaceObject] interface ContactFindOptions' class='idl'>
- <dt>attribute DOMString? filter</dt>
+ <dl title='dictionary ContactName' class='idl'>
+ <dt>DOMString? familyName</dt>
<dd>
- A string-based <a>search filter</a> which provides a hint to the user agent to facilitate contacts selection by the user.
+ This attribute contains the family name (also referred to as the last name) of this <a>Contact</a>.
</dd>
- <dt>attribute boolean? multiple</dt>
+ <dt>DOMString? givenName</dt>
<dd>
- A boolean value to indicate whether multiple Contact objects are wanted as part of the
- <a>Contacts</a> <a href="#widl-Contacts-find-void-DOMStringArray-fields-ContactFindCB-successCB-ContactErrorCB-errorCB-ContactFindOptions-options">find()</a> operation.
- By default this option is set to <code>false</code>.
+ This attribute contains the given name (also referred to as the first name) of this <a>Contact</a>.
+ </dd>
+ <dt>DOMString? middleName</dt>
+ <dd>
+ This attribute contains the middle name of this <a>Contact</a>.
+ </dd>
+ <dt>DOMString? honorificPrefix</dt>
+ <dd>
+ This attribute contains the honorific prefix (or title) of this <a>Contact</a>. E.g. Mr., Dr., Ms., Mrs.
+ </dd>
+ <dt>DOMString? honorificSuffix</dt>
+ <dd>
+ This attribute contains the honorific suffix of this <a>Contact</a>. E.g. Jr., III, Sr.
</dd>
</dl>
</section>
<section>
- <h2><a>ContactFindCB</a> interface</h2>
+ <h2>The <a>ContactField</a> dictionary</h2>
<p>
- This is the wrapper interface for callbacks indicating success of the <a href="#widl-Contacts-find-void-DOMStringArray-fields-ContactFindCB-successCB-ContactErrorCB-errorCB-ContactFindOptions-options">find()</a>
- operation.
+ The <a>ContactField</a> dictionary is a reusable component that is used to capture contact fields of the
+ <a>Contact</a> dictionary that have some modicum of structure.
</p>
- <dl title='[Callback=FunctionOnly, NoInterfaceObject] interface ContactFindCB' class='idl'>
- <dt>void onsuccess ()</dt>
+ <dl title='dictionary ContactField' class='idl'>
+ <dt>DOMString type</dt>
<dd>
- <dl class='parameters'>
- <dt>Contact[] contactObjs</dt>
- <dd>
- An array of <a>Contact</a> objects resulting from the given <a>Contacts</a>
- <a href="#widl-Contacts-find-void-DOMStringArray-fields-ContactFindCB-successCB-ContactErrorCB-errorCB-ContactFindOptions-options">find()</a> operation.
- </dd>
- </dl>
+ This attribute contains the type information for this <a>ContactField</a> and its content varies subject
+ to the contact property this <a>ContactField</a> is representing. For example, if the <a>ContactField</a>
+ is representing a <code>phoneNumber</code> property, the <code>type</code> attribute can be set to
+ <code>home</code>, <code>mobile</code>; if the <a>ContactField</a> is representing the <code>ims</code>
+ property, the type attribute could be set to <code>xmpp</code>, <code>irc</code>, <code>bbm</code>, etc.
+ </dd>
+ <dt>DOMString? value</dt>
+ <dd>
+ This attribute contains the value for this <a>ContactField</a> and its content varies subject to the
+ contact property this <a>ContactField</a> is representing. For example, if the <a>ContactField</a> is
+ representing an <code>email</code>, the value attribute could be set to <code>JoeSmith@example.com</code>,
+ and if the <a>ContactField</a> is representing a <code>url</code>, the value attribute can be set to
+ <code>http://www.example.org/joesmith</code>, etc.
+ </dd>
+ <dt>boolean pref</dt>
+ <dd>
+ This attribute indicates whether this instance of the <a>ContactField</a> is the
+ preferred, or primary, value for the contact property this <a>ContactField</a> is
+ representing in the <a>Contact</a> interface. By default, the value is <code>false</code>.
</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 a DOM attribute by the <a>ContactFindCB</a> object.
- </p>
- <table class='simple'>
- <thead>
- <tr>
- <th>event handler attribute</th>
- <th>event handler event type</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><strong><code>onsuccess</code></strong></td>
- <td><code>success</code></td>
- </tr>
- </tbody>
- </table>
- </section>
- </section>
-
- <section>
- <h2><a>ContactErrorCB</a> interface</h2>
- <p>
- This is the wrapper interface for callbacks indicating failure of the <a href="#widl-Contacts-find-void-DOMStringArray-fields-ContactFindCB-successCB-ContactErrorCB-errorCB-ContactFindOptions-options">find()</a>
- operation.
- </p>
-
- <dl title='[Callback=FunctionOnly, NoInterfaceObject] interface ContactErrorCB' class='idl'>
- <dt>void onerror ()</dt>
- <dd>
- <dl class='parameters'>
- <dt>ContactError error</dt>
- <dd>The <a>ContactError</a> object capturing the type of the error.</dd>
- </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 a DOM attribute by the <a>ContactErrorCB</a> object.
- </p>
-
- <table class='simple'>
- <thead>
- <tr>
- <th>event handler attribute</th>
- <th>event handler event type</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><a>ContactError</a> interface</h2>
+ <h2>The <a>ContactAddress</a> dictionary</h2>
<p>
- The <a>ContactError</a> interface encapsulates all errors in the manipulation of
- <a>Contact</a> objects.
+ The <a>ContactAddress</a> dictionary is a reusable component that is used to capture addresses
+ within the <a>Contact</a> dictionary.
</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 TIMEOUT_ERROR = 2</dt>
- <dd>The requested method timed out before it could be completed.</dd>
+ <dl title='dictionary ContactAddress' class='idl'>
+ <dt>boolean pref</dt>
+ <dd>
+ This attribute indicates whether this instance of the <code>ContactAddress</code> is the preferred,
+ or primary, value for the contact. By default, the value is <code>false</code>.
+ </dd>
+ <dt>DOMString? type</dt>
+ <dd>
+ This attribute contains the type of address this object is representing (e.g. <code>work</code>,
+ <code>home</code>, <code>premises</code>, etc).
+ </dd>
+ <dt>DOMString? streetAddress</dt>
+ <dd>
+ This attribute contains the street address corresponding to this <a>ContactAddress</a>.
+ </dd>
+ <dt>DOMString? locality</dt>
+ <dd>
+ This attribute contains the locality (or city) name corresponding to this <a>ContactAddress</a>.
+ </dd>
+ <dt>DOMString? region</dt>
+ <dd>
+ This attribute contains the region (or state/province) name corresponding to this <a>ContactAddress</a>.
+ </dd>
+ <dt>DOMString? postalCode</dt>
+ <dd>
+ This attribute contains the postal code (or zip) corresponding to this <a>ContactAddress</a>.
+ </dd>
+ <dt>DOMString? country</dt>
+ <dd>
+ This attribute contains the country name corresponding to this <a>ContactAddress</a>.
+ </dd>
+ </dl>
+ </section>
- <dt>const unsigned short PENDING_OPERATION_ERROR = 3</dt>
- <dd>There is already a <a>task</a> in the <a>device task source</a>.</dd>
-
- <dt>const unsigned short IO_ERROR = 4</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 = 5</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 information was denied by 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 Pick Contacts Intent
- processing.</dd>
+ <section>
+ <h2>The <a>ContactOrganization</a> dictionary</h2>
+ <p>
+ The <a>ContactOrganization</a> dictionary is a reusable component that is used to support contact
+ organisations within the <a>Contact</a> dictionary.
+ </p>
+ <dl title='dictionary ContactOrganization' class='idl'>
+ <dt>boolean pref</dt>
+ <dd>
+ This attribute indicates whether this instance of the <code>ContactOrganization</code> is the preferred, or
+ primary, value for the contact. By default, the value is <code>false</code>.
+ </dd>
+ <dt>DOMString? type</dt>
+ <dd>
+ This attribute contains the type of organisation this object is representing.
+ </dd>
+ <dt>DOMString? name</dt>
+ <dd>
+ The name of the organisation.
+ </dd>
+ <dt>DOMString? department</dt>
+ <dd>
+ The department within which this <a>Contact</a> works.
+ </dd>
+ <dt>DOMString? title</dt>
+ <dd>
+ The job title that the <a>Contact</a> holds inside this organisation.
+ </dd>
</dl>
</section>
+ <section>
+ <h2>The <a>ContactError</a> dictionary</h2>
+ <p>
+ If the <a>contact service</a> encounters an error then it MUST return an error
+ (through <code>postFailure()</code>) using the <a>ContactError</a> dictionary.
+ </p>
+ <dl title='dictionary ContactError' class='idl'>
+ <dt>DOMString message</dt>
+ <dd>A message describing the error.</dd>
+ </dl>
+ </section>
+ <section>
+ <h2>Extended Contact Properties and Parameters</h2>
+ <p>
+ A <a>contact service</a> MAY extend the dictionaries described in in the Data Formats section with
+ additional fields. If providing an extended field, a <a>contact service</a> MUST prefix its name
+ with <code>X</code> (U+0058 LATIN CAPITAL LETTER X) or use a vendor-specific prefix.
+ </p>
+ </section>
</section>
-
- <section>
- <h2>Extended Contact Properties and Parameters</h2>
-
- <p>
- The properties and parameters defined on the <a href="#contact-interface"><code>Contact</code></a>
- interface MAY be extended by implementers of this specification.
- </p>
-
- <p>
- Non-standard, private properties and parameters MUST have a prefixed name starting with
- <code>X</code> (U+0058 LATIN CAPITAL 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 and a WebIDL grammar 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='idl' title='Contact implements ContactExtended'>
-
- </div>
-
- <dl title='[NoInterfaceObject] interface ContactExtended' class='idl'>
- <dt>attribute ContactAccount[] Xaccounts</dt>
-
- <dd>One or more user accounts. See [[[POCO-SCHEMA]] Section 7.2.2. <code>accounts</code>].</dd>
- </dl>
-
- <dl title='[NoInterfaceObject] interface ContactAccount' class='idl'>
- <dt>attribute DOMString domain</dt>
-
- <dd>
- <p>
- See [[[POCO-SCHEMA]] Section 7.6. <code>domain</code>].
- </p>
- </dd>
-
- <dt>attribute DOMString username</dt>
-
- <dd>
- <p>
- See [[[POCO-SCHEMA]] Section 7.6. <code>username</code>].
- </p>
- </dd>
-
- <dt>attribute DOMString userid</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>
- The following ABNF grammar extends the grammar found in [[RFC2426]] (Section 4).
-
- <strong>X-ACCOUNT</strong>
-
- Purpose: To specify the components of the accounts for the vCard
- object.
-
- Value type: A single structured text value, separated by the SEMI-
- COLON character (ASCII decimal 59).
-
- Cardinality: (0,n)
-
- Special notes: The structured type value consists of a sequence of
- account components. The component values must be specified in
- their corresponding position. The structured type value
- corresponds, in sequence, to the domain; the username; the userid.
- When a component value is missing, the associated component
- separator must still be specified.
-
- The text components are separated by the SEMI-COLON character
- (ASCII decimal 59).
-
- ABNF:
-
- X-ACCOUNT-param = ; no parameter allowed
- X-ACCOUNT-value = list-component 3(";" list-component)
- </pre>
-
- <p>
- This parameter will be used within the Pick Contacts Intent 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
- alert(contact.Xaccounts[i].username); // null
- alert(contact.Xaccounts[i].userid); // 344aesq2
- }
- </pre>
-
- <p>
- This parameter will be used within the vCard format [[RFC2426]]] as follows:
- </p>
- <pre>
- X-ACCOUNT;thesocialnetwork.com;;344aesq2
- </pre>
- </div>
- </section>
-
<section class="informative appendix">
<h2>User Interaction Guidelines</h2>