Contacts API

Abstract

The Contacts API defines the high-level interfaces required to provide access to a user's unified address book.

Status of This Document

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.

1. Conformance

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.

2. Introduction

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 3rd parties users are, more often than not, required to hand over access to their whole address book. Users are implicitly required to trust 3rd parties with all of their data when, in reality, the user may only wish, or need, to share a subset of their address book information so that an application can fulfill its purpose.

This specification defines the concept of a user's unified address book - where address book data may be sourced from a plurality of sources - both online and locally. This specification then defines the interfaces on which 3rd party applications can access a user's unified address book; with explicit user permission and filtering. The focus of this data sharing is on making the user aware of the data that they will share and putting them at the centre of the data sharing process; free to select both the extent to which they share their address book information and the ability to restrict which pieces of information related to which contact gets shared.

The API itself is agnostic of any underlying address book sources and storage. A conforming implementation is required to implement all fields defined in this specification.

2.1 Usage Examples

The following code extracts illustrate how to search, add, remove and update contact information in a given address book:

Searching for matching contacts.

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'}
                               );

Creating a new contact.

// Create new contact  
var myContact = navigator.service.contacts.create({displayName: 'Robert'}});

// Add additional contact attributes as required...
// myContact.nicknames.push('bobby');

Saving a new contact in the underlying addressbook.

// previous example follow-on...

function successContactCallback(contact) {
    // do something with resulting contact object
    alert(contact.displayName);
    // ...
}

// Save new contact
myContact.save(successContactCallback, generalErrorCB);

Editing an existing contact.

// previous example follow-on...

// e.g. add a new phone number
myContact.phoneNumbers.push({type: 'home', value: '+440000000002'});

// Update existing contact
myContact.save(successContactCallback, generalErrorCB);

Removing an existing contact.

// previous example follow-on...

// Remove existing contact
myContact.remove(successContactCallback, generalErrorCB);

3. Security and Privacy Considerations

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 create, find, save and remove contact information from a user's address book(s). All API methods disclose information related to a user's contacts such as their phone number(s), email address(es) and other personally identifying information. The distribution of this information could potentially compromise the user's privacy. A conforming implementation of this specification must provide a mechanism that protects the user's privacy and this mechanism should ensure that no contact information is creatable, retrivable, updateable or removable without the user's express permission.

3.1 Privacy considerations for implementors of the Contacts API

A user agent must not create, find, save or delete 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 URI of the document origin, as defined in [HTML5]. Those permissions that are acquired through the user interface and that are preserved beyond the current browsing session (i.e. beyond the time when the browsing context, as defined in [HTML5], is navigated to another URL) must be revocable and a 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 create, find, save or remove 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 Runtime may have a prearranged, delegated security relationship with the user and, as such, a suitable alternative security and privacy mechanism with which to authorize the creation, retrieval, update and/or removal of contact information.

3.2 Privacy considerations for recipients of contact information

Recipients must only request contact information when necessary. Recipients must only use the contact information for the task for which it was provided to them. Recipients must dispose of contact information once that task is completed, unless expressly permitted to retain it by the user. Recipients must also take measures to protect this information against unauthorized access. If contact information is stored, users should be allowed to update and delete this information.

The recipient of contact information must not retransmit the contact information without the user's express permission. Care should be taken when retransmitting and use of encryption is encouraged.

Recipients must clearly and conspicuously disclose the fact that they are collecting contact data, the purpose for the collection, how long the data is retained, how the data is secured, how the data is shared if it is shared, how users can access, update and delete the data, and any other choices that users have with respect to the data. This disclosure must include an explanation of any exceptions to the guidelines listed above.

3.3 Additional implementation considerations

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.

4. API Description

4.1 `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;
};

4.1.1 Attributes

contacts of type Contacts, readonly: The root node from which the contacts functionality can be accessed.
No exceptions.

4.2 `Contacts` interface

The Contacts interface exposes a database collecting contacts information, such that they may be created, found, read, updated, and deleted.

Multiple address books, taken from different sources, can be represented within this unified address book interface. Contacts from different sources can be distinguished using the serviceId field.. In addition, multiple address books can be displayed by filtering on the required serviceId value via the Contacts find() function.

Equally, multiple contact groups can be represented within this unified address book by specifying consistent tags value(s) as part of individual Contact objects. Multiple contact groups can be displayed by filtering on the required tags value(s) via the Contacts find() function.

[NoInterfaceObject]
interface Contacts {
    Contact   create (in ContactProperties attributes);
    PendingOp find (in DOMString[] fields, in ContactFindSuccessCB successCB, in optional ContactErrorCB? errorCB, in optional ContactFindOptions? options);
};

4.2.1 Methods

create

Create a new Contact object.

This method takes one argument. When called, it returns a Contact object.

The newly created Contact object must not be stored in the user's address book as a result of calling this method. The Contact save() method must be called on the response of this method to store the new Contact object in the user's address book.

Parameter	Type	Nullable	Optional	Description
attributes	`ContactProperties`	✘	✘	The attributes to assign to the resulting object.

No exceptions.

Return type: Contact

find

Find 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:

If a current find(), save() or remove() operation is pending a response, invoke the errorCB with a PENDING_OPERATION_ERROR code.
Search for contacts in the address book according to the rules defined in Contact Search Processing.
If successful, invoke the associated successCB. If the attempt fails, and the method was invoked with a non-null errorCB argument, this method must invoke the errorCB with a ContactError object as an argument.

Parameter	Type	Nullable	Optional	Description
fields	`DOMString[]`	✘	✘	The search qualifier.
successCB	`ContactFindSuccessCB`	✘	✘	Function to call when the asynchronous operation completes
errorCB	`ContactErrorCB`	✔	✔	Function to call when the asynchronous operation fails.
options	`ContactFindOptions`	✔	✔	The options to apply to the output of this method.

No exceptions.

Return type: PendingOp

4.3 `Contact` interface

The Contact interface captures a single contact item. This interface extends ContactProperties attributes.

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.

[NoInterfaceObject]
interface Contact : ContactProperties {
    readonly attribute DOMString  id;
             attribute DOMString? serviceId;
    Contact   clone ();
    PendingOp save (in ContactSuccessCB successCB, in optional ContactErrorCB? errorCB);
    PendingOp remove (in ContactSuccessCB successCB, in optional ContactErrorCB? errorCB);
};

4.3.1 Attributes

id of type DOMString, readonly

A globally unique identifier for the given Contact object. Each Contact referenced from Contacts 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.

See [[POCO-SCHEMA] Section 7.2.1. id] for additional definition of this attribute.

No exceptions.

serviceId of type DOMString, nullable

Can we remove this attribute? Does a web application need to know the storage location of a Contact record?

This directly relates to ISSUE-43 and discussion thread http://lists.w3.org/Archives/Public/public-device-apis/2010Jun/0248.html.

An identifier that may be provided that represents the address book owner of the current contact object.

This attribute enables multiple address book sources to be tagged and filtered on Contact objects.

The following constants are defined for use in the serviceId attribute for addressing non-networked storage databases:

 
'uicc', 'device'.

A conforming implementation must define a default service identifier on which to store Contact objects that have not yet been assigned to any storage database. The default service identifier will then be used in the Contact save() operation when a serviceId is not recognized or when the serviceId attribute is null.

For all other Contacts sources, it is recommended that the serviceId attribute is assigned as a URI.

No exceptions.

4.3.2 Methods

clone

Create a deep clone copy of the current object minus the current object's id attribute.

The resulting object must be provided with a newly generated id attribute to distiguish the cloned object from the original object.

No parameters.

No exceptions.

Return type: Contact

remove

Remove the current contact from the address book.

In the case that the current id attribute is null and this method is invoked, a ContactErrorCB must be triggered as part of the remove contact process. This error must consist of a ContactError object with a code of NOT_FOUND_ERROR.

This method takes one or two arguments. When called, it immediately returns a PendingOp object, as defined in [CORE-DEVICE], and then asynchronously starts a remove contact process defined as follows:

If a current find(), save() or remove() operation is pending a response, invoke the errorCB with a PENDING_OPERATION_ERROR code.
Remove the current object from Contacts.
If the removal of the current object from Contacts was successful, set the current object's Contact.id value to null and the current object's Contact.serviceId value to null.
If successful, invoke the associated successCB. If the attempt fails, and the method was invoked with a non-null errorCB argument, this method must invoke the errorCB with a ContactError object as an argument.

Parameter	Type	Nullable	Optional	Description
successCB	`ContactSuccessCB`	✘	✘	Function to call when the asynchronous operation completes
errorCB	`ContactErrorCB`	✔	✔	Function to call when the asynchronous operation fails.

No exceptions.

Return type: PendingOp

save

Add or update (as appropriate) the current Contact object to the Contacts.

This method takes one or two arguments. When called, it immediately returns a PendingOp object , as defined in [CORE-DEVICE], and then asynchronously starts a save contact process defined as follows:

If a current find(), save() or remove() operation is pending a response, invoke the errorCB with a PENDING_OPERATION_ERROR code.
If the current Contact.serviceId value is not recognized in Contacts or a Contact.serviceId value has not been set, create and set a new Contact.serviceId value to the default service identifier.
If the current Contact.id value is not recognized in Contacts or a Contact.id value has not been set, create and set a new Contact.id value and add the current object as a new object to Contacts.
If the Contact.id already exists in Contacts then update the existing object in Contacts.
If successful, invoke the associated successCB. If the attempt fails, and the method was invoked with a non-null errorCB argument, this method must invoke the errorCB with a ContactError object as an argument.

Parameter	Type	Nullable	Optional	Description
successCB	`ContactSuccessCB`	✘	✘	Function to call when the asynchronous operation completes
errorCB	`ContactErrorCB`	✔	✔	Function to call when the asynchronous operation fails.

No exceptions.

Return type: PendingOp

4.4 `ContactProperties` interface

The use of Portable Contacts schema as the format for contacts is subject to further discussions in the group.

The ContactProperties interface captures the settable properties of a contact. All properties included in this interface have a corresponding definition in [POCO-SCHEMA].

In addition to the properties defined in this interface, a conforming implementation must support both the Singular and Plural OpenSocial fields defined in [POCO-SCHEMA].

The inclusion of OpenSocial fields in the paragraph above needs further explanation, particularly in relation to contact database searching and sorting.

[NoInterfaceObject]
interface ContactProperties {
    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 DOMString             published;
    attribute DOMString             updated;
    attribute DOMString             birthday;
    attribute DOMString             anniversary;
    attribute DOMString             gender;
    attribute DOMString             note;
    attribute DOMString             preferredUsername;
    attribute ContactField[]        photos;
    attribute ContactField[]        tags;
    attribute ContactField[]        relationships;
    attribute ContactField[]        urls;
    attribute ContactAccount[]      accounts;
    attribute DOMString             utcOffset;
    attribute DOMString             connected;
};

4.4.1 Attributes

accounts of type array of ContactAccount

See [[POCO-SCHEMA] Section 7.2.2. accounts].

No exceptions.

addresses of type array of ContactAddress

See [[POCO-SCHEMA] Section 7.2.2. addresses].

No exceptions.

anniversary of type DOMString

See [[POCO-SCHEMA] Section 7.2.1. anniversary].

No exceptions.

birthday of type DOMString

See [[POCO-SCHEMA] Section 7.2.1. birthday].

No exceptions.

connected of type DOMString

Ignore this [POCO-SCHEMA] attribute?

See [[POCO-SCHEMA] Section 7.2.1. connected].

No exceptions.

displayName of type DOMString

See [[POCO-SCHEMA] Section 7.2.1. displayName].

No exceptions.

emails of type array of ContactField

See [[POCO-SCHEMA] Section 7.2.2. emails].

No exceptions.

gender of type DOMString

See [[POCO-SCHEMA] Section 7.2.1. gender].

No exceptions.

ims of type array of ContactField

See [[POCO-SCHEMA] Section 7.2.2. ims].

No exceptions.

name of type ContactName

See [[POCO-SCHEMA] Section 7.2.1. name].

No exceptions.

nickname of type DOMString

See [[POCO-SCHEMA] Section 7.2.1. nickname].

No exceptions.

note of type DOMString

See [[POCO-SCHEMA] Section 7.2.1. note].

No exceptions.

organizations of type array of ContactOrganization

See [[POCO-SCHEMA] Section 7.2.2. organizations].

No exceptions.

phoneNumbers of type array of ContactField

See [[POCO-SCHEMA] Section 7.2.2. phoneNumbers].

No exceptions.

photos of type array of ContactField

See [[POCO-SCHEMA] Section 7.2.2. photos].

No exceptions.

preferredUsername of type DOMString

See [[POCO-SCHEMA] Section 7.2.1. preferredUsername].

No exceptions.

published of type DOMString

See [[POCO-SCHEMA] Section 7.2.1. published].

No exceptions.

relationships of type array of ContactField

See [[POCO-SCHEMA] Section 7.2.2. relationships].

No exceptions.

tags of type array of ContactField

See [[POCO-SCHEMA] Section 7.2.2. tags].

No exceptions.

updated of type DOMString

See [[POCO-SCHEMA] Section 7.2.1. updated].

No exceptions.

urls of type array of ContactField

See [[POCO-SCHEMA] Section 7.2.2. urls].

No exceptions.

utcOffset of type DOMString

See [[POCO-SCHEMA] Section 7.2.1. utcOffset].

No exceptions.

4.5 `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;
};

4.5.1 Attributes

familyName of type DOMString: See [[POCO-SCHEMA]] Section 7.3. familyName].

No exceptions.
formatted of type DOMString: See [[POCO-SCHEMA]] Section 7.3. formatted].

No exceptions.
givenName of type DOMString: See [[POCO-SCHEMA]] Section 7.3. givenName].

No exceptions.
honorificPrefix of type DOMString: See [[POCO-SCHEMA]] Section 7.3. honorificPrefix].

No exceptions.
honorificSuffix of type DOMString: See [[POCO-SCHEMA]] Section 7.3. honorificSuffix].

No exceptions.
middleName of type DOMString: See [[POCO-SCHEMA]] Section 7.3. middleName].

No exceptions.

4.6 `ContactField` interface

The ContactField interface is a reusable component that is used to support contact fields within the ContactProperties interface.

[NoInterfaceObject]
interface ContactField {
    attribute DOMString type;
    attribute DOMString value;
    attribute boolean   primary;
};

4.6.1 Attributes

primary of type boolean: See [[POCO-SCHEMA]] Section 7.2.2. primary].

No exceptions.
type of type DOMString: See [[POCO-SCHEMA]] Section 7.2.2. type].

No exceptions.
value of type DOMString: See [[POCO-SCHEMA]] Section 7.2.2. value].

No exceptions.

4.7 `ContactAddress` interface

The ContactAddress interface is a reusable component that is used to support contact addresses within the ContactProperties interface.

[NoInterfaceObject]
interface ContactAddress {
    attribute DOMString formatted;
    attribute DOMString streetAddress;
    attribute DOMString locality;
    attribute DOMString region;
    attribute DOMString postalCode;
    attribute DOMString country;
};

4.7.1 Attributes

country of type DOMString: See [[POCO-SCHEMA]] Section 7.4. country].

No exceptions.
formatted of type DOMString: See [[POCO-SCHEMA]] Section 7.4. formatted].

No exceptions.
locality of type DOMString: See [[POCO-SCHEMA]] Section 7.4. locality].

No exceptions.
postalCode of type DOMString: See [[POCO-SCHEMA]] Section 7.4. postalCode].

No exceptions.
region of type DOMString: See [[POCO-SCHEMA]] Section 7.4. region].

No exceptions.
streetAddress of type DOMString: See [[POCO-SCHEMA]] Section 7.4. streetAddress].

No exceptions.

4.8 `ContactOrganization` interface

The ContactOrganization interface is a reusable component that is used to support contact organizations within the ContactProperties interface.

[NoInterfaceObject]
interface ContactOrganization {
    attribute DOMString name;
    attribute DOMString department;
    attribute DOMString title;
    attribute DOMString startDate;
    attribute DOMString endDate;
    attribute DOMString location;
    attribute DOMString description;
};

4.8.1 Attributes

department of type DOMString: See [[POCO-SCHEMA]] Section 7.5. department].

No exceptions.
description of type DOMString: See [[POCO-SCHEMA]] Section 7.5. description].

No exceptions.
endDate of type DOMString: See [[POCO-SCHEMA]] Section 7.5. endDate].

No exceptions.
location of type DOMString: See [[POCO-SCHEMA]] Section 7.5. location].

No exceptions.
name of type DOMString: See [[POCO-SCHEMA]] Section 7.5. name].

No exceptions.
startDate of type DOMString: See [[POCO-SCHEMA]] Section 7.5. startDate].

No exceptions.
title of type DOMString: See [[POCO-SCHEMA]] Section 7.5. title].

No exceptions.

4.9 `ContactAccount` interface

The ContactAccount interface is a reusable component that is used to support contact accounts within the ContactProperties interface.

[NoInterfaceObject]
interface ContactAccount {
    attribute DOMString domain;
    attribute DOMString username;
    attribute DOMString userid;
};

4.9.1 Attributes

domain of type DOMString: See [[POCO-SCHEMA]] Section 7.6. domain].

No exceptions.
userid of type DOMString: See [[POCO-SCHEMA]] Section 7.6. userid].

No exceptions.
username of type DOMString: See [[POCO-SCHEMA]] Section 7.6. username].

No exceptions.

4.10 `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 String?         filter;
    attribute boolean?        multiple;
    attribute unsigned short? limit;
    attribute DOMString       updatedSince;
};

4.10.1 Attributes

filter of type String, nullable

A DOMString-based search filter with which to search and intially filter the Contacts database.

No exceptions.

limit of type unsigned short, nullable

The maximum number of results to return from the contacts search.

This parameter only applies in the case that the associated multiple attribute is equal to true.

If no value is provided, the search will return all Contact object results.

No exceptions.

multiple of type boolean, nullable

A boolean value to indicate whether multiple Contact objects are returnable as part of the associated Contacts find() operation.

No exceptions.

updatedSince of type DOMString

Return only contact records that have been updated on or after the given time, specified as an xs:dateTime.

This filter is based on the updated field as defined in ContactProperties.

No exceptions.

4.11 `ContactFindSuccessCB` interface

[Callback=FunctionOnly, NoInterfaceObject]
interface ContactFindSuccessCB {
    void onSuccess (in Contact[] contactObjs);
};

4.11.1 Methods

onSuccess

Parameter	Type	Nullable	Optional	Description
contactObjs	`Contact[]`	✘	✘	The Contact objects resulting from the given `Contacts` find() method. `Contacts` find()

No exceptions.

Return type: void

4.12 `ContactSuccessCB` interface

[Callback=FunctionOnly, NoInterfaceObject]
interface ContactSuccessCB {
    void onSuccess (in Contact contactObj);
};

4.12.1 Methods

onSuccess

Parameter	Type	Nullable	Optional	Description
contactObj	`Contact`	✘	✘	The Contact object resulting from the given `Contact` save() or `Contact` remove() method.

No exceptions.

Return type: void

4.13 `ContactErrorCB` interface

[Callback=FunctionOnly, NoInterfaceObject]
interface ContactErrorCB {
    void onError (in ContactError error);
};

4.13.1 Methods

onError

Parameter	Type	Nullable	Optional	Description
error	`ContactError`	✘	✘	The Contact API related error object.

No exceptions.

Return type: void

4.14 `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 NOT_FOUND_ERROR = 2;
    const unsigned short TIMEOUT_ERROR = 3;
    const unsigned short PENDING_OPERATION_ERROR = 4;
    const unsigned short IO_ERROR = 5;
    const unsigned short NOT_SUPPORTED_ERROR = 6;
    const unsigned short PERMISSION_DENIED_ERROR = 20;
    readonly attribute unsigned short code;
};

4.14.1 Attributes

code of type unsigned short, readonly: An error code assigned by an implementation when an error has occurred in Contacts API processing.
No exceptions.

4.14.2 Constants

INVALID_ARGUMENT_ERROR of type unsigned short: An invalid parameter was provided when the requested method was invoked.
IO_ERROR of type unsigned short: An error occurred in communication with the underlying implementation that meant the requested method could not complete.
NOT_FOUND_ERROR of type unsigned short: If no response information can be provided from the requested method.
NOT_SUPPORTED_ERROR of type unsigned short: The requested method is not supported by the current implementation.
PENDING_OPERATION_ERROR of type unsigned short: If the user agent is currently waiting for a callback on a current find(), save() or remove() operation, as defined in this specification.
PERMISSION_DENIED_ERROR of type unsigned short: Access to the requested method was denied at the implementation or by the user.
TIMEOUT_ERROR of type unsigned short: The requested method timed out before it could be completed.
UNKNOWN_ERROR of type unsigned short: An unknown error occurred.

5. Contact Search Processing

The Contacts find() method provides an operation to search for one of more Contact objects within the Contacts database.

5.1 Search Qualifiers

The search qualifier provides an application with a way to request the specific subset of ContactProperties 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 ContactProperties 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 ContactProperties within any resulting Contact object(s).

If a specific search qualifier element provided, or filter[x], does not match any well-known ContactProperties attribute, filter[x] should be ignored when executing the current Contacts find() operation.

5.1.1 Complex Search Qualifiers

Certain ContactProperties attributes can be considered complex by the fact that the information they contain is available only through child DOMString-based attributes of a complex Object object.

In such cases, a requesting application must be able to request both the full complex ContactProperties attribute and also be able to request individual parts of a complex ContactProperties attribute in the search qualifier provided to a Contacts find() operation.

For example, the name attribute of ContactProperties is defined to be of complex type ContactName. Therefore, a requesting application may request either the full complex attribute (i.e. name) or specific individual attributes of this complex 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 complex ContactProperties attribute is defined as a sequence or array of complex objects, specific individual attributes can be referenced by using the complex attribute name, a dot (.) character and the individual attribute to be retrieved.

For example, the addresses attribute of ContactProperties allows multiple ContactAddress objects to be defined. To request individual attributes of this complex attribute an application would request e.g. addresses.locality, addresses.region, etc.

5.1.2 Search Qualifier Example

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:

Return only the valid ContactProperties requested in the provided search qualifier (name, emails.value - friends is not a valid ContactProperties attribute so ignore this element).

5.2 Options Processing

5.2.1 Search Cardinality

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 ContactFindSuccessCB 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 ContactFindSuccessCB callback function.

An implementation must specify a suitable integer-based upper cardinality limit to limit the maximum number of Contact objects that may be returned in the case that the multiple flag is true and the limit flag is out of bounds.

If a ContactFindOptions object is provided to the Contacts find() operation and its limit attribute is greater than zero and less than or equal to the implementation's upper cardinality limit, then [X] must be set to the provided limit value.

The limit attribute is out of bounds if a ContactFindOptions object is provided to the Contacts find() operation and its limit attribute is less than or equal to zero or greater than the implementation's upper cardinality limit. In this case [X] must be set to the implementation's upper cardinality limit.

5.2.2 Search Sorting

The Contacts find() operation must return successful callback results according to the sorting guidelines defined in this section.

A search weight is a numeric value defined for each attribute in a Contact object. A lower value denotes a higher placing in the ultimate sorting of Contacts find() results. Search weights for each ContactProperties field are defined in Appendix B.

For example, if a search filter of 'Bob' matches to name.givenName in Object A and to displayName in Object B, Object B will be the first result object returned from the successCB of the given Contacts find() operation, followed by Object A.

Include UNICODE guidelines for intra-attribute sorting of results (where multiple Contact objects match on the same attribute)... [UNICODE] DUCET

5.2.3 Search Filters

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 all the fields of a 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 a ContactProperties 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 ContactFindSuccessCB.

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.

Let contactsets be initially the set of all known contacts in the Contacts database.

Let contactsresult be initially an empty Object object.

If filter is a DOMString object

Let contactset be the next enumerable Object in contactsets. If there is no next enumerable Object, go to step 5.
Let partialMatchFound be the result of applying the partial matching algorithm, providing filter and contactset as inputs.
If partialMatchFound is true, add contactset to contactsresult.
Go to step 1.
Sort contactsresult according to the guidelines in Search Sorting.
Return contactsresult.

If filter is another native object type

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:

Let hasPartialMatch be initially set to false.

If contactset is an Object object

Let elementvalue be the String value of the next enumerable property in contactset. If there are no more enumerable properties, go to step 5.
Let hasPartialMatch be the boolean result for the comparison of filter with elementvalue in a compatibility caseless manner and with a partial value match policy applied to both sides of the comparison operation.
If hasPartialMatch is true, go to step 5.
Go to step 1.
Return hasPartialMatch.

If contactset is another native object type

Return false.

5.2.3.1 Search Filter Example

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:

Using ECMA-262 3rd Edition regular expression syntax and psuedo-code, the search filter provided can be represented as:

      ( displayName = /∧.*Robert.*$/i ) ∪ ( name.formatted = /∧.*Robert.*$/i ) ∪ ( nickname = /∧.*Robert.*$/i ) 
        ∪ ( tags.value = /∧.*Robert.*$/i ) ∪ ( phoneNumbers.value = /∧.*Robert.*$/i )  ∪ ( addresses.formatted = /∧.*Robert.*$/i ) 
          ∪ ... etc for all contact attributes and properties ...

Return only the valid ContactProperties 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.

A. User Interaction Guidelines

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, saved or removed from their unified address book. This annex provides some examples of a conformant user experience that this specification enables.

A.1 Sharing Contact Information

A website requests access to a user's address book with the following code:

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'}
                               );

As a result of executing this code, the user agent may provide a non-blocking contact search notification as follows:

Contact Search Notification
(View as PNG)

If an additional find(), save() or remove() 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 the user clicks 'Cancel', the ContactErrorCB defined for the 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, utilising all of the parameters provided in the find() operation as follows:

Contact Picker
(View as PNG)

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 the user clicks 'Cancel', the ContactErrorCB associated to the current find() operation will be invoked with an error code of PERMISSION_DENIED_ERROR.

If the user clicks 'Select', the ContactFindSuccessCB 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.

Include permission review/revocation mockup?

A.2 Contact Writebacks

A.2.1 Saving a Contact to the Address Book

Include Contact creation/modification writeback mockup.

A.2.2 Removing a Contact from the Address Book

Include Contact deletion writeback mockup.

B. Search Weights

The following table defines the search weight values for each search qualifier provided in this specification.

Search Qualifier	Search Weight
`displayName`	1
`name.formatted`	2
`nickname`	3
`tags.value`	4
`phoneNumbers.value`	5
`addresses.formatted`	6
`organizations.name`	7
`emails.value`	8
`ims.value`	9
`preferredUsername`	10
`name.familyName`	11
`name.givenName`	12
`name.middleName`	13
`addresses.country`	14
`addresses.region`	15
`addresses.streetAddress`	16
`addresses.locality`	17
`addresses.postalCode`	18
`organizations.department`	19
`organizations.title`	20
`organizations.startDate`	21
`organizations.endDate`	22
`organizations.location`	23
`organizations.description`	24
`accounts.domain`	25
`accounts.userid`	26
`accounts.username`	27
`photos.value`	28
`relationships.value`	29
`urls.value`	30
`gender`	31
`birthday`	32
`anniversary`	33
`published`	34
`updated`	35
`utcOffset`	36
`notes`	37
`name.honorificPrefix`	38
`name.honorificSuffix`	39
`phoneNumbers.type`	40
`addresses.type`	41
`emails.type`	42
`ims.type`	43
`tags.type`	44
`photos.type`	45
`relationships.type`	46
`urls.type`	47
`connected`	48
`id`	49
`phoneNumbers.primary`	n/a (boolean attribute)
`addresses.primary`	n/a (boolean attribute)
`emails.primary`	n/a (boolean attribute)
`ims.primary`	n/a (boolean attribute)
`tags.primary`	n/a (boolean attribute)
`photos.primary`	n/a (boolean attribute)
`relationships.primary`	n/a (boolean attribute)
`urls.primary`	n/a (boolean attribute)
`phoneNumbers`	n/a (complex attribute)
`addresses`	n/a (complex attribute)
`emails`	n/a (complex attribute)
`ims`	n/a (complex attribute)
`photos`	n/a (complex attribute)
`tags`	n/a (complex attribute)
`relationships`	n/a (complex attribute)
`urls`	n/a (complex attribute)

C. References

C.1 Normative references

[CORE-DEVICE]: Robin Berjon. Core Device Interfaces. 02 December 2009. W3C Editor's Draft. (Work in progress.) URL: http://dev.w3.org/2009/dap/device/
[POCO-SCHEMA]: Joseph Smarr. Portable Contacts 1.0 Draft C: Contact Schema 5 August 2008. URL: http://portablecontacts.net/draft-spec.html#schema
[RFC2119]: S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[UNICODE]: The Unicode Consortium. The Unicode Standard. 2003. Defined by: The Unicode Standard, Version 4.0 (Boston, MA, Addison-Wesley, ISBN 0-321-18578-1), as updated from time to time by the publication of new versions URL: http://www.unicode.org/unicode/standard/versions/enumeratedversions.html
[WEBIDL]: Cameron McCormack. Web IDL. 19 December 2008. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2008/WD-WebIDL-20081219

C.2 Informative references

[HTML5]: Ian Hickson; David Hyatt. HTML 5. 4 March 2010. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2010/WD-html5-20100304/

Contacts API

W3C Working Draft 01 July 2010

Abstract

Status of This Document

Table of Contents

1. Conformance

2. Introduction

2.1 Usage Examples

3. Security and Privacy Considerations

3.1 Privacy considerations for implementors of the Contacts API

3.2 Privacy considerations for recipients of contact information

3.3 Additional implementation considerations

4. API Description

4.1 ServiceContacts interface

4.1.1 Attributes

4.2 Contacts interface

4.2.1 Methods

4.3 Contact interface

4.3.1 Attributes

4.3.2 Methods

4.4 ContactProperties interface

4.4.1 Attributes

4.5 ContactName interface

4.5.1 Attributes

4.6 ContactField interface

4.6.1 Attributes

4.7 ContactAddress interface

4.7.1 Attributes

4.8 ContactOrganization interface

4.8.1 Attributes

4.9 ContactAccount interface

4.9.1 Attributes

4.10 ContactFindOptions interface

4.10.1 Attributes

4.11 ContactFindSuccessCB interface

4.11.1 Methods

4.12 ContactSuccessCB interface

4.12.1 Methods

4.13 ContactErrorCB interface

4.13.1 Methods

4.14 ContactError interface

4.14.1 Attributes

4.14.2 Constants

5. Contact Search Processing

5.1 Search Qualifiers

5.1.1 Complex Search Qualifiers

5.1.2 Search Qualifier Example

5.2 Options Processing

5.2.1 Search Cardinality

5.2.2 Search Sorting

5.2.3 Search Filters

5.2.3.1 Search Filter Example

A. User Interaction Guidelines

A.1 Sharing Contact Information

A.2 Contact Writebacks

A.2.1 Saving a Contact to the Address Book

A.2.2 Removing a Contact from the Address Book

B. Search Weights

C. References

C.1 Normative references

C.2 Informative references

4.1 `ServiceContacts` interface

4.2 `Contacts` interface

4.3 `Contact` interface

4.4 `ContactProperties` interface

4.5 `ContactName` interface

4.6 `ContactField` interface

4.7 `ContactAddress` interface

4.8 `ContactOrganization` interface

4.9 `ContactAccount` interface

4.10 `ContactFindOptions` interface

4.11 `ContactFindSuccessCB` interface

4.12 `ContactSuccessCB` interface

4.13 `ContactErrorCB` interface

4.14 `ContactError` interface