Copyright © 2010 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
The Contacts API defines the high-level interfaces required to provide read access to a user's unified address book.
Methods to manipulate a user's unified address book, to add and remove contact information, are being developed in an accompanying specification [CONTACTS-WRITER-API].
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
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.
This document was published by the Device APIs and Policy Working Group as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-device-apis@w3.org (subscribe, archives). All feedback is welcome.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
ServiceContacts interface
Contacts interface
Contact interface
ContactName interface
ContactField interface
ContactAddress interface
ContactOrganization interface
ContactFindOptions interface
ContactFindCB interface
ContactErrorCB interface
ContactError interface
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].
This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.
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.
This section is non-normative.
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.
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 application can fulfill its purpose.
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.
A conforming implementation is required to implement all fields defined in this specification.
The following code illustrates how to obtain contact information from a user's address book:
function successContactFindCallback(contacts) { // do something with resulting contact objects for (var i in contacts) alert(contacts[i].displayName); // ... } function generalErrorCB(error) { // do something with resulting errors alert(error.code); // ... } // Perform an address book search. Obtain the 'name' and 'emails' properties // and initially filter the list to Contact records containing 'Bob': navigator.service.contacts.find(['name', 'emails'], successContactFindCallback, generalErrorCB, {filter: 'Bob'} ); // ..is equivalent to: navigator.service.contacts(/* parameters */)
The terms document base URL, browsing context, event handler attributes, event handler event type, task, task source and task queues are defined by the HTML5 specification [HTML5].
The task source used by this specification is the PendingOp task source.
PendingOp needs updating in [CORE-DEVICE] to show that it is a valid task source.
To dispatch a success event means that an event with the name success, which does
not bubble and is not cancelable, and which uses the Event interface, is to be dispatched at the ContactFindCB object.
To dispatch an error event means that an event with the name error, which does
not bubble and is not cancelable, and which uses the Event interface, is to be dispatched at the ContactErrorCB object.
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.
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.
A user agent must not retrieve contact information to Web sites without the express permission of the user. A user agent must acquire permission through a user interface, unless they have prearranged trust relationships with users, as described below. The user interface must include the document base URL. 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 is navigated to another URL) must be revocable and a user agent must respect revoked permissions.
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 find function is called on
this API.
A user agent 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.
This section is non-normative.
Web sites owners that retrieve contacts information using this API are denoted as recipients below.
Recipients should only request contact information when necessary, and only use the contact information for the task for which it was provided to them.
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.
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 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 should include an explanation of any exceptions to the guidelines listed above.
This section is non-normative.
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.
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.
ServiceContacts interface
The ServiceContacts interface is exposed on the navigator.service
object, as defined in [CORE-DEVICE].
Service implements ServiceContacts;[NoInterfaceObject]
interface ServiceContacts {
readonly attribute Contacts contacts;
};
contacts of type Contacts, readonlyContacts interface
The Contacts interface exposes a database collecting contacts information that may be retrieved.
Multiple contact groups can be represented within this unified address book by specifying consistent categories value(s) as part of individual Contact objects. Multiple contact groups can be displayed by filtering on the
required categories value(s) via the Contacts find() function.
[NoInterfaceObject]
interface Contacts {
caller PendingOp find (in DOMString[] fields, in ContactFindCB successCB, in optional ContactErrorCB? errorCB, in optional ContactFindOptions? options);
};
findFind contacts in the address book according to the find contacts process detailed below.
This method takes two, three or four arguments. When called, it immediately returns a PendingOp object, as
defined in [CORE-DEVICE], and then asynchronously starts a find contacts process defined as follows:
PendingOp task source in one of the task queues
(i.e. an existing find() operation is still pending a response), and the current method was invoked with a
non-null errorCB argument, dispatch an error event with a PENDING_OPERATION_ERROR code value.
success event. If the attempt fails, and the method was
invoked with a non-null errorCB argument, this method must dispatch an error
event with the code attribute set according to the type of failure that has occurred.
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| fields | DOMString[] | ✘ | ✘ | The search qualifier. |
| successCB | | ✘ | ✘ | Function to call when the asynchronous operation completes |
| errorCB | | ✔ | ✔ | Function to call when the asynchronous operation fails. |
| options | | ✔ | ✔ | The options to apply to the output of this method. |
caller PendingOpContact interface
The attributes provided in this interface are under review and are likely to change as the recommendation progresses.
The Contact interface captures the properties of a contact object.
All Contact objects must include all attributes supported by the implementation,
regardless of whether these attributes have been assigned a non-null value or a null 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 Contact object and must have a value of null.
Additional attributes may be included according to the provisions detailed in Extended Contact Properties and Parameters. 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 Contact object and must have a value of null.
[NoInterfaceObject]
interface Contact {
readonly attribute DOMString id;
attribute DOMString displayName;
attribute ContactName name;
attribute DOMString nickname;
attribute ContactField[] phoneNumbers;
attribute ContactField[] emails;
attribute ContactAddress[] addresses;
attribute ContactField[] ims;
attribute ContactOrganization[] organizations;
attribute Date revision;
attribute Date birthday;
attribute DOMString gender;
attribute DOMString note;
attribute ContactField[] photos;
attribute DOMString[] categories;
attribute ContactField[] urls;
attribute DOMString timezone;
};
addresses of type array of ContactAddressThis attribute represents one or more physical addresses associated with this Contact.
birthday of type DateThis attribute contains birthday of this Contact.
The year value may be set to 0000 when the age of the Contact is private or the year is not available.
categories of type array of DOMStringThis attribute contains one or more user-defined categories/tags/labels associated with this Contact. e.g. "family", "favorite".
displayName of type DOMStringThis attribute contains the display name of this Contact which is suitable for display to the end-users.
Each Contact must include either a displayName or the name attribute.
emails of type array of ContactFieldThis attribute represents one or more email addresses associated with this Contact.
gender of type DOMStringThis attribute contains the gender of this Contact. This attribute should have one of the following values:
male, female, undisclosed
This attribute may return a different value if it is not covered by one of these values.
id of type DOMString, readonly
A globally unique identifier for the given Contact object. Each Contact must
include a non-empty id value.
An implementation must maintain this globally unique resource identifier when a Contact is added to, or present within, an Address Book.
ims of type array of ContactFieldThis attribute represents one or more instant messaging identifiers associated with this Contact.
name of type ContactName
This attribute represents the full name of this Contact indicated by the name
components associated with the ContactName object.
nickname of type DOMStringThis attribute contains the nickname (or a casual name) for this Contact.
note of type DOMStringThis attribute contains the personal notes (free-text) for this Contact that is managed by the user of the Address Book.
This field may contain newlines (\n).
organizations of type array of ContactOrganizationThis attribute represents one or more organizations associated with this Contact.
phoneNumbers of type array of ContactFieldThis attribute represents one or more phone numbers associated with this Contact.
photos of type array of ContactFieldThis attribute represents one or more photos (that may be displayed) associated with this Contact.
The photos must be specified in the value attribute of the ContactField object either by using a URL
(representing an actual image file and not a web page pointing to that image file) or base64 encoded string representing the image data.
Service Providers may return the same image at different sizes, though it is recognized that no standard for describing images of various sizes currently exists.
This attribute should not be used to send down arbitrary photos taken by this user, but specifically profile photos of the contact suitable for display when describing the contact.
revision of type DateThis atttribute contains the timestamp information associated with this Contact, which represents the last known modified time. If no modified time exists, then this object contains the timestamp of when the object was created.
timezone of type DOMStringThe value contains the time zone of this Contact as an offset from UTC.
The value must be specified as a positive or negative difference
from the UTC in units of hours and minutes (i.e. +hh:mm). Example, by specifying +05:30 indicates the Contact
is associated with a current time zone of GMT+05:30.
This value may change over time due to daylight saving time, and is thus meant to signify only the current value of the user's timezone offset.
urls of type array of ContactFieldThis attribute represents one or more web resources (i.e. URLs) associated with this Contact e.g. personal web page, blog.
The web resources must be specified by the value attribute of the ContactField object using a URL.
In addition to the standard values for type, this field also defines the additional type values:
blog, profile
ContactName interface
The ContactName interface describes a contact's name.
[NoInterfaceObject]
interface ContactName {
attribute DOMString formatted;
attribute DOMString familyName;
attribute DOMString givenName;
attribute DOMString middleName;
attribute DOMString honorificPrefix;
attribute DOMString honorificSuffix;
};
familyName of type DOMStringThis attribute contains the family name (also referred to as the last name) of this Contact.
formatted of type DOMString
This attribute contains the full name, including all the individual components such as givenName, middleName,
familyName, prefix, suffix as appropriate, and formatted for display (e.g. Mr. Joe Smith Jr).
givenName of type DOMStringThis attribute contains the given name (also referred to as the first name) of this Contact.
honorificPrefix of type DOMStringThis attribute contains the honorific prefix (or title) of this Contact. E.g. Mr. Dr. Ms. Mrs.,
honorificSuffix of type DOMStringThis attribute contains the honorific suffix of this Contact. E.g. Jr, III, Sr.
middleName of type DOMStringThis attribute contains the middle name of this Contact.
ContactField interface
The ContactField interface is a reusable component that is used to support contact fields within the Contact interface.
[NoInterfaceObject]
interface ContactField {
attribute DOMString type;
attribute DOMString value;
attribute boolean pref;
};
pref of type boolean
This attribute indicates whether this instance of the ContactField is the preferred, or primary, value for the contact property this
ContactField is representing in the Contact interface.
type of type DOMString
This attribute contains the type information for this ContactField and is subject to the contact property this
ContactField is representing in the Contact interface. For example, if the ContactField is
representing a phoneNumber property, the type attribute is set to home, mobile,
and if the Contact Field is representing ims property, the type attribute is set to yahoo, gtalk,
bbm, etc.
value of type DOMString
This attribute contains the value for this ContactField and is subject to the contact property this
ContactField is representing in the Contact interface. For example, if the ContactField is
representing an email, the value attribute is set to JoeSmith@example.com, and if the ContactField is representing a url, the value
attribute is set to http://www.example.org/joesmith, etc.
ContactAddress interface
The ContactAddress interface is a reusable component that is used to support contact addresses within the Contact interface.
[NoInterfaceObject]
interface ContactAddress {
attribute DOMString formatted;
attribute DOMString streetAddress;
attribute DOMString locality;
attribute DOMString region;
attribute DOMString postalCode;
attribute DOMString country;
};
country of type DOMString
This attribute contains the country name corresponding to this ContactAddress.
formatted of type DOMStringThis attribute contains the full physical address including street, locality, region, postalCode, and country as appropriate, and formatted for display.
locality of type DOMString
This attribute contains the locality (or city) name corresponding to this ContactAddress.
postalCode of type DOMString
This attribute contains the postal code (or zip) corresponding to this ContactAddress.
region of type DOMString
This attribute contains the region (or state/province) name corresponding to this ContactAddress.
streetAddress of type DOMString
This attribute contains the street address corresponding to this ContactAddress.
ContactOrganization interface
The ContactOrganization interface is a reusable component that is used to support contact organizations within the Contact interface.
[NoInterfaceObject]
interface ContactOrganization {
attribute DOMString name;
attribute DOMString department;
attribute DOMString title;
};
department of type DOMStringThis attribute contains the Job Title information of the Contact associated with this Organization.
name of type DOMStringThis attribute contains the name of the Organization and must be assigned a non-null value.
title of type DOMStringThis attribute contains the department information of the Organization associated with this Contact.
ContactFindOptions interface
The ContactFindOptions interface describes the options that can be applied to
contact searching. When a ContactFindOptions parameter is provided to the Contacts find() operation, it should be processed according to the provisions detailed in Options Processing.
[NoInterfaceObject]
interface ContactFindOptions {
attribute DOMString? filter;
attribute boolean? multiple;
attribute Date? updatedSince;
};
filter of type DOMString, nullableContacts database.
multiple of type boolean, nullableContacts find() operation.
By default this option is set to true.
updatedSince of type Date, nullable
Return only contact records that have been updated on or after the given time, specified as an ECMAScript Date
object.
This filter is applied to the revision field as defined in Contact.
ContactFindCB interface
[Callback=FunctionOnly, NoInterfaceObject]
interface ContactFindCB : PendingOp {
void onsuccess (in Contact[] contactObjs);
};
The following is the event handler attribute (and its corresponding event handler event type) that must be
supported as a DOM attribute by the ContactFindCB object.
| event handler attribute | event handler event type |
|---|---|
onsuccess
|
success
|
ContactErrorCB interface
[Callback=FunctionOnly, NoInterfaceObject]
interface ContactErrorCB : PendingOp {
void onerror (in ContactError error);
};
onerror| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| error | | ✘ | ✘ | The Contact API related error object. |
void
The following is the event handler attribute (and its corresponding event handler event type) that must be
supported as a DOM attribute by the ContactErrorCB object.
| event handler attribute | event handler event type |
|---|---|
onerror
|
error
|
ContactError interface
The ContactError interface encapsulates all errors in the manipulation of Contact objects in the Contacts API.
[NoInterfaceObject]
interface ContactError {
const unsigned short UNKNOWN_ERROR = 0;
const unsigned short INVALID_ARGUMENT_ERROR = 1;
const unsigned short TIMEOUT_ERROR = 2;
const unsigned short PENDING_OPERATION_ERROR = 3;
const unsigned short IO_ERROR = 4;
const unsigned short NOT_SUPPORTED_ERROR = 5;
const unsigned short PERMISSION_DENIED_ERROR = 20;
readonly attribute unsigned short code;
};
code of type unsigned short, readonlyINVALID_ARGUMENT_ERROR of type unsigned shortIO_ERROR of type unsigned shortNOT_SUPPORTED_ERROR of type unsigned shortPENDING_OPERATION_ERROR of type unsigned shortPERMISSION_DENIED_ERROR of type unsigned shortTIMEOUT_ERROR of type unsigned shortUNKNOWN_ERROR of type unsigned short
The Contacts find() method provides an operation to search for one of more Contact objects within the Contacts database.
The search qualifier provides an application with a way to request the specific subset of Contact properties it wishes to obtain in any resulting successful callback. The
search qualifier is deployed to minimize the data that needs to be shared with an application in order to let that
application fulfill its function on behalf of the user. The search qualifier is included within a Contacts find() operation as the filter parameter.
A search qualifier must be specified from a requesting application as a part of any Contacts find() operation.
If the search qualifier provided is of zero-length then the current Contacts find() operation must not return any Contact properties within any resulting Contact object(s).
In the case that the search qualifier provided is of non-zero-length then the current Contacts find() operation must return only the matching Contact properties within any resulting Contact object(s).
If a provided search qualifier element (filter[x]) does not match a Contact attribute, filter[x] should be ignored when executing the
current Contacts find() operation.
We call composed attributes Contact attributes of types object, sequence,
array or any which contain information only available only through child attributes of that object.
A requesting application must be able to request both the full composed Contact attribute and also be able to request individual parts of a composed Contact attribute in the search qualifier provided to a Contacts find() operation.
For example, the name attribute of a Contact object is defined to be of composed type ContactName. Therefore, a requesting application may request either the full
composed attribute (i.e. name) or specific individual attributes of this composed attribute (i.e.
name.formatted, name.familyName, name.givenName, name.middleName,
name.honorificPrefix, name.honorificSuffix) as part of a Contacts find() operation's search qualifier.
In the case that a composed Contact attribute is defined as a sequence or array of composed objects, specific
individual attributes can be referenced by using the composed attribute name, a dot (.) character and the
individual attribute to be retrieved.
For example, the addresses attribute of Contact allows multiple ContactAddress objects to be defined. To request individual attributes of
this composed attribute an application would request e.g. addresses.locality, addresses.region, etc.
The following Contact search is initiated:
navigator.service.contacts.find(['emails.value', 'name', 'friends'], function(contacts) { for(i in contacts) { for(j in contacts[i].emails) alert(contacts[i].emails[j]); } });
The above example logically implies:
Contact attributes requested in the provided search qualifier
(name, emails.value - friends is not a valid Contact attribute so ignore this element).
By default, the Contacts find() operation must return either an empty sequence or a single Contact object, accessible as part of the sequence returned in the ContactFindCB callback function.
If a ContactFindOptions object is provided to the Contacts find() operation and its multiple attribute is set to true, the Contacts find() operation must return either an empty sequence, a single Contact object or [X] number of Contact objects, accessible as part of the sequence returned in the ContactFindCB callback function.
A search filter may be specified from a requesting web application to initially filter the Contacts database to a
more specific set of Contact objects in which it is interested. The search filter is included as
the filter attribute of the ContactFindOptions object provided to a Contacts find() operation.
A search filter is used to search Contact attributes within the Contacts database and represents the logical union, or ∪, of
provided values that are matched therein.
All contact searching must apply a loose-matching policy to the search filter provided. If an attribute being
searched in a Contact object, stored within the Contacts database, is a partial value match of the input
filter value, that Contact object must be returned as part of the resulting ContactFindCB.
A conforming implementation must only allow the provided search filter to be applied to fields requested in the provided
search qualifier. The id attribute must always be implicitly searchable from any requesting web application
regardless of whether it has been included as part of any provided search qualifier. For example, if the given search
qualifier contains 'name' and 'displayName', then the rules for processing search filters should
only be applied to all sub-fields of the name attribute (i.e. name.formatted,
name.firstName, name.givenName, name.middleName, name.honorificPrefix,
name.honorificSuffix), the displayName attribute and the id attribute.
A partial value match refers to both syntactic and semantic partial matching of an input filter value with a corresponding value in the address book and denotes that a corresponding match was found in the address book that begins with, contains or ends with the value of the input filter value, or any variation thereof.
Comparing two strings in a compatibility caseless manner means using the Unicode compatibility caseless match operation to compare the two strings. [UNICODE]
A partial value match must use the compatibility caseless manner in which to match against corresponding values
in the Contacts database.
The rules for processing search filters is defined below and is always provided with a filter parameter, representing the filter attribute of the ContactFindOptions parameter provided within the current Contacts find() operation.
Contacts database.
Let contactsresult be initially an empty Array object.
true, add contactset to contactsresult.
Return contactsets.
The partial matching algorithm is defined below and is always provided with a filter parameter, representing the input string to compare; and a contactset parameter, representing an individual Contact object:
false.
true, go to step 5.
Return false.
The following Contact search is initiated:
navigator.service.contacts.find(['name', 'addresses.locality', 'addresses.country', 'phoneNumbers', 'emails'], function(contacts) { for(x in contacts) alert(contacts[x].name); }, { filter: 'Robert' });
The above example logically implies:
( name.formatted = /∧.*Robert.*$/i ) ∪ ( phoneNumbers.value = /∧.*Robert.*$/i ) ∪ ( emails.value = /∧.*Robert.*$/i ) ∪ ( name.familyName = /∧.*Robert.*$/i ) ∪ ( name.givenName = /∧.*Robert.*$/i ) ∪ ( name.middleName = /∧.*Robert.*$/i ) ∪ ( addresses.country = /∧.*Robert.*$/i ) ∪ ( addresses.locality = /∧.*Robert.*$/i ) ∪ ( phoneNumbers.type = /∧.*Robert.*$/i ) ∪ ( emails.type = /∧.*Robert.*$/i ) ∪ ( id = /∧.*Robert.*$/i )
id attribute is implicitly appended along with any search
filter attributes provided, regardless of whether it was provided as a search qualifier from the requesting
application.Contact properties requested in the provided search qualifier
(name, addresses.locality, addresses.country, phoneNumbers,
emails) and only for the Contact objects returned from the rules for processing search filters
with the search filter derived in step 1 provided as the filter input parameter.
The properties and parameters defined on the Contact interface may be extended by implementors of this specification.
Non-standard, private properties and parameters should have a prefixed name starting with X (U+0058 LATIN CAPTIAL
LETTER X) or use a vendor-specific prefix. Extended properties and parameters can be defined bilaterally between user agents without outside registration or standardization.
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.
A new parameter is required by Company X to provide information related to a user's accounts registered across different networks and services.
The [WEBIDL] syntax for this parameter is defined as follows:
Contact implements ContactExtended;[NoInterfaceObject]
interface ContactExtended {
attribute ContactAccount[] Xaccounts;
};
Xaccounts of type array of ContactAccountaccounts].
[NoInterfaceObject]
interface ContactAccount {
attribute DOMString domain;
attribute DOMString username;
attribute DOMString userid;
};
domain of type DOMString
See [[POCO-SCHEMA] Section 7.6. domain].
userid of type DOMString
See [[POCO-SCHEMA] Section 7.6. userid].
username of type DOMString
See [[POCO-SCHEMA] Section 7.6. username].
The corresponding vCard [RFC2426] notation for this parameter is defined as follows:
The following ABNF grammar extends the grammar found in [RFC2426] (Section 4). X-ACCOUNT 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)
This parameter will be used within the Contacts API as follows:
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 }
This parameter will be used within the vCard format [RFC2426]] as follows:
X-ACCOUNT;thesocialnetwork.com;;344aesq2
This section is non-normative.
The API contained in this document can be invoked either programmatically (for example, inline within a general script) or resulting from the interaction of a user.
The interaction of a user is when a user invokes the API from an
HTMLElement [HTML5] within the current
browsing context via a valid auto-invocation event.
A valid auto-invocation event includes any of the following event types, as defined in [DOM-LEVEL-3-EVENTS]:
clickdblclickmouseupThe find() method on Contacts should, if the method was invoked
by an interaction of a user (as opposed to having been created and executed in general script), display the
Contact Picker directly.
This section is non-normative.
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.
A website requests access to a user's address book with the following code:
<script type="text/javascript"> function successContactFindCallback(contacts) { // do something with resulting contact objects for (var i in contacts) alert(contacts[i].name); // ... } function generalErrorCB(error) { // do something with resulting errors alert(error.code); // ... } // Perform an address book search. Obtain the 'name' and 'emails' properties // and initially filter the list to Contact records containing 'Bob': navigator.service.contacts.find(['name', 'emails'], successContactFindCallback, generalErrorCB, {filter: 'Bob'} ); </script>
As a result of executing this code, the user agent may provide a non-blocking contact search notification as follows:
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 PENDING_OPERATION_ERROR if that operation was defined with a
non-null errorCB parameter.
If the user clicks 'Cancel', the errorCB, if non-null for the current find() operation, will be
invoked with an error code of PERMISSION_DENIED_ERROR.
If the user clicks 'Select', the user agent may provide a contact picker, utilizing all of the parameters provided in the find() operation as follows:
In this dialog, the user is provided with a summary of the sharing that the application is requesting and the option to select one or more contacts (as appropriate) from the user interface.
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 PENDING_OPERATION_ERROR if that operation was defined with a
non-null errorCB parameter.
If the user clicks 'Cancel', the errorCB, if non-null for the current find() operation, will be
invoked with an error code of PERMISSION_DENIED_ERROR.
If the user clicks 'Select', the ContactFindCB associated to the current find() operation will be invoked with
the contact information selected by the user provided as the only parameter.
Further to this initial sharing of Contact information, the Security and Privacy Considerations section expects that the user should easily be able to review and revoke permissions to web applications at a later date.
A website requests access to a user's address book with the following code:
<input type="button" value="Share Contacts" onclick="getContacts()" /> <script type="text/javascript"> function successContactFindCallback(contacts) { // do something with resulting contact objects for (var i in contacts) alert(contacts[i].name); // ... } function generalErrorCB(error) { // do something with resulting errors alert(error.code); // ... } function getContacts() { // Perform an address book search. Obtain the 'name' and 'emails' properties // and initially filter the list to Contact records containing 'Bob': navigator.service.contacts.find(['name', 'emails'], successContactFindCallback, generalErrorCB, {filter: 'Bob'} ); } </script>
This code may render as follows within the user agent:
If the user clicks on the rendered button element then the user agent may directly provide a contact picker, as defined in
API Invocation via DOM Events, utilizing all of the
parameters provided in the find() operation as follows:
In this dialog, the user is provided with a summary of the sharing that the application is requesting and the option to select one or more contacts (as appropriate) from the user interface.
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 PENDING_OPERATION_ERROR if that operation was defined with a
non-null errorCB parameter.
If the user clicks 'Cancel', the errorCB, if non-null for the current find() operation, will be
invoked with an error code of PERMISSION_DENIED_ERROR.
If the user clicks 'Select', the ContactFindCB associated to the current find() operation will be invoked with
the contact information selected by the user provided as the only parameter.
Further to this initial sharing of Contact information, the Security and Privacy Considerations section expects that the user should easily be able to review and revoke permissions to web applications at a later date.
