The Bondi Contact Module: bondi.contact - Version 1.01

27 July 2009

Authors

Guillermo Caudevilla Laliena <guillermo.caudevilla@vodafone.com>
Pedro Fraca Tarancon <pfracat@corp.vodafone.es>

Abstract

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

1. Introduction
- 1.1. Features
- 1.2. Device Capabilities
2. Type Definitions
- 2.1. AddressBookArray
- 2.2. ContactsArray
3. Interfaces
- 3.1. ContactArraySuccessCallback
- 3.2. ContactManager
- 3.3. AddressBook
- 3.4. Contact

Summary of Methods

Interface	Method
ContactArraySuccessCallback	void onSuccess(ContactsArray contacts)
ContactManager	AddressBookArray getAddressBooks()
AddressBook	Contact createContact(Map 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, Map filter)
Contact	Object getProperty(DOMString propertyName) StringArray getSupportedPropertyKeys() void setProperty(DOMString propertyName, Object propertyValue)

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. 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 provided is provided.

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.2. 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. `ContactsArray`

Array of Contacts.

        typedef sequence<Contact>     ContactsArray;

3. Interfaces

3.1. `ContactArraySuccessCallback`

Success callback for retrieving a list of contacts.

        [Callback=FunctionOnly, NoInterfaceObject] interface ContactArraySuccessCallback {
                void onSuccess(in ContactsArray 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(ContactsArray contacts);

Parameters

contacts: The list of contacts

3.2. `ContactManager`

The ContactManager interface offers methods to retrieve addressbooks.

        interface ContactManager {

                AddressBookArray getAddressBooks()
                        raises(SecurityError);
        };

Addressbook availabe are: SIM Device memory AddressBook

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 Map 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 Map filter)
                        raises(SecurityError, DeviceAPIError);

        };

Methods

createContact

Creates a contact Object.

Signature

Contact createContact(Map options);

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

Parameters

options: Optional Map containing the Associative The following property keys are supported:
- "name": String. Name of the contact.
- "nickName": String. Descriptive name of the contact.
- "address": Map. Supported keys "street","number","postalcode","city","country";
- "telephone": String. Mobile phone of the contact.
- "mail": String. E-mail address of the contact.
- "photo": String. Path to the image of the contact.
Supported properties also are returned by the getSupportedPropertyKeys contact method.
For SIM contacts only "name" and "telephone" keys are supported

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(SuccessCallback successCallback, ErrorCallback errorCallback, 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 map of the contact address property values.
  var contactAddress = {street:"Gran Via",number:"32",postalcode:"50013",city:"Zaragoza",country:"Spain"};

        // Create the contact.
        var contact = addressbooks[0].createContact(
                           { name:'Pedro Fraca',
                             nickName:'peter',
                             address:contactAddress,
                             mail:'pedro@gmail.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(SuccessCallback successCallback, ErrorCallback errorCallback, 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(SuccessCallback successCallback, ErrorCallback errorCallback, 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(SuccessCallback successCallback, 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(ContactArraySuccessCallback successCallback, ErrorCallback errorCallback, Map 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 conductes 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: Associative Array with the criteria that object will be match. The following property keys are supported:
- "name": String. Name of the contact.
- "nickName": String. Descriptive name of the contact.
- "address": Map. Supported keys "street","number","postalcode","city","country";
- "telephone": String. Mobile phone of the contact.
- "mail": String. E-mail address of the contact.
- "photo": String. Path to the image of the contact.
Supported properties also are returned by the getSupportedPropertyKeys contact method.

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 Map address;

                attribute File photo;

                attribute DOMString telephone;

                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";

Map address

The address key is a map with the following keys supported street,number,postalcode,city,country

Code example

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

File photo

Picture of the contact.

Code example

        var contact = addressBook.CreateContact(null);
        contact.photo = "\guillermo.jpg";

DOMString telephone

Telephone of the contact.

Code example

        var contact = addressBook.CreateContact(null);
        contact.telephone = "+34666666666";

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(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(DOMString propertyName, 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));

The Bondi Contact Module: bondi.contact - Version 1.01

27 July 2009

Authors

Abstract

Table of Contents

Summary of Methods

1. Introduction

Code example

1.1. Features

1.2. Device capabilities

2. Type Definitions

2.1. AddressBookArray

2.2. ContactsArray

3. Interfaces

3.1. ContactArraySuccessCallback

Methods

Signature

Parameters

3.2. ContactManager

Methods

Signature

Return value

Exceptions

API features

Code example

3.3. AddressBook

Methods

Signature

Parameters

Return value

Exceptions

API features

Code example

Signature

Parameters

Return value

Exceptions

API features

Code example

Signature

Parameters

Return value

Exceptions

API features

Code example

Signature

Parameters

Return value

Exceptions

API features

Code example

Signature

Parameters

Return value

Exceptions

API features

Code example

Signature

Parameters

Return value

Exceptions

API features

Code example

3.4. Contact

Attributes

Code example

Code example

Code example

Code example

Code example

Code example

Code example

Methods

Signature

Parameters

Return value

Exceptions

Code example

Signature

Return value

2.1. `AddressBookArray`

2.2. `ContactsArray`

3.1. `ContactArraySuccessCallback`

3.2. `ContactManager`

3.3. `AddressBook`

3.4. `Contact`