W3C

Contacts Manager API

W3C Working Draft 7 March 2013

This version:
http://www.w3.org/TR/2013/WD-contacts-manager-api-20130307/
Latest published version:
http://www.w3.org/TR/contacts-manager-api/
Latest editor's draft:
http://sysapps.github.com/sysapps/proposals/Contacts/Contacts.html
Editors:
Eduardo Fullea, Telefonica
Jose M. Cantera, Telefonica
Christophe Dumez, Samsung Electronics, Co., Ltd

Copyright © 2013 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.

Abstract

This specification defines a System Level API which offers a simple interface to manage user's contacts stored in the system's address book. A typical use case of the Contacts API is the implementation of an application to manage said 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 defines a System Level API to manage the user's contacts that are stored in the system's address book. Future versions of this specification are expected to align the contact data model with the Contacts API being defined by the Device APIs Working Group.

This document was published by the System Applications Working Group as a First Public 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-sysapps@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.

Table of Contents

1. Introduction

This section is non-normative.

The Contacts API allows applications to provide the functionality of a usual an application to manage an address book, thus allowing the display and management (create, edit, remove, etc.) of contacts.

An example of use is provided below:

Example 1 
var contact = new Contact();
contact.givenName[0] = 'John'
contact.familyName[0] = 'Doe'
var mobilephone = new contactField();
mobilephone.value = '+34698765432'
mobilephone.type[0] = 'PREF'
contact.tel[0] = mobilephone
var request = navigator.contacts.save(contact);
request.onsuccess = function() { 
            window.console.log('Contact saved!'); 
}
request.onerror = function(e) {
        window.console.error(e);
}

2. 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.

3. Terminology

The EventHandler interface represents a callback used for event handlers as defined in [HTML5].

The concepts queue a task and fire a simple event are defined in [HTML5].

The terms event handler and event handler event types are defined in [HTML5].

4. Security and privacy considerations

This API must be only exposed to trusted content

6. ContactsManager Interface

The ContactsManager interface exposes the contacts management functionality.

[NoInterfaceObject]
interface ContactsManager : EventTarget {
    ContactsRequest find (ContactFindOptions options);
    ContactsRequest clear ();
    ContactsRequest save (Contact contact);
    ContactsRequest remove (Contact contact);
             attribute EventHandler oncontactschange;
};

6.1 Attributes

oncontactschange of type EventHandler
May be used to set an event handler to be called when contacts are added, deleted or changed in some way.

6.2 Methods

clear
This method allows to remove all contacts in the address book.
No parameters.
Return type: ContactsRequest
find
This method allows to instantiate a new ContactsRequest object intended to search contacts within the address book that match the criteria indicated in the options parameter.
Parameter Type Nullable Optional Description
options ContactFindOptions ✘ ✘ Set of criteria that a contact needs to match to be included in the outcomes of the find operation.
Return type: ContactsRequest
remove
This method allows to remove a contact from the address book.
Parameter Type Nullable Optional Description
contact Contact ✘ ✘ The Contact object that is requested to be removed from the address book.
Return type: ContactsRequest
save
This method allows to save a contact in the address book, e.g. an existing contact after having been edited. So if a contact with the same identifier, i.e. id, already exists in the address book, it will be updated.
Parameter Type Nullable Optional Description
contact Contact ✘ ✘ The Contact object that is requested to be saved in the address book.
Return type: ContactsRequest

The find method when invoked MUST run the following steps:

  1. Make a request to the system to retrieve the contacts in the address book matching with the criteria indicated in the options parameter.
  2. Create a new ContactsRequest object and set readyState of the ContactsRequest object to 'processing' and return the ContactsRequest to the caller
  3. If there is an error invoke the onerror event handler of the ContactsRequest object
  4. When the request has been completed:
    1. set the readyState of the ContactsRequest object to 'done'
    2. set the result of the ContactsRequest object to array of Contact objects returned by the system.
    3. invoke the onsuccess event handler of the ContactsRequest

The clear method when invoked MUST run the following steps:

  1. Make a request to the system to clear all the contacts in the address book.
  2. Create a new ContactsRequest object and set readyState of the ContactsRequest object to 'processing' and return the ContactsRequest to the caller
  3. If there is an error invoke the onerror event handler of the ContactsRequest object
  4. When the request has been completed:
    1. set the readyState of the ContactsRequest object to 'done'
    2. set the result of the ContactsRequest object to 'true'
    3. invoke the onsuccess event handler of the ContactsRequest

The save method when invoked MUST run the following steps:

  1. Make a request to the system to save the Contact object passed as parameter in the address book.
  2. Create a new ContactsRequest object and set readyState of the ContactsRequest object to 'processing' and return the ContactsRequest to the caller
  3. If there is an error invoke the onerror event handler of the ContactsRequest object
  4. When the request has been completed:
    1. set the readyState of the ContactsRequest object to 'done'
    2. set the result of the ContactsRequest object to the saved Contact object as returned by the system, and which therefore includes the id, published and updated parameters, which could be not present in the original Contact object passed as parameter, for instance if it is a brand new Contact object not yet stored in the address book
    3. invoke the onsuccess event handler of the ContactsRequest

The remove method when invoked MUST run the following steps:

  1. Make a request to the system to remove the Contact object passed as parameter from the address book.
  2. Create a new ContactsRequest object and set readyState of the ContactsRequest object to 'processing' and return the ContactsRequest to the caller
  3. If there is an error invoke the onerror event handler of the ContactsRequest object
  4. When the request has been completed:
    1. set the readyState of the ContactsRequest object to 'done'
    2. set the result of the ContactsRequest object to 'true'
    3. invoke the onsuccess event handler of the ContactsRequest

Upon a change in a contact or set thereof is performed (i.e. contact(s) added / modified / removed) the system MUST fire a simple event named contactschange that implements the ContactsChangeEvent interface at the ContactsManager object

6.3 Event handlers

The following are the event handlers (and their corresponding event handler event types) that MUST be supported as attributes by the ContactsManager object:

event handler event handler event type
oncontactschange contactschange

The event named contactschange MUST implement the ContactsChangeEvent interface.

7. ContactFindOptions Interface

The ContactFindOptions interface represents the criteria used to select the contacts to be returned by a find operation.

[NoInterfaceObject]
interface ContactFindOptions {
             attribute DOMString     filterValue;
             attribute DOMString     filterOp;
             attribute DOMString[]   filterBy;
             attribute DOMString     sortBy;
             attribute DOMString     sortOrder;
             attribute unsigned long filterLimit;
};

7.1 Attributes

filterBy of type array of DOMString
Represents the set of fields in which the search is performed (e.g. "givenName").
filterLimit of type unsigned long
Represents the maximum number of results that can be returned by the search operation.
filterOp of type DOMString
Represents the filtering operator used for the filtering (e.g. "contains").
filterValue of type DOMString
Represents the value used for the filtering (e.g. "Tom").
sortBy of type DOMString
Represents the field by which the results of the search are sorted (e.g. "givenName").
sortOrder of type DOMString
Represents the order in which the results of the search are sorted (e.g. "descending").
Issue 1

It is for further study whether the level of flexibility of the filters needs to be increased and/or additional mechanisms need to be put in place so that applications can keep a local copy of the address book and perform the filtering locally (e.g. startTrackingChanges() and getNewChanges() methods)

8. ContactField Interface

The ContactField interface represents a user's contact address and the type associated to it.

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

8.1 Attributes

type of type array of DOMString
Indicates whether it is a preferred address ("PREF") and the type of contact address (e.g. "home", "work"). Several type attributes are possible for each single contact address.
value of type DOMString, readonly
A string that contains the user's address.

9. ContactTelField Interface

The ContactTelField interface represents a telephone number as well as metadata associated to it, namely the type of address and the carrier providing service to the telephony subscription associated to that number.

[NoInterfaceObject]
interface ContactTelField : Contact Field {
             attribute DOMString carrier;
};

9.1 Attributes

carrier of type DOMString
Indicates the carrier providing service to the telephony subscription associated to that number

10. ContactAddress Interface

The ContactAddress interface represents a user's phisical address and the type associated to it. This interface is based on vCard 4.0 ADR attribute.

[NoInterfaceObject]
interface ContactAddress {
             attribute DOMString[] type;
             attribute DOMString   streetAddress;
             attribute DOMString   locality;
             attribute DOMString   region;
             attribute DOMString   postalCode;
             attribute DOMString   countryName;
};

10.1 Attributes

countryName of type DOMString
A string that contains the name of the country. It maps to the seventh component in vCard's ADR attribute.
locality of type DOMString
A string that contains the name of the locality. It maps to the forth component in vCard's ADR attribute.
postalCode of type DOMString
A string that contains the postal code. It maps to the sixth component in vCard's ADR attribute.
region of type DOMString
A string that contains the name of the region. It maps to the fifth component in vCard's ADR attribute.
streetAddress of type DOMString
A string that contains the name of the street. It maps to the third component in vCard's ADR attribute.
type of type array of DOMString
Indicates whether it is a preferred address ("PREF") and the type of contact address (e.g. "home", "work"). Several type attributes are possible for each single contact address.

11. ContactProperties Interface

The ContactProperties interface contains all the properties associated to the contact. As a principle the attributes are based on vCard 4.0 and reuse the literal used in that standard. Any deviation is mentioned in the description of the corresponding attribute.

[NoInterfaceObject]
interface ContactProperties {
             attribute DOMString[]       name;
             attribute DOMString[]       honorificPrefix;
             attribute DOMString[]       givenName;
             attribute DOMString[]       additionalName;
             attribute DOMString[]       familyName;
             attribute DOMString[]       honorificSuffix;
             attribute DOMString[]       nickname;
             attribute ContactField[]    email;
             attribute DOMString[]       photo;
             attribute ContactField[]    url;
             attribute DOMString[]       categories;
             attribute ContactAddress[]  adr;
             attribute ContactTelField[] tel;
             attribute DOMString[]       org;
             attribute DOMString[]       jobTitle;
             attribute Date              bday;
             attribute DOMString[]       note;
             attribute ContactAddress[]  impp;
             attribute Date              anniversary;
             attribute DOMString         sex;
             attribute DOMString         genderIdentity;
};

11.1 Attributes

additionalName of type array of DOMString
A string or set thereof representing any additional name of the contact. It maps to the third component in vCard's N attribute.
adr of type array of ContactAddress
An ContactAddress element or set thereof containing the user's phisical address(es). It maps to vCard's ADR attribute
anniversary of type Date
A Date element representing the contact's anniversary. It maps to vCard's ANNIVERSARY attribute
bday of type Date
A Date element representing the contact's birth date. It maps to vCard's BDAY attribute
categories of type array of DOMString
A string or set thereof representing the category or categories associated to the contact (e.g. "family"). It maps to vCard's CATEGORIES attribute.
email of type array of ContactField
An ContactField element or set thereof containing the contact's email address(es). It maps to vCard's EMAIL attribute.
familyName of type array of DOMString
A string or set thereof representing the contact's family name(s). It maps to the first component in vCard's N attribute.
genderIdentity of type DOMString
A free text string representing the contact's gender identity. It maps to the second component of vCard's GENDER attribute.
givenName of type array of DOMString
A string or set thereof representing the contact's given name(s). It maps to the second component in vCard's N attribute.
honorificPrefix of type array of DOMString
A string or set thereof representing the contact's honorific prefix(es). It maps to the forth component in vCard's N attribute.
honorificSuffix of type array of DOMString
A string or set thereof representing the contact's honorific suffix(es). It maps to the fifth component in vCard's N attribute.
impp of type array of ContactAddress
An ContactAddress element or set thereof containing the user's instant messaging address(es). It maps to vCard's IMPP attribute
jobTitle of type array of DOMString
A string or set thereof representing the contact's job title(s). It maps to vCard's TITLE attribute
name of type array of DOMString
A string or set thereof representing the contact's display name(s). It maps to vCard's FN attribute.
nickname of type array of DOMString
A string or set thereof representing the contact's nick name(s). It maps to vCard's NICKNAME attribute.
note of type array of DOMString
A string or set thereof specifying supplemental information or a comment that is associated with the contact. It maps to vCard's NOTE attribute
org of type array of DOMString
A string or set thereof representing the organization(s) the contact belongs to. It maps to vCard's ORG attribute
photo of type array of DOMString
A string or set thereof representing the UIR of the photo(s) of the contact. It maps to vCard's PHOTO attribute.
sex of type DOMString
A string representing the contact's sex with following possible values: "M" for male, "F" for female, "O" for other, "N" for "none or not applicable" and "U" for "unknown". It maps to the first component of vCard's GENDER attribute.
tel of type array of ContactTelField
An ContactTelField element or set thereof containing the user's telephone numbers.It maps to vCard's TEL attribute
url of type array of ContactField
An ContactField element or set thereof containing the user's urls (e.g. personal blog). It maps to vCard's URL attribute.

12. Contact Interface

The Contact interface represents a contact stored in the address book.

[NoInterfaceObject]
interface Contact {
    readonly attribute DOMString id;
    readonly attribute boolean   readOnly;
    readonly attribute Date      lastUpdated;
};

12.1 Attributes

id of type DOMString, readonly
Represents a unique identifier of the contact in the address book.
lastUpdated of type Date, readonly
A Date element representing the date when the contact was last updated.
readOnly of type boolean, readonly
If set to true indicates that the contact cannot be saved to the address book, and thus it cannot be modified. This attribute can be used to mark those contacts that are synchronized from a source to which the addrwess book cannot populate changes (e.g. online services)

13. ContactsRequest Interface

The ContactsRequest interface represents an ongoing operation. It provides callbacks that are called when the operation completes, as well as a reference to the operation's result. A method that initiates an operation (e.g. remove contact via the remove method in the ContactsManager interface) may return a ContactsRequest object that can be used to monitor the progress of that operation.

[NoInterfaceObject]
interface ContactsRequest {
    readonly attribute DOMString    readyState;
    readonly attribute DOMError?    error;
    readonly attribute any?         result;
             attribute EventHandler onsuccess;
             attribute EventHandler onerror;
};

13.1 Attributes

error of type DOMError, readonly, nullable
An error that occured during the request. Errors are as defined in [DOM4].
onerror of type EventHandler
onsuccess of type EventHandler
readyState of type DOMString, readonly
Indicates the state of the request, with possible string values 'processing',if the request has been made and it is progressing, or 'done', if the request has been already completed.
result of type any, readonly, nullable
Indicates the result of the request. The type depends on the sort of request, and is specified in the description of each method that returns a ContactsRequest object, e.g. remove method of the ContactsManager object.

13.2 Event handlers

The following are the event handlers (and their corresponding event handler event types) that MUST be supported as attributes by the ContactsRequest object:

event handler event handler event type
onsuccess success
onerror error

14. ContactsChangeEvent Interface

The ContactsChangeEvent interface represents events related to the set of contacts that have been simultaneously added, removed and/or modified. Changes that are applied to the address book in batches cause a ContactsChangeEvent with multiple contact references to be fired, whereas changes applied sequentially cause a ContactsChangeEvent with a single contact reference to be fired

[NoInterfaceObject]
interface ContactsChangeEvent : Event {
    readonly attribute DOMString[] added;
    readonly attribute DOMString[] modified;
    readonly attribute DOMString[] removed;
};

14.1 Attributes

added of type array of DOMString, readonly
Indicates the identifier(s) of the Contact object(s) that have been added.
modified of type array of DOMString, readonly
Indicates the identifier(s) of the Contact object(s) that have been modified.
removed of type array of DOMString, readonly
Indicates the identifier(s) of the Contact object(s) that have been removed.

15. Acknowledgements

The editors would like to express their gratitude to the Mozilla B2G Team for their technical guidance, implementation work and support

A. References

A.1 Normative references

[DOM4]
Anne van Kesteren; Aryeh Gregor; Lachlan Hunt; Ms2ger. DOM4. 6 December 2012. W3C Working Draft. URL: http://www.w3.org/TR/2012/WD-dom-20121206/
[HTML5]
Robin Berjon et al. HTML5. 17 December 2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/html5/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[WEBIDL]
Cameron McCormack. Web IDL. 27 September 2011. W3C Working Draft. URL: http://www.w3.org/TR/2011/WD-WebIDL-20110927/