Bondi logo

The Bondi contact Module - Version 1.1

26 October 2009

Authors

© 2009 OMTP Ltd. All rights reserved. OMTP and OMTP BONDI are registered trademarks of OMTP Ltd.

Abstract

This module provides access to both SIM and phone based contacts.

Table of Contents

Summary of Methods

InterfaceMethod
ContactArraySuccessCallbackvoid onSuccess(ContactArray contacts)
ContactManagerAddressBookArray getAddressBooks()
AddressBookContact createContact(ContactOptions options)
PendingOperation addContact(SuccessCallback successCallback, ErrorCallback errorCallback, Contact contact)
PendingOperation updateContact(SuccessCallback successCallback, ErrorCallback errorCallback, Contact contact)
PendingOperation deleteContact(SuccessCallback successCallback, ErrorCallback errorCallback, Contact contact)
PendingOperation deleteAllContacts(SuccessCallback successCallback, ErrorCallback errorCallback)
PendingOperation findContacts(ContactArraySuccessCallback successCallback, ErrorCallback errorCallback, ContactFilter filter)
ContactObject getProperty(DOMString propertyName)
StringArray getSupportedPropertyKeys()
void setProperty(DOMString propertyName, Object propertyValue)
Address
PhoneNumber
ContactOptions
ContactFilter
ContactManagerObject

1. Introduction

The Contact API provides access to contacts on the device by exposing an array of addressbooks. An AddressBook can be accessed using the getAddressBooks method. An Addressbook is a collection of contacts. Conceptually there are two types of AddressBook, the SIM and device memory addressbook. A contact is a person stored in the Addressbook with properties such a name, phone, address, mail. Contacts in a SIM AddressBook can only store name and phone properties. It is possible to read, create, delete, update contacts in a given AddressBook. The properties supported are returned by the contact class method getSupportedPropertyKeys. These supported keys are valid for the createContact and/or updateContact method. It is also possible to find contacts using a filter supplied to the method findContacts.

Code example
        bondi.requestFeature(successCB, errorCB, "pim.contact");

        // Here we're obtaining the sim addressbook stored at position 1 of the array
        var addressbooks = bondi.pim.contact.getAddressBooks();
        var sim = addressbooks[1];

1.1. Feature set

This is the URI used to declare this API's feature set, for use in bondi.requestFeature. For the URL, the list of features included by the feature set is provided.

http://bondi.omtp.org/api/pim.contact

All the Contact features

Includes API features:

  • http://bondi.omtp.org/api/pim.contact.read
  • http://bondi.omtp.org/api/pim.contact.write

1.2. Features

This is the list of URIs used to declare this API's features, for use in bondi.requestFeature. For each URL, the list of functions covered is provided.

When any of the features

is successfully requested, the interface ContactManager is instantiated, and the resulting object appears in the global namespace as .contactManager.

http://bondi.omtp.org/api/pim.contact.read

Device capabilities:

  • pim.contact.read
http://bondi.omtp.org/api/pim.contact.write

Device capabilities:

  • pim.contact.write

1.3. Device capabilities

pim.contact.read

Read the contacts stored in the terminal

pim.contact.write

Writes contacts to be stored in the terminal

2. Type Definitions

2.1. AddressBookArray

Array of AddressBook. 

        typedef sequence<AddressBook> AddressBookArray;

2.2. ContactArray

Array of Contacts. 

        typedef sequence<Contact>     ContactArray;

3. Interfaces

3.1. ContactArraySuccessCallback

Success callback for retrieving a list of contacts. 

        [Callback=FunctionOnly, NoInterfaceObject] interface ContactArraySuccessCallback {
                void onSuccess(in ContactArray contacts);
        };

Success callback that takes an array of Contacts as input argument. It is used in the asynchronous operation to get a list of contacts.

Methods

onSuccess

Method invoked when a list of contacts is retrieved succesfully

Signature
void onSuccess(in ContactArray contacts);
Parameters
  • contacts: The list of contacts

3.2. ContactManager

The ContactManager interface offers methods to retrieve addressbooks. 

        interface ContactManager {

        const unsigned short MOBILE_NUMBER  = 0;
        const unsigned short LANDLINE_NUMBER  = 1;
        const unsigned short FAX_NUMBER  = 2;
        const unsigned short WORK_NUMBER  = 3;
        const unsigned short HOME_NUMBER  = 4;

                AddressBookArray getAddressBooks()
                        raises(SecurityError);
        };

Addressbook availabe are: SIM Device memory AddressBook

Constants

unsigned short MOBILE_NUMBER

The phone number is a mobile

unsigned short LANDLINE_NUMBER

The phone number is a landline number

unsigned short FAX_NUMBER

The phone number is a fax number

unsigned short WORK_NUMBER

The phone number is a work number

unsigned short HOME_NUMBER

The phone number is a home number

Methods

getAddressBooks

Returns the available address books in the device.

Signature
AddressBookArray getAddressBooks();
Return value
An array of AddressBook Objects for each address book available in the device. First position [0] will be assigned to the native device address book, second position [1] to the SIM address book.
Exceptions
  • SecurityError:

    PERMISSION_DENIED_ERROR when access is denied by the security policy.

API features
http://bondi.omtp.org/api/pim.contact.read
Code example
        var addressbooks = bondi.pim.contact.getAddressBooks();
        var simBook = addressbooks[1];

3.3. AddressBook

Abstraction of a list of contacts A list representing all the contacts available in a given addressBook The AddressBook interface offers methods to
- Find contacts using filters with the findContacs method
- Add contacts using the addContact method
- Update existing contacts using the updateContact method
- Delete a specific contact using the deleteContact method
- Clear the entire contacts list using the clearContact method 

        interface AddressBook {

                Contact createContact([Optional] in ContactOptions options)
                        raises(SecurityError, DeviceAPIError);

                PendingOperation addContact(in SuccessCallback successCallback,
                                            in ErrorCallback errorCallback,
                                            in Contact contact)
                        raises(SecurityError, DeviceAPIError);

                PendingOperation updateContact(in SuccessCallback successCallback,
                                               in ErrorCallback errorCallback,
                                               in Contact contact)
                        raises(SecurityError, DeviceAPIError);

                PendingOperation deleteContact(in SuccessCallback successCallback,
                                               in ErrorCallback errorCallback,
                                               in Contact contact)
                        raises(SecurityError, DeviceAPIError);

                PendingOperation deleteAllContacts(in SuccessCallback successCallback,
                                                   in ErrorCallback errorCallback)
                        raises(SecurityError, DeviceAPIError);

                PendingOperation findContacts(in ContactArraySuccessCallback successCallback,
                                              in ErrorCallback errorCallback,
                                              in ContactFilter filter)
                        raises(SecurityError, DeviceAPIError);
        };

Methods

createContact

Creates a contact Object.

Signature
Contact createContact(in ContactOptions options);

The address key is a map with next keys at least supported street, number,postalcode,city,country

Parameters
  • options: Contains the contact information
Return value
A Contact Object.
Exceptions
  • SecurityError:

    PERMISSION_DENIED_ERROR when access is denied by the security policy.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if the options are wrong or if another any argument passed is wrong

API features
http://bondi.omtp.org/api/pim.contact.write
Code example
        var addressbooks = bondi.pim.contact.getAddressBooks();

        // Create a map of the contact address property values.
  var contactAddress = {street:"Gran Via",number:"32",postalcode:"50013",city:"Zaragoza",country:"Spain"};

        // Create a contact.
        var contact = addressbooks[0].createContact(
                           { name:'Pedro Fraca',
                             nickName:'peter',
                             address:contactAddress,
                             mail:'pedro@gmail.com',
                             telephone:'6666666666',
                             photo:'images/pedro.jpg'});
addContact

Adds a contact to the address book.

Signature
PendingOperation addContact(in SuccessCallback successCallback, in ErrorCallback errorCallback, in Contact contact);

This is an asynchronous method.

Parameters
  • successCallback: function called when the invocation ends successfully.
  • errorCallback: function called when an error occurs
  • contact: the Contact object to be added to the terminal storage
Return value
PendingOperation in order to cancel the async call.
Exceptions
  • SecurityError:

    PERMISSION_DENIED_ERROR when access is denied by the security policy.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if an invalid parameter is given

API features
http://bondi.omtp.org/api/pim.contact.write
Code example
        var addressbooks = bondi.pim.contact.getAddressBooks();
        // Create a contact.
        var contact = addressbooks[0].createContact(
                           { name:'John Smith',
                             nickName:'johny',
                             address:{street:"Gran Via",number:"32",postalcode:"50013",city:"Zaragoza",country:"ES"},
                             mail:'john@smith.com',
                             telephone:'6666666666'});

        // Define the success callback.
        function successCallback(response) {
                alert("Added");
        }

        // Define the error callback.
        function errorCallback(response) {
                alert( "The following error: " +  response.code + ", occurred adding a contact");
        }

        // Add it to the address book.
        myAddressBooks[0].addContact(successCallback,errorCallback,contact);
updateContact

Updates a contact in the address book.

Signature
PendingOperation updateContact(in SuccessCallback successCallback, in ErrorCallback errorCallback, in Contact contact);

This is an asynchronous method.

Parameters
  • successCallback: function called when the invocation ends successfully.
  • errorCallback: function called when an error occurs
  • contact: the Contact object to be updated into the terminal storage
Return value
PendingOperation in order to cancel the async call.
Exceptions
  • SecurityError:

    PERMISSION_DENIED_ERROR when access is denied by the security policy.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if an invalid parameter is given

API features
http://bondi.omtp.org/api/pim.contact.write
Code example
        var addressbooks = bondi.pim.contact.getAddressBooks();

        // Retrieve the contact you want to work with using a helper function.
        contact = getContactHelper();

        // Set a new telephone number for the contact
        contact.telephone = "+34666666668";

        // Define the success callback.
        function successCallback(response) {
                alert("Updated");
        }

        // Define the error callback.
        function errorCallback(response) {
                alert( "The following error: " +  response.code + ", ocurred updating a contact");
        }

        // Update the contact.
        addressbooks[0].updateContact(successCallback,errorCallback,contact);
deleteContact

Deletes a contact from the address book.

Signature
PendingOperation deleteContact(in SuccessCallback successCallback, in ErrorCallback errorCallback, in Contact contact);

This is an asynchronous method.

Parameters
  • successCallback: function called when the invocation ends successfully.
  • errorCallback: function called when an error occurs
  • contact: the Contact object to be deleted from the terminal storage
Return value
PendingOperation in order to cancel the async call.
Exceptions
  • SecurityError:

    PERMISSION_DENIED_ERROR when access is denied by the security policy.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if an invalid parameter is given

API features
http://bondi.omtp.org/api/pim.contact.write
Code example
        var myAddressBooks = bondi.pim.contact.getAddressBooks();

        // Retrieve the contact you want to delete using a helper function.
        contact = getContactHelper();

        // Define the success callback.
        function successCallback(response) {
                alert("Deleted");
        }

        // Define the error callback.
        function errorCallback(response) {
                alert( "The following error: " +  response.code + " ocurred deleting a contact.");
        }

        myAddressBooks[0].deleteContact(successCallback,errorCallback,contact);
deleteAllContacts

Deletes all contacts in the address book.

Signature
PendingOperation deleteAllContacts(in SuccessCallback successCallback, in ErrorCallback errorCallback);

This is an asynchronous method.

Parameters
  • successCallback: function called when the invocation ends successfully.
  • errorCallback: function called when an error occurs
Return value
PendingOperation in order to cancel the async call.
Exceptions
  • SecurityError:

    PERMISSION_DENIED_ERROR when access is denied by the security policy.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if an invalid parameter is given

API features
http://bondi.omtp.org/api/pim.contact.write
Code example
        var myAddressBooks = bondi.pim.contact.getAddressBooks();

        // Define the success callback.
        function successCallback(response) {
                alert("Deleted!");
        }

        // Define the error callback.
        function errorCallback(response) {
                alert( "The following error: " +  response.code + ", occurred deleting all contacts.");
        }

        // Delete all contacts...
        myAddressBooks[0].deleteAllContacts(successCallback, errorCallback);
findContacts

Retrieves an array of Contact Objects for contacts stored within the address book and matching the selected filter.

Signature
PendingOperation findContacts(in ContactArraySuccessCallback successCallback, in ErrorCallback errorCallback, in ContactFilter filter);

This is an asynchronous method.

In a search using this method, if more than one value is used, then the AND operator will be used betwwen all values to perform the search.

In a search using strings, the search conducted is case sensitive. If the string is found anywhere inside the key object value, the entire object will be returned.

Parameters
  • successCallback: function called when the invocation ends successfully.
  • errorCallback: function called when an error occurs
  • filter: Options to filter contacts
Return value
PendingOperation in order to cancel the async call.
Exceptions
  • SecurityError:

    PERMISSION_DENIED_ERROR when access is denied by the security policy.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if an invalid parameter is given

API features
http://bondi.omtp.org/api/pim.contact.read
Code example
        var myAddressBooks = bondi.pim.contact.getAddressBooks();

        // Define the success callback.
        function successCallback(response) {
                alert(response.length + " results found.");
        }

        // Define the error callback.
        function errorCallback(response) {
                alert( "The following error: " +  response.code + ", occurred finding contacts");
        }

        // Find all contacts in the first address book with the name 'Guillermo'.
        myAddressBooks[0].findContacts(successCallback, errorCallback, {name:"Guillermo"});

3.4. Contact

Contact object Abstraction of a device contact. This interface offers properties to manage each contact property It includes methods to get a specific property and to get the available properties to use in the findContact filter, addeContact and updateContact methods. If the contact is a SIM contact only phone and name will be filled. Also if the contact is a SIM contact only phone and name will be returned by the getSupportedPropertyKeys 

        interface Contact {

                attribute DOMString id;

                attribute DOMString name;

                attribute DOMString nickname;

                attribute Address address;

                attribute DOMString photo;

                attribute PhoneNumberArray phoneNumbers;

                attribute DOMString email;

                Object getProperty(in DOMString propertyName)
                        raises(DeviceAPIError);

                StringArray getSupportedPropertyKeys();


                 void setProperty(in DOMString propertyName, in Object propertyValue)
                        raises(DeviceAPIError);
        };

Attributes

DOMString id

Unique identifier assigned to the contact in the platform. Read only.

Code example
        var contact = addressBook.CreateContact();
        var id = contact.id;
DOMString name

Name of the contact.

Code example
        var contact = addressBook.CreateContact();
        contact.name = "Guillermo";
DOMString nickname

Nickname of the contact.

Code example
        var contact = addressBook.CreateContact();
        contact.nickName = "gcaudev";
Address address

Contact address

Code example
        var contact = addressBook.CreateContact();
  var contactAddress = {street:"Gran Via",number:"32",postalcode:"50013",city:"Zaragoza",country:"Spain"};
        contact.address = contactAddress;
DOMString photo

Picture of the contact.

Code example
        var contact = addressBook.CreateContact(null);
        contact.photo = "\guillermo.jpg";
PhoneNumberArray phoneNumbers

Telephone of the contact.

Code example
        TODO
DOMString email

Email of the contact.

Code example
        var contact = addressBook.CreateContact(null);
        contact.email = "guillermo.caudevilla@vodafone.com";

Methods

getProperty

Gets the value of any of the Contact Object properties.

Signature
Object getProperty(in DOMString propertyName);

This method provides a means of accessing any platform-specific properties that are not already exposed by the standard property attributes.

Parameters
  • propertyName: The property name to be returned
Return value
Object containing the value of that property.
Exceptions
  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if invalid propertyName is given

Code example
        var location = contact.getProperty("location");
getSupportedPropertyKeys

Returns the supported attributes for contacts in this address book.

Signature
StringArray getSupportedPropertyKeys();
Return value
An array of Strings containing the contact properties for this implementation. I.e. {"name", "nickName", "address", "photo", "telephone", "email"}
Code example
        var addressbooks = bondi.pim.contact.getAddressBooks();
        var attributes = addressbooks[0].getSupportedPropertyKeys();
        alert("Number of attributes: " + attributes.length());
setProperty

Sets the value of a Contact Object property.

Signature
void setProperty(in DOMString propertyName, in Object propertyValue);
Parameters
  • propertyName: The property name to be set
  • propertyValue: Value to be assigned to the property
Exceptions
  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if invalid propertyName is given

Code example
        var name = "Guillermo Caudevilla Laliena";
        contact.setProperty("name", name.substring(0, maxSize-1));

3.5. Address

contains a set of properties which describe a location on the earth's surface 

        interface Address
        {
             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;
        };
Code example
        var addressbooks = bondi.pim.contact.getAddressBooks();
        // Create a contact.
        var contact = addressbooks[0].createContact(
                           { name:'John Smith',
                             nickName:'johny',
                             address:{street:"Gran Via",number:"32",postalcode:"50013",city:"Zaragoza",country:"ES"},
                             mail:'john@smith.com'});

Attributes

DOMString country

Country specified using the two-letter [ISO 3166-1] code.

DOMString region

Name of a country subdivision (e.g. the state name in the US).

DOMString county

Name of a land area within the larger region.

DOMString city

Reflects the name of the city.

DOMString street

Reflects the name of the street.

DOMString streetNumber

Reflects the location's street number.

DOMString premises

Denotes the details of the premises, such as a building name, block of flats, etc.

DOMString additionalInformation

Contains other address details that are not captured by the rest of the attributes in this interface. Examples include a floor number in a building, an apartment number, the name of an office occupant, etc..

DOMString postalCode

Reflects the postal code of the location (e.g. the zip code in the US).

3.6. PhoneNumber

Contains information about the phone numbers of a contact. 

         interface PhoneNumber
        {
          attribute DOMString number;
          
          attribute unsigned short type;
          
          attribute unsigned short subType;
          
        };

This interface is intended to store the information related with a phone number, providing also information on whether it is a work or home number (type) or on the device subtype (fax, fixed or mobile).

Code example
 TODO

Attributes

DOMString number

phone Number

unsigned short type

phone type (work or home)

unsigned short subType

phone subtype (mobile, landline or fax)

3.7. ContactOptions

Interface used for contact creation. 

    [NoInterfaceObject, Callback] interface ContactOptions {
       
      attribute DOMString name;
       
      attribute DOMString nickName;
        
      attribute Address address;
        
      attribute DOMString picture;

      attribute PhoneNumberArray phoneNumbers;

      attribute DOMString email;
    };

This interface is intended to be used for input parameters for contact creation (createContact). All the attributes are optional and by default are undefined.

Code example
        var addressbooks = bondi.pim.contact.getAddressBooks();
        // Create a contact.
        var contact = addressbooks[0].createContact(
                           { name:'John Smith',
                             nickName:'johny',
                             address:{street:"Gran Via",number:"32",postalcode:"50013",city:"Zaragoza",country:"ES"},
                             mail:'john@smith.com',
                             telephone:'6666666666'});

Attributes

DOMString name

Contact's full name

DOMString nickName

Contact's nickname

Address address

Contact's address

DOMString picture

Contact's picture

PhoneNumberArray phoneNumbers

Contact's phone numbers

DOMString email

Contact's email

3.8. ContactFilter

Interface used for contact filter in the findContacts. 

    [NoInterfaceObject, Callback] interface ContactFilter {
      attribute DOMString name;
       
      attribute DOMString nickName;
        
      attribute Address address;

      attribute DOMString telephone;
  
      attribute DOMString email;
    };

This interface is intended to be used to indicate the filters to be used when filtering contacts. All the attributes are optional and by default are undefined.

Attributes

DOMString name

Contact's full name

DOMString nickName

Contact's nickname

Address address

Contact's address

DOMString telephone

Phone number to be searched in the contact's phone numbers

DOMString email

Contact's e-mail address

3.9. ContactManagerObject

Specifies what is instantiated at feature request 

        interface ContactManagerObject {
                readonly attribute ContactManager contactManager; 
        };