CARVIEW |
Contacts Manager API
W3C Working Group Note , edited in place
- This version:
- https://www.w3.org/TR/2015/NOTE-contacts-manager-api-20150602/
- Latest published version:
- https://www.w3.org/TR/contacts-manager-api/
- Previous version:
- https://www.w3.org/TR/2013/WD-contacts-manager-api-20130307/
- Latest editor's draft:
- https://www.w3.org/2012/sysapps/contacts-manager-api/
- Editors:
- Eduardo Fullea, Telefonica
- Jose M. Cantera, Telefonica
- Christophe Dumez, Samsung Electronics, Co., Ltd
This document includes material copied from the W3C Editor's Draft of the Contacts Manager API from 04 April 2014. Copyright © 2015 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and permissive document license 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
Status Update (23 January 2023): Retired Note CSS was applied. In the Status of This Document, a link to Contact Picker API was added for further technical work.
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 https://www.w3.org/TR/.
🚩
This document is retired and MUST NOT be used for further technical work.
See the Contact Picker API instead and raise issues in the w3c/contact-picker repository.
🚩 Retired document. Do not use.
This document defines a System Level API to manage the user's contacts that are stored in the system's address book.
If you find any issue with this specification, please file a bug on Github.
This document was produced by the System Applications Working Group. Members of this Working Group have agreed not to progress the Contacts Manager API specification further as a Recommendation track document, electing instead to publish it as an informative Working Group Note under a permissive license with a view to enabling it to form the basis of further work by others, e.g. in a W3C Community Group.
This document was published by the System Applications Working Group as a Working Group Note. If you wish to make comments regarding this document, please send them to public-sysapps@w3.org (subscribe, archives). All comments are welcome.
W3C makes this document available under the terms of the W3C Software and Document License pursuant to W3C's policy for Relicensing Unfinished W3C Specifications. Publication as a Working Group Note 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.
This document is governed by the 1 August 2014 W3C Process Document.
Table of Contents
- 1. Introduction
- 2. Conformance
- 3. Terminology
- 4. Security and privacy considerations
- 5.
Navigator
Interface - 6.
ContactsManager
Interface - 7.
ContactFindOptions
Dictionary - 8.
ContactField
Interface - 9.
ContactTelField
Interface - 10.
ContactAddress
Interface - 11. The
ContactGender
enum - 12.
ContactName
Interface - 13.
Contact
Interface - 14.
ContactsChangeEvent
Interface - 15. Acknowledgements
- A. References
1. Introduction
This section is non-normative.
The Contacts API allows to manage (create, edit, remove, etc) user's contacts stored in the system's address book, and thus provides the functionality needed to implement an application to manage said address book.
An example of use is provided below:
var contactName = new ContactName({ givenNames: ['John'], familyNames: ['Doe'] }); var mobilePhone = new ContactTelField({ types: ['home'], preferred: true, value: '+34698765432' }); var contact = new Contact({ name: contactName, phoneNumbers: [mobilePhone] }); navigator.contacts.save(contact).then( function(contact) { window.console.log('Contact ' + contact.name.givenNames[0] + ' ' + contact.name.familyNames[0] + ' saved!'); }, function(error) { window.console.error('Error: ' + error); } )
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 word MUST is 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].
The Promise interface, the concepts of a resolver, a resolver's fulfill algorithm and a resolver's reject algorithm are defined in ECMAScript 6 (ECMA-262).
4. Security and privacy considerations
This API must be only exposed to trusted content
5. Navigator
Interface
partial interface Navigator {
readonly attribute ContactsManager
contacts;
};
5.1 Attributes
contacts
of typeContactsManager
, readonly- The object that exposes the contacts management functionality.
6. ContactsManager
Interface
The ContactsManager
interface exposes the contacts management
functionality.
interface ContactsManager : EventTarget {
Promise find (optional ContactFindOptions
options);
Promise clear ();
Promise save (Contact
contact);
Promise remove (DOMString contactId);
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.
It returns a
Promise
that will allow the caller to be notified about the result of the operation.No parameters.Return type:Promise
find
- This method allows to search contacts within the address book that
match the criteria indicated in the
options
parameter. It returns aPromise
that will allow the caller to be notified about the result of the operation.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:Promise
remove
- This method allows to remove a contact from the address book.
It returns a
Promise
that will allow the caller to be notified about the result of the operation.Parameter Type Nullable Optional Description contactId DOMString
✘ ✘ The identifier of the Contact
object that is requested to be removed from the address book.Return type:Promise
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. It returns aPromise
that will allow the caller to be notified about the result of the operation.Parameter Type Nullable Optional Description contact Contact
✘ ✘ The Contact
object that is requested to be saved in the address book.Return type:Promise
The find
method when invoked MUST run the
following steps:
- Let promise be a new
Promise
object and resolver its associated resolver. - Return promise and continue the following steps asynchronously.
- Make a request to the system to retrieve the contacts in the
address book matching the criteria indicated in the
options
parameter. - If there is an error invoke resolver's reject algorithm with no argument and terminate these steps.
- When the request has been completed:
- Let contacts be a new array of
Contact
objects providing the results of the find operation. - Invoke resolver's fulfill algorithm with
contacts as the
value
argument.
- Let contacts be a new array of
The clear
method when invoked MUST run the
following steps:
- Let promise be a new
Promise
object and resolver its associated resolver. - Return promise and continue the following steps asynchronously.
- Make a request to the system to clear all the contacts in the address book.
- If there is an error invoke resolver's reject algorithm with no argument and terminate these steps.
- When the request has been completed invoke resolver's fulfill algorithm with no argument and terminate these steps.
The save
method when invoked MUST run the
following steps:
- Let promise be a new
Promise
object and resolver its associated resolver. - Return promise and continue the following steps asynchronously.
- Make a request to the system to save in the address book the
Contact
object passed as parameter. - If there is an error invoke resolver's reject algorithm with no argument and terminate these steps.
- When the request has been completed:
- Let contact be the
Contact
object as returned by the system, and which therefore has itsid
andlastUpdated
parameters set, whereas they could be null in the originalContact
object passed as parameter, for instance if it is a brand newContact
object not yet stored in the address book. - Invoke resolver's fulfill algorithm with
contact as the
value
argument.
- Let contact be the
The remove
method when invoked MUST run the
following steps:
- Let promise be a new
Promise
object and resolver its associated resolver. - Return promise and continue the following steps asynchronously.
- Make a request to the system to remove the
Contact
object identified by thecontactId
passed as parameter from the address book. - If there is an error invoke resolver's reject algorithm with no argument and terminate these steps.
- When the request has been completed invoke resolver's fulfill algorithm with no argument and terminate these steps.
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
that implements the
contactschange
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
MUST implement the
contactschange
ContactsChangeEvent
interface.
7. ContactFindOptions
Dictionary
The ContactFindOptions
dictionary represents the criteria used
to select the contacts to be returned by a find
operation.
dictionary ContactFindOptions {
DOMString value;
FilterOperator
operator;
sequence<DOMString> fields;
sequence<DOMString> sortBy;
SortOrder
sortOrder;
unsigned long resultsLimit;
};
7.1 Dictionary ContactFindOptions
Members
fields
of type sequence<DOMString>,- Represents the set of fields in which the search is performed (e.g. "givenName").
operator
of typeFilterOperator
,- Represents the filtering operator used for the filtering.
resultsLimit
of type unsigned long,- Represents the maximum number of results that can be returned by the search operation.
sortBy
of type sequence<DOMString>,- Represents the fields by which the results of the search are sorted (e.g. ["givenNames", "familyNames"]). The results are sorted by the first field, then by the following one, if present, and so on.
sortOrder
of typeSortOrder
,- Represents the order in which the results of the search are sorted.
value
of type DOMString,- Represents the value used for the filtering (e.g. "Tom").
7.2 Enumerations
There are 2 possible filter operations:
enum FilterOperator {
"contains",
"is"
};
Enumeration description | |
---|---|
contains | With this operation, a contact will be returned if its filtered field contains the given value. |
is | With this operation, a contact will be returned if its filtered field matches exactly the given value. |
The returned contacts can be sorted in one of the following orders:
enum SortOrder {
"ascending",
"descending"
};
Enumeration description | |
---|---|
ascending | The contacts will be sorted in ascending order. |
descending | The contacts will be sorted in descending order. |
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 attribute and the
types associated to it.
[Constructor(optional ContactFieldInit initDict)]
interface ContactField {
attribute DOMString[] types;
attribute boolean preferred;
attribute DOMString value;
};
8.1 Attributes
preferred
of type boolean,- Indicates whether this is the preferred contact field.
types
of type array of DOMString,- Indicates the types of this contact field (e.g. "home", "work").
value
of type DOMString,- A string that contains the user's address.
8.2 ContactFieldInit
Dictionary
dictionary ContactFieldInit {
sequence<DOMString> types;
boolean preferred;
DOMString value;
};
8.2.1 Dictionary ContactFieldInit
Members
preferred
of type boolean,types
of type sequence<DOMString>,value
of type DOMString,
9. ContactTelField
Interface
The ContactTelField
interface represents a telephone number as
well as metadata associated to it, namely the types (e.g. "voice", "text")
and the carrier providing service to the telephony subscription associated
to that number.
[Constructor(optional ContactTelFieldInit initDict)]
interface ContactTelField : ContactField
{
attribute DOMString? carrier;
};
9.1 Attributes
carrier
of type DOMString, , nullable- Indicates the carrier providing service to the telephony subscription associated to that number
9.2 ContactTelFieldInit
Dictionary
dictionary ContactTelFieldInit : ContactFieldInit
{
DOMString carrier;
};
9.2.1 Dictionary ContactTelFieldInit
Members
carrier
of type DOMString,
10. ContactAddress
Interface
The ContactAddress
interface represents a user's physical
address and the types associated to it. This interface is based on vCard 4.0 ADR attribute.
[Constructor(optional ContactAddressInit initDict)]
interface ContactAddress {
attribute DOMString[] types;
attribute boolean preferred;
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.
preferred
of type boolean,- Indicates whether this is the preferred contact field.
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.
types
of type array of DOMString,- Indicates the types of this contact field (e.g. "home", "work").
10.2 ContactAddressInit
Dictionary
dictionary ContactAddressInit {
sequence<DOMString> types;
boolean preferred;
DOMString streetAddress;
DOMString locality;
DOMString region;
DOMString postalCode;
DOMString countryName;
};
10.2.1 Dictionary ContactAddressInit
Members
countryName
of type DOMString,locality
of type DOMString,postalCode
of type DOMString,preferred
of type boolean,region
of type DOMString,streetAddress
of type DOMString,types
of type sequence<DOMString>,
11. The ContactGender
enum
enum ContactGender {
"male",
"female",
"other",
"none",
"unknown"
};
Enumeration description | |
---|---|
male | contact is a male. |
female | contact is a female. |
other | contact has another gender. |
none | contact does not have a gender (not applicable). |
unknown | contact's gender is unknown. |
12. ContactName
Interface
The ContactName
interface represents a user's naming attributes.
[Constructor(optional ContactNameInit initDict)]
interface ContactName {
attribute DOMString displayName;
attribute DOMString[] honorificPrefixes;
attribute DOMString[] givenNames;
attribute DOMString[] additionalNames;
attribute DOMString[] familyNames;
attribute DOMString[] honorificSuffixes;
attribute DOMString[] nicknames;
};
12.1 Attributes
additionalNames
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.
displayName
of type DOMString,- A string representing the contact's display name. It maps to vCard's FN attribute.
familyNames
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.
givenNames
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.
honorificPrefixes
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.
honorificSuffixes
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.
nicknames
of type array of DOMString,- A string or set thereof representing the contact's nick name(s). It maps to vCard's NICKNAME attribute.
12.2 ContactNameInit
Dictionary
dictionary ContactNameInit {
DOMString displayName;
sequence<DOMString> honorificPrefixes;
sequence<DOMString> givenNames;
sequence<DOMString> additionalNames;
sequence<DOMString> familyNames;
sequence<DOMString> honorificSuffixes;
sequence<DOMString> nicknames;
};
12.2.1 Dictionary ContactNameInit
Members
additionalNames
of type sequence<DOMString>,displayName
of type DOMString,familyNames
of type sequence<DOMString>,givenNames
of type sequence<DOMString>,honorificPrefixes
of type sequence<DOMString>,honorificSuffixes
of type sequence<DOMString>,nicknames
of type sequence<DOMString>,
13. Contact
Interface
The Contact
interface represents a contact stored in the address
book. As a principle the attributes are based on vCard 4.0 and reuse the
literal used in that standard. Any naming deviation is mentioned in the
description of the corresponding attribute. Whereas this correspondence
facilitates the import/export from/to vCard format it should be noted that
a vCard import/export API is out of scope of this specification as parsing
and serializing can be efficiently done in JavaScript, and libraries are
readily available.
[Constructor(optional ContactInit contactInitDict)]
interface Contact {
readonly attribute DOMString? id;
readonly attribute Date? lastUpdated;
attribute ContactName
name;
attribute ContactField
[] emails;
attribute DOMString[] photos;
attribute ContactField
[] urls;
attribute DOMString[] categories;
attribute ContactAddress
[] addresses;
attribute ContactTelField
[] phoneNumbers;
attribute DOMString[] organizations;
attribute DOMString[] jobTitles;
attribute Date? birthday;
attribute DOMString[] notes;
attribute ContactField
[] impp;
attribute Date? anniversary;
attribute ContactGender
gender;
};
13.1 Attributes
addresses
of type array ofContactAddress
,- A
ContactAddress
element or set thereof containing the user's physical address(es). It maps to vCard's ADR attribute anniversary
of type Date, , nullable- A
Date
element representing the contact's anniversary. It maps to vCard's ANNIVERSARY attribute birthday
of type Date, , nullable- 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.
emails
of type array ofContactField
,- A
ContactField
element or set thereof containing the contact's email address(es). It maps to vCard's EMAIL attribute. gender
of typeContactGender
,- A string representing the contact's gender. It maps to the first component of vCard's GENDER attribute.
id
of type DOMString, readonly , nullable- Represents a unique identifier of the contact in the address book.
impp
of type array ofContactField
,- A
ContactField
element or set thereof containing the user's instant messaging address(es). It maps to vCard's IMPP attribute jobTitles
of type array of DOMString,- A string or set thereof representing the contact's job title(s). It maps to vCard's TITLE attribute
lastUpdated
of type Date, readonly , nullable- A
Date
element representing the date when the contact was last updated. name
of typeContactName
,- An object representing the different naming attributes of the contact.
notes
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
organizations
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
phoneNumbers
of type array ofContactTelField
,- A
ContactTelField
element or set thereof containing the user's telephone numbers. It maps to vCard's TEL attribute photos
of type array of DOMString,- A string or set thereof representing the URI of the photo(s) of the contact. It maps to vCard's PHOTO attribute.
urls
of type array ofContactField
,- A
ContactField
element or set thereof containing the user's urls (e.g. personal blog). It maps to vCard's URL attribute.
13.2 Steps
The Contact
interface's contructor when invoked MUST run the
following steps:
- Let contact be a new
Contact
object. - Make a request to the system to generate a new unique contact identifier.
- Set the
id
attribute of contact to the generated contact identifier. - Set the
lastUpdated
attribute of contact to the Date at which the constructor was invoked. - Set the other attributes of contact to the value of the
corresponding element in the
contactInitDict
dictionary, if present.
13.3 ContactInit
Dictionary
dictionary ContactInit {
ContactName
name;
sequence<ContactField
> emails;
sequence<DOMString> photos;
sequence<ContactField
> urls;
sequence<DOMString> categories;
sequence<ContactAddress
> addresses;
sequence<ContactTelField
> phoneNumbers;
sequence<DOMString> organizations;
sequence<DOMString> jobTitles;
Date birthday;
sequence<DOMString> notes;
sequence<ContactField
> impp;
Date anniversary;
ContactGender
gender;
};
13.3.1 Dictionary ContactInit
Members
addresses
of type sequence<ContactAddress
>,anniversary
of type Date,birthday
of type Date,categories
of type sequence<DOMString>,emails
of type sequence<ContactField
>,gender
of typeContactGender
,impp
of type sequence<ContactField
>,jobTitles
of type sequence<DOMString>,name
of typeContactName
,notes
of type sequence<DOMString>,organizations
of type sequence<DOMString>,phoneNumbers
of type sequence<ContactTelField
>,photos
of type sequence<DOMString>,urls
of type sequence<ContactField
>,
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
[Constructor(DOMString type, optional ContactsChangeEventInit
eventInitDict)]
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.
14.2 ContactsChangeEventInit
Dictionary
dictionary ContactsChangeEventInit : EventInit {
sequence<DOMString> added;
sequence<DOMString> modified;
sequence<DOMString> removed;
};
14.2.1 Dictionary ContactsChangeEventInit
Members
added
of type sequence<DOMString>,modified
of type sequence<DOMString>,removed
of type sequence<DOMString>,
15. Acknowledgements
The editors would like to express their gratitude to the Mozilla B2G Team for their technical guidance, implementation work and support, and specially to Tantek Çelik and Gregor Wagner, the original authors of B2G Contact API.
A. References
A.1 Normative references
- [HTML5]
- Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Theresa O'Connor; Silvia Pfeiffer. HTML5. 28 October 2014. W3C Recommendation. URL: https://www.w3.org/TR/html5/
- [RFC2119]
- S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
- [WEBIDL]
- Cameron McCormack. Web IDL. 19 April 2012. W3C Candidate Recommendation. URL: https://www.w3.org/TR/WebIDL/
A.2 Informative references
- [DOM4]
- Anne van Kesteren; Aryeh Gregor; Ms2ger; Alex Russell; Robin Berjon. W3C DOM4. 28 April 2015. W3C Last Call Working Draft. URL: https://www.w3.org/TR/dom/