W3C

The Contacts API

W3C Working Draft 21 January 2010

This Version:
http://www.w3.org/TR/2010/WD-contacts-api-20100121/
Latest Published Version:
http://www.w3.org/TR/contacts-api/
Latest Editor's Draft:
http://dev.w3.org/2009/dap/contacts/
Editor:
Richard Tibbett, France Telecom

Abstract

This specification defines an API that provides 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 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-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.

Table of Contents

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.

2. Introduction

This section is non-normative.

The Contacts API defines a high-level interface to provide access to the user's unified contact information, such as names, addresses and other contact information.

The API itself is agnostic of any underlying address book sources and data formats.

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].name);
    // ...
}

function generalErrorCB(error) {
    // do something with resulting errors
    // alert(error.code);
    // ...
}

// Perform an address book search
navigator.service.contacts.find( {name: 'Bob'},
                                successContactFindCallback, 
                                generalErrorCB );

Creating a new contact.

// previous example follow-on...

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

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

Adding a new contact.

// previous example follow-on...

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

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

Editing an existing contact.

// previous example follow-on...

// e.g. add a new phone number
myContact.phones.push({types: ['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

This section is under development.

This section has been inspired (verbatim where necessary) from the Geolocation WG latest public working draft specification.

There are a number of reasons for this approach:

1. The programmatic styles of the Contacts API and Geolocation API are very similar and because they both have the the same implied user experience within the same implied User Agent the general security and privacy considerations of both APIs should remain common.

2. The ability to align the security and privacy considerations of the Geolocation API with DAP APIs is important for the potential future benefit of making any security and privacy mechanisms developed within the DAP WG applicable to the Geolocation API at some point in its own ongoing development.

The API defined in this specification can be used to create, retrieve, update and remove contact information from a user's address books. 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, retrieve, update 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, update 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 actual object of which the API will be hanging off is still under discussion (e.g. navigator.service vs from navigator.device); see ISSUE-67

The ServiceContacts interface is exposed on the navigator.service object, as defined in [CORE-DEVICE].

Service implements ServiceContacts;

All instances of the Service type are defined to also implement the ServiceContacts interface.

[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 a consistent categories value(s) as part of individual Contact objects. Multiple contact groups can be displayed by filtering on the required categories value(s) via the Contacts find() function.

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

4.2.1 Methods

create
Create a new Contact object.

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

ParameterTypeNullableOptionalDescription
attributesContactProperties The attributes to assign to the resulting object.
No exceptions.
Return type: Contact
find

Find contacts in the address book based on a ContactProperties object acting as a filter.

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:

  1. Search for contacts in the address book according to the contact search processing rules.
  2. 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.
ParameterTypeNullableOptionalDescription
filterContactProperties The filter used in order to select which contacts are returned.
successCBContactFindSuccessCB Function to call when the asynchronous operation completes
errorCBContactErrorCB Function to call when the asynchronous operation fails.
optionsContactOptions 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.

Each resulting Contact object must include a non-null name attribute. All other attributes may be optionally assigned a value by the user and/or implementation.

[NoInterfaceObject]
interface Contact : ContactProperties {
    readonly attribute DOMString id;
    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

Perhaps we don't want to recommend the use of UUID URN here. Saying that id must be globally unique could suffice, and there may be good reasons why someone would want to use something else (e.g. a SHA mailbox as in FOAF).

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.

An implementation may use an IANA registered identifier format. The value can also be a non-standard format.

It is recommended that an implementation assign the id attribute as a UUID URN as defined in [RFC4122].

{id: 'urn:uuid:d13d4fd0-4ce9-1cef-b1f2-10a9c1446bf0'}
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 ContactError::CONTACT_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:

  1. Remove the current object from Contacts.
  2. 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.
ParameterTypeNullableOptionalDescription
successCBContactSuccessCB Function to call when the asynchronous operation completes
errorCBContactErrorCB 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.

In the case that the name attribute is null and this method is invoked, an ContactErrorCB must be triggered as part of the save contact process. This error must consist of a ContactError object with a code of ContactError::CONTACT_INVALID_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 save contact process defined as follows:

  1. If the Contact.id already exists in Contacts then update the existing object in Contacts.
  2. If a current Contact.id value does not current exist in Contacts or the current Contact.id value has not been set, add the current object as a new object to Contacts.
  3. 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.
ParameterTypeNullableOptionalDescription
successCBContactSuccessCB Function to call when the asynchronous operation completes
errorCBContactErrorCB Function to call when the asynchronous operation fails.
No exceptions.
Return type: PendingOp

4.4 ContactProperties interface

The ContactProperties interface captures the settable properties of a contact.

ContactProperties is used as part of the Contact object. ContactProperties can also be used as the basis of the Contacts.find() searches within the address book.

Attributes of the ContactProperties interface that expect a singular value have singular spelling (e.g. name) and attributes that may have one or more values have plural spelling (e.g. phones) to make the distinction of these fields easier.

When ContactProperties is used as an input parameter to Contacts.find() methods, fields that are set to null are considered to match anything.

[NoInterfaceObject]
interface ContactProperties {
    attribute DOMString?       name;
    attribute DOMString[]      nicknames;
    attribute ContactField[]   phones;
    attribute ContactField[]   emails;
    attribute ContactAddress[] addresses;
    [PutForwards=value]
    attribute ContactField[]   impps;
    attribute DOMString?       serviceId;
    attribute DOMString[]      categories;
};

4.4.1 Attributes

addresses of type array of ContactAddress

Aligned with Geolocation v2 specification.

One or more addresses associated with the contact.

The first object in this sequence is inferred to be the user's preferred/default address.

{addresses: [{streetNumber: '123', 
              street: 'Main Street', 
              city: 'My Town', 
              region: 'CA', 
              postalCode: '91921-1234', 
              country: 'USA'}]}
No exceptions.
categories of type array of DOMString

One or more contact categories/groups to associate the contact with.

{categories: ['friends', 'w3c', 'information technology', 'engineers']}
No exceptions.
emails of type array of ContactField

One or more email addresses associated with the contact.

The first object in this sequence is inferred to be the user's preferred/default email address.

The following constants are defined for use in the types attribute for email addresses:

'home', 'work', 'personal', 'business'.

Additional values may be provided for the types attribute.

{emails: [{types: ['work'], value: 'john.q.quinlan@barfooinc.com'}, 
          {types: ['home', 'mobile'], value: 'jquinlan@mail.com'}]}
No exceptions.
impps of type array of ContactField

One or more instant messaging and presence protocol addresses associated with the contact.

The first object in this sequence is inferred to be the user's preferred/default instant messaging and presence protocol address.

The following constants are defined for use in the types attribute for instant messaging and presence protocol addresses:

'home', 'work', 'personal', 'business'.

Additional values may be provided for the types attribute.

{impps: [{types: ['work'], value:'im:jquinlan@foobarinc.com'},
         {types: ['work', 'mobile'], value:'sip:jquinlan@foobarinc.com'}]}
No exceptions.
name of type DOMString, nullable

The contact's name represented in a formatted manner

Each contact must include a non-empty name value.

{name: 'Mr. John Q. Public, Esq.'}
No exceptions.
nicknames of type array of DOMString

One or more nicknames associated with the contact

{nicknames: ['jim', 'jimmie']}
No exceptions.
phones of type array of ContactField

One or more telephone numbers associated with the contact.

The first object in this sequence is inferred to be the user's preferred/default phone number.

The following constants are defined for use in the types attribute for phone numbers:

'home', 'work', 'voice', 'fax', 'fixed', 'mobile', 'car', 'video', 'isdn', 'pager', 'modem', 'pcs'.

Additional values may be provided for the types attribute.

{phones: [{types: ['home'], value: '+442088450343'}, 
          {types: ['work'], value: '+442088450343'}] }
No exceptions.
serviceId of type DOMString, nullable

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.

It is recommended that an implementation assign the serviceId attribute as a URI.

{serviceId: 'http://foobar.com/myservices/v1/addressbook'}
No exceptions.

4.5 ContactField interface

The ContactField/Field interface is a reusable component that is used to support contact fields within the ContactProperties interface. It defines an optional types parameter that can be provided with a standard value.

[NoInterfaceObject]
interface ContactField {
    attribute sequence<DOMString>? types;
    attribute DOMString            value;
};

4.5.1 Attributes

types of type sequence<DOMString>, nullable
One or more contexts to associate with the given value.
No exceptions.
value of type DOMString
The value of the current object.
No exceptions.

4.6 ContactAddress interface

The ContactAddress interface is a reusable component that is used to support address information within the ContactProperties interface.

[NoInterfaceObject]
interface ContactAddress {
    attribute DOMString country;
    attribute DOMString region;
    attribute DOMString county;
    attribute DOMString city;
    attribute DOMString street;
    attribute DOMString streetNumber;
    attribute DOMString premises;
    attribute DOMString additionalInformation;
    attribute DOMString postalCode;
};

4.6.1 Attributes

additionalInformation of type DOMString
Additional information (e.g. floor number in a building, an apartment number, the name of an office occupant, etc) not captured in other ContactAddress properties.
No exceptions.
city of type DOMString
The city of the address.
No exceptions.
country of type DOMString
The country of the address, specified using the two-letter [ISO 3166-1] code.
No exceptions.
county of type DOMString
The name of a land area within the larger region.
No exceptions.
postalCode of type DOMString
The postal code of the address.
No exceptions.
premises of type DOMString
Details of the premises (e.g. block of flats, building name) of the address.
No exceptions.
region of type DOMString
The country subdivision (e.g state) of the address.
No exceptions.
street of type DOMString
The street of the address.
No exceptions.
streetNumber of type DOMString
The street number of the address.
No exceptions.

4.7 ContactOptions interface

Rename this to "ContactSearchFilter" or similar?

The ContactOptions interface describes the options that can be applied to contact searching.

[NoInterfaceObject]
interface ContactOptions {
    attribute unsigned short limit;
    attribute unsigned short page;
    attribute DOMString?     sort;
    attribute boolean?       group;
};

4.7.1 Attributes

group of type boolean, nullable

The ECMA-262 specification says in, section 12.6.4, "[for the for-in Statement t]he mechanics and order of enumerating the properties [...] is not specified."

However, all major browsers loop over the properties of an object in the order in which they were defined (ref: [1] but independently verified). Chrome has some minor issues, but due to the overwhelming implementation of this behaviour in all other major browsers, the Chrome development team have marked this as a bug and it is due for fix in an upcoming release [2].

Whether the first property in the related ContactProperties object (in the order in which those properties were defined) should be grouped.

Only the first ContactProperties property provided can be grouped.

No exceptions.
limit of type unsigned short

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

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

No exceptions.
page of type unsigned short

The page number of the contacts search to return. If the requested page index does not exist, this parameter must be assigned the default value.

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

No exceptions.
sort of type DOMString, nullable

The ECMA-262 specification says in, section 12.6.4, "[for the for-in Statement t]he mechanics and order of enumerating the properties [...] is not specified."

However, all major browsers loop over the properties of an object in the order in which they were defined (ref: [1] but independently verified). Chrome has some minor issues, but due to the overwhelming implementation of this behaviour in all other major browsers, the Chrome development team have marked this as a bug and it is due for fix in an upcoming release [2].

Would it be better to have sort: ['field1', 'field2'] and descending: true|false where the latter is only meaningful if sort was specified?

The direction in which to sort the first property in the related ContactProperties object (in the order in which those properties were defined).

Only the first ContactProperties property provided is sortable.

This attribute must be one of the following constants:

'asc', 'desc'

If a different value is provided, this field defaults to null

No exceptions.

4.8 ContactFindSuccessCB interface

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

4.8.1 Methods

onSuccess
ParameterTypeNullableOptionalDescription
contactObjssequence<Contact> The sequence of Contact objects resulting from the given Contacts find() method.
No exceptions.
Return type: void

4.9 ContactSuccessCB interface

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

4.9.1 Methods

onSuccess
ParameterTypeNullableOptionalDescription
contactObjContact The Contact object resulting from the given Contact commmit() or Contact remove() method.
No exceptions.
Return type: void

4.10 ContactErrorCB interface

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

4.10.1 Methods

onError
ParameterTypeNullableOptionalDescription
errorContactError The Contact API related error object of an unsuccessful asynchronous operation.
No exceptions.
Return type: void

4.11 ContactError interface

Add Contacts API specific error codes...

The ContactError interface encapsulates all errors in the manipulation of Contact objects in the Contacts API.

[NoInterfaceObject]
interface ContactError : GenericError {
    const unsigned short CONTACT_NOT_FOUND_ERROR = 30;
    const unsigned short CONTACT_INVALID_ERROR = 31;
};

4.11.1 Constants

CONTACT_INVALID_ERROR of type unsigned short
The Contact object does not include all mandatory attributes required in Contacts.
CONTACT_NOT_FOUND_ERROR of type unsigned short
The Contact object requested could not be found in Contacts.

5. General API Support

This section defines the general API interfaces required by this specification that may also be in use in other DAP APIs.

The following interfaces may be general interfaces for use throughout all APIs. They are included here for now for API spec completion.

5.1 GenericError interface

The GenericError interface encapsulates all general errors and is the basis of all errors produced by DAP APIs.

[NoInterfaceObject]
interface GenericError {
    const unsigned short UNKNOWN_ERR = 0;
    const unsigned short INVALID_ARGUMENT_ERROR = 1;
    const unsigned short NOT_FOUND_ERROR = 2;
    const unsigned short PENDING_OPERATION_ERROR = 3;
    const unsigned short IO_ERROR = 4;
    const unsigned short NOT_SUPPORTED_ERROR = 5;
    const unsigned short PERMISSION_DENIED_ERROR = 20;
    readonly attribute unsigned short code;
};

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

5.1.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 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 PendingOp (as defined in [CORE-DEVICE]) associated with the requested callback produces an error on cancel().
PERMISSION_DENIED_ERROR of type unsigned short
The requested method was rejected permission was denied at the implementation or by the user.
UNKNOWN_ERR of type unsigned short
An unknown error occurred.

6. Contact Search Processing Rules

The Contacts interface find() method provides a method to search for contacts according to the input of a ContactProperties object.

All fields within a ContactProperties object provided to this method represent a logical UNION of value matching. Fields provided with a null value are considered to match anything.

For example, the following ContactProperties object is supplied for Contact searching:

navigator.contacts.find({
                            name:'Robert', 
                            nicknames:['Bob']
                        }, 
                        /*...*/);
The above example logically implies: "find contact objects that contain a name of 'Robert' AND a nickname of 'Bob'".

We need to be a lot clearer about partial matching included below. It might just be simpler to use pass RegExp objects around. Then again it might not...

All contact searching should apply a loose-matching policy. If a ContactProperties attribute being searched in Contacts partially matches the input filter value, a Contact object representing the contact should be returned as part of the resulting ContactFindSuccessCB.

The rules for processing filter combinations is defined below and is always provided with an input parameter and, an optional options parameter. Its behaviour depends on the type of input:

Let contactsset be initially the set of all known contacts
If input is an Object object
  1. Let singlefilter be the input parameter being parsed.
  2. Let item be the next enumerable property in singlefilter. If there are no more enumerable properties, go to step 6.
  3. If the value of item is null, go to step 2.
  4. Let contactsset be the subset of contactsset whose elements have the item value set to the value of item.
  5. Go to step 2.
  6. If the value of options is not null. apply the provided options to contactsset.
  7. Return contactsset.
If input is another native object type

Return a null value.

 

7. Use Cases and Requirements

7.1 Use Cases

Use Case 1: Upload a set of contact details to a user's social network

A user is registered on a number of different social networking sites and would like to upload some or all of their address book contacts to the service. Using the Contacts API, the Web application has access to the user's address book, subject to user opt-in, and it is therefore able to import the user's selected contacts in to their service.

Use Case 2: Download a set of contact details from a user's social network

A social networking user would like to download some or all of their social network contacts to their native address book, in to their native phone dialling application or in to another application for offline / non-web use. Using the Contacts API, the Web application provides the user with an export function and, subject to user opt-in, the selected contacts can be downloaded and imported in to the user's address book.

Use Case 3: A user would like to keep their work address book and personal address book seperate

The Contacts API will provide all address book contacts in a unified way but the user would like to associate individual contacts to individual address books - keeping their work and social address books seperated. The Contacts API must allow Web Applications to distinguish between multiple address book stores and allow the user to manage different address books according to their needs.

Use Case 4: A user maintains a single unified address book but would like to maintain groups of contacts within that address book

A user has a number of friends, family, colleagues and other contacts in their address book. They would like to create groups and assign existing contacts to these groups. The user can create, update or remove as many groups as they like and equally they would like to be able to add, remove and update the members assigned to those groups whenever they need to. The user's contacts can belong to multiple groups at the any one time.

Use Case 5: Use a web interface to manage contact details on both the user's device and the web

A Web Application is built that allows users to add, update and remove friend's contact details stored in their native address book. The Web Application can add, remove and update contact details, subject to user opt-in, and these details are automatically propagated from the web interface to the user's address book.

Use Case 6: A user would like to export contacts from the one address book store and import them to another address book store

The user maintains multiple address books that are stored on both the web and on their device(s). The user would like to move some or all of their contacts from one address book store to another. Using the Contacts API, the user can assign contact details to different address book stores. The underlying implementation will action the import/export process when the user changes to which address book store a contact is associated and the user makes an active request, via the Contacts API, to update the modified contacts.

Use Case 7: A user would like to be notified when friends have a birthday coming up

A user would like their favorite Web Application to inform them when all their friend's birthdays are coming up. The user imports some or all of their address book contacts to the Web Application. The web application can read in the contacts' birthdays as well as other useful identifying information (e.g. the contacts' names). The Web Application can then email, SMS or otherwise notify the user when a contact's birthday is coming up.

Use Case 8: A user would like his/her contacts to update their own contact details via a mediating Web Application and sync any changes to their current address book

User's contact details are constantly changing and being updated. A user has uploaded their address book to a Web Application which has then allowed the user's contacts to update the details contained therein in a collaborative way. The user can then synchronise any changes made by his/her contacts when they e.g. visit that Web Application at any point in the future.

7.2 Requirements

A. Features for Future Consideration

The requirements document contains a list of features that were considered for this version but deferred to future work [DAP-REQS].

B. Acknowledgements

The editor would like to thank the input from the PhoneGap, Nokia, and OMTP BONDI groups and the feedback received from W3C DAP members to date ...

C. References

C.1 Normative references

[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt

C.2 Informative 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/
[DAP-REQS]
Robin Berjon; et al. Device API Requirements. 05 October 2009. Editor's Draft. (Work in progress.) URL: http://dev.w3.org/2009/dap/api-reqs/
[HTML5]
Ian Hickson; David Hyatt. HTML 5. 25 August 2009. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2009/WD-html5-20090825/
[RFC4122]
P. Leach; M. Mealling; R. Salz. A Universally Unique IDentifier (UUID) URN Namespace July 2005. Internet RFC 4122. URL: http://www.ietf.org/rfc/rfc4122.txt