Contacts API Specification

[23 April 2009]

Revision:
$Rev: 245 $

Abstract

This specification defines an API that provides scripted access to contact (address book) information associated with the hosting device.

Status of this document

Nokia hereby grants to the W3C a perpetual, nonexclusive, royalty-free, world-wide right and license under any Nokia copyrights on this contribution, to copy, publish and distribute the contribution under the W3C document licenses.

Additionally, should the submission be used as a contribution towards a W3C Activity, Nokia grants a right and license of the same scope to any derivative works prepared by the W3C and based on, or incorporating all or part of, the contribution. Nokia further agrees that any derivative works of this contribution prepared by the W3C shall be solely owned by the W3C.

Nokia Corporation agrees to offer W3C members and non-members granting reciprocal terms a non-assignable, non-sublicensable, worldwide and royalty free license to make, have made, use, sell, have sold, offer to sell, import, and distribute and dispose of implementations of any portion of the submission that is subsequently incorporated into a W3C Recommendation. Such license shall extend to all Essential Claims owned or controlled by Nokia Corporation and shall be available as long as the Recommendation is in effect.

Table of contents

Introduction

This section is non-normative.

The Contacts API defines high level interface for accessing contact information associated with the hosting device.

The following code extract illustrates how to work with a contact service in the hosting device:

Example of instantiating a service object to access the device contacts.

    // Loads an instance of a contacts interface identified by a service name
    // "device", an interface name "contacts" and an interface version "1" or later. 
    var myContacts = org.w3c.device.load("device", "contacts", "1");
    

NOTE: the namespace for the service interface loader is tentative.

Example of retrieving a list of contacts in the hosting device contacts database.

    // A callback to display a summary of the contact names.
    function callback(iterator, status, transactionId)  {
        var contact, summary;
        while (contact = iterator.next())  {
            summary += contact.name.first + " " + contact.name.last + "\n"; 
        }
        alert(summary);
    }
    
    // Retrieves all the contact items matching a substring "John" and invokes
    // a callback with a status code, a transaction id and an iterator of
    // contact items as arguments.
    myContacts.getContacts(callback, "John");
    

Example of retrieving a list of contact groups in the hosting device contacts database.

    // A callback to display a summary of the contact group names.
    function callback(iterator, status, transactionId)  {
        var groupInfo, summary;      
        while (groupInfo = iterator.next())  {
            summary += groupInfo.group.name + "\n";
        }
        alert(summary);
    }
     
    // Retrieves all group items and invokes a callback with a status code,
    // a transaction id and an iterator of groups as arguments.
    myContacts.getGroups(callback);
    

Example of adding a contact item to the contact database and subsequently updating it.

     
    // Adds a new contact item to the contacts database and returns an id
    // uniquely identifying the added contact item.
    var contactId = myContacts.addContact({ 
        name: { first: "John", last: "Doe" },
        tel:  { mobile: "1234567890" }                      
    });

    // Modifies the contact identified by contactId. Adds a new landline number
    // and changes the mobile number.
    myContacts.updateContact({ 
        id : contactId,
        tel: { land: "9999999999", mobile: "1234500000" }
    });
    

Example of adding a new group item to the contact database and subsequently renaming it.

    // Adds a new group with a name "Friends".
    var groupId = myContacts.addGroup("Friends");
    
    // Changes the group name from "Friends" to "Buddies". 
    myContacts.updateGroup({ 
        groupId: groupId,
        groupName: "Buddies"
    });
    

Example of removing selected contact items from the contacts database.

     
    // A callback to delete matched contacts from the contacts database.
    function callback(iterator, status, transactionId)  {
        var contact, toDelete = [];
        while (contact = iterator.next())  {
            toDelete.push(contact.id);
        }
        // Delete matched contacts.
        myContacts.deleteContacts(toDelete);
    }
    
    // Retrieves all the contact items matching a substring "Jane" and invokes
    // a callback with a status code, a transaction id and an iterator of
    // contact items as arguments.
    myContacts.getContacts(callback, "Jane");
    

Example of adding and removing a contact item to and from a group.

    // Adds a new contact to the contact database identified by contactId.
    var contactId = myContacts.addContact({ 
        name: { first: "John", last: "Doe" },
        tel:  { mobile: "1234567890" }                      
    });
         
    // Creates a new contact group named "Friends" identified by groupId.
    groupId = myContacts.addGroup("Friends");
     
    // Adds the contact "John Doe" to the "Friends" group.
    myContacts.addContactsToGroup(groupId, contactId);
     
    // Removes the contact "John Doe" from the "Friends" groups.
    myContacts.removeContactsFromGroup(groupId, contactId);
    

Example of listing all the groups and contacts associated with them.

    
    // A callback to display a summary of the contact groups and associated contacts.
    function callback(iterator, status, transactionId)  {
        var groupInfo, summary;      
        while (groupInfo = iterator.next())  {
            summary += "Group " + groupInfo.group.name + " contains the following contacts:\n";
            for (var i in groupInfo.contents) {
                var contact = getContactInfo(groupInfo.contents[i]);
                summary += contact.name.first + " " + contact.name.last + "\n";
            } 
        }
    }
     
    // Retrieves all group items and invokes a callback with a status code,
    // a transaction id and an iterator of groups as arguments.
    myContacts.getGroups(callback);
    

Scope

This section is non-normative.

This specification is limited to [define scope].

Use-Cases and Requirements

Use-Cases

To be written ...

Requirements

The [API name] API must [do something].

Security and privacy considerations

The API defined in this specification can be used to retrieve users contact list information thus a conforming implementation should ensure no contact information is made available without the user's informed consent.

Privacy considerations for implementors of Contacts API

A conforming implementation of this specification MUST provide a mechanism that protects the user's privacy and this mechanism should ensure that privacy information is not revealed without user's informed consent.

Conformance requirements

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

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 [WebIDL].

API Description

Contact interface

The Contact object can be used by scripts to programmatically access the contact database of the hosting device.

  interface Contact {
    int getContacts(in ContactsListCallback callback);
    int getContacts(in ContactsListCallback callback, in DOMString match);
    int getContacts(in ContactsListCallback callback, in DOMString match, in SortOrder sortOrder);
        
    int getGroups(in GroupListCallback callback);
    
    DOMString addContact(in ContactItem contactItem);
    DOMString addGroup(in DOMString groupName);
    
    void updateContact(in ContactItem contactItem);
    void updateGroup(in GroupItem group);
    
    void deleteContacts(in DOMString contactId);
    void deleteContacts(in sequence<DOMString> contactIds);
    
    void deleteGroups(in DOMString groupId);
    void deleteGroups(in sequence<DOMString> groupIds);
    
    ContactItem getContactInfo(in DOMString contactId);
    GroupInfo getGroupInfo(in DOMString groupId);
    
    int getContactIds(in ContactIdsCallback callback)
    int getContactIds(in ContactIdsCallback callback, in DOMString match);
    int getContactIds(in ContactIdsCallback callback, in DOMString match, in SortOrder sortOrder);
    
    int getGroupIds(in GroupIdsCallback callback);
    
    void addContactsToGroup(in DOMString groupId, in DOMString contactId);
    void addContactsToGroup(in DOMString groupId, in sequence<DOMString> contactIds);

    void removeContactsFromGroup(in DOMString groupId, in DOMString contactId);
    void removeContactsFromGroup(in DOMString groupId, in sequence<DOMString> contactIds);
    
    void cancel(in int transactionId);
  };
        
  interface ContactsListCallback {
    void handleEvent(in ContactIterator contactIterator,
                     in int status, 
                     in int transactionId);
  };
  
  interface GroupListCallback {
    void handleEvent(in GroupIterator groupIterator,
                     in int status,
                     in int transactionId);
  };
  
  interface ContactIdsCallback {
    void handleEvent(in sequence<DOMString> contactIds,
                     in int status,
                     in int transactionId);
  };
  
  interface GroupIdsCallback {
    void handleEvent(in sequence<DOMString> groupIds,
                     in int status,
                     in int transactionId);
  };
  

Allowed values for status in ContactsListCallback, GroupListCallback, ContactIdsCallback and GroupIdsCallback must be defined.

The getContacts() takes one, two or three arguments. When called it must immediately return a unique transactionId and then asynchronously retrieve a ContactIterator object in the callback based on the specified match and sortOrder arguments.

ContactItem properties attributes within the search range of the match argument is implementation specific. Searching either first or last attributes of the ContactItem must be supported by all implementations. When match is undefined or null then, ContactIterator object to all the contact items in the default database must be retrieved. Seach is case-insensitive and matches substrings.

sortOrder specifies sorting order according to defined constants. If undefined or null then contact entries will be sorted ASCENDING based last and first fields. last takes precedence over first by the sort algorithm.

The sort algorithm must be defined.

The getGroups() takes callback argument. When called it must immediately return a unique transactionId and then asynchronously retrieve a GroupIterator of all the groups.

The addContact() takes ContactItem object as an argument, adds it to the default database it and returns a unique id of the successfully added contact item.

The addGroup() takes groupName as an argument and adds it to the default database and returns a unique groupId of the successfully added group item.

The updateContact() takes ContactItem object as an argument and updates the existing contact item in the default database identified by the unique id.

The updateGroup() takes GroupItem object as an argument and updates existing group item in default database identified by the unique groupId.

The deleteContacts() takes either a single or a list of contactId values which identify the contacts to be removed from the default database.

The deleteGroups() takes either a single or a list of groupId values which identify the groups to be removed from the default database.

The getContactInfo() returns a ContactItem object identified by a contactId.

The getGroupInfo() returns a GroupInfo object identified by groupId.

The getContactIds() takes one, two or three arguments. When called it must immediately return a unique transactionId and then asynchronously retrieve a list of contactIds based on the specified match and sortOrder.

ContactItem objects are searched for the specified match text. Conforming implementations must support searching either based on first or last attributes of the ContactItem object. When match is undefined or null a list of all contactId values must be returned.

This search algorithm must be defined in a platform independent way.

sortOrder specifies sorting order according to the defined constants. If undefined or null then contact entries will be sorted ASCENDING based on last and first attributes where last takes precedence over first.

This sort algorithm must be defined in a platform independent way.

The getGroupIds() takes callback argument. When called it must immediately return a unique transactionId and then asynchronously retrieve a list of all groupIds existing in default database in the callback.

The addContactsToGroup() takes two arguments. The groupId argument identifies the group with which the specified contacts are associated. The second attribute takes either a single contactId value or a list of contactId values which identify the ContactItem objects.

The removeContactsFromGroup() takes two arguments. The groupId argument identifies the group from which the specified contacts are disassociated from. The second attribute takes either a single contactId value or a list of contactId values which identify the ContactItem objects.

The cancel() method takes a unique transactionId of an ongoing asynchronous request to be cancelled.

ContactItem interface

ContactItem objects are regular ECMAScript objects that have the following properties:

  interface ContactItem { 
     readonly  attribute DOMString      id; 
               attribute NameFields     name;
               attribute TelDetails     tel;
               attribute AddressDetails address; 
               attribute CompanyFields  company;
  };
  

The optionality of the attributes in a ContactItem object depends on the method which operates on the object. When this object is passed to addContact() method as an argument, at least one argument in addition to id must be specified. For the updateContact() method the attribute id must be specified. All the other attributes are optional.

The maximum length of ContactItem attributes vary from one implementation to other and hence a least acceptable length must be defined or must have a mechanism to dynamically query maximum length supported by an attribute.

All the attributes in ContactItem are not necessarily supported by all implementation. Such attributes are tagged as Platform Specific. The minimal common supported set of attributes that must be supported by all implementations must be specified.

The id attribute represents a unique identifier of a contact item in the database. addContact() method ignores this attribute if specified.

The name attribute contains the detailed name information associated with the contact item.

The tel attribute contains the detailed telephone number information associated with the contact item.

The address attribute contains the detailed address information associated with the contact item.

The company attribute contains the detailed company information associated with the contact item.

NameFields interface

NameFields objects are regular ECMAScript objects that have the following properties:

  interface NameFields { 
     attribute DOMString last; 
     attribute DOMString first;
     attribute DOMString middle; 
     attribute DOMString prefix;
     attribute DOMString suffix; 
  };
  

All the attributes in NameFields are optional.

The last attribute represents the last name of the contact item.

The first attribute represents the first name of the contact item.

The middle attribute represents the middle name of the contact item. This is Platform Specific attribute.

The prefix attribute represents the name prefix of the contact item. This is Platform Specific attribute.

The suffix attribute represents the name suffix of the contact item. This is Platform Specific attribute.

TelDetails interface

TelDetails objects are regular ECMAScript objects that have the following properties:

  interface TelDetails { 
     attribute sequence<DOMString> landline; 
     attribute sequence<DOMString> mobile;
     attribute sequence<DOMString> video; 
     attribute sequence<DOMString> fax;
     attribute sequence<DOMString> voip;
     attribute TelFields           home;
     attribute TelFields           work; 
  };
  

All the attributes in TelDetails are optional.

The landline attribute represents a list of the general landline numbers associated with the contact item.

The mobile attribute represents a list of the general mobile numbers associated with the contact item.

The video attribute represents a list of the general video numbers associated with the contact item.

The fax attribute represents a list of the general fax numbers associated with the contact item.

The voip attribute represents a list of the general Voice over Internet Protocol (VoIP) numbers associated with the contact item.

The home attribute contains the detailed home related telephone number information associated with the contact item.

The work attribute contains the detailed work related telephone number information associated with the contact item.

The sip: and sips: schemes follow the guidelines in [RFC2396].

TelFields interface

TelFields objects are regular ECMAScript objects that have the following properties:

  interface TelFields { 
     attribute sequence<DOMString> landline; 
     attribute sequence<DOMString> mobile;
     attribute sequence<DOMString> video; 
     attribute sequence<DOMString> fax;
     attribute sequence<DOMString> voip;
  };
  

All the attributes in TelFields are optional.

The landline attribute represents a list of landline numbers. This is a Platform Specific attribute.

The mobile attribute represents a list of mobile numbers. This is a Platform Specific attribute.

The video attribute represents a list of video numbers. This is a Platform Specific attribute.

The fax attribute represents a list of fax numbers. This is a Platform Specific attribute.

The voip attribute represents a list of Voice over Internet Protocol (VoIP). This is a Platform Specific attribute.

AddressDetails interface

AddressDetails objects are regular ECMAScript objects that have the following properties:

  interface AddressDetails { 
     attribute DOMString           street; 
     attribute DOMString           local;
     attribute DOMString           region; 
     attribute DOMString           code;
     attribute DOMString           country;
     attribute sequence<DOMString> email;
     attribute DOMString           uri;
     attribute AddressFields       home;
     attribute AddressFields       work; 
  };
  

All the attributes in AddressDetails are optional.

The street attribute represents street details of the general address information.

The local attribute represents location details of the general address information.

The region attribute represents region related details of the general address information.

The code attribute represents area code of the general address information.

The country attribute represents country name of the general address information.

The email attribute contains a list of general email addresses.

The uri attribute represents general web address link.

The home attribute contains the detailed home related address information represented as an AddressFields object.

The work attribute contains the detailed work related address information represented as an AddressFields object.

AddressFields interface

AddressFields objects are regular ECMAScript objects that have the following properties:

  interface AddressFields { 
     attribute DOMString           street; 
     attribute DOMString           local;
     attribute DOMString           region; 
     attribute DOMString           code;
     attribute DOMString           country;
     attribute sequence<DOMString> email;
     attribute DOMString           uri;
  };
  

All the attributes in AddressFields are optional.

The street attribute represents home or work related street address information. This is a Platform Specific attribute.

The local attribute represents home or work related location address information. This is a Platform Specific attribute.

The region attribute represents home or work related region address information. This is a Platform Specific attribute.

The code attribute represents home or work related postal/zip code. This is a Platform Specific attribute.

The country attribute represents home or work related country information. This is a Platform Specific attribute.

The email attribute represents a list of home or work related email addresses. This is a Platform Specific attribute.

The uri attribute represents the home or work related web address link. This is a Platform Specific attribute.

CompanyFields interface

CompanyFields objects are regular ECMAScript objects that have the following properties:

  interface CompanyFields { 
     attribute DOMString name; 
     attribute DOMString title; 
  };
  

All the attributes in CompanyFields are optional.

The name attribute represents the company name.

The title attribute represents the job title.

GroupItem interface

GroupItem objects are regular ECMAScript objects that have the following properties:

  interface GroupItem { 
     attribute DOMString groupId; 
     attribute DOMString groupName; 
  };
  

The groupId attribute represents a unique identifier of a contact group item in the database. This field must be specified in the context of updateGroup() method.

The groupName attribute represents the name of the contact group.

GroupInfo interface

GroupInfo objects are regular ECMAScript objects that have the following properties:

  interface GroupInfo { 
     attribute GroupItem           group;
     attribute sequence<DOMString> contents;
  };
  

The group contains contact information specific to the group item.

The contents attribute contains a list of contactId values which identify the contacts associated with the group identified by the groupId attribute of the GroupItem object.

ContactIterator interface

ContactIterator objects are regular ECMAScript objects that have the following properties:

  interface ContactIterator { 
     ContactItem next();
     boolean     hasNext();
  };
  

The next() method returns the next ContactItem object in the list. If the last object has been reached, the method must return null.

The hasNext() method returns true if the next contact item exists, otherwise false.

GroupIterator interface

GroupIterator objects are regular ECMAScript objects that have the following properties:

  interface GroupIterator { 
     GroupInfo next();
     boolean   hasNext();
  };
  

The next() method returns the next GroupItem object in the list. If the last object has been reached, the method must return null.

The hasNext() method returns true if the next group item exists, otherwise false.

Exception handling

On error, the APIs throw DeviceException with an informative error code. The DeviceException interface and error constants are defined in Appendix A.

Defined Constants

Sort Order Constants

Sort order must take these constant values of type unsigned short int.

SORT_ASCENDING
The value of 0 represents ascending sort order.
SORT_DESCENDING
The value of 1 represents descending sort order.

References

[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels.
[WEBIDL]
Web IDL.
[RFC2396]
Uniform Resource Identifiers (URI): Generic Syntax.