Contact API

The Contact API provides functionality for managing address books.

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

RFC 2426 vCard MIME Directory Profile defines a format for exchanging contacts. The 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.

Since: 1.0

Table of Contents


Summary of Interfaces and Methods

Interface Method
ContactManagerObject
ContactManager
void getAddressBooks (AddressBookArraySuccessCallback successCallback, optional ErrorCallback? errorCallback)
void addAddressBook (AddressBook addressBook)
void removeAddressBook (AddressBookId addressBookId)
Person get (PersonId personId)
void update (Person person)
void updateBatch (Person[] persons, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)
void remove (PersonId personId)
void removeBatch (PersonId[] personIds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)
void find (PersonArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional AbstractFilter? filter, optional SortMode? sortMode)
void findByUsageCount (ContactUsageCountFilter filter, PersonArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional SortModeOrder? sortModeOrder, optional unsigned long limit, optional unsigned long offset)
void removeChangeListener (long watchId)
AddressBook
void add (Contact contact)
void addBatch (Contact[] contacts, optional ContactArraySuccessCallback? successCallback, optional ErrorCallback? errorCallback)
void update (Contact contact)
void updateBatch (Contact[] contacts, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)
void remove (ContactId id)
void removeBatch (ContactId[] ids, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)
void find (ContactArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional AbstractFilter? filter, optional SortMode? sortMode)
long addChangeListener (AddressBookChangeCallback successCallback, optional ErrorCallback? errorCallback)
void removeChangeListener (long watchId)
void addGroup (ContactGroup group)
Person
void link (PersonId personId)
Person unlink (ContactId contactId)
long getUsageCount (optional ContactUsageType? type)
void resetUsageCount (optional ContactUsageType? type)
ContactInit
Contact
DOMString convertToString (optional ContactTextFormat? format)
ContactRef
ContactNameInit
ContactName
ContactOrganizationInit
ContactOrganization
ContactWebSite
ContactAnniversary
ContactAddressInit
ContactAddress
ContactPhoneNumber
ContactEmailAddress
ContactInstantMessenger
ContactGroup
ContactRelationship
ContactExtensionInit
ContactExtension
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;

Since: 1.0

1.2. ContactId

The contact identifier.
  typedef DOMString ContactId;

Since: 1.0

1.3. PersonId

The person identifier.
  typedef DOMString PersonId;

Since: 2.0

1.4. ContactGroupId

The group identifier.
  typedef DOMString ContactGroupId;

Since: 2.0

1.5. ContactUsageCountFilter

Type of filter.
  typedef (AttributeFilter or AttributeRangeFilter) ContactUsageCountFilter;

Since: 3.0

1.6. ContactTextFormat

Specifies the contact formats used for export. The possible values are:
  enum ContactTextFormat { "VCARD_30" };

Since: 1.0

  • VCARD_30 - vCard v3.0 format

Currently, vCard v3.0 is the only format supported by the Tizen platform.

1.7. ContactRelationshipType

Specifies the relationship types. The possible values are:
  enum ContactRelationshipType { "OTHER", "ASSISTANT", "BROTHER", "CHILD", "DOMESTIC_PARTNER", "FATHER", "FRIEND", "MANAGER", "MOTHER",
    "PARENT", "PARTNER", "REFERRED_BY", "RELATIVE", "SISTER", "SPOUSE", "CUSTOM" };

Since: 2.3

  • ASSISTANT - The relation type for an assistant
  • BROTHER - The relation type for a brother
  • CHILD - The relation type for a child
  • DOMESTIC_PARTNER - The relation type for a domestic partner
  • FATHER - The relation type for a father
  • FRIEND - The relation type for a friend
  • MANAGER - The relation type for a manager
  • MOTHER - The relation type for a mother
  • PARENT - The relation type for a parent
  • PARTNER - The relation type for a partner
  • REFERRED_BY - The relation type for referred-by
  • RELATIVE - The relation type for a relative
  • SISTER - The relation type for a sister
  • SPOUSE - The relation type for a spouse
  • OTHER - Any other relationship
  • CUSTOM - Custom relationship. The actual type can be set in the label.

1.8. ContactInstantMessengerType

Specifies instant messenger types. The possible values are:
  enum ContactInstantMessengerType { "OTHER", "GOOGLE", "WLM", "YAHOO", "FACEBOOK", "ICQ", "AIM", "QQ", "JABBER", "SKYPE", "IRC",
    "CUSTOM" };

Since: 2.3

  • GOOGLE - The IM service provider name for Google Talk
  • WLM - The IM service provider name for Windows Live Messenger
  • YAHOO - The IM service provider name for Yahoo! Messenger
  • FACEBOOK - The IM service provider name for Facebook Messenger
  • ICQ - The IM service provider name for ICQ
  • AIM - The IM service provider name for AOL Instant Messenger
  • QQ - The IM service provider name for QQ
  • JABBER - The IM service provider name for Jabber
  • SKYPE - The IM service provider name for Skype
  • IRC - The IM service provider name for IRC
  • OTHER - Any other IM service provider
  • CUSTOM - Custom IM service provider. The actual type can be set in the label.

1.9. ContactUsageType

Specifies contact usage types. The possible values are:
  enum ContactUsageType { "OUTGOING_CALL", "OUTGOING_MSG", "OUTGOING_EMAIL", "INCOMING_CALL", "INCOMING_MSG", "INCOMING_EMAIL",
    "MISSED_CALL", "REJECTED_CALL", "BLOCKED_CALL", "BLOCKED_MSG" };

Since: 3.0

  • OUTGOING_CALL - outgoing call usage type
  • OUTGOING_MSG - outgoing message usage type
  • OUTGOING_EMAIL - outgoing email usage type
  • INCOMING_CALL - incoming call usage type
  • INCOMING_MSG - incoming message usage type
  • INCOMING_EMAIL - incoming email usage type
  • MISSED_CALL - missed call usage type
  • REJECTED_CALL - rejected call usage type
  • BLOCKED_CALL - blocked call usage type
  • BLOCKED_MSG - blocked message usage type

2. Interfaces

2.1. ContactManagerObject

The ContactManagerObject interface defines what is instantiated by the Tizen object from the Tizen Platform.
  [NoInterfaceObject] interface ContactManagerObject {
    readonly attribute ContactManager contact;
  };
  Tizen implements ContactManagerObject;

Since: 1.0

The tizen.contact object allows access to the Contact API functionality.

Attributes

  • readonly ContactManager contact
    Object representing a contact manager.

    Since: 1.0

2.2. ContactManager

The ContactManager interface provides access to the Contact API functionality.
  [NoInterfaceObject] interface ContactManager {
    void getAddressBooks(AddressBookArraySuccessCallback successCallback, optional ErrorCallback? errorCallback)
                         raises(WebAPIException);
    AddressBook getUnifiedAddressBook() raises(WebAPIException);
    AddressBook getDefaultAddressBook() raises(WebAPIException);
    void addAddressBook(AddressBook addressBook) raises(WebAPIException);
    void removeAddressBook(AddressBookId addressBookId) 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);
    void findByUsageCount(ContactUsageCountFilter filter, PersonArraySuccessCallback successCallback,
                          optional ErrorCallback? errorCallback, optional SortModeOrder? sortModeOrder, optional unsigned long limit,
                          optional unsigned long offset) raises(WebAPIException);
    long addChangeListener(PersonsChangeCallback successCallback) raises(WebAPIException);
    void removeChangeListener(long watchId) raises(WebAPIException);
  };

Since: 1.0

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.
void getAddressBooks(AddressBookArraySuccessCallback successCallback, optional ErrorCallback? errorCallback);

Since: 1.0

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 method is launched with these error types:

  • UnknownError - If any error occurs while trying to get the address books

Privilege level: public

Privilege: http://tizen.org/privilege/contact.read

Parameters:

  • successCallback: Callback method to be invoked when the invocation ends successfully.
  • errorCallback [optional] [nullable]: Callback method to be invoked when an error occurs.

Exceptions:

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

Code example:

var addressbook;

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

function contactsFoundCB(contacts)
{
  /* Contact is successfully found. */
  /* Tries 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");
}

/* Defines 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 tizen.Contact(
    {
      name: new tizen.ContactName(
          {firstName: "Jeffrey", lastName: "Hyman", nicknames: ["joey ramone"]}),
      emails: [new tizen.ContactEmailAddress("user@domain.com")],
      phoneNumbers: [new tizen.ContactPhoneNumber("123456789")]
    });

    addressbook.add(contact);

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

/* Gets a list of available address books. */
tizen.contact.getAddressBooks(addressBooksCB, errorCB);
getUnifiedAddressBook
Gets the aggregation of all address books.
AddressBook getUnifiedAddressBook();

Since: 2.1

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.

Privilege level: public

Privilege: http://tizen.org/privilege/contact.read

Return value:

    AddressBook: The unified AddressBook object.

Exceptions:

  • WebAPIException
    • with error type SecurityError, if the application does not have the privilege to call this method.

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

    • with error type UnknownError in any other error case.

Code example:

var addressbook;

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

function contactsFoundCB(contacts)
{
  /* Contact has been successfully found. */
  /* Tries 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);
  }
}

/* Gets the unified address book. */
addressbook = tizen.contact.getUnifiedAddressBook();

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

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

/* Contact has been successfully added. */
/* Tries to check whether the added contact can be retrieved from the address book. */
/* If the address book is empty, only the item added through saveContact should be returned. */
var filter = new tizen.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.
AddressBook getDefaultAddressBook();

Since: 1.0

The default address book is one of the addressBooks that is the appointed addressbook from platform or operator.

Privilege level: public

Privilege: http://tizen.org/privilege/contact.read

Return value:

    AddressBook: The default AddressBook object.

Exceptions:

  • WebAPIException
    • with error type SecurityError, if the application does not have the privilege to call this method.

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

    • with error type UnknownError in any other error case.

Code example:

var addressbook;

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

function contactsFoundCB(contacts)
{
  /* Contact has been successfully found. */
  /* Tries 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);
  }
}

/* Gets the default address book. */
addressbook = tizen.contact.getDefaultAddressBook();

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

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

/* Contact has been successfully added. */
/* Checks whether the added contact can be retrieved from the address book. */
/* If the address book is empty, only the item added through saveContact should be returned. */
var filter = new tizen.AttributeFiilter("name.firstName", "CONTAINS", "Jeffrey");
try
{
  addressbook.find(contactsFoundCB, errorCB, filter);
}
catch (err)
{
  console.log("The following error occurred while finding: " + err.name);
}
addAddressBook
Adds an addressbook to the contact database synchronously.
void addAddressBook(AddressBook addressBook);

Since: 2.3

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

Privilege level: public

Privilege: http://tizen.org/privilege/contact.write

Parameters:

  • addressBook: Address book to be added.

Exceptions:

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

    • with error type UnknownError, if the address book could not be inserted due to an unknown error.

Code example:

var appId = tizen.application.getCurrentApplication().appInfo.id;
tizen.account.getAccounts(
    function(accounts)
    {
      var account = accounts[0];
      if (account)
      {
        var addressbook = new tizen.AddressBook(account.id, "remote addressbook");
        tizen.contact.addAddressBook(addressbook);
      }
    },
    function(e)
    {
      console.log("Error: " + e.message);
    },
    appId);
removeAddressBook
Removes an address book from the contact database synchronously.
void removeAddressBook(AddressBookId addressBookId);

Since: 2.3

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

Privilege level: public

Privilege: http://tizen.org/privilege/contact.write

Parameters:

  • addressBookId: Identifier (id attribute) of the address book object to delete.

Exceptions:

  • WebAPIException
    • with error type NotFoundError, if the identifier does not match any address book.

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

    • with error type InvalidValuesError, if specified addressBookId is an id of default address book.

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

    • with error type UnknownError, if the address book could not be removed due to an unknown error.

Code example:

var appId = tizen.application.getCurrentApplication().appInfo.id;
tizen.account.getAccounts(
    function(accounts)
    {
      var account = accounts[0];
      if (account)
      {
        var addressbook = new tizen.AddressBook(account.id, "remote addressbook");
        tizen.contact.addAddressBook(addressbook);
        tizen.contact.removeAddressBook(addressbook.id);
      }
    },
    function(e)
    {
      console.log("Error: " + e.message);
    },
    appId);
getAddressBook
Gets the address book with the specified identifier.
AddressBook getAddressBook(AddressBookId addressBookId);

Since: 1.0

Privilege level: public

Privilege: http://tizen.org/privilege/contact.read

Parameters:

  • addressBookId: Address book identifier.

Return value:

    AddressBook: The matching AddressBook object.

Exceptions:

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

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

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

    • with error type UnknownError in case of any other error.

Code example:

var contactRef;  /* ContactRef supposed to be initialized. */
try
{
  /* Retrieves the Contact corresponding to a given ContactRef. */
  var addressBook = tizen.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.
Person get(PersonId personId);

Since: 2.0

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

Privilege level: public

Privilege: http://tizen.org/privilege/contact.read

Parameters:

  • personId: Person identifier.

Return value:

    Person: The matching Person object.

Exceptions:

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

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

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

    • with error type UnknownError in any other error case.

Code example:

var contactRef;  /* ContactRef supposed to be initialized. */
try
{
  /* Retrieves the Person corresponding to a Contact. */
  var addressBook = tizen.contact.getAddressBook(contactRef.addressBookId);
  var contact = addressBook.get(contactRef.contactId);
  var person = tizen.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.
void update(Person person);

Since: 2.0

Privilege level: public

Privilege: http://tizen.org/privilege/contact.write

Parameters:

  • person: Person object to be updated.

Exceptions:

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

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

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

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

Code example:

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

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

try
{
  tizen.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.
void updateBatch(Person[] persons, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

Since: 2.0

The ErrorCallback method 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.

Privilege level: public

Privilege: http://tizen.org/privilege/contact.write

Parameters:

  • persons: List of Person objects to be saved in the terminal storage.
  • successCallback [optional] [nullable]: Callback method to be invoked when the invocation ends successfully.
  • errorCallback [optional] [nullable]: Callback method to be invoked when the request to update the details of a person fails.

Exceptions:

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

Code example:

/* Defines 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
  {
    tizen.contact.updateBatch(persons, personsUpdatedCB, errorCB);
  }
  catch (err)
  {
    console.log("The following error occurred while updating: " + err.name);
  }
}

try
{
  tizen.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.
void remove(PersonId personId);

Since: 2.0

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.

Privilege level: public

Privilege: http://tizen.org/privilege/contact.write

Parameters:

  • personId: Identifier (id attribute) of the Person object to delete.

Exceptions:

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

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

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

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

Code example:

/* Defines 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
    {
      tizen.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
{
  tizen.contact.find(personsFoundCB, errorCB);
}
catch (err)
{
  console.log("The following error occurred while finding: " + err.name);
}
removeBatch
Removes persons from contact DB asynchronously.
void removeBatch(PersonId[] personIds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

Since: 2.0

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

The ErrorCallback method 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.

Privilege level: public

Privilege: http://tizen.org/privilege/contact.write

Parameters:

  • personIds: List of identifiers (id attribute) for the Person objects to delete.
  • successCallback [optional] [nullable]: Callback method to be invoked when the invocation ends successfully.
  • errorCallback [optional] [nullable]: Callback method to be invoked when the request to delete persons fails.

Exceptions:

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

Code example:

/* Defines 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
    {
      tizen.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
{
  tizen.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.
void find(PersonArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional AbstractFilter? filter,
          optional SortMode? sortMode);

Since: 2.0

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

Privilege level: public

Privilege: http://tizen.org/privilege/contact.read

Parameters:

  • successCallback: Callback method to be invoked when the invocation ends successfully.
  • errorCallback [optional] [nullable]: Callback method to be invoked when an error occurs.
  • filter [optional] [nullable]: Filter to select the persons returned.
  • sortMode [optional] [nullable]: Variable to determine the sort order in which the persons are returned.

Exceptions:

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

Code example:

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

/* Defines 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 tizen.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 tizen.SortMode("displayName", "ASC");
try
{
  tizen.contact.find(personsFoundCB, errorCB, filter, sortingMode);
}
catch (err)
{
  console.log("The following error occurred while finding: " + err.name);
}
findByUsageCount
Gets an array of Person objects from the contact DB which match the supplied filter. This method is for filtering usageCount property of Person objects.
void findByUsageCount(ContactUsageCountFilter filter, PersonArraySuccessCallback successCallback,
                      optional ErrorCallback? errorCallback, optional SortModeOrder? sortModeOrder, optional unsigned long limit,
                      optional unsigned long offset);

Since: 3.0

If the filter is passed and contains valid value, only this value in the address book that match the filter criteria as specified in the ContactUsageCountFilter interface will be returned 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 attributeName in filter must be one of ContactUsageType value.

The ErrorCallback method is launched with these error types:

  • InvalidValuesError - If any of the input parameters contain an invalid value.

Privilege level: public

Privilege: http://tizen.org/privilege/contact.read

Parameters:

  • filter: Filter to select the persons returned.
  • successCallback: Callback method to be invoked when the invocation ends successfully.
  • errorCallback [optional] [nullable]: Callback method to be invoked when an error occurs.
  • sortModeOrder [optional] [nullable]: Variable to determine the sort order in which the persons are returned. Default is "ASC".
  • limit [optional]: Value, that determines limit for returned array size. By default, method would return all found records.
  • offset [optional]: Value, that determines offset of returned array. By default, offset is 0.

Exceptions:

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

Code example:

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

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

/* Finds all the persons in the contact DB that have exactly five OUTGOING_CALL. */
var filter = new tizen.AttributeFilter("OUTGOING_CALL", "EXACTLY", 5);
/* Finds all the persons in the contact DB that have OUTGOING_CALL in range <0, 5>. */
/* var filter = new tizen.AttributeRangeFilter("OUTGOING_CALL", 0, 5); */
try
{
  /* Finds three most used contacts from contacts found with filter. */
  tizen.contact.findByUsageCount(filter, personsFoundCB, errorCB, "DESC", 3, 0);
  /* Finds three least used contacts from contacts found with filter. */
  /* tizen.contact.findByUsageCount(filter, personsFoundCB, errorCB, "ASC", 3, 0);. */
}
catch (err)
{
  console.log("The following error occurred while finding: " + err.name);
}

Output example:

3 results found.
addChangeListener
Subscribes to receive notifications about person changes.
long addChangeListener(PersonsChangeCallback successCallback);

Since: 2.0

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.

Privilege level: public

Privilege: http://tizen.org/privilege/contact.read

Parameters:

  • successCallback: Contains the methods for different types of change notifications.

Return value:

    long: Identifier used to clear the watch subscription.

Exceptions:

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

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

    • with error type UnknownError in any other case.

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 person changes. */
watcherId = tizen.contact.addChangeListener(watcher);
removeChangeListener
Unsubscribes to person changes watch operation.
void removeChangeListener(long watchId);

Since: 2.0

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.

Privilege level: public

Privilege: http://tizen.org/privilege/contact.read

Parameters:

  • watchId: Subscription identifier.

Exceptions:

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

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

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

    • with error type UnknownError in any other error case.

Code example:

var watcherId = 0;  /* Watcher identifier. */

/* Receives person 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");
  }
};

/* Cancels the watch operation. */
function cancelWatch()
{
  tizen.contact.removeChangeListener(watcherId);
}

/* Registers to be notified of person changes. */
watcherId = tizen.contact.addChangeListener(watcher);

2.3. AddressBook

The AddressBook interface provides methods to manage an address book.
  [Constructor(AccountId accountId, DOMString name)]
  interface AddressBook {
    readonly attribute AddressBookId? id;
    readonly attribute DOMString name;
    readonly attribute boolean readOnly;
    readonly attribute AccountId? accountId;
    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);
  };

Since: 1.0

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

  • 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 the following methods to manipulate groups within the address book:

  • getGroup() - To get a group having a 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

Code example:

var appId = tizen.application.getCurrentApplication().appInfo.id;
tizen.account.getAccounts(
    function(accounts)
    {
      var account = accounts[0];
      if (account)
      {
        var addressbook = new tizen.AddressBook(account.id, "remote addressbook");

        /* "addressbook" variable is not available until it is inserted into database. */
        tizen.contact.addAddressBook(addressbook);
      }
    },
    function(e)
    {
      console.log("Error: " + e.message);
    },
    appId);

Constructors

Constructor (AccountId, DOMString)
AddressBook(AccountId accountId, DOMString name);

Attributes

  • readonly AddressBookId id [nullable]
    Unique identifier of the address book.

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

    Since: 1.0

  • readonly DOMString name
    The address book descriptive name.

    Since: 1.0

  • readonly boolean readOnly
    Indicates whether the address book is read-only.

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

    Since: 1.0

  • readonly AccountId accountId [nullable]
    Account identifier.

    Since: 2.3

Methods

get
Gets the contact with the specified identifier.

Since: 1.0

Privilege level: public

Privilege: http://tizen.org/privilege/contact.read

Parameters:

  • id: Contact identifier.

Return value:

    Contact: The matching Contact object.

Exceptions:

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

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

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

    • with error type UnknownError in any other error case.

Code example:

var contactRef;  /* ContactRef supposed to be initialized. */
try
{
  /* Retrieves the Contact corresponding to a given ContactRef. */
  var addressBook = tizen.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.
void add(Contact contact);

Since: 1.0

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, a 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 the 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.

Privilege level: public

Privilege: http://tizen.org/privilege/contact.write

Parameters:

  • contact: Contact to be added.

Exceptions:

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

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

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

Code example:

var addressbook;

/* Gets the default address book. */
addressbook = tizen.contact.getDefaultAddressBook();

try
{
  var contact = new tizen.Contact(
  {
    name: new tizen.ContactName(
        {firstName: "Jeffrey", lastName: "Hyman", nicknames: ["joey ramone"]}),
    emails: [new tizen.ContactEmailAddress("user@domain.com")],
    phoneNumbers: [new tizen.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.
void addBatch(Contact[] contacts, optional ContactArraySuccessCallback? successCallback, optional ErrorCallback? errorCallback);

Since: 1.0

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

Privilege level: public

Privilege: http://tizen.org/privilege/contact.write

Parameters:

  • contacts: List of contacts to add.
  • successCallback [optional] [nullable]: Callback method to be invoked when the invocation ends successfully.
  • errorCallback [optional] [nullable]: Callback method to be invoked when the request fails.

Exceptions:

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

Code example:

var addressbook;

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

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

/* Gets the default address book. */
addressbook = tizen.contact.getDefaultAddressBook();

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

var c2 = new tizen.Contact(
{
  name: new tizen.ContactName({firstName: "Elton", lastName: "John", nicknames: ["El"]}),
  emails: [new tizen.ContactEmailAddress("user2@domain.com")],
  phoneNumbers: [new tizen.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.
void update(Contact contact);

Since: 1.0

Privilege level: public

Privilege: http://tizen.org/privilege/contact.write

Parameters:

  • contact: Contact object to update.

Exceptions:

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

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

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

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

Code example:

var addressbook;

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

function contactsFoundCB(contacts)
{
  /* Contact has been successfully found. */
  /* Tries 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);
  }
}

/* Gets the default address book. */
addressbook = tizen.contact.getDefaultAddressBook();

var filter = new tizen.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.
void updateBatch(Contact[] contacts, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

Since: 1.0

The ErrorCallback method 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.

Privilege level: public

Privilege: http://tizen.org/privilege/contact.write

Parameters:

  • contacts: List of contact objects to be saved in the terminal storage.
  • successCallback [optional] [nullable]: Callback method to be invoked when the invocation ends successfully.
  • errorCallback [optional] [nullable]: Callback method to be invoked when the request to update contacts fails.

Exceptions:

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

Code example:

var addressbook;

/* Defines 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)
{
  /* 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);
  }
}

/* Gets the default address book. */
addressbook = tizen.contact.getDefaultAddressBook();

var filter = new tizen.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.
void remove(ContactId id);

Since: 1.0

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.

Privilege level: public

Privilege: http://tizen.org/privilege/contact.write

Parameters:

  • id: Identifier (id attribute) of the contact object to delete.

Exceptions:

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

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

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

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

Code example:

var addressbook;

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

function contactsFoundCB(contacts)
{
  /* 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");
  }
}

/* Gets the default address book. */
addressbook = tizen.contact.getDefaultAddressBook();

var filter = new tizen.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.
void removeBatch(ContactId[] ids, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

Since: 1.0

The ErrorCallback method 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.

Privilege level: public

Privilege: http://tizen.org/privilege/contact.write

Parameters:

  • ids: List of identifiers (id attribute) for the contact objects to be deleted.
  • successCallback [optional] [nullable]: Callback method to be invoked when the invocation ends successfully.
  • errorCallback [optional] [nullable]: Callback method to be invoked when the request to delete contacts fails.

Exceptions:

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

Code example:

var addressbook;

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

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

function contactsFoundCB(contacts)
{
  /* 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");
  }
}

/* Gets the default address book. */
addressbook = tizen.contact.getDefaultAddressBook();

var filter = new tizen.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.
void find(ContactArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional AbstractFilter? filter,
          optional SortMode? sortMode);

Since: 1.0

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

Privilege level: public

Privilege: http://tizen.org/privilege/contact.read

Parameters:

  • successCallback: Callback method to be invoked when the invocation ends successfully.
  • errorCallback [optional] [nullable]: Callback method to be invoked when an error occurs.
  • filter [optional] [nullable]: Filter used to select the contacts to be returned.
  • sortMode [optional] [nullable]: Sort order in which the contacts are returned.

Exceptions:

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

Code example:

var addressbook;

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

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

/* Gets the default address book. */
addressbook = tizen.contact.getDefaultAddressBook();

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

/* The contacts returned by the find() query will be sorted by */
/* ascending last name. */
var sortingMode = new tizen.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.
long addChangeListener(AddressBookChangeCallback successCallback, optional ErrorCallback? errorCallback);

Since: 1.0

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.

Privilege level: public

Privilege: http://tizen.org/privilege/contact.read

Parameters:

  • successCallback: Callback method to be invoked when different types of address book change notifications are received.
  • errorCallback [optional] [nullable]: Callback method to be invoked if address book changes cannot be watched.

Return value:

    long: An identifier used to clear the watch subscription.

Exceptions:

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

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

    • with error type UnknownError in any other case.

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 change watch operation.
void removeChangeListener(long watchId);

Since: 1.0

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.

Privilege level: public

Privilege: http://tizen.org/privilege/contact.read

Parameters:

  • watchId: Subscription identifier.

Exceptions:

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

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

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

    • with error type UnknownError in any other error case.

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

/* Cancels 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.
ContactGroup getGroup(ContactGroupId groupId);

Since: 2.0

Privilege level: public

Privilege: http://tizen.org/privilege/contact.read

Parameters:

  • groupId: Group identifier.

Return value:

    ContactGroup: The matching ContactGroup object.

Exceptions:

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

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

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

    • with error type UnknownError in any other error case.

Code example:

try
{
  /* Retrieves the Person corresponding to a Contact. */
  var addressBook = tizen.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.
void addGroup(ContactGroup group);

Since: 2.0

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.

Privilege level: public

Privilege: http://tizen.org/privilege/contact.write

Parameters:

  • group: ContactGroup object to be added.

Exceptions:

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

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

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

Code example:

var addressbook;

/* Gets the address book. */
var addressbook = tizen.contact.getDefaultAddressBook();

try
{
  var group = new tizen.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.
void updateGroup(ContactGroup group);

Since: 2.0

Privilege level: public

Privilege: http://tizen.org/privilege/contact.write

Parameters:

  • group: ContactGroup object to be updated.

Exceptions:

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

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

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

Code example:

var addressbook;

/* Gets the address book. */
var addressbook = tizen.contact.getDefaultAddressBook();

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.
void removeGroup(ContactGroupId groupId);

Since: 2.0

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.

Privilege level: public

Privilege: http://tizen.org/privilege/contact.write

Parameters:

  • groupId: Identifier (id attribute) of the ContactGroup object to be deleted.

Exceptions:

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

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

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

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

Code example:

var addressbook;

/* Gets the default address book. */
var addressbook = tizen.contact.getDefaultAddressBook();

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.
ContactGroup[] getGroups();

Since: 2.0

Privilege level: public

Privilege: http://tizen.org/privilege/contact.read

Return value:

    ContactGroup[]: The array of ContactGroup object from this address book.

Exceptions:

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

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

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

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

Code example:

var addressbook;

/* Gets the default address book. */
var addressbook = tizen.contact.getDefaultAddressBook();

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);
    long getUsageCount(optional ContactUsageType? type) raises(WebAPIException);
    void resetUsageCount(optional ContactUsageType? type) raises(WebAPIException);
  };

Since: 2.0

Attributes

  • readonly PersonId id
    The identifier of the person.

    Since: 2.0

  • readonly DOMString displayName
    The person display name as a string. It is selected from the contacts' display names.

    Since: 2.0

  • readonly long contactCount
    The count of the contacts of a person.

    Since: 2.0

  • readonly boolean hasPhoneNumber
    Indicates whether a person has a phone number.

    Since: 2.0

  • readonly boolean hasEmail
    Indicates whether the person has an email addresses.

    Since: 2.0

  • boolean isFavorite
    Indicates whether the contact is a favorite.

    Indicates whether the person was marked as Favorite.

    By default, this attribute is set to false.

    Since: 2.0

  • DOMString photoURI [nullable]
    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 exists, it cannot become null and except the linked contact's photoURI, any other file cannot be set as photoURI.

    By default, this attribute is set to null.

    Since: 2.0

  • DOMString ringtoneURI [nullable]
    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.

    Since: 2.0

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

    Since: 2.0

Methods

Aggregates another person to this person.
void link(PersonId personId);

Since: 2.0

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.

Privilege level: public

Privilege: http://tizen.org/privilege/contact.write

Parameters:

  • personId: ID of person to be merged.

Exceptions:

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

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

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

Code example:

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

function personsFoundCB(persons)
{
  /* Persons have 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
{
  tizen.contact.find(personsFoundCB, errorCB);
}
catch (err)
{
  console.log("The following error occurred while adding: " + err.name);
}
Separates a contact from this person.
Person unlink(ContactId contactId);

Since: 2.0

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.

Privilege level: public

Privilege: http://tizen.org/privilege/contact.write

Parameters:

  • contactId: ID of contact to unlink.

Return value:

    Person: Newly created Person object that indicates the separated contact

Exceptions:

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

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

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

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

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

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

/* Defines the contact search success callback. */
function contactsFoundCB(contacts)
{
  if (contacts.length > 1)
  {
    try
    {
      /* Unlinks the 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
{
  /* Gets the person. */
  person = tizen.contact.get(myPersonId);

  /* Gets the default address book. */
  addressbook = tizen.contact.getDefaultAddressBook();

  /* Finds all the contacts in the default address book with personId */
  /* as exactly myPersonId. */
  var filter = new tizen.AttributeFilter("personId", "EXACTLY", myPersonId);

  addressbook.find(contactsFoundCB, errorCB, filter);
}
catch (err)
{
  console.log("The following error occurred while processing: " + err.name);
}
getUsageCount
Gets person's usage count.
long getUsageCount(optional ContactUsageType? type);

Since: 3.0

Privilege level: public

Privilege: http://tizen.org/privilege/contact.read

Parameters:

  • type [optional] [nullable]: Type of usage to get. Null means usages of all types will be retrieved.

Return value:

    long: Number of usages.

Exceptions:

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

Code example:

var myPersonId = "1";  /* ID of person. */
var person = tizen.contact.get(myPersonId);

var outCalls = person.getUsageCount(OUTGOING_CALL);
var allUsages = person.getUsageCount();

console.log("Number of outgoing calls: " + outCalls);
console.log("Number of all usages: " + allUsages);

Output example:

Number of outgoing calls: 12
Number of all usages: 24
resetUsageCount
Resets a person's usage count.
void resetUsageCount(optional ContactUsageType? type);

Since: 3.0

If this method is successful, the person is no longer in the most frequently contacted person list.

Privilege level: public

Privilege: http://tizen.org/privilege/contact.write

Parameters:

  • type [optional] [nullable]: Type of usage to reset. Null means all usage types will be reset.

Exceptions:

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

    • with error type SecurityError, if the application does not have the privilege to call this method.

Code example:

var myPersonId = "1";  /* ID of person. */
var person = tizen.contact.get(myPersonId);
console.log("Usage count before reset: " + person.getUsageCount());
person.resetUsageCount();
console.log("Usage count after reset: " + person.getUsageCount());

Output example:

Usage count before reset: 2
Usage count after reset: 0

2.5. ContactInit

The ContactInit dictionary specifies contact attributes upon contact creation.
  dictionary ContactInit {
    ContactName name;
    ContactAddress[] addresses;
    DOMString photoURI;
    ContactPhoneNumber[] phoneNumbers;
    ContactEmailAddress[] emails;
    ContactInstantMessenger[] messengers;
    ContactRelationship[] relationships;
    ContactExtension[] extensions;
    Date birthday;
    ContactAnniversary[] anniversaries;
    ContactOrganization[] organizations;
    DOMString[] notes;
    ContactWebSite[] urls;
    DOMString ringtoneURI;
    DOMString messageAlertURI;
    DOMString vibrationURI;
    ContactGroupId[] groupIds;
  };

Since: 1.0

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

2.6. Contact

The Contact 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;
    attribute ContactAddress[] addresses;
    attribute DOMString? photoURI;
    attribute ContactPhoneNumber[] phoneNumbers;
    attribute ContactEmailAddress[] emails;
    attribute ContactInstantMessenger[] messengers;
    attribute ContactRelationship[] relationships;
    attribute ContactExtension[] extensions;
    attribute Date? birthday;
    attribute ContactAnniversary[] anniversaries;
    attribute ContactOrganization[] organizations;
    attribute DOMString[] notes;
    attribute ContactWebSite[] urls;
    attribute DOMString? ringtoneURI;
    attribute DOMString? messageAlertURI;
    attribute DOMString? vibrationURI;
    attribute ContactGroupId[] groupIds;
    DOMString convertToString(optional ContactTextFormat? format) raises(WebAPIException);
    Contact clone() raises(WebAPIException);
  };

Since: 1.0

Code example:

/* Gets the default address book. */
var addressbook = tizen.contact.getDefaultAddressBook();

var contact = null;

try
{
  contact = new tizen.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);
}

Code example:

/* Gets the default address book. */
var addressbook = tizen.contact.getDefaultAddressBook();
var contact = null;

var name = new tizen.ContactName({firstName: "Forrest", lastName: "Gump"});
var addresses =
    [new tizen.ContactAddress({city: "New York", streetAddress: "46th St.", isDefault: true})];
var phoneNumbers = [
  new tizen.ContactPhoneNumber("(111) 555-1212"), new tizen.ContactPhoneNumber("(111) 555-1213")
];

try
{
  contact = new tizen.Contact({name: name, addresses: addresses, phoneNumbers: phoneNumbers});
}
catch (err)
{
  console.log("The following error occurred while creating contact: " + 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);
}

Constructors

Constructor (ContactInit?)
Contact(optional ContactInit? ContactInitDict);
Constructor (DOMString)
Contact(DOMString stringRepresentation);

Attributes

  • readonly ContactId id [nullable]
    The identifier of a Raw contact.

    By default, this attribute is set to null.

    Since: 1.0

  • readonly PersonId personId [nullable]
    The identifier of the person corresponding to the raw contact.

    By default, this attribute is set to null.

    Since: 2.0

  • readonly AddressBookId addressBookId [nullable]
    The identifier of the address book that corresponds to the raw contact. By default, this attribute is set to null.

    Since: 2.0

  • readonly Date lastUpdated [nullable]
    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.

    Since: 1.0

  • readonly boolean isFavorite
    Indicates whether a contact is favorite.

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

    By default, this attribute is set to false.

    Since: 1.0

    Code example:

    if (contact.isFavorite)
    {
      /* ... */
    }
    
  • ContactName name [nullable]
    The name of a contact.

    Since: 1.0

  • ContactAddress[] addresses
    The contact addresses.

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

    Since: 1.0

    Code example:

    var contactInit = {};
    var contactAddr = new tizen.ContactAddress(
        {streetAddress: "Gran Via, 32", postalCode: "50013", city: "Zaragoza", country: "ES"});
    contactInit.addresses = [contactAddr];
    
  • DOMString photoURI [nullable]
    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.

    Since: 1.0

    Code example:

    var contactInit = {};
    tizen.filesystem.resolve("images/mypicture.jpg", function(imageFile)
    {
      contactInit.photoURI = imageFile.toURI();
    });
    
  • ContactPhoneNumber[] phoneNumbers
    The telephone numbers of the contact.

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

    Since: 1.0

    Code example:

    var contactInit = {};
    var phoneNumber = new tizen.ContactPhoneNumber("123456789");
    contactInit.phoneNumbers = [phoneNumber];
    
  • ContactEmailAddress[] emails
    The email addresses of the contact.

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

    Since: 1.0

    Code example:

    var contactInit = {};
    var email = new tizen.ContactEmailAddress("deedee@ramones.com");
    contactInit.emails = [email];
    
  • ContactInstantMessenger[] messengers
    The instant messenger addresses of the contact.

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

    Since: 2.3

    Code example:

    var contactInit = {};
    var messenger = new tizen.ContactInstantMessenger("user@example.com");
    contactInit.messengers = [messenger];
    
  • ContactRelationship[] relationships
    The relationships of the contact.

    The direction of relationship is: contact (owner of relationship) is a relationship type to relative name.

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

    Since: 2.3

    Code example:

    var contactInit = {};
    /* Contact is brother of "Anna". */
    var relationship = new tizen.ContactRelationship("Anna", "BROTHER");
    contactInit.relationships = [relationship];
    
  • ContactExtension[] extensions
    The extended data of the contact.

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

    Since: 3.0

    Code example:

    var contactInit = {};
    var extension = new tizen.ContactExtension({data1: 20, data2: "Place of birth: ElblÄ…g"});
    contactInit.extensions = [extension];
    
  • Date birthday [nullable]
    The birthday of the contact.

    Date specification of the birthday of the contact (see RFC 2426 Section 3.1.5).

    By default, this attribute is set to null.

    Since: 1.0

    Code example:

    var contactInit = {};
    contactInit.birthday = new Date(1996, 4, 15);
    
  • ContactAnniversary[] anniversaries
    The list of anniversaries for the contact.

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

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

    Since: 1.0

    Code example:

    var contactInit = {};
    var marriage_anniv = new tizen.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.

    Since: 1.0

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

    Since: 2.0

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

    Since: 1.0

  • DOMString ringtoneURI [nullable]
    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.

    Since: 1.0

  • DOMString messageAlertURI [nullable]
    The URI of a custom message alert for a contact.

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

    Since: 2.3

  • DOMString vibrationURI [nullable]
    The URI of a custom vibration alert for a contact.

    Vibration patterns in .ivt files are accepted. If an invalid file is set the default vibration alert will be used.

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

    Since: 2.3

  • 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 case multiple categories are available, the first one is the default one. See RFC 2426, Section 3.6.1.

    Since: 2.0

Methods

convertToString
Converts the Contact item to a string format.
DOMString convertToString(optional ContactTextFormat? format);

Since: 1.0

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

Parameters:

  • format [optional] [nullable]: 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 TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

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

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

    • with error type UnknownError in any other error case.

Code example:

var addressbook;

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

/* Defines the contact find success callback. */
function contactsFoundCB(contacts)
{
  try
  {
    /* Converts 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);
  }
}

/* Gets the default address book. */
addressbook = tizen.contact.getDefaultAddressBook();

/* Finds all contacts in the address book whose first name contains the string "Chris". */
var filter = new tizen.AttributeFilter("firstName", "CONTAINS", "Chris");
try
{
  addressbook.find(contactsFoundCB, errorCB, filter);
}
catch (err)
{
  console.log("The following error occurred while finding: " + err.name);
}
clone
Creates a clone of the Contact object, detached from any address book.
Contact clone();

Since: 1.0

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 SecurityError, if the functionality is not allowed.

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

    • with error type UnknownError in any other error case.

Code example:

/* Gets the default address book. */
var addressbook = tizen.contact.getDefaultAddressBook();

var bob = new tizen.Contact();
bob.name = new tizen.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;
  };

Since: 1.0

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.

Constructors

Constructor (AddressBookId, ContactId)
ContactRef(AddressBookId addressBookId, ContactId contactId);

Code example:

/* Gets the default address book. */
var addressbook = tizen.contact.getDefaultAddressBook();

/* Creates a new contact. */
var eve = new tizen.Contact();
eve.name = new tizen.ContactName({firstName: "Eve", lastName: "Green"});
addressbook.add(eve);

/* Creates a reference to this contact. */
var refToEve = new tizen.ContactRef(addressbook.id, eve.id);

Attributes

  • AddressBookId addressBookId
    The address book identifier.

    Since: 1.0

  • ContactId contactId
    The contact identifier inside the address book.

    Since: 1.0

2.8. ContactNameInit

The ContactNameInit dictionary defines 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 phoneticMiddleName;
    DOMString phoneticLastName;
  };

Since: 1.0

See the ContactName interface for more information about the members.

2.9. ContactName

The ContactName 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? phoneticMiddleName;
    attribute DOMString? phoneticLastName;
    readonly attribute DOMString? displayName;
  };

Since: 1.0

Constructors

Constructor (ContactNameInit?)
ContactName(optional ContactNameInit? nameInitDict);

Code example:

var myContactName = new tizen.ContactName({prefix: "Mr.", firstName: "John", lastName: "Doe"});

Attributes

  • DOMString prefix [nullable]
    The name prefix of a contact.

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

    Since: 1.0

    Code example:

    contact.name.prefix = "Dr.";
    
  • DOMString suffix [nullable]
    The name suffix of a contact.

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

    Since: 2.0

    Code example:

    contact.name.suffix = "Jr.";
    
  • DOMString firstName [nullable]
    The first (given) name of a contact.

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

    Since: 1.0

    Code example:

    contact.name.firstName = "Douglas";
    
  • DOMString middleName [nullable]
    The middle name of a contact.

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

    Since: 1.0

    Code example:

    contact.name.middleName = "Glenn";
    
  • DOMString lastName [nullable]
    The last (family) name of a contact.

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

    Since: 1.0

    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.

    Since: 1.0

    Code example:

    contact.name.nickNames = ["Dee Dee"];
    
  • DOMString phoneticFirstName [nullable]
    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.

    Since: 2.0

  • DOMString phoneticMiddleName [nullable]
    The phonetic middle name of a contact.

    Describes how the middle 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.

    Since: 2.3

  • DOMString phoneticLastName [nullable]
    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.

    Since: 2.0

  • readonly DOMString displayName [nullable]
    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.

    Since: 1.0

2.10. ContactOrganizationInit

The ContactOrganizationInit dictionary defines the properties of a ContactOrganization, to pass to the ContactOrganization constructor.
  dictionary ContactOrganizationInit {
    DOMString name;
    DOMString department;
    DOMString title;
    DOMString role;
    DOMString logoURI;
  };

Since: 1.0

See ContactOrganization interface for information about members.

2.11. ContactOrganization

The ContactOrganization 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;
  };

Since: 1.0

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 tizen.ContactOrganization({name: "Nice Company", role: "SW Engineer"});

Constructors

Constructor (ContactOrganizationInit?)
ContactOrganization(optional ContactOrganizationInit? orgInitDict);

Attributes

  • DOMString name [nullable]
    The name of an organization.

    For more details, see RFC 2426, Section 3.5.5.

    Since: 1.0

  • DOMString department [nullable]
    The organizational unit name.

    For more details, see RFC 2426, Section 3.5.5.

    Since: 1.0

  • DOMString title [nullable]
    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.

    Since: 1.0

  • DOMString role [nullable]
    An attribute to store the role, occupation, or business category (such as "Programmer").

    For more details, see RFC 2426, Section 3.5.2.

    Since: 1.0

  • DOMString logoURI [nullable]
    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.

    Since: 1.0

2.12. ContactWebSite

The ContactWebSite interface contains the URL and the type of web site.
  [Constructor(DOMString url, optional DOMString type)]
  interface ContactWebSite {
    attribute DOMString url;
    attribute DOMString type;
  };

Since: 1.0

For more details, see RFC 2426, Section 3.6.8.

Code example:

var contactInit = {};
var blog = new tizen.ContactWebSite("http://www.domain.com", "BLOG");
contactInit.urls = [blog];

Constructors

Constructor (DOMString, DOMString)
ContactWebSite(DOMString url, optional DOMString type);

Attributes

  • DOMString url
    The URL for the contact's web site.

    Since: 1.0

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

    Since: 1.0

2.13. ContactAnniversary

The ContactAnniversary interface contains the date and description of an anniversary.
  [Constructor(Date date, optional DOMString? label)]
  interface ContactAnniversary {
    attribute Date date;
    attribute DOMString? label;
  };

Since: 1.0

Code example:

var contactInit = {};
var marriage_anniv = new tizen.ContactAnniversary(new Date(1976, 11, 2), "Marriage");
contactInit.anniversaries = [marriage_anniv];

Constructors

Constructor (Date, DOMString?)
ContactAnniversary(Date date, optional DOMString? label);

Attributes

  • Date date
    The date of an anniversary.

    Since: 1.0

  • DOMString label [nullable]
    The text describing an anniversary.

    By default, this attribute is set to null.

    Since: 1.0

2.14. ContactAddressInit

The ContactAddressInit dictionary defines 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;
    DOMString label;
  };

Since: 1.0

See ContactAddress interface for more information about the members.

2.15. ContactAddress

The ContactAddress 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;
    attribute DOMString? label;
  };

Since: 1.0

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 tizen.ContactAddress(
{
  streetAddress: "Gran Via, 32",
  postalCode: "50013",
  city: "Zaragoza",
  country: "ES",
  types: ["WORK"]
});
contactInit.contactAddress = [contactAddress];

Constructors

Constructor (ContactAddressInit?)
ContactAddress(optional ContactAddressInit? addressInitDict);

Attributes

  • DOMString country [nullable]
    The country of the address.

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

    Since: 1.0

  • DOMString region [nullable]
    The name of a country subdivision.

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

    Since: 1.0

  • DOMString city [nullable]
    The name of the locality. For example, the city, county, town, or village.

    Since: 1.0

  • DOMString streetAddress [nullable]
    The street address, for example, building number and street name/number.

    Since: 1.0

  • DOMString additionalInformation [nullable]
    Additional address details that are required for an accurate address. For example, floor number, apartment number, suite name, the name of an office occupant, and so on.

    Since: 1.0

  • DOMString postalCode [nullable]
    The postal code of the location (also known as the zip code in the US).

    Since: 1.0

  • boolean isDefault
    The default state of an address.

    Indicates whether the address was marked as default 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.

    Since: 2.0

  • 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
    • OTHER - Indicates other type of address
    • CUSTOM - Indicates custom type of address. The actual type can be set in the label.

    By default, this attribute is set to HOME.

    Since: 1.0

    Remark: "OTHER" and "CUSTOM" types are added since Tizen 2.3.

  • DOMString label [nullable]
    The address label, can hold a custom address type.

    By default, this attribute is initialized to null.

    Since: 2.3

2.16. ContactPhoneNumber

The ContactPhoneNumber interface 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;
    attribute DOMString? label;
  };

Since: 1.0

This interface provides the phone number and the type of number such as work, home and car or the device subtype such as fax, fixed and mobile. When searching by phoneNumber, matchflag "CONTAINS" provides a result set which is retrieved from normalized phoneNumber as searching value.

For more details, see RFC 2426, Section 3.3.1

Code example:

var contactInit = {};
var phoneNumber = new tizen.ContactPhoneNumber("123456789", ["WORK", "VOICE"], true);
contactInit.phoneNumbers = [phoneNumber];

Constructors

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

Attributes

  • DOMString number
    The full phone number.

    Since: 1.0

  • boolean isDefault
    The default state of the phone number.

    Indicates whether the phone number was marked as default for the contact. Only one phone number for a person can have the 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.

    Since: 2.0

  • 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
    • ASSISTANT - Indicates assistant number
    • OTHER - Indicates other type of number
    • CUSTOM - Indicates custom type of number. The actual type can be set in the label.

    Since: 1.0

    Remark: "ASSISTANT", "OTHER" and "CUSTOM" types are added since Tizen 2.3.

  • DOMString label [nullable]
    The phone number label, can hold a custom phone number type.

    By default, this attribute is initialized to null.

    Since: 2.3

2.17. ContactEmailAddress

The ContactEmailAddress interface 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;
    attribute DOMString? label;
  };

Since: 1.0

For more details, see RFC 2426, Section 3.3.2.

Code example:

var contactInit = {};
var email = new tizen.ContactEmailAddress("user@domain.com", ["WORK"]);
contactInit.emails = [email];

Constructors

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

Attributes

  • DOMString email
    The full email address.

    Since: 1.0

  • boolean isDefault
    The default state of an email address.

    Indicates whether the email address was marked as default for the contact. Only one email address for a person can have the 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 false.

    Since: 2.0

  • 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
    • OTHER - Indicates other type of email
    • CUSTOM - Indicates custom type of email. The actual type can be set in the label.

    By default, this attribute is set to WORK.

    Since: 1.0

    Remark: "OTHER" and "CUSTOM" types are added since Tizen 2.3.

  • DOMString label [nullable]
    The email label, can hold a custom email type.

    By default, this attribute is initialized to null.

    Since: 2.3

2.18. ContactInstantMessenger

The ContactInstantMessenger interface contains the instant messenger (IM) address and the type of IM provider.
  [Constructor(DOMString imAddress, optional ContactInstantMessengerType? type)]
  interface ContactInstantMessenger {
    attribute DOMString imAddress;
    attribute ContactInstantMessengerType type;
    attribute DOMString? label;
  };

Since: 2.3

Code example:

var contactInit = {};
var messenger = new tizen.ContactInstantMessenger("user@domain.com", "GOOGLE");
contactInit.messengers = [messenger];

Constructors

Constructor (DOMString, ContactInstantMessengerType?)
ContactInstantMessenger(DOMString imAddress, optional ContactInstantMessengerType? type);

Attributes

  • DOMString imAddress
    The full instant messenger address.

    Since: 2.3

  • ContactInstantMessengerType type
    The instant messenger provider type.

    By default, this attribute is set to "OTHER".

    Since: 2.3

  • DOMString label [nullable]
    The instant messenger label, can hold a custom messenger type.

    By default, this attribute is initialized to null.

    Since: 2.3

2.19. ContactGroup

The ContactGroup interface that defines a group.
  [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;
  };

Since: 2.0

Code example:

var addressbook = null;
var group = null;
var ringtones = null;

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

/* Defines the success callback for retrieving all the Address Books. */
function addressBooksCB(addressbooks)
{
  addressbook = addressbooks[0];
  try
  {
    group = new tizen.ContactGroup("Family", ringtones.resolve("ring.mp3").toURI());
  }
  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);
  }
}

tizen.filesystem.resolve("ringtones", function(dir)
{
  ringtones = dir;
  tizen.contact.getAddressBooks(addressBooksCB, errorCB);
});

Constructors

Constructor (DOMString, DOMString?, DOMString?)
ContactGroup(DOMString name, optional DOMString? ringtoneURI, optional DOMString? photoURI);

Attributes

  • readonly ContactGroupId id [nullable]
    The identifier of a group.

    By default, this attribute is set to null.

    Since: 2.0

  • readonly AddressBookId addressBookId [nullable]
    The identifier of the address book that the group belongs to.

    By default, this attribute is set to null.

    Since: 2.0

  • DOMString name
    The name of a group.

    Since: 2.0

  • DOMString ringtoneURI [nullable]
    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.

    Since: 2.0

  • DOMString photoURI [nullable]
    The 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.

    Since: 2.0

  • readonly DOMString readOnly
    The flag indicating whether the group can be modified or removed. Some groups cannot be edited if this flag is set to true.

    By default, this attribute is set to false.

    Since: 2.0

2.20. ContactRelationship

The ContactRelationship interface contains the relationship of the contact.
  [Constructor(DOMString relativeName, optional ContactRelationshipType? type)]
  interface ContactRelationship {
    attribute DOMString relativeName;
    attribute ContactRelationshipType type;
    attribute DOMString? label;
  };

Since: 2.3

The direction of relationship is: contact (owner of relationship) is a relationship type to relative name. See code example below.

Code example:

var contactInit = {};
/* Contact is brother of "Anna". */
var relationship = new tizen.ContactRelationship("Anna", "BROTHER");
contactInit.relationships = [relationship];

Constructors

Constructor (DOMString, ContactRelationshipType?)
ContactRelationship(DOMString relativeName, optional ContactRelationshipType? type);

Attributes

  • DOMString relativeName
    The name of the person in a particular relationship.

    Since: 2.3

  • ContactRelationshipType type
    The relationship type.

    By default, this attribute is set to "OTHER".

    Since: 2.3

  • DOMString label [nullable]
    The relationship label, can hold a custom relationship type.

    By default, this attribute is initialized to null.

    Since: 2.3

2.21. ContactExtensionInit

The ContactExtensionInit dictionary defines the properties of a ContactExtension to pass to the ContactExtension constructor.
  dictionary ContactExtensionInit {
    long data1;
    DOMString data2;
    DOMString data3;
    DOMString data4;
    DOMString data5;
    DOMString data6;
    DOMString data7;
    DOMString data8;
    DOMString data9;
    DOMString data10;
    DOMString data11;
    DOMString data12;
  };

Since: 3.0

See ContactExtension interface for more information about the members.

2.22. ContactExtension

The ContactExtension interface contains the extended data of the contact.
  [Constructor(optional ContactExtensionInit? extensionInitDict)]
  interface ContactExtension {
    attribute long data1;
    attribute DOMString? data2;
    attribute DOMString? data3;
    attribute DOMString? data4;
    attribute DOMString? data5;
    attribute DOMString? data6;
    attribute DOMString? data7;
    attribute DOMString? data8;
    attribute DOMString? data9;
    attribute DOMString? data10;
    attribute DOMString? data11;
    attribute DOMString? data12;
  };

Since: 3.0

See code example below.

Code example:

var name = new tizen.ContactName({firstName: "Anna"});

var contact_extension1 = new tizen.ContactExtension({data1: 20, data2: "Place of birth: ElblÄ…g"});
var contact_extension2 = new tizen.ContactExtension({data3: "Favourite color: green"});
var contact1 =
    new tizen.Contact({name: name, extensions: [contact_extension1, contact_extension2]});

console.log(contact1.extensions[1].data3);

Output example:

Favourite color: green

Constructors

Constructor (ContactExtensionInit?)
ContactExtension(optional ContactExtensionInit? extensionInitDict);

Attributes

  • long data1
    The extended data of a contact.

    Since: 3.0

  • DOMString data2 [nullable]
    The extended data of a contact.

    Since: 3.0

  • DOMString data3 [nullable]
    The extended data of a contact.

    Since: 3.0

  • DOMString data4 [nullable]
    The extended data of a contact.

    Since: 3.0

  • DOMString data5 [nullable]
    The extended data of a contact.

    Since: 3.0

  • DOMString data6 [nullable]
    The extended data of a contact.

    Since: 3.0

  • DOMString data7 [nullable]
    The extended data of a contact.

    Since: 3.0

  • DOMString data8 [nullable]
    The extended data of a contact.

    Since: 3.0

  • DOMString data9 [nullable]
    The extended data of a contact.

    Since: 3.0

  • DOMString data10 [nullable]
    The extended data of a contact.

    Since: 3.0

  • DOMString data11 [nullable]
    The extended data of a contact.

    Since: 3.0

  • DOMString data12 [nullable]
    The extended data of a contact.

    Since: 3.0

2.23. PersonArraySuccessCallback

The PersonArraySuccessCallback interface defines the success callback that is used for retrieving a list of persons.
  [Callback=FunctionOnly, NoInterfaceObject] interface PersonArraySuccessCallback {
    void onsuccess(Person[] persons);
  };

Since: 2.0

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
Called when a list of persons is retrieved successfully.
void onsuccess(Person[] persons);

Since: 1.0

Parameters:

  • persons: List of persons.

Code example:

function onerror(err)
{
  console.log("The following error occurred " + err.name);
}

function onsuccess(persons)
{
  var p;

  /* Log each found person's name to the console. */
  for (p = 0; p < persons.length; p += 1)
  {
    console.log("Name: " + persons[p].displayName);
  }
}

try
{
  tizen.contact.find(onsuccess, onerror);
}
catch (err)
{
  console.log("The following error occurred while finding: " + err.name);
}

2.24. ContactArraySuccessCallback

The ContactArraySuccessCallback interface defines the success callback that is used for saving and retrieving a list of contacts.
  [Callback=FunctionOnly, NoInterfaceObject] interface ContactArraySuccessCallback {
    void onsuccess(Contact[] contacts);
  };

Since: 1.0

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
Called when a list of contacts is retrieved successfully.
void onsuccess(Contact[] contacts);

Since: 1.0

Parameters:

  • contacts: List of contacts. The Contacts that were successfully saved must have their identifiers set.

2.25. AddressBookArraySuccessCallback

The AddressBookArraySuccessCallback interface defines the success callback that is called when retrieving a list of AddressBooks.
  [Callback=FunctionOnly, NoInterfaceObject] interface AddressBookArraySuccessCallback {
    void onsuccess(AddressBook[] addressbooks);
  };

Since: 1.0

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

Methods

onsuccess
Called when a list of address books is retrieved successfully.
void onsuccess(AddressBook[] addressbooks);

Since: 1.0

Parameters:

  • addressbooks: Address books that were successfully retrieved.

Code example:

function errorCB(err)
{
  console.log("An error occurred: " + err.name);
}

/* Callback invoked on successful retrieval of all the Address Books. */
function addressBooksCB(addressBooks)
{
  console.log(addressBooks.length + " address books available");
}

/* Gets a list of available address books. */
tizen.contact.getAddressBooks(addressBooksCB, errorCB);

2.26. AddressBookChangeCallback

The AddressBookChangeCallback interface provides 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);
  };

Since: 1.0

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

Methods

oncontactsadded
Called when contacts are added to the address book.
void oncontactsadded(Contact[] contacts);

Since: 1.0

Parameters:

  • contacts: List of the added contacts.

Code example:

var watcherId = 0;  /* Watcher identifier. */
var addressbook = tizen.contact.getDefaultAddressBook();

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

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

/* Adds a new contact to invoke an oncontactsadded call:. */
try
{
  var contact = new tizen.Contact(
  {
    name: new tizen.ContactName({firstName: "John", lastName: "Doe", nicknames: ["Johnny"]}),
    emails: [new tizen.ContactEmailAddress("john@doe.com")],
    phoneNumbers: [new tizen.ContactPhoneNumber("789456123")]
  });
  addressbook.add(contact);
}
catch (err)
{
  console.log("An error occurred while adding a contact: " + err.name + ", " + err.message);
}
oncontactsupdated
Called when contacts are updated in the address book.
void oncontactsupdated(Contact[] contacts);

Since: 1.0

Parameters:

  • contacts: List of the updated contacts.

Code example:

var watcherId = 0;  /* Watcher identifier. */
var addressbook = tizen.contact.getDefaultAddressBook();

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

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

/* Updates a contact to invoke an oncontactsupdated call:. */
function errorCB(error)
{
  console.log(error.name + ": " + error.message);
}

function contactsFoundCB(contacts)
{
  contacts[0].name.firstName = "Stanley";
  try
  {
    addressbook.update(contacts[0]);
    console.log("Successfully updated");
  }
  catch (err)
  {
    console.log(err.name + ": " + err.message);
  }
}

var filter = new tizen.AttributeFilter("name.lastName", "EXACTLY", "Doe");
try
{
  addressbook.find(contactsFoundCB, errorCB, filter);
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}
oncontactsremoved
Called when contacts are deleted from the address book.
void oncontactsremoved(ContactId[] contactIds);

Since: 1.0

Parameters:

  • contactIds: List of the deleted contacts' identifiers.

Code example:

var watcherId = 0;  /* Watcher identifier. */
var addressbook = tizen.contact.getDefaultAddressBook();

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

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

/* Removes a first contact whose name is "Doe". */
/* to invoke oncontactsremoved call. */
function onErrorCB(err)
{
  console.log("An error occurred: " + err.name);
}

function onContactsFoundCB(contacts)
{
  if (contacts.length > 0)
  {
    try
    {
      addressbook.remove(contacts[0].id);
      console.log("First contact has been removed");
    }
    catch (err)
    {
      console.log("An error occurred while removing: " + err.name);
    }
  }
  else
  {
    console.log("No contacts to delete");
  }
}

var filter = new tizen.AttributeFilter("name.lastName", "EXACTLY", "Doe");
try
{
  addressbook.find(onContactsFoundCB, onErrorCB, filter);
}
catch (err)
{
  console.log("An error occurred while finding: " + err.name);
}

2.27. PersonsChangeCallback

The PersonsChangeCallback interface provides the methods to be called for change notifications.
  [Callback, NoInterfaceObject] interface PersonsChangeCallback {
    void onpersonsadded(Person[] persons);
    void onpersonsupdated(Person[] persons);
    void onpersonsremoved(PersonId[] personIds);
  };

Since: 2.0

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

Methods

onpersonsadded
Called when persons are added to the person list.
void onpersonsadded(Person[] persons);

Since: 2.0

Parameters:

  • persons: List of the added persons.

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 address book changes. */
watcherId = tizen.contact.addChangeListener(watcher);
onpersonsupdated
Called when persons are updated in the person list.
void onpersonsupdated(Person[] persons);

Since: 2.0

Parameters:

  • persons: List of the updated persons.

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 address book changes. */
watcherId = tizen.contact.addChangeListener(watcher);
onpersonsremoved
Called when persons are deleted from the person list.
void onpersonsremoved(PersonId[] personIds);

Since: 2.0

Parameters:

  • personIds: List of the deleted persons' identifiers.

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 address book changes. */
watcherId = tizen.contact.addChangeListener(watcher);

3. Related Feature

Method tizen.systeminfo.getCapability() can be used in application runtime to check whether this API is supported.

To guarantee the running of the application on a device with Account feature, declare the following feature requirement in the config file:

  • http://tizen.org/feature/account
  • To guarantee the running of the application on a device with Contact feature, declare the following feature requirement in the config file:

  • http://tizen.org/feature/contact
  • For more information, see Application Filtering.

    4. Full WebIDL

    module Contact {
      typedef DOMString AddressBookId;
      typedef DOMString ContactId;
      typedef DOMString PersonId;
      typedef DOMString ContactGroupId;
      typedef (AttributeFilter or AttributeRangeFilter) ContactUsageCountFilter;
      enum ContactTextFormat { "VCARD_30" };
      enum ContactRelationshipType { "OTHER", "ASSISTANT", "BROTHER", "CHILD", "DOMESTIC_PARTNER", "FATHER", "FRIEND", "MANAGER", "MOTHER",
        "PARENT", "PARTNER", "REFERRED_BY", "RELATIVE", "SISTER", "SPOUSE", "CUSTOM" };
      enum ContactInstantMessengerType { "OTHER", "GOOGLE", "WLM", "YAHOO", "FACEBOOK", "ICQ", "AIM", "QQ", "JABBER", "SKYPE", "IRC",
        "CUSTOM" };
      enum ContactUsageType { "OUTGOING_CALL", "OUTGOING_MSG", "OUTGOING_EMAIL", "INCOMING_CALL", "INCOMING_MSG", "INCOMING_EMAIL",
        "MISSED_CALL", "REJECTED_CALL", "BLOCKED_CALL", "BLOCKED_MSG" };
      dictionary ContactInit {
        ContactName name;
        ContactAddress[] addresses;
        DOMString photoURI;
        ContactPhoneNumber[] phoneNumbers;
        ContactEmailAddress[] emails;
        ContactInstantMessenger[] messengers;
        ContactRelationship[] relationships;
        ContactExtension[] extensions;
        Date birthday;
        ContactAnniversary[] anniversaries;
        ContactOrganization[] organizations;
        DOMString[] notes;
        ContactWebSite[] urls;
        DOMString ringtoneURI;
        DOMString messageAlertURI;
        DOMString vibrationURI;
        ContactGroupId[] groupIds;
      };
      dictionary ContactNameInit {
        DOMString prefix;
        DOMString suffix;
        DOMString firstName;
        DOMString middleName;
        DOMString lastName;
        DOMString[] nicknames;
        DOMString phoneticFirstName;
        DOMString phoneticMiddleName;
        DOMString phoneticLastName;
      };
      dictionary ContactOrganizationInit {
        DOMString name;
        DOMString department;
        DOMString title;
        DOMString role;
        DOMString logoURI;
      };
      dictionary ContactAddressInit {
        DOMString country;
        DOMString region;
        DOMString city;
        DOMString streetAddress;
        DOMString additionalInformation;
        DOMString postalCode;
        boolean isDefault;
        DOMString[] types;
        DOMString label;
      };
      dictionary ContactExtensionInit {
        long data1;
        DOMString data2;
        DOMString data3;
        DOMString data4;
        DOMString data5;
        DOMString data6;
        DOMString data7;
        DOMString data8;
        DOMString data9;
        DOMString data10;
        DOMString data11;
        DOMString data12;
      };
      Tizen implements ContactManagerObject;
      [NoInterfaceObject] interface ContactManagerObject {
        readonly attribute ContactManager contact;
      };
      [NoInterfaceObject] interface ContactManager {
        void getAddressBooks(AddressBookArraySuccessCallback successCallback, optional ErrorCallback? errorCallback)
                             raises(WebAPIException);
        AddressBook getUnifiedAddressBook() raises(WebAPIException);
        AddressBook getDefaultAddressBook() raises(WebAPIException);
        void addAddressBook(AddressBook addressBook) raises(WebAPIException);
        void removeAddressBook(AddressBookId addressBookId) 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);
        void findByUsageCount(ContactUsageCountFilter filter, PersonArraySuccessCallback successCallback,
                              optional ErrorCallback? errorCallback, optional SortModeOrder? sortModeOrder, optional unsigned long limit,
                              optional unsigned long offset) raises(WebAPIException);
        long addChangeListener(PersonsChangeCallback successCallback) raises(WebAPIException);
        void removeChangeListener(long watchId) raises(WebAPIException);
      };
      [Constructor(AccountId accountId, DOMString name)]
      interface AddressBook {
        readonly attribute AddressBookId? id;
        readonly attribute DOMString name;
        readonly attribute boolean readOnly;
        readonly attribute AccountId? accountId;
        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);
        long getUsageCount(optional ContactUsageType? type) raises(WebAPIException);
        void resetUsageCount(optional ContactUsageType? type) raises(WebAPIException);
      };
      [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;
        attribute ContactAddress[] addresses;
        attribute DOMString? photoURI;
        attribute ContactPhoneNumber[] phoneNumbers;
        attribute ContactEmailAddress[] emails;
        attribute ContactInstantMessenger[] messengers;
        attribute ContactRelationship[] relationships;
        attribute ContactExtension[] extensions;
        attribute Date? birthday;
        attribute ContactAnniversary[] anniversaries;
        attribute ContactOrganization[] organizations;
        attribute DOMString[] notes;
        attribute ContactWebSite[] urls;
        attribute DOMString? ringtoneURI;
        attribute DOMString? messageAlertURI;
        attribute DOMString? vibrationURI;
        attribute ContactGroupId[] groupIds;
        DOMString convertToString(optional ContactTextFormat? format) raises(WebAPIException);
        Contact clone() raises(WebAPIException);
      };
      [Constructor(AddressBookId addressBookId, ContactId contactId)]
      interface ContactRef {
        attribute AddressBookId addressBookId;
        attribute ContactId contactId;
      };
      [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? phoneticMiddleName;
        attribute DOMString? phoneticLastName;
        readonly attribute DOMString? displayName;
      };
      [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;
      };
      [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;
        attribute DOMString? label;
      };
      [Constructor(DOMString number, optional DOMString[] types, optional boolean isDefault)]
      interface ContactPhoneNumber {
        attribute DOMString number;
        attribute boolean isDefault;
        attribute DOMString[] types;
        attribute DOMString? label;
      };
      [Constructor(DOMString email, optional DOMString[] types, optional boolean isDefault)]
      interface ContactEmailAddress {
        attribute DOMString email;
        attribute boolean isDefault;
        attribute DOMString[] types;
        attribute DOMString? label;
      };
      [Constructor(DOMString imAddress, optional ContactInstantMessengerType? type)]
      interface ContactInstantMessenger {
        attribute DOMString imAddress;
        attribute ContactInstantMessengerType type;
        attribute DOMString? label;
      };
      [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;
      };
      [Constructor(DOMString relativeName, optional ContactRelationshipType? type)]
      interface ContactRelationship {
        attribute DOMString relativeName;
        attribute ContactRelationshipType type;
        attribute DOMString? label;
      };
      [Constructor(optional ContactExtensionInit? extensionInitDict)]
      interface ContactExtension {
        attribute long data1;
        attribute DOMString? data2;
        attribute DOMString? data3;
        attribute DOMString? data4;
        attribute DOMString? data5;
        attribute DOMString? data6;
        attribute DOMString? data7;
        attribute DOMString? data8;
        attribute DOMString? data9;
        attribute DOMString? data10;
        attribute DOMString? data11;
        attribute DOMString? data12;
      };
      [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);
      };
    };