Samsung Electronics logo

Samsung Web API: Contact

© 2013 Samsung Electronics Co., Ltd. All rights reserved.

Introduction

This API is for managing Address Books.

A contact is a set of information that describes a contact. The contact contains information, such as phone numbers, e-mail addresses, etc.

RFC 2426 vCard MIME Directory Profile defines a format for exchanging contacts. Contact API refers to this specification to provide a mapping of the specified contact attributes.

A person is a set of information that describes a person. Two different contacts that indicate the same person will have the same person ID. A person has a display contact ID that indicates a contact that represents information of the person. A person is automatically created when a new contact is added.

This API provides functionality to read, create, remove, and update contacts in specific address books. Address books can be obtained using the getAddressBooks() method, which returns an array of AddressBook objects.

For more information on the Contact features, see Contact Guide.

Table of Contents

Summary of Interfaces and Methods

Interface Method
ContactManagerObject
ContactManager void getAddressBooks(AddressBookArraySuccessCallback successCallback, ErrorCallback? errorCallback)
AddressBook getUnifiedAddressBook()
AddressBook getDefaultAddressBook()
AddressBook getAddressBook(AddressBookId addressBookId)
Person get(PersonId personId)
void update(Person person)
void updateBatch(Person[] persons, SuccessCallback? successCallback, ErrorCallback? errorCallback)
void remove(PersonId personId)
void removeBatch(PersonId[] personIds, SuccessCallback? successCallback, ErrorCallback? errorCallback)
void find(PersonArraySuccessCallback successCallback, ErrorCallback? errorCallback, AbstractFilter? filter, SortMode? sortMode)
long addChangeListener(PersonsChangeCallback successCallback)
void removeChangeListener(long watchId)
AddressBook Contact get(ContactId id)
void add(Contact contact)
void addBatch(Contact[] contacts, ContactArraySuccessCallback? successCallback, ErrorCallback? errorCallback)
void update(Contact contact)
void updateBatch(Contact[] contacts, SuccessCallback? successCallback, ErrorCallback? errorCallback)
void remove(ContactId id)
void removeBatch(ContactId[] ids, SuccessCallback? successCallback, ErrorCallback? errorCallback)
void find(ContactArraySuccessCallback successCallback, ErrorCallback? errorCallback, AbstractFilter? filter, SortMode? sortMode)
long addChangeListener(AddressBookChangeCallback successCallback, ErrorCallback? errorCallback)
void removeChangeListener(long watchId)
ContactGroup getGroup(ContactGroupId groupId)
void addGroup(ContactGroup group)
void updateGroup(ContactGroup group)
void removeGroup(ContactGroupId groupId)
ContactGroup[] getGroups()
Person void link(PersonId personId)
Person unlink(ContactId contactId)
ContactInit
Contact DOMString convertToString(ContactTextFormat? format)
Contact clone()
ContactRef
ContactNameInit
ContactName
ContactOrganizationInit
ContactOrganization
ContactWebSite
ContactAnniversary
ContactAddressInit
ContactAddress
ContactPhoneNumber
ContactEmailAddress
ContactGroup
PersonArraySuccessCallback void onsuccess(Person[] persons)
ContactArraySuccessCallback void onsuccess(Contact[] contacts)
AddressBookArraySuccessCallback void onsuccess(AddressBook[] addressbooks)
AddressBookChangeCallback void oncontactsadded(Contact[] contacts)
void oncontactsupdated(Contact[] contacts)
void oncontactsremoved(ContactId[] contactIds)
PersonsChangeCallback void onpersonsadded(Person[] persons)
void onpersonsupdated(Person[] persons)
void onpersonsremoved(PersonId[] personIds)

1. Type Definitions

1.1. AddressBookId

The address book identifier. 

  typedef DOMString AddressBookId;

1.2. ContactId

The contact identifier. 

  typedef DOMString ContactId;

1.3. PersonId

The person identifier. 

  typedef DOMString PersonId;

1.4. ContactGroupId

The group identifier. 

  typedef DOMString ContactGroupId;

1.5. ContactTextFormat

An enumerator that indicates the contact format that is used for export. * The possible values are: 

  enum ContactTextFormat {"VCARD_30"};
  • VCARD_30 - vCard v3.0 format

Currently, vCard v3.0 is the only format supported.

2. Interfaces

2.1. ContactManagerObject

Defines what is instantiated by the webapis object. 

  [NoInterfaceObject] interface ContactManagerObject {
    readonly attribute ContactManager contact;
  };
  WebAPIs implements ContactManagerObject;

There is a webapis.contact object that allows access to the Contact API functionality.

2.2. ContactManager

This interface provides access to the API functionality. 

  [NoInterfaceObject] interface ContactManager {

    void getAddressBooks(AddressBookArraySuccessCallback successCallback,
                         optional ErrorCallback? errorCallback) raises(WebAPIException);

    AddressBook getUnifiedAddressBook() raises(WebAPIException);

    AddressBook getDefaultAddressBook() raises(WebAPIException);

    AddressBook getAddressBook(AddressBookId addressBookId) raises(WebAPIException);

    Person get(PersonId personId) raises(WebAPIException);

    void update(Person person) raises(WebAPIException);

    void updateBatch(Person[] persons,
                     optional SuccessCallback? successCallback,
                     optional ErrorCallback? errorCallback) raises(WebAPIException);

    void remove(PersonId personId) raises(WebAPIException);

    void removeBatch(PersonId[] personIds,
                     optional SuccessCallback? successCallback,
                     optional ErrorCallback? errorCallback) raises(WebAPIException);

    void find(PersonArraySuccessCallback successCallback,
              optional ErrorCallback? errorCallback,
              optional AbstractFilter? filter,
              optional SortMode? sortMode) raises(WebAPIException);

    long addChangeListener(PersonsChangeCallback successCallback) raises(WebAPIException);

    void removeChangeListener(long watchId) raises(WebAPIException);
  };

This interface offers a method to retrieve the address books objects. The address book objects can be manipulated with the provided functionalities to add, remove, and update the contained information.

METHODS

getAddressBooks

Gets the available address books.

Signature
void getAddressBooks(AddressBookArraySuccessCallback successCallback, optional ErrorCallback? errorCallback);

If the operation completes successfully, the successCallback must be invoked with the phone address book and the SIM address book (if any). Other address books present in the device should also be returned.

If no address book is present, the successCallback will be invoked with an empty array.

The errorCallback is launched with these error types:

  • InvalidValuesError - If the event given in argument is not a recurring event.
  • UnknownError - If any other error occurs while trying to get the address books.
Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: AddressBookArraySuccessCallback.
    • Description: The method to call when the invocation ends successfully.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: The method to call when an error occurs.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
  var addressbook;

  // Define the error callback for all the asynchronous calls
  function errorCB(err) {
    console.log( 'The following error occurred: ' +  err.name);
  }

  function contactsFoundCB(contacts) {
    // The contact has been successfully found
    // Let's try to change the first name
    contacts[0].name.firstName = 'Jeffrey Ross';
    try {
      addressbook.update(contacts[0]);
    } catch (err) {
      console.log( 'The following error occurred while updating: ' +  err.name);
    }
    console.log('First contact was updated');
  }

  // Define the success callback for retrieving all the
  // Address Books
  function addressBooksCB(addressbooks) {
    if(addressbooks.length > 0) {
      addressbook = addressbooks[0];
      console.log('The addressbook type is ' + addressbook.type +
            ' and name ' + addressbook.name);

      var contact = new webapis.Contact(
                         {name: new webapis.ContactName({firstName:'Jeffrey',
                                 lastName:'Hyman',
                                 nicknames:['joey ramone']}),
                          emails:[new webapis.ContactEmailAddress('user@domain.com')],
                          phoneNumbers:[new webapis.ContactPhoneNumber('123456789')]});

      addressbook.add(contact);

      // The contact has been successfully added
      // Checks whether the added contact can be retrieved from the address book or not.
      // If the address book is empty, only the item added through saveContact
      // should be returned
      var filter = new webapis.AttributeFilter('name.firstName', 'CONTAINS', 'Jeffrey');
      try {
        addressbook.find(contactsFoundCB, errorCB, filter);
      } catch (err) {
        console.log( 'The following error occurred while finding: ' +  err.name);
      }
    }
  }

  // Get a list of available address books.
  webapis.contact.getAddressBooks(addressBooksCB, errorCB);

getUnifiedAddressBook

Gets the aggregation of all address books.

Signature
AddressBook getUnifiedAddressBook();

The unified address book is a logical address book that represents an aggregation of all address books that are obtained by getAddressBooks() and contains all contacts in the address books. Note that the unified address book does not have an address book ID and it is set to null.

Return value
AddressBook The unified AddressBook object.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

Code example
  var addressbook;

  // Define the error callback
  function errorCB(err) {
    console.log( 'The following error occurred: ' +  err.name);
  }

  function contactsFoundCB(contacts) {
    // The contact has been successfully found
    // Let's try to change the first name
    contacts[0].name.firstName = 'Jeffrey Ross';
    try {
      addressbook.update(contacts[0]);
      console.log('First contact was updated');
    } catch (err) {
      console.log( 'The following error occurred while updating: ' +  err.name);
    }
  }

  // Get unified address book.
  addressbook = webapis.contact.getUnifiedAddressBook();

  // Add a new contact
  var contact = new webapis.Contact(
                     {name: new webapis.ContactName({firstName:'Jeffrey',
                             lastName:'Hyman',
                             nicknames:['joey ramone']}),
                      emails:[new webapis.ContactEmailAddress('user@domain.com')],
                      phoneNumbers:[new webapis.ContactPhoneNumber('123456789')]});

  try {
    addressbook.add(contact);
  } catch (err) {
    console.log( 'The following error occurred while adding: ' +  err.name);
  }

  // The contact has been successfully added
  // Let's try to check if we can retrieve the added
  // contact from the address book. If the address book
  // was empty only the item added through saveContact should
  // be returned
  var filter = new webapis.AttributeFiilter('name.firstName', 'CONTAINS', 'Jeffrey');
  try {
    addressbook.find(contactsFoundCB, errorCB, filter);
  } catch (err) {
    console.log( 'The following error occurred while finding: ' +  err.name);
  }

getDefaultAddressBook

Gets the default address book.

Signature
AddressBook getDefaultAddressBook();

The default address book is the appointed addressbook from platform or operator. This is one of addressBooks and it has the address book ID.

If the operation completes successfully, it must return the default address book.

Return value
AddressBook The default AddressBook object.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

Code example
  var addressbook;

  // Define the error callback
  function errorCB(err) {
    console.log( 'The following error occurred: ' +  err.name);
  }

  function contactsFoundCB(contacts) {
    // The contact has been successfully found
    // Let's try to change the first name
    contacts[0].name.firstName = 'Jeffrey Ross';
    try {
      addressbook.update(contacts[0]);
      console.log('First contact was updated');
    } catch (err) {
      console.log( 'The following error occurred while updating: ' +  err.name);
    }
  }

  // Get default address book.
  addressbook = webapis.contact.getDefaultAddressBook();

  // Add a new contact
  var contact = new webapis.Contact(
                     {name: new webapis.ContactName({firstName:'Jeffrey',
                             lastName:'Hyman',
                             nicknames:['joey ramone']}),
                      emails:[new webapis.ContactEmailAddress('user@domain.com')],
                      phoneNumbers:[new webapis.ContactPhoneNumber('123456789')]});

  try {
    addressbook.add(contact);
  } catch (err) {
    console.log( 'The following error occurred while adding: ' +  err.name);
  }

  // The contact has been successfully added
  // Checks whether the added contact can be retrieved from the address book or not.
  // If the address book is empty, only the item added
  // through em>saveContact /em>should be returned
  var filter = new webapis.AttributeFiilter('name.firstName', 'CONTAINS', 'Jeffrey');
  try {
    addressbook.find(contactsFoundCB, errorCB, filter);
  } catch (err) {
    console.log( 'The following error occurred while finding: ' +  err.name);
  }

getAddressBook

Gets the address book with the specified identifier.

Signature
AddressBook getAddressBook(AddressBookId addressBookId);

If the operation completes successfully, it must return the address book with the specified identifier.

Parameters
  • addressBookId
    • Optional: No.
    • Nullable: No.
    • Type: AddressBookId.
    • Description: The address book identifier.
Return value
AddressBook The matching AddressBook object.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

    with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    with error type NotFoundError, if there is no address book with the given identifier.

Code example
 var contactRef; // ContactRef supposed to be initialized
 try {
   // Retrieves the Contact corresponding to a given ContactRef.
   var addressBook = webapis.contact.getAddressBook(contactRef.addressBookId);
   var contact = addressBook.get(contactRef.contactId);
   console.log("Successfully resolved contact with id: " + contactRef.contactId);
 } catch(err) {
   console.log("Error: " + err.name);
 }

get

Gets the person with the specified identifier.

Signature
Person get(PersonId personId);

If the operation completes successfully, it must return the person with the specified identifier.

Parameters
  • personId
    • Optional: No.
    • Nullable: No.
    • Type: PersonId.
    • Description: The Person identifier.
Return value
Person The matching Person object.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

    with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    with error type NotFoundError, if there is no person with the given identifier.

Code example
 var contactRef; // ContactRef supposed to be initialized
 try {
   // Retrieves the Person corresponding to a Contact.
   var addressBook = webapis.contact.getAddressBook(contactRef.addressBookId);
   var contact = addressBook.get(contactRef.contactId);
   var person = webapis.contact.get(contact.personId);
   console.log("Successfully resolved person with id: " + contact.personId);
 } catch(err) {
   console.log("Error: " + err.name);
 }

update

Updates a person in the address book synchronously.

Signature
void update(Person person);
Parameters
  • person
    • Optional: No.
    • Nullable: No.
    • Type: Person.
    • Description: The person object to be updated.
Exceptions
  • WebAPIException:

    with error type UnknownError, if the person could not be updated to an unknown error.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

    with error type InvalidValuesError, if any input parameter contains invalid values.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    with error type NotFoundError, if the identifier does not match.

Code example
  // Define the error callback
  function errorCB(err) {
    console.log( 'The following error occurred: ' +  err.name);
  }

  function personsFoundCB(persons) {
    // The person has been successfully found
    // Let's try to change the isFavorite attribute
    persons[0].isFavorite = true;
    try {
      webapis.contact.update(persons[0]);
      console.log('First person was updated');
    } catch (err) {
      console.log( 'The following error occurred while updating: ' +  err.name);
    }
  }

  try {
    webapis.contact.find(personsFoundCB, errorCB);
  } catch (err) {
    console.log( 'The following error occurred while finding: ' +  err.name);
  }

updateBatch

Updates several existing persons in the contact DB asynchronously.

Signature
void updateBatch(Person[] persons, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

The errorCallback() is launched with these error types:

  • NotFoundError - If an identifier in the IDs parameter does not correspond to the id attribute of any person in the contact DB.
  • InvalidValuesError - If any of the input parameters contain an invalid value.
  • UnknownError - If any other error occurs, while trying to add the persons.

If the details of any persons cannot be updated, the error callback function that was passed in the invocation will be called.

Parameters
  • persons
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: A list of Person objects to be saved in the terminal storage.
  • successCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SuccessCallback.
    • Description: The method to call when the invocation ends successfully.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: The method to call when the request to update the details of a person fail.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

Code example
  // Define the error callback for all the asynchronous calls
  function errorCB(err) {
    console.log('The following error occurred: ' +  err.name);
  }

  function personsUpdatedCB() {
    console.log('Contacts were updated');
  }

  function personsFoundCB(persons) {
    // The person has been successfully found
    for(var i = 0; i < persons.length; i++) {
      persons[i].isFavorite = true;
    }
    try {
      webapis.contact.updateBatch(persons, personsUpdatedCB, errorCB);
    } catch (err) {
      console.log('The following error occurred while updating: ' +  err.name);
    }
  }

  try {
    webapis.contact.find(personsFoundCB, errorCB);
  } catch (err) {
    console.log('The following error occurred while finding: ' +  err.name);
  }

remove

Removes a person from the contact DB synchronously.

Signature
void remove(PersonId personId);

Removes the person that corresponds to the specified identifier and the contacts related to the person as well. This function will throw an exception if it fails to remove the specified person.

Parameters
  • personId
    • Optional: No.
    • Nullable: No.
    • Type: PersonId.
    • Description: An identifier (ID attribute) of the Person object to delete.
Exceptions
  • WebAPIException:

    with error type UnknownError, if the person could not be removed to an unknown error.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

    with error type InvalidValuesError, if any input parameter contains invalid values.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    with error type NotFoundError, if the identifier does not match any persons.

Code example
  // Define the error callback
  function errorCB(err) {
    console.log('The following error occurred: ' +  err.name);
  }

  function personsFoundCB(persons) {
    // The person has been successfully found
    if(persons.length > 0) {
      try {
        webapis.contact.remove(persons[0].id);
        console.log('First person was removed');
      } catch (err) {
        console.log('The following error occurred while removing: ' +  err.name);
      }
    } else {
      console.log( 'No persons.');
    }
  }

  try {
    webapis.contact.find(personsFoundCB, errorCB);
  } catch (err) {
    console.log( 'The following error occurred while finding: ' +  err.name);
  }

removeBatch

Removes persons from contact DB asynchronously.

Signature
void removeBatch(PersonId[] personIds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

Removes the persons that correspond to the specified identifiers as well as the contacts related to them.

The errorCallback() is launched with these error types:

  • NotFoundError - If an identifier in the personIds parameter does not correspond to the ID of any person in the contact DB. (Otherwise, the implementation will attempt to remove the contacts corresponding to these identifiers).
  • InvalidValuesError - If any of the input parameters contain an invalid value.
  • UnknownError - If any other error occurs while trying to remove the persons.
Parameters
  • personIds
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: A list of identifiers (id attribute) for the Person objects to delete.
  • successCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SuccessCallback.
    • Description: The method to call when the invocation ends successfully.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: The method to call when the request to delete persons fails.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
  // Define the error callback
  function errorCB(err) {
    console.log( 'The following error occurred: ' +  err.name);
  }

  function personsRemovedCB() {
    console.log('Contacts were removed');
  }

  function personsFoundCB(persons) {
    // The person has been successfully found
    if(persons.length > 2) {
      try {
        webapis.contact.removeBatch([persons[0].id, persons[1].id], personsRemovedCB, errorCB);
      } catch (err) {
        console.log( 'The following error occurred while removing: ' +  err.name);
      }
    } else {
      console.log( 'Not enough persons.');
    }
  }

  try {
    webapis.contact.find(personsFoundCB, errorCB);
  } catch (err) {
    console.log( 'The following error occurred while finding: ' +  err.name);
  }

find

Gets an array of all Person objects from the contact DB or the ones that match the optionally supplied filter.

Signature
void find(PersonArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional AbstractFilter? filter, optional SortMode? sortMode);

If the filter is passed and contains valid values, only those values in the address book that match the filter criteria as specified in the AbstractFilter interface will be returned in the successCallback. If no filter is passed, the filter contains any invalid values, the filter is null or undefined, then the implementation must return the full list of contact items in the successCallback. If no persons are available in the contact DB or no person matches the filter criteria, the successCallback will be invoked with an empty array.

The errorCallback() is launched with these error types:

  • InvalidValuesError - If any of the input parameters contain an invalid value.
  • UnknownError - If any other error occurs while trying to retrieve the persons.
Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: PersonArraySuccessCallback.
    • Description: The method to call when the invocation ends successfully.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: The method to call when an error occurs.
  • filter
    • Optional: Yes.
    • Nullable: Yes.
    • Type: AbstractFilter.
    • Description: A filter to select which persons are returned.
  • sortMode
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SortMode.
    • Description: A variable to determine the sort order in which the persons are returned.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
  // Define the error callback.
  function errorCB(err) {
    console.log( 'The following error occurred: ' +  err.name);
  }

  // Define the person search success callback.
  function personsFoundCB(persons) {
    console.log(persons.length + ' results found.');
  }

  // Finds all the persons in the contact DB that have the word Ramone in their display name
  var filter = new webapis.AttributeFilter('displayName', 'CONTAINS', 'Ramone');

  // The persons returned by the find() query will be sorted in the ascending order of their display name.
  var sortingMode =  new webapis.SortMode('displayName', 'ASC');
  try {
    webapis.contact.find(personsFoundCB, errorCB,
                     filter, sortingMode);
  } catch (err) {
    console.log( 'The following error occurred while finding: ' +  err.name);
  }

addChangeListener

Subscribes to receive notifications about persons' changes.

Signature
long addChangeListener(PersonsChangeCallback successCallback);

When executed, the implementation must immediately return a subscription identifier that identifies the watch operation. After returning the identifier, the watch operation is started asynchronously.

Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: PersonsChangeCallback.
    • Description: Contains the methods for different types of change notifications.
Return value
long Identifier used to clear the watch subscription.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other case.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

    with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var watcherId = 0; // watcher identifier

 var watcher = {
   onpersonsadded: function(persons) {
     console.log(persons.length + ' persons were added');
   },
   onpersonsupdated: function(persons) {
     console.log(persons.length + ' persons were updated');
   },
   onpersonsremoved: function(ids) {
     console.log(ids.length + ' persons were deleted');
   }
 };

 // registers to be notified when the persons' changes
 watcherId = webapis.contact.addChangeListener(watcher);

removeChangeListener

Unsubscribes a persons' changes watch operation.

Signature
void removeChangeListener(long watchId);

If the watchId argument is valid and corresponds to a subscription already in place, the watch process must immediately stop and no further callbacks MUST be invoked. If the watchId argument is not valid or does not correspond to a valid subscription, the method should return without any further action.

Parameters
  • watchId
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: A subscription Identifier.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

    with error type NotFoundError, if there is no listener with the given identifier.

    with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var watcherId = 0; // watcher identifier

 // Receives persons' changes
 var watcher = {
   onpersonsadded: function(persons) {
     console.log(persons.length + ' persons were added');
   },
   onpersonsupdated: function(persons) {
     console.log(persons.length + ' persons were updated');
   },
   onpersonsremoved: function(ids) {
     console.log(ids.length + ' persons were removed');
   }
 };

 // Cancel the watch operation
 function cancelWatch() {
    webapis.contact.removeChangeListener(watcherId);
 }

 // registers to be notified when the persons' changes
 watcherId = webapis.contact.addChangeListener(watcher);

2.3. AddressBook

This interface provides methods to manage an address book. 

  [NoInterfaceObject] interface AddressBook {

    readonly attribute AddressBookId? id;

    readonly attribute DOMString name;

    readonly attribute boolean readOnly;

    Contact get(ContactId id) raises(WebAPIException);

    void add(Contact contact) raises(WebAPIException);

    void addBatch(Contact[] contacts,
                  optional ContactArraySuccessCallback? successCallback,
                  optional ErrorCallback? errorCallback) raises(WebAPIException);

    void update(Contact contact) raises(WebAPIException);

    void updateBatch(Contact[] contacts,
                     optional SuccessCallback? successCallback,
                     optional ErrorCallback? errorCallback) raises(WebAPIException);

    void remove(ContactId id) raises(WebAPIException);

    void removeBatch(ContactId[] ids,
                     optional SuccessCallback? successCallback,
                     optional ErrorCallback? errorCallback) raises(WebAPIException);

    void find(ContactArraySuccessCallback successCallback,
              optional ErrorCallback? errorCallback,
              optional AbstractFilter? filter,
              optional SortMode? sortMode) raises(WebAPIException);

    long addChangeListener(AddressBookChangeCallback successCallback,
                           optional ErrorCallback? errorCallback) raises(WebAPIException);

    void removeChangeListener(long watchId) raises(WebAPIException);

    ContactGroup getGroup(ContactGroupId groupId) raises(WebAPIException);

    void addGroup(ContactGroup group) raises(WebAPIException);

    void updateGroup(ContactGroup group) raises(WebAPIException);

    void removeGroup(ContactGroupId groupId) raises(WebAPIException);

    ContactGroup[] getGroups() raises(WebAPIException);
  };

An address book is a collection of contacts and groups. This interface offers methods to manage the address book and to manipulate contacts within the address book, such as:

  • get() - To get contacts that have a specific ID
  • find() - To find contacts using filters
  • add() or addBatch() - To add contacts to a specific address book
  • update() or updateBatch() - To update contacts in a specific address book
  • remove() or removeBatch() - To remove existing contacts
  • addChangeListener() or removeChangeListener() - To watch for address book changes

This interface also offers methods to manipulate groups within the address book, such as:

  • getGroup() - To get a group having specific ID
  • getGroups() - To get groups in a specific address book
  • addGroup() - To add groups to a specific address book
  • updateGroup() - To update groups in a specific address book
  • removeGroup() - To remove existing groups

ATTRIBUTES

readonly AddressBookId? id

An attribute to uniquely identify the address book.

The value of this attribute shall be null if the address book is the unified address book.

This attribute is read-only.

readonly DOMString name

The address book descriptive name.

This attribute is read-only.

readonly boolean readOnly

An attribute to indicate if the address book is read-only.

Some on line address books cannot be edited and will have this flag set to true.

This attribute is read-only.

METHODS

get

Gets the contact with the specified identifier.

Signature
Contact get(ContactId id);

If the operation completes successfully, it must return the contact with the specified identifier.

Parameters
  • id
    • Optional: No.
    • Nullable: No.
    • Type: ContactId.
    • Description: A contact identifier.
Return value
Contact The matching Contact object.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

    with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    with error type NotFoundError, if there is no contact with the given identifier.

Code example
 var contactRef; // ContactRef supposed to be initialized
 try {
   // Retrieves the Contact corresponding to a given ContactRef.
   var addressBook = webapis.contact.getAddressBook(contactRef.addressBookId);
   var contact = addressBook.get(contactRef.contactId);
   console.log("Successfully resolved contact with id: " + contactRef.contactId);
 } catch(err) {
   console.log("Error: " + err.name);
 }

add

Adds a contact to the address book synchronously.

Signature
void add(Contact contact);

If the contact is successfully inserted in the addressbook, the Contact object will have its identifier (id attribute) set when the function returns. This operation is done successfully, new person object is also generated automatically.

If you wish to update an existing contact, call the update() method instead. If you wish to add a copy of an existing Contact object, call Contact.clone() method first and pass the clone to the add() method.

The contact shall be added to default address book if the address book is the unified address book.

Parameters
  • contact
    • Optional: No.
    • Nullable: No.
    • Type: Contact.
    • Description: A contact to be added.
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error occurs while trying to insert the contact.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

    with error type InvalidValuesError, if any input parameter contains invalid values.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
  var addressbook;

  // Get default address book
  addressbook = webapis.contact.getDefaultAddressBook();

  try {
    var contact = new webapis.Contact({name: new webapis.ContactName({firstName:'Jeffrey',
                                          lastName:'Hyman',
                                          nicknames:['joey ramone']}),
                                    emails:[new webapis.ContactEmailAddress('user@domain.com')],
                                    phoneNumbers:[new webapis.ContactPhoneNumber('123456789')]});
    addressbook.add(contact);
    console.log('Contact added with id ' + contact.id);
  } catch (err) {
    console.log( 'The following error occurred while adding: ' +  err.name);
  }

addBatch

Adds several contacts to the address book asynchronously.

Signature
void addBatch(Contact[] contacts, optional ContactArraySuccessCallback? successCallback, optional ErrorCallback? errorCallback);

If all the contacts are successfully added to the address book, the success callback will be invoked, passing the list of Contact objects that were added, with their identifier set (id attribute).

The errorCallback() is launched with these error types:

  • InvalidValuesError - If any of the input parameters contain an invalid value, the contact has any invalid value or the address book has some restrictions (such as, limitations in the size of text attributes) because of which the contact items were not added.
  • UnknownError - If any other error occurs, while trying to add the contacts.

If you wish to update an existing contact, call the update() method instead. If you wish to add a copy of an existing Contact object, call Contact.clone() method first and pass the clone to the add() method.

If any of the contacts cannot be added, the error callback function that was passed in the invocation will be called.

The contacts shall be added to local phone address book if the address book is the default address book.

Parameters
  • contacts
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: A list of contacts to add.
  • successCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ContactArraySuccessCallback.
    • Description: The method to call when the invocation ends successfully.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: The method to call when the request fails.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

Code example
  var addressbook;

  // Define the error callback
  function errorCB(err) {
    console.log( 'The following error occurred: ' +  err.name);
  }

  // Define the add contact success callback
  function contactsAddedCB(contacts) {
    console.log( contacts.length + ' contact(s) were successfully added to an Address Book' );
  };

  // Get default address book
  addressbook = webapis.contact.getDefaultAddressBook();

  var c1 = new webapis.Contact({name: new webapis.ContactName({firstName:'Jeffrey',
                             lastName:'Hyman',
                             nicknames:['joey ramone']}),
                             emails:[new webapis.ContactEmailAddress('user1@domain.com')],
                             phoneNumbers:[new webapis.ContactPhoneNumber('123456789')]});

  var c2 = new webapis.Contact({name: new webapis.ContactName({firstName:'Elton',
                             lastName:'John',
                             nicknames:['El']}),
                             emails:[new webapis.ContactEmailAddress('user2@domain.com')],
                             phoneNumbers:[new webapis.ContactPhoneNumber('987654321')]});

  try {
    addressbook.addBatch([c1, c2], contactsAddedCB, errorCB);
  } catch (err) {
    console.log( 'The following error occurred while adding: ' +  err.name);
  }

update

Updates a contact in the address book synchronously.

Signature
void update(Contact contact);
Parameters
  • contact
    • Optional: No.
    • Nullable: No.
    • Type: Contact.
    • Description: A contact object to update.
Exceptions
  • WebAPIException:

    with error type UnknownError, if the contact could not be updated to an unknown error.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

    with error type InvalidValuesError, if any input parameter contains invalid values.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    with error type NotFoundError, if the identifier does not match.

Code example
  var addressbook;

  // Define the error callback
  function errorCB(err) {
    console.log( 'The following error occurred: ' +  err.name);
  }

  function contactsFoundCB(contacts) {
    // The contact has been successfully found
    // Let's try to change the first name
    contacts[0].name.firstName = 'Christopher';
    try {
      addressbook.update(contacts[0]);
      console.log('First contact was updated');
    } catch (err) {
      console.log( 'The following error occurred while updating: ' +  err.name);
    }
  }

  // Get default address book.
  addressbook = webapis.contact.getDefaultAddressBook();

  var filter = new webapis.AttributeFilter('name.firstName', 'CONTAINS', 'Chris');
  try {
    addressbook.find(contactsFoundCB, errorCB, filter);
  } catch (err) {
    console.log( 'The following error occurred while finding: ' +  err.name);
  }

updateBatch

Updates several existing contacts in the address book asynchronously.

Signature
void updateBatch(Contact[] contacts, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

The errorCallback() is launched with these error types:

  • NotFoundError - If an identifier in the IDs parameter does not correspond to the id attribute of any contact in the address book.
  • InvalidValuesError - If any of the input parameters contain an invalid value.
  • UnknownError - If any other error occurs, while trying to add the contacts.

If any of the contacts could not be updated, the error callback function that was passed in the invocation will be called.

Parameters
  • contacts
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: A list of contact objects to be saved in the terminal storage.
  • successCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SuccessCallback.
    • Description: The method to call when the invocation ends successfully.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: The method to call when the request to update contacts fails.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

Code example
  var addressbook;

  // Define the error callback for all the asynchronous calls
  function errorCB(err) {
    console.log('The following error occurred: ' +  err.name);
  }

  function contactsUpdatedCB() {
    console.log('Contacts were updated');
  }

  function contactsFoundCB(contacts) {
    // The contact has been successfully found
    for(var i = 0; i < contacts.length; i++) {
      contacts[i].name.firstName = 'Christopher';
    }
    try {
      addressbook.updateBatch(contacts, contactsUpdatedCB, errorCB);
    } catch (err) {
      console.log('The following error occurred while updating: ' +  err.name);
    }
  }

  // Get default address book.
  addressbook = webapis.contact.getDefaultAddressBook();

  var filter = new webapis.AttributeFilter('name.firstName', 'CONTAINS', 'Chris');
  try {
    addressbook.find(contactsFoundCB, errorCB, filter);
  } catch (err) {
    console.log('The following error occurred while finding: ' +  err.name);
  }

remove

Removes a contact from the address book synchronously.

Signature
void remove(ContactId id);

Removes the contact in the address book that corresponds to the specified identifier. This function will throw an exception if it failed to remove the specified contact.

Parameters
  • id
    • Optional: No.
    • Nullable: No.
    • Type: ContactId.
    • Description: An identifier (id attribute) of the contact object to delete.
Exceptions
  • WebAPIException:

    with error type UnknownError, if the contact could not be removed to an unknown error.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

    with error type InvalidValuesError, if any input parameter contains invalid values.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    with error type NotFoundError, if the identifier does not match any contact in the address book.

Code example
  var addressbook;

  // Define the error callback
  function errorCB(err) {
    console.log('The following error occurred: ' +  err.name);
  }

  function contactsFoundCB(contacts) {
    // The contact has been successfully found
    if(contacts.length > 0) {
      try {
        addressbook.remove(contacts[0].id);
        console.log('First contact was removed');
      } catch (err) {
        console.log('The following error occurred while removing: ' +  err.name);
      }
    } else {
      console.log( 'No contacts.');
    }
  }

  // Get default address book.
  addressbook = webapis.contact.getDefaultAddressBook();

  var filter = new webapis.AttributeFilter('name.firstName', 'CONTAINS', 'Chris');
  try {
    addressbook.find(contactsFoundCB, errorCB, filter);
  } catch (err) {
    console.log( 'The following error occurred while finding: ' +  err.name);
  }

removeBatch

Removes several contacts from the address book asynchronously.

Signature
void removeBatch(ContactId[] ids, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

The errorCallback() is launched with these error types:

  • NotFoundError - If an identifier in the IDs parameter does not correspond to the id attribute of any contact in the address book (Otherwise, the implementation will attempt to remove the contacts that correspond to these identifiers).
  • InvalidValuesError - If any of the input parameters contain an invalid value.
  • UnknownError - If any other error occurs while trying to remove the contacts.
Parameters
  • ids
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: A list of identifiers (id attribute) for the contact objects to be deleted.
  • successCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SuccessCallback.
    • Description: The method to call when the invocation ends successfully.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: The method to call when the request to delete contacts fails.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
  var addressbook;

  // Define the error callback
  function errorCB(err) {
    console.log( 'The following error occurred: ' +  err.name);
  }

  function contactsRemovedCB() {
    console.log('Contacts were removed');
  }

  function contactsFoundCB(contacts) {
    // The contact has been successfully found
    if(contacts.length > 2) {
      try {
        addressbook.removeBatch([contacts[0].id, contacts[1].id], contactsRemovedCB, errorCB);
      } catch (err) {
        console.log( 'The following error occurred while removing: ' +  err.name);
      }
    } else {
      console.log( 'Not enough contacts.');
    }
  }

  // Get default address book.
  addressbook = webapis.contact.getDefaultAddressBook();

  var filter = new webapis.AttributeFilter('name.firstName', 'CONTAINS', 'Chris');
  try {
    addressbook.find(contactsFoundCB, errorCB, filter);
  } catch (err) {
    console.log( 'The following error occurred while finding: ' +  err.name);
  }

find

Finds an array of all Contact objects from the specified address book or an array of Contact objects that match the optionally supplied filter.

Signature
void find(ContactArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional AbstractFilter? filter, optional SortMode? sortMode);

If the filter is passed and contains valid values, only those values in the address book that match the filter criteria as specified in the AbstractFilter interface will be returned in the successCallback. If no filter is passed, the filter contains any invalid values, the filter is null or undefined, then the implementation MUST return the full list of contact items in the successCallback. If no contacts are available in the address book or no contact matches the filter criteria, the successCallback will be invoked with an empty array.

The errorCallback() is launched with these error types:

  • InvalidValuesError - If any of the input parameters contain an invalid value.
  • UnknownError - If any other error occurs while trying to retrieve the contacts.
Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: ContactArraySuccessCallback.
    • Description: The method to call when the invocation ends successfully.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: The method to call when an error occurs.
  • filter
    • Optional: Yes.
    • Nullable: Yes.
    • Type: AbstractFilter.
    • Description: A filter used to select which contacts are returned.
  • sortMode
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SortMode.
    • Description: A variable to determine the sort order in which the contacts are returned.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
  var addressbook;

  // Define the error callback.
  function errorCB(err) {
    console.log( 'The following error occurred: ' +  err.name);
  }

  // Define the contact search success callback.
  function contactsFoundCB(contacts) {
     console.log(contacts.length + ' results found.');
  }

  // Get default address book
  addressbook = webapis.contact.getDefaultAddressBook();

  // Find all contacts in the address book that have "Ramone" in the nick name.
  var filter = new webapis.AttributeFilter('name.nicknames', 'CONTAINS', 'Ramone');

  // The contacts returned by the find() query will be sorted by
  // ascending last name.
  var sortingMode =  new webapis.SortMode('name.lastName', 'ASC');
  try {
    addressbook.find(contactsFoundCB, errorCB,
                     filter, sortingModes);
  } catch (err) {
    console.log( 'The following error occurred while finding: ' +  err.name);
  }

addChangeListener

Subscribes to receive notifications about address book changes.

Signature
long addChangeListener(AddressBookChangeCallback successCallback, optional ErrorCallback? errorCallback);

When executed, the implementation must immediately return a subscription identifier that identifies the watch operation. After returning the identifier, the watch operation is started asynchronously.

Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: AddressBookChangeCallback.
    • Description: The method to call when different types of address book change notifications are received.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: The method to call if address book changes cannot be watched.
Return value
long An identifier used to clear the watch subscription.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other case.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

    with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var watcherId = 0; // watcher identifier
 var addressbook; // This example assumes addressbook is initialized

 var watcher = {
   oncontactsadded: function(contacts) {
     console.log(contacts.length + ' contacts were added');
   },
   oncontactsupdated: function(contacts) {
     console.log(contacts.length + ' contacts were updated');
   },
   oncontactsremoved: function(ids) {
     console.log(ids.length + ' contacts were deleted');
   }
 };

 // Registers to be notified when the address book changes
 watcherId = addressbook.addChangeListener(watcher);

removeChangeListener

Unsubscribes an address book changes watch operation.

Signature
void removeChangeListener(long watchId);

If the watchId argument is valid and corresponds to a subscription already in place, the watch process MUST immediately stop and no further callbacks MUST be invoked. If the watchId argument is not valid or does not correspond to a valid subscription, the method should return without any further action.

Parameters
  • watchId
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: A subscription identifier.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

    with error type NotFoundError, if there is no listener with the given identifier.

    with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var watcherId = 0; // watcher identifier
 var addressbook; // This example assumes addressbook is initialized

 // Receives address book changes
 var watcher = {
   oncontactsadded: function(contacts) {
     console.log(contacts.length + ' contacts were added');
   },
   oncontactsupdated: function(contacts) {
     console.log(contacts.length + ' contacts were updated');
   },
   oncontactsremoved: function(ids) {
     console.log(ids.length + ' contacts were removed');
   }
 };

 // Cancel the watch operation
 function cancelWatch() {
    addressbook.removeChangeListener(watcherId);
 }

 // registers to be notified when the address book changes
 watcherId = addressbook.addChangeListener(watcher);

getGroup

Gets the group with the specified identifier.

Signature
ContactGroup getGroup(ContactGroupId groupId);

If the operation completes successfully, it must return the group with the given identifier.

Parameters
  • groupId
    • Optional: No.
    • Nullable: No.
    • Type: ContactGroupId.
    • Description: A group identifier.
Return value
ContactGroup The matching ContactGroup object.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

    with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    with error type NotFoundError, if there is no contact with the given identifier.

Code example
 try {
   // Retrieves the Person corresponding to a Contact.
   var addressBook = webapis.contact.getAddressBook(contactRef.addressBookId);
   var contact = addressBook.get(contactRef.contactId);
   var group = addressBook.getGroup(contact.groupIds[0].id);
   console.log("Successfully resolved group with id: " + contact.groupIds[0].id);
 } catch(err) {
   console.log("Error: " + err.name);
 }

addGroup

Adds a group to the address book.

Signature
void addGroup(ContactGroup group);

If the group is successfully inserted in the addressbook, the Group object will have its identifier (id attribute) set when the function returns.

The group shall be added to local phone address book if the address book is the default address book.

Parameters
  • group
    • Optional: No.
    • Nullable: No.
    • Type: ContactGroup.
    • Description: A ContactGroup object to be added.
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error occurs while trying to insert the contact.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

    with error type InvalidValuesError, if any input parameter contains invalid values.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
  var addressbook;

  // Get address book
  var addressbooks = webapis.contact.getAddressBooks();
  addressbook = addressbooks[0];

  try {
    var group = new webapis.ContactGroup('Company');
    addressbook.addGroup(group);
    console.log('Group added with id ' + group.id);
  } catch (err) {
    console.log( 'The following error occurred while adding: ' +  err.name);
  }

updateGroup

Updates a group in the address book.

Signature
void updateGroup(ContactGroup group);
Parameters
  • group
    • Optional: No.
    • Nullable: No.
    • Type: ContactGroup.
    • Description: A ContactGroup object to be updated.
Exceptions
  • WebAPIException:

    with error type UnknownError, if the group could not be updated to an unknown error.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

    with error type InvalidValuesError, if any input parameter contains invalid values.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
  var addressbook;

  // Get address book.
  var addressbooks = webapis.contact.getAddressBooks();
  addressbook = addressbooks[0];

  try {
    groups = addressbook.getGroups();
    groups[0].name = 'Friends';
    addressbook.updateGroup(groups[0]);
    console.log('First group was updated');
  } catch (err) {
    console.log( 'The following error occurred while adding: ' +  err.name);
  }

removeGroup

Removes a group from the address book.

Signature
void removeGroup(ContactGroupId groupId);

Removes the group in the address book that corresponds to the specified identifier. This method will throw an exception if it failed to remove the specified group.

Parameters
  • groupId
    • Optional: No.
    • Nullable: No.
    • Type: ContactGroupId.
    • Description: An identifier (id attribute) of the ContactGroup object to be deleted.
Exceptions
  • WebAPIException:

    with error type UnknownError, if the group could not be removed to an unknown error.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

    with error type InvalidValuesError, if any input parameter contains invalid values.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    with error type NotFoundError, if the identifier does not match any contact in the address book.

Code example
  var addressbook;

  // Get default address book.
  var addressbooks = webapis.contact.getAddressBooks();
  addressbook = addressbooks[0];

  try {
    groups = addressbook.getGroups();
    addressbook.removeGroup(groups[0].id);
    console.log('First group was removed');
  } catch (err) {
    console.log( 'The following error occurred while finding: ' +  err.name);
  }

getGroups

Gets an array of all ContactGroup objects from the specified address book.

Signature
ContactGroup[] getGroups();
Return value
ContactGroup[] The array of ContactGroup object from this address book.
Exceptions
  • WebAPIException:

    with error type UnknownError, if the group could not be retrieved due to an unknown error.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

    with error type InvalidValuesError, if any input parameter contains invalid values.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    with error type NotFoundError, if the identifier does not match any contact in the address book.

Code example
  var addressbook;

  // Get default address book.
  var addressbooks = webapis.contact.getAddressBooks();
  addressbook = addressbooks[0];

  try {
    groups = addressbook.getGroups();
    console.log('Number of groups is ' + groups.length);
  } catch (err) {
    console.log( 'The following error occurred while finding: ' +  err.name);
  }

2.4. Person

The person object. 

  [NoInterfaceObject] interface Person {
    readonly attribute PersonId id;

    readonly attribute DOMString displayName;

    readonly attribute long contactCount;

    readonly attribute boolean hasPhoneNumber;

    readonly attribute boolean hasEmail;

    attribute boolean isFavorite;

    attribute DOMString? photoURI;

    attribute DOMString? ringtoneURI;

    attribute ContactId displayContactId;

    void link(PersonId personId) raises(WebAPIException);

    Person unlink(ContactId contactId) raises(WebAPIException);
  };

ATTRIBUTES

readonly PersonId id

The identifier of the person.

This attribute is read-only.

readonly DOMString displayName

An attribute to identify a person by storing the display name in a string. It is selected from the contacts' display names.

This attribute is read-only.

readonly long contactCount

An attribute to count the number of the contacts that belong to a person.

This attribute is read-only.

readonly boolean hasPhoneNumber

An attribute to indicate if a person has a phone number.

This attribute is read-only.

readonly boolean hasEmail

An attribute to indicate if the person has an email addresses.

This attribute is read-only.

boolean isFavorite

An attribute to indicate whether the contact is a favorite or not.

Indicates if the person was marked as Favorite or not.

By default, this attribute is set to false.

DOMString? photoURI

The URI of a picture of a person.

This attribute is used to store a URI that points to an image that can represent the person object. This attribute only contains a local file URI. Person's photoURI is bounded to linked contacts' valid photoURI. It means that if photoURI is existed, it can't become null and except linked contact's photoURI, any file can't be set as photoURI

By default, this attribute is set to null.

DOMString? ringtoneURI

An attribute to specify and store the URI of a custom ringtone for a contact.

By default, this attribute is initialized to null. This attribute only contains a local file URI.

ContactId displayContactId

The ID of a contact that represents information of the person.

The contact, this value is indicating, is used to show detailed information of the person.

METHODS

link

Aggregates another person to this person.

Signature
void link(PersonId personId);

Person is a meta object which aggregates contacts and to make a person, user should combine related contacts. For this operation, link method is provided. If "Person A" is linked to "Person B", contacts related to "Person A" are aggregated to "Person B". After this function returns, the target "Person A" is removed from DB.

Parameters
  • personId
    • Optional: No.
    • Nullable: No.
    • Type: PersonId.
    • Description: The ID of person to be merged.
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error occurs while trying to insert the contact.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

    with error type InvalidValuesError, if any input parameter contains invalid values.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
  // Define the error callback for all the asynchronous calls
  function errorCB(err) {
    console.log( 'The following error occurred: ' +  err.name);
  }

  function personsFoundCB(persons) {
    // The persons has been successfully found
    try {
      persons[0].link(persons[1].id);
      console.log('Second person was merged to the first person.');
    } catch (err) {
      console.log( 'The following error occurred while updating: ' +  err.name);
    }
  }

  try {
    webapis.contact.find(personsFoundCB, errorCB);
  } catch (err) {
    console.log( 'The following error occurred while adding: ' +  err.name);
  }

unlink

Separates a contact from this person.

Signature
Person unlink(ContactId contactId);

Person is aggregated contacts and if a user wants to detach one contact from person, unlink method is provided. Unlink is basically detaching a contact object from linked contacts so only a contact Id linked to the person can be used as the input parameter. This function returns a newly created Person object that indicates the separated contact.

Parameters
  • contactId
    • Optional: No.
    • Nullable: No.
    • Type: ContactId.
    • Description: The ID of contact to unlink.
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error occurs while trying to insert the contact.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

    with error type InvalidValuesError, if any input parameter contains invalid values.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
  var myPersonId = '1'; //ID of modified

  var addressbook; // Default addressbook
  var person;    // Existing person obtained from addressbook
  var newPerson; // New person, which will be created during unlink

  // Define the error callback.
  function errorCB(err) {
    console.log( 'The following error occurred: ' +  err.name);
  }

  // Define the contact search success callback.
  function contactsFoundCB(contacts) {
    if (contacts.length > 1) {
      try {
        // unlink first contact
        newPerson = person.unlink(contacts[0].id);
      } catch (err) {
        console.log( 'The following error occurred while unlink: ' +  err.name);
      }
    } else {
        console.log( 'Not enough contacts ');
    }
  }

  try {
    // Get person
    person = webapis.contact.get(myPersonId);

    // Get default address book
    addressbook = webapis.contact.getDefaultAddressBook();

    // Find all contacts in the default address book that personId
    // is exactly myPersonId
    var filter = new webapis.AttributeFilter('personId', 'EXACTLY', myPersonId);

    addressbook.find(contactsFoundCB, errorCB, filter);
  } catch (err) {
    console.log( 'The following error occurred while processing: ' +  err.name);
  }

2.5. ContactInit

Provides a dictionary for specifying contact attributes upon contact creation. 

  dictionary ContactInit {
    ContactName name;
    ContactAddress[] addresses;
    DOMString photoURI;
    ContactPhoneNumber[] phoneNumbers;
    ContactEmailAddress[] emails;
    Date birthday;
    ContactAnniversary[] anniversaries;
    ContactOrganization[] organizations;
    DOMString[] notes;
    ContactWebSite[] urls;
    DOMString ringtoneURI;
    ContactGroupId[] groupIds;
  };

This dictionary is used to input parameters when contacts are created.

2.6. Contact

This interface is used to create a Contact object. 

  [Constructor(optional ContactInit? ContactInitDict),
   Constructor(DOMString stringRepresentation)]
  interface Contact {
    readonly attribute ContactId? id;

    readonly attribute PersonId? personId;

    readonly attribute AddressBookId? addressBookId;

    readonly attribute Date? lastUpdated;

    readonly attribute boolean isFavorite;

    attribute ContactName? name setraises(WebAPIException);

    attribute ContactAddress[] addresses setraises(WebAPIException);

    attribute DOMString? photoURI setraises(WebAPIException);

    attribute ContactPhoneNumber[] phoneNumbers setraises(WebAPIException);

    attribute ContactEmailAddress[] emails setraises(WebAPIException);

    attribute Date? birthday setraises(WebAPIException);

    attribute ContactAnniversary[] anniversaries setraises(WebAPIException);

    attribute ContactOrganization[] organizations setraises(WebAPIException);

    attribute DOMString[] notes setraises(WebAPIException);

    attribute ContactWebSite[] urls setraises(WebAPIException);

    attribute DOMString? ringtoneURI setraises(WebAPIException);

    attribute ContactGroupId[] groupIds setraises(WebAPIException);

    DOMString convertToString(optional ContactTextFormat? format) raises(WebAPIException);

    Contact clone() raises(WebAPIException);
  };
Code example
  // Get the default address book
  var addressbook = webapis.contact.getDefaultAddressBook();

  var contact = null;

  try {
    contact = new webapis.Contact(
                      "BEGIN:VCARD\n"+
                      "VERSION:3.0\n"+
                      "N:Gump;Forrest\n"+
                      "FN:Forrest Gump\n"+
                      "ORG:Bubba Gump Shrimp Co.\n"+
                      "TITLE:Shrimp Man\n"+
                      "TEL;WORK:(111) 555-1212\n"+
                      "TEL;HOME:(404) 555-1212\n"+
                      "EMAIL;WORK;PREF:forrestgump@example.com\n"+
                      "END:VCARD");
  } catch (err) {
    console.log( 'The following error occurred while converting: ' +  err.name);
  }

  try {
    if (contact) {
      addressbook.add(contact);
      console.log('Contact was added with ID ' + contact.id);
    }
  } catch (err) {
    console.log( 'The following error occurred while adding: ' +  err.name);
  }

ATTRIBUTES

readonly ContactId? id

An attribute to identify a raw contact.

By default, this attribute is set to null.

This attribute is read-only.

readonly PersonId? personId

The identifier of the person corresponding to the raw contact.

By default, this attribute is set to null.

This attribute is read-only.

readonly AddressBookId? addressBookId

The identifier of the address book that corresponds to the raw contact. By default, this attribute is set to null.

This attribute is read-only.

readonly Date? lastUpdated

The timestamp for the last update of a contact.

Specifies revision information about the contact.

By default, this attribute is set to null. Initially, once a contact is added to an address book, this value is the same as the creation date. For more details, see RFC 2426, Section 3.6.4.

This attribute is read-only.

readonly boolean isFavorite

An attribute to indicate whether a contact is favorite or not.

This value is associated with the isFavorite attribute of Person that this contact indicates.

By default, this attribute is set to false.

This attribute is read-only.
Code example
   if (contact.isFavorite) {
     // ...
   }

ContactName? name

An attribute to store the name of a contact.

ContactAddress[] addresses

The contact addresses.

By default, this attribute is set to an empty array.

Code example
 var contactInit = {};
 var contactAddr = new webapis.ContactAddres({streetAddress:'Gran Via, 32',
                    postalCode:'50013',city:'Zaragoza',country:'ES'});
 contactInit.addresses = [contactAddr];

DOMString? photoURI

The URI to the picture of the contact.

This attribute is used to store a URI that points to an image that can represent the contact object. This attribute only contains a local file URI. See RFC 2426, Section 3.1.4.

By default, this attribute is set to null.

Code example
  var contactInit = {};
  contactInit.photoURI = 'file:///opt/media/Downloads/mypicture.jpg';

ContactPhoneNumber[] phoneNumbers

The telephone numbers of the contact.

By default, this attribute is set to empty array.

Code example
   var contactInit = {};
   var phoneNumber = new webapis.ContactPhoneNumber('123456789');
   contactInit.phoneNumbers = [phoneNumber];

ContactEmailAddress[] emails

The email addresses of the contact.

By default, this attribute is set to empty array.

Code example
   var contactInit = {};
   var email = new webapis.ContactEmailAddress('deedee@ramones.com');
   contactInit.emails = [email];

Date? birthday

The birthday of the contact.

Defines specify the birthday of the contact (see RFC 2426 - Section 3.1.5).

By default, this attribute is set to null.

Code example
   var contactInit = {};
   contactInit.birthday = new Date(1996, 4, 15);

ContactAnniversary[] anniversaries

The list of anniversaries for the contact.

Defines specify arbitrary anniversaries for the contact (in addition to the birthday).

By default, this attribute is set to empty array.

Code example
   var contactInit = {};
   var marriage_anniv = new webapis.ContactAnniversary(new Date(1976, 11, 2), 'Marriage');
   contactInit.anniversaries = [marriage_anniv];

ContactOrganization[] organizations

The organizations the contact belongs to.

Contains information related to the contact's company or organization.

For more details, see RFC 2426, Section 3.5.

DOMString[] notes

The notes associated to the contact.

To specify supplemental information or a comment related to the contact.

For more details, see RFC 2426, Section 3.6.2.

ContactWebSite[] urls

The URLs associated to the contact.

By default, this attribute is initialized to an empty array.

In case multiple URLs are available, the first one is the default one. For more details, see RFC 2426, Section 3.6.8.

DOMString? ringtoneURI

The URI to the custom ringtone for the contact.

To specify a custom ringtone for the contact.

By default, this attribute is initialized to null. This attribute only contains a local file URI scheme; For more details, see RFC 2426, Section 3.6.6.

ContactGroupId[] groupIds

The groups the contact belongs to.

To associate groups to the contact.

By default, this attribute is initialized to an empty array.

In a case where multiple categories are available, the first one is the default one. See RFC 2426, Section 3.6.1.

METHODS

convertToString

Converts the Contact item to a string format.

Signature
DOMString convertToString(optional ContactTextFormat? format);

A textual representation for the contact will be generated and returned synchronously. The export format is set via the format parameter.

Parameters
  • format
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ContactTextFormat.
    • Description: Format to use for export. If this value is null or empty, it converts to platform default format.
Return value
DOMString The string representation of the Contact item.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
  var addressbook;

  // Define the error callback.
  function errorCB(err) {
    console.log( 'The following error occurred: ' +  err.name);
  }

  // Define the contact find success callback.
  function contactsFoundCB(contacts) {
    try {
      // Convert the first contact to vCard 3.0 format
      var vcard = contacts[0].convertToString("VCARD_30");
      console.log('textual representation of the contact is: ' + vcard);
    } catch (err) {
      console.log( 'The following error occurred while converting: ' +  err.name);
    }
  }

  // Get the default address book
  addressbook = webapis.contact.getDefaultAddressBook();

  // Find all contact in the address book whose first name contains the string 'Chris'.
  var filter = new webapis.AttributeFilter('firstName', 'CONTAINS', 'Chris');
  try {
    addressbook.find(contactsFoundCB, errorCB, filter);
  } catch (err) {
    console.log( 'The following error occurred while finding: ' +  err.name);
  }

clone
Signature
Contact clone();

Creates a clone of the Contact object, detached from any address book.

The Contact object returned by the clone() method will have its identifier set to null and will be detached from any address book.

Return value
Contact A new clone of the Contact object.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

Code example
  // Get default address book.
  var addressbook = webapis.contact.getDefaultAddressBook();

  var bob = new webapis.Contact();
  bob.name = new webapis.ContactName({firstName:'Bob',
                                    lastName:'Smith'});
  addressbook.add(bob);
  var alice = bob.clone();
  contact.name.firstName = "Alice"; // Bob's wife
  addressbook.add(alice);

2.7. ContactRef

The fully-defined contact reference. 

  [Constructor(AddressBookId addressBookId, ContactId contactId)]
  interface ContactRef {
    attribute AddressBookId addressBookId;

    attribute ContactId contactId;
  };

It contains both the identifier of the address book which the contact is in, and the contact identifier within this address book.

This interface is used by other APIs to uniquely and globally identify contacts.

ATTRIBUTES

AddressBookId addressBookId

The address book identifier.

ContactId contactId

The contact identifier inside the address book.

2.8. ContactNameInit

The properties of a ContactName, to pass to the ContactName constructor. 

  dictionary ContactNameInit {
    DOMString prefix;
    DOMString suffix;
    DOMString firstName;
    DOMString middleName;
    DOMString lastName;
    DOMString[] nicknames;
    DOMString phoneticFirstName;
    DOMString phoneticLastName;
  };

See ContactName interface for more information about the members.

2.9. ContactName

This interface contains all information related to a contact name. 

  [Constructor(optional ContactNameInit? nameInitDict)]
  interface ContactName {
    attribute DOMString? prefix;

    attribute DOMString? suffix;

    attribute DOMString? firstName;

    attribute DOMString? middleName;

    attribute DOMString? lastName;

    attribute DOMString[] nicknames;

    attribute DOMString? phoneticFirstName;

    attribute DOMString? phoneticLastName;

    readonly attribute DOMString? displayName;
  };

ATTRIBUTES

DOMString? prefix

The name prefix of a contact.

By default, this attribute is initialized to null. See also RFC 2426, Section 3.1.1.

Code example
   contact.name.prefix = "Dr.";

DOMString? suffix

The name suffix of a contact.

By default, this attribute is initialized to null. See also RFC 2426, Section 3.1.1.

Code example
   contact.name.suffix = "Jr.";

DOMString? firstName

The first (given) name of a contact.

By default, this attribute is initialized to null. See also RFC 2426, Section 3.1.1.

Code example
   contact.name.firstName = 'Douglas';

DOMString? middleName

The middle name of a contact.

By default, this attribute is initialized to null. See also RFC 2426, Section 3.1.1.

Code example
   contact.name.middleName = 'Glenn';

DOMString? lastName

The last (family) name of a contact.

By default, this attribute is initialized to null. See also RFC 2426, Section 3.1.1.

Code example
   contact.name.lastName = 'Colvin';

DOMString[] nicknames

The nicknames of a contact.

The nickname is a name used instead of, or in addition to, the given name of a contact, place, or thing. It can also be used to specify a familiar form of a proper name.

By default, this attribute is initialized to an empty array.

In case multiple nicknames are available the first one is the default. See RFC 2426, Section 3.1.3.

Code example
   contact.name.nickNames = ['Dee Dee'];

DOMString? phoneticFirstName

The phonetic first name of a contact.

Describes how the first name should be pronounced. This is very important in some languages, such as Japanese, because the same 'Kanji' may have several pronunciations.

By default, this attribute is set to null.

DOMString? phoneticLastName

The phonetic last name of a contact.

Describes how the last name should be pronounced. This is very important in some languages, such as Japanese, because the same 'Kanji' may have several pronunciations.

By default, this attribute is set to null.

readonly DOMString? displayName

The display name of a contact.

The string which can be displayed to identify the contact. It is composed of the first and last names if available, otherwise, it will fall back to the most adequate field available to identify the contact (such as nickname).

By default, this attribute is set to null. Initially, once a contact is added to an address book, this value is composed.

This attribute is read-only.

2.10. ContactOrganizationInit

The properties of a ContactOrganization, to pass to the ContactOrganization constructor. 

  dictionary ContactOrganizationInit {
    DOMString name;
    DOMString department;
    DOMString title;
    DOMString role;
    DOMString logoURI;
  };

See ContactOrganization interface for information about members.

2.11. ContactOrganization

This interface contains the information about the organization or company that a contact belongs to. 

  [Constructor(optional ContactOrganizationInit? orgInitDict)]
  interface ContactOrganization {
    attribute DOMString? name;

    attribute DOMString? department;

    attribute DOMString? title;

    attribute DOMString? role;

    attribute DOMString? logoURI;
  };

By default, each of the attributes of this interface are null.

For more details, see RFC 2426, Section 3.5.

Code example
 var organization = new webapis.ContactOrganization({name: "Samsung", role: "SW Engineer"});

ATTRIBUTES

DOMString? name

The name of an organization.

For more details, see RFC 2426, Section 3.5.5.

DOMString? department

The organizational unit name.

For more details, see RFC 2426, Section 3.5.5.

DOMString? title

The job title.

To specify the job title, functional position or function (such as 'Director, Research and Development').

For more details, see RFC 2426, Section 3.5.1.

DOMString? role

An attribute to store the role, occupation, or business category (such as 'Programmer').

For more details, see RFC 2426, Section 3.5.2.

DOMString? logoURI

The URI to the logo of a company.

To specify a graphic image of a logo associated with an organization. This attribute only contains file URI Scheme; remote pictures could be loaded to local with Download API. For more details, see RFC 2426, Section 3.5.3.

2.12. ContactWebSite

The ContactWebSite object that contains the URL and the type of web site. 

  [Constructor(DOMString url, optional DOMString type)]
  interface ContactWebSite
  {
    attribute DOMString url;

    attribute DOMString type;
  };

For more details, see RFC 2426, Section 3.6.8.

Code example
  var contactInit = {}
  var blog = new webapis.ContactWebSite('http://www.domain.com', 'BLOG');
  contactInit.urls = [blog];

ATTRIBUTES

DOMString url

The URL for the contact's web site.

DOMString type

The type of web site.

At least the following values must be supported:

  • HOMEPAGE - Indicates a home page.
  • BLOG - Indicates a blog.

By default, this attribute is set to HOMEPAGE.

2.13. ContactAnniversary

This interface implements the ContactAnniversary object that contains the date and description of an anniversary. 

  [Constructor(Date date, optional DOMString? label)]
  interface ContactAnniversary
  {
    attribute Date date;

    attribute DOMString? label;
  };
Code example
  var contactInit = {}
  var marriage_anniv = new webapis.ContactAnniversary(new Date(1976, 11, 2), 'Marriage');
  contactInit.anniversaries = [marriage_anniv];

ATTRIBUTES

Date date

The date of an anniversary.

DOMString? label

The text describing an anniversary.

By default, this attribute is set to null.

2.14. ContactAddressInit

The properties of a ContactAddress to pass to the ContactAddress constructor. 

  dictionary ContactAddressInit
  {
    DOMString country;
    DOMString region;
    DOMString city;
    DOMString streetAddress;
    DOMString additionalInformation;
    DOMString postalCode;
    boolean isDefault;
    DOMString[] types;
  };

See ContactAddress interface for more information about the members.

2.15. ContactAddress

This interface contains a set of attributes that represent a particular point on the Earth's surface. 

  [Constructor(optional ContactAddressInit? addressInitDict)]
  interface ContactAddress
  {
    attribute DOMString? country;

    attribute DOMString? region;

    attribute DOMString? city;

    attribute DOMString? streetAddress;

    attribute DOMString? additionalInformation;

    attribute DOMString? postalCode;

    attribute boolean isDefault;

    attribute DOMString[] types;
  };

Except isDefault and types attributes, each of the attributes of this interface are set to null by default.

For more details, see RFC 2426, Section 3.2.1.

Code example
   var contactInit = {};
   var contactAddress = new webapis.ContactAddress({streetAddress:'Gran Via, 32',
                                                  postalCode:'50013', city:'Zaragoza',
                                                 country:'ES', types:['WORK']});
   contactInit.contactAddress = [contactAddress];

ATTRIBUTES

DOMString? country

The country of the address.

It is recommended that the country is specified using the two-letter [ISO 3166-1] code.

DOMString? region

The name of a country subdivision.

For example, State (United States) or Province (Spain).

DOMString? city

The name of the locality. For example, the city, county, town, or village.

DOMString? streetAddress

The street address, for example, building number and street name/number.

DOMString? additionalInformation

An attribute to capture any other address details that are required for an accurate address. For example, floor number, apartment number, suite name, the name of an office occupant, etc.

DOMString? postalCode

The postal code of the location (also known as the zip code in the US).

boolean isDefault

The default state of an address.

Indicates if the address was marked as default or not for the contact. The only one among addresses for a person can have default property, so that this attribute might be changed without explicit modification according to the policy of platform.

It deals with the 'pref' TYPE on RFC 2426, Section 3.2.1

By default, this attribute is set to false.

DOMString[] types

The case insensitive list of address types.

For more details, see RFC 2426, Section 3.2.1.

At least the following values must be supported:

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

By default, this attribute is set to HOME.

2.16. ContactPhoneNumber

The ContactPhoneNumber object that contains the number and the type of phone number. 

  [Constructor(DOMString number, optional DOMString[] types, optional boolean isDefault)]
  interface ContactPhoneNumber
  {
    attribute DOMString number;

    attribute boolean isDefault;

    attribute DOMString[]? types;
  };

This interface provides the phone number and the type of number, for example, work, home, car, etc., or the device subtype, for example, fax, fixed, or mobile.

For more details, see RFC 2426, Section 3.3.1

Code example
   var contactInit = {};
   var phoneNumber = new webapis.ContactPhoneNumber('123456789', ['WORK','VOICE'], true);
   contactInit.phoneNumbers = [phoneNumber];

ATTRIBUTES

DOMString number

The full phone number.

boolean isDefault

The default state of the phone number.

Indicates if the phone number was marked as default or not for the contact. The only one among phone numbers for a person can have default property, so that this attribute might be changed without explicit modification according to the policy of platform.

It deals with the 'pref' TYPE on RFC 2426, Section 3.3.1

By default, this attribute is set to false.

DOMString[]? types

The case insensitive list of phone types, as defined in RFC 2426.

Specifies the intended use of the phone number.

At least the following values must be supported:

  • WORK - Indicates a work 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

2.17. ContactEmailAddress

The ContactEmailAddress object that contains the email address and the type of email address. 

  [Constructor(DOMString email, optional DOMString[] types, optional boolean isDefault)]
  interface ContactEmailAddress
  {
    attribute DOMString email;

    attribute boolean isDefault;

    attribute DOMString[] types;
  };

For more details, see RFC 2426, Section 3.3.2.

Code example
  var contactInit = {};
  var email = new webapis.ContactEmailAddress('user@domain.com', ['WORK']);
  contactInit.emails = [email];

ATTRIBUTES

DOMString email

The full email address.

boolean isDefault

The default state of an email address.

Indicates if the email address was marked as default or not for the contact. The only one among email addresses for a person can have default property, so that this attribute might be changed without explicit modification according to the policy of platform.

It deals with the 'pref' TYPE on RFC 2426, Section 3.3.2

By default, this attribute is set to null.

DOMString[] types

The case insensitive list of email types.

Specifies the intended use of the email address.

At least the following values must be supported:

  • WORK - Indicates a work email
  • HOME - Indicates a home email
  • MOBILE - Indicates a mobile email

By default, this attribute is set to WORK.

2.18. ContactGroup

The group object. 

  [Constructor(DOMString name, optional DOMString? ringtoneURI, optional DOMString? photoURI)]
  interface ContactGroup
  {
    readonly attribute ContactGroupId? id;

    readonly attribute AddressBookId? addressBookId;

    attribute DOMString name;

    attribute DOMString? ringtoneURI;

    attribute DOMString? photoURI;

    readonly attribute DOMString readOnly;
  };
Code example
  var addressbook = null;
  var group = null;

  // Define the error callback for all the asynchronous calls
  function errorCB(err) {
    console.log( 'The following error occurred: ' +  err.name);
  }

  // Define the success callback for retrieving all the
  // Address Books
  function addressBooksCB(addressbooks) {
    addressbook = addressbooks[0];
    try {
      group = new webapis.ContactGroup('Family', 'file://opt/media/Downloads/ring.mp3');
    } catch (err) {
      console.log( 'The following error occurred while converting: ' +  err.name);
    }

    try {
      if (group) {
        addressbook.addGroup(group);
        console.log('Group was added with ID ' + group.id);
      }
    } catch (err) {
      console.log( 'The following error occurred while adding: ' +  err.name);
    }
  }

  webapis.contact.getAddressBooks(addressBooksCB, errorCB);

ATTRIBUTES

readonly ContactGroupId? id

The identifier of a group.

By default, this attribute is set to null.

This attribute is read-only.

readonly AddressBookId? addressBookId

The identifier of the address book that the group belongs to.

By default, this attribute is set to null.

This attribute is read-only.

DOMString name

The name of a group.

DOMString? ringtoneURI

The URI to the custom ringtone for a group.

To specify a custom ringtone for a group.

By default, this attribute is initialized to null. This attribute only contains a local file URI.

DOMString? photoURI

An attribute to store a URI that points to an image that can represent the Group object. This attribute only contains a local file URI.

By default, this attribute is set to null.

readonly DOMString readOnly

The flag indicating if the group can be modified / removed or not. Some groups cannot be edited if this flag sets to true.

By default, this attribute is set to false.

This attribute is read-only.

2.19. PersonArraySuccessCallback

The success callback that is used for retrieving a list of persons. 

  [Callback=FunctionOnly, NoInterfaceObject] interface PersonArraySuccessCallback {
    void onsuccess(Person[] persons);
  };

The success callback that takes an array of persons as an input argument. It is used in the asynchronous operation to get or save a list of persons.

METHODS

onsuccess

The method invoked when a list of persons is retrieved successfully.

Signature
void onsuccess(Person[] persons);
Parameters
  • persons
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: List of persons.

2.20. ContactArraySuccessCallback

The success callback that is used for saving and retrieving a list of contacts. 

  [Callback=FunctionOnly, NoInterfaceObject] interface ContactArraySuccessCallback {
    void onsuccess(Contact[] contacts);
  };

The success callback that takes an array of contacts as an input argument. It is used in the asynchronous operation to get or save a list of contacts.

METHODS

onsuccess

The method invoked when a list of contacts is retrieved successfully.

Signature
void onsuccess(Contact[] contacts);
Parameters
  • contacts
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: List of contacts. The Contacts that were successfully saved must have their identifiers set.

2.21. AddressBookArraySuccessCallback

The success callback when retrieving a list of AddressBooks. 

  [Callback=FunctionOnly, NoInterfaceObject] interface AddressBookArraySuccessCallback {
    void onsuccess(AddressBook[] addressbooks);
  };

The success callback that takes an array of AddressBooks as an input argument. It is used in the asynchronous operation to get address books.

METHODS

onsuccess

The method invoked when a list of address books is retrieved successfully.

Signature
void onsuccess(AddressBook[] addressbooks);
Parameters
  • addressbooks
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: The address books to retrieve.

2.22. AddressBookChangeCallback

The interface for specifying the methods to be called for address book change notifications. 

  [Callback, NoInterfaceObject] interface AddressBookChangeCallback {
    void oncontactsadded(Contact[] contacts);

    void oncontactsupdated(Contact[] contacts);

    void oncontactsremoved(ContactId[] contactIds);
  };

This interface specifies a set of functions that will be invoked every time an address book change occurs (contact addition/update/deletion).

METHODS

oncontactsadded

The method invoked when contacts are added to the address book.

Signature
void oncontactsadded(Contact[] contacts);
Parameters
  • contacts
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: A list of contacts to add.

oncontactsupdated

The method invoked when contacts are updated in the address book.

Signature
void oncontactsupdated(Contact[] contacts);
Parameters
  • contacts
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: A list of contacts to update.

oncontactsremoved

The method invoked when contacts are deleted from the address book.

Signature
void oncontactsremoved(ContactId[] contactIds);
Parameters
  • contactIds
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: A list of identifiers for the contacts to delete.

2.23. PersonsChangeCallback

The interface for specifying the methods to be called for change notifications. 

  [Callback, NoInterfaceObject] interface PersonsChangeCallback {
    void onpersonsadded(Person[] persons);

    void onpersonsupdated(Person[] persons);

    void onpersonsremoved(PersonId[] personIds);
  };

This interface specifies a set of functions that will be invoked every time person's list change occurs (person addition/update/deletion).

METHODS

onpersonsadded

The method invoked when persons are added to the person list.

Signature
void onpersonsadded(Person[] persons);
Parameters
  • persons
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: A list of persons to add.

onpersonsupdated

The method invoked when persons are updated in the person list.

Signature
void onpersonsupdated(Person[] persons);
Parameters
  • persons
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: A list of persons to update.

onpersonsremoved

The method invoked when persons are deleted from the person list.

Signature
void onpersonsremoved(PersonId[] personIds);
Parameters
  • personIds
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: A list of identifiers for the persons to delete.

3. Full WebIDL 

module Contact {

  typedef DOMString AddressBookId;

  typedef DOMString ContactId;

  typedef DOMString PersonId;

  typedef DOMString ContactGroupId;

  enum ContactTextFormat {"VCARD_30"};

  [NoInterfaceObject] interface ContactManagerObject {
    readonly attribute ContactManager contact;
  };
  WebAPIs implements ContactManagerObject;

  [NoInterfaceObject] interface ContactManager {

    void getAddressBooks(AddressBookArraySuccessCallback successCallback,
                         optional ErrorCallback? errorCallback) raises(WebAPIException);

    AddressBook getUnifiedAddressBook() raises(WebAPIException);

    AddressBook getDefaultAddressBook() raises(WebAPIException);

    AddressBook getAddressBook(AddressBookId addressBookId) raises(WebAPIException);

    Person get(PersonId personId) raises(WebAPIException);

    void update(Person person) raises(WebAPIException);

    void updateBatch(Person[] persons,
                     optional SuccessCallback? successCallback,
                     optional ErrorCallback? errorCallback) raises(WebAPIException);

    void remove(PersonId personId) raises(WebAPIException);

    void removeBatch(PersonId[] personIds,
                     optional SuccessCallback? successCallback,
                     optional ErrorCallback? errorCallback) raises(WebAPIException);

    void find(PersonArraySuccessCallback successCallback,
              optional ErrorCallback? errorCallback,
              optional AbstractFilter? filter,
              optional SortMode? sortMode) raises(WebAPIException);

    long addChangeListener(PersonsChangeCallback successCallback) raises(WebAPIException);

    void removeChangeListener(long watchId) raises(WebAPIException);
  };

  [NoInterfaceObject] interface AddressBook {

    readonly attribute AddressBookId? id;

    readonly attribute DOMString name;

    readonly attribute boolean readOnly;

    Contact get(ContactId id) raises(WebAPIException);

    void add(Contact contact) raises(WebAPIException);

    void addBatch(Contact[] contacts,
                  optional ContactArraySuccessCallback? successCallback,
                  optional ErrorCallback? errorCallback) raises(WebAPIException);

    void update(Contact contact) raises(WebAPIException);

    void updateBatch(Contact[] contacts,
                     optional SuccessCallback? successCallback,
                     optional ErrorCallback? errorCallback) raises(WebAPIException);

    void remove(ContactId id) raises(WebAPIException);

    void removeBatch(ContactId[] ids,
                     optional SuccessCallback? successCallback,
                     optional ErrorCallback? errorCallback) raises(WebAPIException);

    void find(ContactArraySuccessCallback successCallback,
              optional ErrorCallback? errorCallback,
              optional AbstractFilter? filter,
              optional SortMode? sortMode) raises(WebAPIException);

    long addChangeListener(AddressBookChangeCallback successCallback,
                           optional ErrorCallback? errorCallback) raises(WebAPIException);

    void removeChangeListener(long watchId) raises(WebAPIException);

    ContactGroup getGroup(ContactGroupId groupId) raises(WebAPIException);

    void addGroup(ContactGroup group) raises(WebAPIException);

    void updateGroup(ContactGroup group) raises(WebAPIException);

    void removeGroup(ContactGroupId groupId) raises(WebAPIException);

    ContactGroup[] getGroups() raises(WebAPIException);
  };

  [NoInterfaceObject] interface Person {
    readonly attribute PersonId id;

    readonly attribute DOMString displayName;

    readonly attribute long contactCount;

    readonly attribute boolean hasPhoneNumber;

    readonly attribute boolean hasEmail;

    attribute boolean isFavorite;

    attribute DOMString? photoURI;

    attribute DOMString? ringtoneURI;

    attribute ContactId displayContactId;

    void link(PersonId personId) raises(WebAPIException);

    Person unlink(ContactId contactId) raises(WebAPIException);
  };

  dictionary ContactInit {
    ContactName name;
    ContactAddress[] addresses;
    DOMString photoURI;
    ContactPhoneNumber[] phoneNumbers;
    ContactEmailAddress[] emails;
    Date birthday;
    ContactAnniversary[] anniversaries;
    ContactOrganization[] organizations;
    DOMString[] notes;
    ContactWebSite[] urls;
    DOMString ringtoneURI;
    ContactGroupId[] groupIds;
  };

  [Constructor(optional ContactInit? ContactInitDict),
   Constructor(DOMString stringRepresentation)]
  interface Contact {
    readonly attribute ContactId? id;

    readonly attribute PersonId? personId;

    readonly attribute AddressBookId? addressBookId;

    readonly attribute Date? lastUpdated;

    readonly attribute boolean isFavorite;

    attribute ContactName? name setraises(WebAPIException);

    attribute ContactAddress[] addresses setraises(WebAPIException);

    attribute DOMString? photoURI setraises(WebAPIException);

    attribute ContactPhoneNumber[] phoneNumbers setraises(WebAPIException);

    attribute ContactEmailAddress[] emails setraises(WebAPIException);

    attribute Date? birthday setraises(WebAPIException);

    attribute ContactAnniversary[] anniversaries setraises(WebAPIException);

    attribute ContactOrganization[] organizations setraises(WebAPIException);

    attribute DOMString[] notes setraises(WebAPIException);

    attribute ContactWebSite[] urls setraises(WebAPIException);

    attribute DOMString? ringtoneURI setraises(WebAPIException);

    attribute ContactGroupId[] groupIds setraises(WebAPIException);

    DOMString convertToString(optional ContactTextFormat? format) raises(WebAPIException);

    Contact clone() raises(WebAPIException);
  };

  [Constructor(AddressBookId addressBookId, ContactId contactId)]
  interface ContactRef {
    attribute AddressBookId addressBookId;

    attribute ContactId contactId;
  };

  dictionary ContactNameInit {
    DOMString prefix;
    DOMString suffix;
    DOMString firstName;
    DOMString middleName;
    DOMString lastName;
    DOMString[] nicknames;
    DOMString phoneticFirstName;
    DOMString phoneticLastName;
  };

  [Constructor(optional ContactNameInit? nameInitDict)]
  interface ContactName {
    attribute DOMString? prefix;

    attribute DOMString? suffix;

    attribute DOMString? firstName;

    attribute DOMString? middleName;

    attribute DOMString? lastName;

    attribute DOMString[] nicknames;

    attribute DOMString? phoneticFirstName;

    attribute DOMString? phoneticLastName;

    readonly attribute DOMString? displayName;
  };

  dictionary ContactOrganizationInit {
    DOMString name;
    DOMString department;
    DOMString title;
    DOMString role;
    DOMString logoURI;
  };

  [Constructor(optional ContactOrganizationInit? orgInitDict)]
  interface ContactOrganization {
    attribute DOMString? name;

    attribute DOMString? department;

    attribute DOMString? title;

    attribute DOMString? role;

    attribute DOMString? logoURI;
  };

  [Constructor(DOMString url, optional DOMString type)]
  interface ContactWebSite
  {
    attribute DOMString url;

    attribute DOMString type;
  };

  [Constructor(Date date, optional DOMString? label)]
  interface ContactAnniversary
  {
    attribute Date date;

    attribute DOMString? label;
  };

  dictionary ContactAddressInit
  {
    DOMString country;
    DOMString region;
    DOMString city;
    DOMString streetAddress;
    DOMString additionalInformation;
    DOMString postalCode;
    boolean isDefault;
    DOMString[] types;
  };

  [Constructor(optional ContactAddressInit? addressInitDict)]
  interface ContactAddress
  {
    attribute DOMString? country;

    attribute DOMString? region;

    attribute DOMString? city;

    attribute DOMString? streetAddress;

    attribute DOMString? additionalInformation;

    attribute DOMString? postalCode;

    attribute boolean isDefault;

    attribute DOMString[] types;
  };

  [Constructor(DOMString number, optional DOMString[] types, optional boolean isDefault)]
  interface ContactPhoneNumber
  {
    attribute DOMString number;

    attribute boolean isDefault;

    attribute DOMString[]? types;
  };

  [Constructor(DOMString email, optional DOMString[] types, optional boolean isDefault)]
  interface ContactEmailAddress
  {
    attribute DOMString email;

    attribute boolean isDefault;

    attribute DOMString[] types;
  };

  [Constructor(DOMString name, optional DOMString? ringtoneURI, optional DOMString? photoURI)]
  interface ContactGroup
  {
    readonly attribute ContactGroupId? id;

    readonly attribute AddressBookId? addressBookId;

    attribute DOMString name;

    attribute DOMString? ringtoneURI;

    attribute DOMString? photoURI;

    readonly attribute DOMString readOnly;
  };

  [Callback=FunctionOnly, NoInterfaceObject] interface PersonArraySuccessCallback {
    void onsuccess(Person[] persons);
  };

  [Callback=FunctionOnly, NoInterfaceObject] interface ContactArraySuccessCallback {
    void onsuccess(Contact[] contacts);
  };

  [Callback=FunctionOnly, NoInterfaceObject] interface AddressBookArraySuccessCallback {
    void onsuccess(AddressBook[] addressbooks);
  };

  [Callback, NoInterfaceObject] interface AddressBookChangeCallback {
    void oncontactsadded(Contact[] contacts);

    void oncontactsupdated(Contact[] contacts);

    void oncontactsremoved(ContactId[] contactIds);
  };

  [Callback, NoInterfaceObject] interface PersonsChangeCallback {
    void onpersonsadded(Person[] persons);

    void onpersonsupdated(Person[] persons);

    void onpersonsremoved(PersonId[] personIds);
  };
};