Bondi logo

The Bondi contact Module - Version 1.1

February 2010

Authors

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

Abstract

This module provides access to contacts available in the Address Books.

Table of Contents

Summary of Methods

InterfaceMethod
ContactArraySuccessCallbackvoid onSuccess(ContactArray contacts)
AddressBookArraySuccessCallbackvoid onSuccess(AddressBookArray addressbooks)
ContactManagerPendingOperation getAddressBooks(AddressBookArraySuccessCallback successCallback, ErrorCallback errorCallback)
AddressBookContact createContact(ContactProperties 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 findContacts(ContactArraySuccessCallback successCallback, ErrorCallback errorCallback, ContactFilter filter)
Contact
ContactProperties
Address
PhoneNumber
EmailAddress
ContactAddress
ContactFilter
ContactManagerObject

1. Introduction

Copyright 2010 OMTP Ltd.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

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

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/1.1/pim.contact

All the Contact features

Includes API features:

  • http://bondi.omtp.org/api/1.1/pim.contact.read
  • http://bondi.omtp.org/api/1.1/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 .contact.

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

Device capabilities:

  • pim.contact.read
http://bondi.omtp.org/api/1.1/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 Contact. 

        typedef sequence<Contact>     ContactArray;

2.3. PhoneNumberArray

Array of PhoneNumber. 

        typedef sequence<PhoneNumber> PhoneNumberArray;

2.4. EmailAddressArray

Array of EmailAddress. 

        typedef sequence<EmailAddress> EmailAddressArray;

2.5. ContactAddressArray

Array of Address. 

        typedef sequence<ContactAddress> ContactAddressArray;

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 successfully

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

3.2. AddressBookArraySuccessCallback

Success callback for retrieving a list of address books. 

        [Callback=FunctionOnly, NoInterfaceObject] interface AddressBookArraySuccessCallback {
                void onSuccess(in AddressBookArray addressbooks);
        };

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

Methods

onSuccess

Method invoked when a list of contacts is retrieved successfully

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

3.3. ContactManager

The ContactManager interface offers methods to retrieve addressbooks. 

        [NoInterfaceObject] interface ContactManager {

                PendingOperation getAddressBooks(in AddressBookArraySuccessCallback successCallback,
                                in ErrorCallback errorCallback);
        };

Methods

getAddressBooks

Returns the available address books in the device.

Signature
PendingOperation getAddressBooks(in AddressBookArraySuccessCallback successCallback, in ErrorCallback errorCallback);

This is an asynchronous method.

If no Address Book is available the successCallback will be invoked with an empty array

If access is denied by the security policy the ErrorCallback will be invoked with a SecurityError PERMISSION_DENIED_ERROR

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.
API features
http://bondi.omtp.org/api/1.1/pim.contact.read
Code example
        // Define the success callback.
        function addressBookSuccessCallback(addressBooks) {
                // do something with resulting addressBooks
        }

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

        // Get a list of available address books.
        bondi.pim.contact.getAddressBooks(addressBookSuccessCallback,errorCallback);

3.4. 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 findContacts method
- Add contacts using the addContact method
- Update existing contacts using the updateContact method
- Delete a specific contact using the deleteContact method 

        [NoInterfaceObject] interface AddressBook {


                const unsigned short SIM_ADDRESS_BOOK = 0;

                const unsigned short DEVICE_ADDRESS_BOOK = 1;


                readonly attribute unsigned short type;

                readonly attribute DOMString name;

                Contact createContact([Optional] in ContactProperties options)
                        raises(DeviceAPIError);

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

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

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

                PendingOperation findContacts(in ContactArraySuccessCallback successCallback,
                                in ErrorCallback errorCallback,
                                [Optional] in ContactFilter filter);

        };

Constants

unsigned short SIM_ADDRESS_BOOK

Constant used to identify SIM Address Books.

unsigned short DEVICE_ADDRESS_BOOK

Constant used to identify Device Address Books.

Attributes

readonly unsigned short type

Address Book Type Read only.

It MUST be one of the below constants: SIM_ADDRESS_BOOK = 0 DEVICE_ADDRESS_BOOK = 1

Code example
        // Define the success callback.
        function addressBookSuccessCallback(addressBooks) {
          alert("The address book type is " + addressBooks[0].type);    
        }

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

        // Get a list of available address books.
        bondi.pim.contact.getAddressBooks(addressBookSuccessCallback,errorCallback);
readonly DOMString name

Address Book Human Readable Name Read only.

Code example
        // Define the success callback.
        function addressBookSuccessCallback(addressBooks) {
          alert("The address book name is " + addressBooks[0].name);    
        }

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

        // Get a list of available address books.
        bondi.pim.contact.getAddressBooks(addressBookSuccessCallback,errorCallback);

Methods

createContact

Creates a contact Object.

Signature
Contact createContact(in ContactProperties options);
Parameters
  • options: Contains the contact information
Return value
A Contact Object.
Exceptions
  • DeviceAPIError:

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

Code example
        // Define the address book success callback.
        function addressBookSuccessCallback(addressBooks) {
        // Create a map of the contact address property values.

                // Create a contact.
                var contact = addressbooks[0].createContact(
                           { name:'Pedro Fraca',
                             nicknames:['peter'],
                             emails:[{email:'pedro@gmail.com'}],
                             phoneNumbers:[{number:'6666666666'}],
                             photoURI:'http://foo.com/images/pedro.jpg'});
        }

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

        // Get a list of available address books.
        bondi.pim.contact.getAddressBooks(addressBookSuccessCallback,errorCallback);
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. If the contact is successfully added, the SuccessCallback is invoked.

If access is denied by the security policy the ErrorCallback will be invoked with a SecurityError PERMISSION_DENIED_ERROR

If any argument is wrong the ErrorCallback will be invoked with a DeviceAPIError INVALID_ARGUMENT_ERROR

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.
API features
http://bondi.omtp.org/api/1.1/pim.contact.write
Code example
        // Define the address book success callback.
        function addressBookSuccessCallback(addressBooks) {

                // Create a contact.
                var contact = addressbooks[0].createContact(
                           { name:'Pedro Fraca',
                             nicknames:['peter'],
                             emails:[{email:'pedro@gmail.com'}],
                             phoneNumbers:[{number:'6666666666'}],
                             photoURI:'http://foo.com/images/pedro.jpg'});

                // Add it to the address book.
                addressBooks[0].addContact(contactSuccessCallback,errorCallback,contact);
        }

        // Define the success callback.
        function contactSuccessCallback(response) {
                alert("Contact added successfully");
        }               

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

        // Get a list of available address books.
        bondi.pim.contact.getAddressBooks(addressBookSuccessCallback,errorCallback);
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.

If the contact is successfully updated, the SuccessCallback is invoked.

If access is denied by the security policy the ErrorCallback will be invoked with a SecurityError PERMISSION_DENIED_ERROR

If any argument is wrong the ErrorCallback will be invoked with a DeviceAPIError INVALID_ARGUMENT_ERROR

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.
API features
http://bondi.omtp.org/api/1.1/pim.contact.write
Code example
        // Define the address book success callback.
        function addressBookSuccessCallback(addressBooks) {
              addressBook = addressBooks[0];
                // Find all contacts in the first address book with the name 'Guillermo'.
                addressBook.findContacts(contactFindSuccessCallback, errorCallback, {name:"Guillermo"});
        }

        // Define the success callback.
        function contactFindSuccessCallback(response) {
        var contact = response[0];
          // Edit contact as required. e.g. add a new telephone number
          contact.phoneNumbers.push({number:"+34666666668",type:'work'});
          addressBook.updateContact(updateSuccessCallback,errorCallback,contact);
        }               

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

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

      var addressBook;
        // Get a list of available address books.
        bondi.pim.contact.getAddressBooks(addressBookSuccessCallback,errorCallback);
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.

If the contact is successfully deleted, the SuccessCallback is invoked.

If access is denied by the security policy the ErrorCallback will be invoked with a SecurityError PERMISSION_DENIED_ERROR

If any argument is wrong the ErrorCallback will be invoked with a DeviceAPIError INVALID_ARGUMENT_ERROR

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.
API features
http://bondi.omtp.org/api/1.1/pim.contact.write
Code example
        // Define the address book success callback.
        function addressBookSuccessCallback(addressBooks) {
              addressBook = addressBooks[0];
                // Find all contacts in the first address book with the name 'Guillermo'.
                addressBook.findContacts(contactFindSuccessCallback, errorCallback, {name:"Guillermo"});
        }

        // Define the success callback.
        function contactFindSuccessCallback(response) {
                addressBook.deleteContact(deleteSuccessCallback,errorCallback,response[0]);
        }               

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

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

      var addressBook;
        // Get a list of available address books.
        bondi.pim.contact.getAddressBooks(addressBookSuccessCallback,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.

The filtering is implemented according to the design patterns (chapter 2.4). If no filter is passed all the contacts will be returned.

If the method is successfully executed, the SuccessCallback is invoked.

If no contact is available in the address book the successCallback will be invoked with an empty array

If access is denied by the security policy the ErrorCallback will be invoked with a SecurityError PERMISSION_DENIED_ERROR

If any argument is wrong the ErrorCallback will be invoked with a DeviceAPIError INVALID_ARGUMENT_ERROR

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.
API features
http://bondi.omtp.org/api/1.1/pim.contact.read
Code example
        // Define the address book success callback.
        function addressBookSuccessCallback(addressBooks) {
              addressBook = addressBooks[0];
                // Find all contacts in the first address book with the name 'Guillermo'.
                addressBook.findContacts(contactFindSuccessCallback, errorCallback, {name:"Guillermo"});
        }

        // Define the success callback.
        function contactFindSuccessCallback(response) {
                alert("findContacts returned successfully");
        }               

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

      var addressBook;
        // Get a list of available address books.
        bondi.pim.contact.getAddressBooks(addressBookSuccessCallback,errorCallback);

3.5. Contact

Contact object Abstraction of a device contact. This interface extends ContactProperties to manage each contact property 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 

        [NoInterfaceObject] interface Contact : ContactProperties {

                readonly attribute DOMString id;

        };

Attributes

readonly DOMString id

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

Code example
        // Define the address book success callback.
        function addressBookSuccessCallback(addressBooks) {

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

        // Define the success callback.
        function contactFindSuccessCallback(response) {
                alert("The first contact id is " + response[0].id);
        }               

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

        // Get a list of available address books.
        bondi.pim.contact.getAddressBooks(addressBookSuccessCallback,errorCallback);

3.6. ContactProperties

Interface used for contact creation and as the basis of a filter for contact searching. 

        [NoInterfaceObject] interface ContactProperties {

                attribute DOMString name;

                attribute StringArray nicknames;

                attribute ContactAddressArray addresses;

                attribute DOMString photoURI; 

                attribute PhoneNumberArray phoneNumbers;

                attribute EmailAddressArray emails;

        };

This interface is intended to be used for input parameters for contact creation (createContact) and for input parameters for contact searching (findContacts).

It includes methods to get a specific property and to set the available properties to use in the findContacts filter, addContact and updateContact methods.

All the attributes are optional and by default are undefined.

Attributes

DOMString name

Name of the contact.

Code example
        var contact = addressBook.createContact();
        contact.name = "Guillermo";
StringArray nicknames

Nickname of the contact.

In case multiple nicknames are available the first one is the default one

Code example
        var contact = addressBook.createContact();
        contact.nicknames[0] = "gcaudev";
ContactAddressArray addresses

Contact addresses

In case multiple addresses are available the first one is the default one

Code example
        var contact = addressBook.createContact();
      var contactAddress = {street:"Gran Via",number:"32",postalcode:"50013",city:"Zaragoza",country:"ES"};
        contact.addresses[0] = contactAddress;
DOMString photoURI

URL to the picture of the contact.

Code example
        var contact = addressBook.createContact(null);
        contact.photoURI = "file://mydevice/store/contacts/1/guillermo.jpg";
PhoneNumberArray phoneNumbers

Telephone of the contact.

In case multiple telephones are available the first one is the default one

Code example
        var contact = addressBook.createContact(null);
      var phoneNumber = {number:"666666666"};
        contact.phoneNumbers[0] = phoneNumber;
EmailAddressArray emails

Email of the contact.

In case multiple emails are available the first one is the default one

Code example
        var contact = addressBook.createContact(null);
      var email = {email:"user@domain.com"};
        contact.emails[0] = email;

3.7. Address

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

        [NoInterfaceObject] 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',
                         nicknames:['johny'],
                       contactAddresses:[{street:"Gran Via",number:"32",postalcode:"50013",city:"Zaragoza",country:"ES"}],
                         emails:[{email:'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.8. PhoneNumber

Contains information about the phone numbers of a contact. 

        [NoInterfaceObject] interface PhoneNumber
        {
                attribute DOMString number;

                attribute StringArray types;

        };

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
        var contact = addressBook.createContact(null);
      var phoneNumber = {number:"666666666",types:['WORK','VOICE']};
        contact.phoneNumbers[0] = phoneNumber;

Attributes

DOMString number

phone Number

StringArray types

Case insensitive list of phone types as defined in RFC2426 At least the following values MUST be supported:

  • WORK - Indicates a work number
  • PREF - Indicates preferred number
  • HOME - Indicates a home number
  • VOICE - Indicates a voice number (Default)
  • FAX - Indicates a facsimile number
  • MSG - Indicates a messaging service on the number
  • CELL - Indicates a cellular number
  • PAGER - Indicates a pager number
  • BBS - Indicates a bulletin board service number
  • MODEM - Indicates a MODEM number
  • CAR - Indicates a car-phone number
  • ISDN - Indicates an ISDN number
  • VIDEO - Indicates a video-phone number
  • PCS - Personal Communication Standard

3.9. EmailAddress

Contains information about the email addresses of a contact. 

        [NoInterfaceObject] interface EmailAddress
        {
                attribute DOMString email;

                attribute StringArray types;

        };
Code example
        var contact = addressBook.createContact(null);
      var email = {email:"user@domain.com",types:['WORK','PREF']};
        contact.emails[0] = email;

Attributes

DOMString email

Email Address

StringArray types

Case insensitive list of email types At least the following values MUST be supported:

  • WORK - Indicates a work email
  • PREF - Indicates preferred email
  • HOME - Indicates a home email

3.10. ContactAddress

Contains information about the addresses of a contact. 

        [NoInterfaceObject] interface ContactAddress : Address
        {
                attribute StringArray types;

        };
Code example
        var contact = addressBook.createContact(null);
      var contactAddress = {street:"Gran Via",number:"32",postalcode:"50013",city:"Zaragoza",
                           country:"ES",types:['WORK','PREF']};
        contact.contactAddresses[0] = contactAdress;

Attributes

StringArray types

Case insensitive list of address types At least the following values MUST be supported:

  • WORK - Indicates a work address
  • PREF - Indicates preferred address
  • HOME - Indicates a home address

3.11. ContactFilter

Interface used to create Filter objects following the Contact structure. 

        [NoInterfaceObject] interface ContactFilter : GenericFilter {
        };

3.12. ContactManagerObject

Specifies what is instantiated at feature request 

        interface ContactManagerObject {
                readonly attribute ContactManager contact;
        };