This specification defines an API that provides scripted access to contact (address book) information associated with the hosting device.
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.
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);
This section is non-normative.
This specification is limited to [define scope].
To be written ...
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.
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.
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].
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
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
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
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
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
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
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
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
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
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
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
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.
On error, the APIs throw DeviceException with an informative error code.
The DeviceException interface and error constants are defined in
Appendix A.
Sort order must take these constant values of type
unsigned short int.
SORT_ASCENDING0 represents ascending sort order.SORT_DESCENDING1 represents descending sort order.