Contact API
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.
Remark: In order to access files, a proper privilege has to be defined additionally:
- for accessing only internal storage using this API, a privilege http://tizen.org/privilege/mediastorage must be provided,
- for accessing only external storage using this API, a privilege http://tizen.org/privilege/externalstorage must be provided,
- for accessing internal and external storage using this API, privileges (http://tizen.org/privilege/mediastorage and http://tizen.org/privilege/externalstorage) must be provided.
- Storage privileges are privacy-related privileges and there is a need of asking user directly with proper pop-up. Please refer to Privacy Privilege API for more details.
For more information on the Contact features, see Contact Guide.
Since: 4.0
Table of Contents
- 1. Type Definitions
- 1.1. AddressBookId
- 1.2. ContactId
- 1.3. PersonId
- 1.4. ContactGroupId
- 1.5. ContactUsageCountFilter
- 1.6. ContactTextFormat
- 1.7. ContactRelationshipType
- 1.8. ContactInstantMessengerType
- 1.9. ContactUsageType
- 2. Interfaces
- 2.1. ContactManagerObject
- 2.2. ContactManager
- 2.3. AddressBook
- 2.4. Person
- 2.5. ContactInit
- 2.6. Contact
- 2.7. ContactRef
- 2.8. ContactNameInit
- 2.9. ContactName
- 2.10. ContactOrganizationInit
- 2.11. ContactOrganization
- 2.12. ContactWebSite
- 2.13. ContactAnniversary
- 2.14. ContactAddressInit
- 2.15. ContactAddress
- 2.16. ContactPhoneNumber
- 2.17. ContactEmailAddress
- 2.18. ContactInstantMessenger
- 2.19. ContactGroup
- 2.20. ContactRelationship
- 2.21. ContactExtensionInit
- 2.22. ContactExtension
- 2.23. PersonArraySuccessCallback
- 2.24. ContactArraySuccessCallback
- 2.25. AddressBookArraySuccessCallback
- 2.26. AddressBookChangeCallback
- 2.27. PersonsChangeCallback
- 3. Related Feature
- 4. Full WebIDL
Summary of Interfaces and Methods
1. Type Definitions
1.5. ContactUsageCountFilter
typedef (AttributeFilter or AttributeRangeFilter) ContactUsageCountFilter;
Since: 4.0
1.6. ContactTextFormat
enum ContactTextFormat { "VCARD_30" };
Since: 4.0
- VCARD_30 - vCard v3.0 format
Currently, vCard v3.0 is the only format supported by the Tizen platform.
1.7. ContactRelationshipType
enum ContactRelationshipType { "OTHER", "ASSISTANT", "BROTHER", "CHILD", "DOMESTIC_PARTNER", "FATHER", "FRIEND", "MANAGER", "MOTHER", "PARENT", "PARTNER", "REFERRED_BY", "RELATIVE", "SISTER", "SPOUSE", "CUSTOM" };
Since: 4.0
- 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
enum ContactInstantMessengerType { "OTHER", "GOOGLE", "WLM", "YAHOO", "FACEBOOK", "ICQ", "AIM", "QQ", "JABBER", "SKYPE", "IRC", "CUSTOM" };
Since: 4.0
- 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
enum ContactUsageType { "OUTGOING_CALL", "OUTGOING_MSG", "OUTGOING_EMAIL", "INCOMING_CALL", "INCOMING_MSG", "INCOMING_EMAIL", "MISSED_CALL", "REJECTED_CALL", "BLOCKED_CALL", "BLOCKED_MSG" };
Since: 4.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
[NoInterfaceObject] interface ContactManagerObject { readonly attribute ContactManager contact; };
Tizen implements ContactManagerObject;
Since: 4.0
The tizen.contact object allows access to the Contact API functionality.
Attributes
-
readonly
ContactManager contactObject representing a contact manager.
Since: 4.0
2.2. ContactManager
[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: 4.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: 4.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: 4.0
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); }
- WebAPIException
-
getDefaultAddressBook
-
Gets the default address book.
AddressBook getDefaultAddressBook();
Since: 4.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); }
- WebAPIException
-
addAddressBook
-
Adds an addressbook to the contact database synchronously.
void addAddressBook(AddressBook addressBook);
Since: 4.0
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: 4.0
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: 4.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.
Since: 4.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: 4.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 or the application does not have privilege to access the storage. For more information, see Storage privileges.
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: 4.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 or the application does not have privilege to access the storage. For more information, see Storage privileges.
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: 4.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: 4.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: 4.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: 4.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: 4.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: 4.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
[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: 4.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);
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: 4.0
-
readonly
DOMString nameThe address book descriptive name.
Since: 4.0
-
readonly
boolean readOnlyIndicates whether the address book is read-only.
Some on line address books cannot be edited and will have this flag set to true.
Since: 4.0
-
readonly
AccountId accountId [nullable]Account identifier.
Since: 4.0
Methods
-
get
-
Gets the contact with the specified identifier.
Since: 4.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: 4.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 or the application does not have privilege to access the storage. For more information, see Storage privileges.
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: 4.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 or the application does not have privilege to access the storage. For more information, see Storage privileges.
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: 4.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 or the application does not have privilege to access the storage. For more information, see Storage privileges.
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: 4.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 or the application does not have privilege to access the storage. For more information, see Storage privileges.
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: 4.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: 4.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: 4.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: 4.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: 4.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: 4.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: 4.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 or the application does not have privilege to access the storage. For more information, see Storage privileges.
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: 4.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 or the application does not have privilege to access the storage. For more information, see Storage privileges.
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: 4.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: 4.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); }
- WebAPIException
2.4. Person
[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; readonly 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: 4.0
Attributes
-
readonly
PersonId idThe identifier of the person.
Since: 4.0
-
readonly
DOMString displayNameThe person display name as a string. It is selected from the contacts' display names.
Since: 4.0
-
readonly
long contactCountThe count of the contacts of a person.
Since: 4.0
-
readonly
boolean hasPhoneNumberIndicates whether a person has a phone number.
Since: 4.0
-
readonly
boolean hasEmailIndicates whether the person has an email addresses.
Since: 4.0
-
boolean isFavoriteIndicates whether the contact is a favorite.
Indicates whether the person was marked as Favorite.
By default, this attribute is set to false.
Since: 4.0
-
readonly
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: 4.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: 4.0
-
ContactId displayContactIdThe 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: 4.0
Methods
-
link
-
Aggregates another person to this person.
void link(PersonId personId);
Since: 4.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); }
-
unlink
-
Separates a contact from this person.
Since: 4.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: 4.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: 4.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
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: 4.0
This dictionary is used to input parameters when contacts are created.
2.6. Contact
[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: 4.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?)
-
Constructor (DOMString)
Contact(optional ContactInit? ContactInitDict);
Contact(DOMString stringRepresentation);
Attributes
-
readonly
ContactId id [nullable]The identifier of a Raw contact.
By default, this attribute is set to null.
Since: 4.0
-
readonly
PersonId personId [nullable]The identifier of the person corresponding to the raw contact.
By default, this attribute is set to null.
Since: 4.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: 4.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: 4.0
-
readonly
boolean isFavoriteIndicates 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: 4.0
Code example:
if (contact.isFavorite) { /* ... */ }
-
ContactName name [nullable]The name of a contact.
Since: 4.0
-
ContactAddress[]
addressesThe contact addresses.
By default, this attribute is set to an empty array.
Since: 4.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: 4.0
Code example:
var contactInit = {}; tizen.filesystem.resolve("images/mypicture.jpg", function(imageFile) { contactInit.photoURI = imageFile.toURI(); });
-
ContactPhoneNumber[]
phoneNumbersThe telephone numbers of the contact.
By default, this attribute is set to an empty array.
Since: 4.0
Code example:
var contactInit = {}; var phoneNumber = new tizen.ContactPhoneNumber("123456789"); contactInit.phoneNumbers = [phoneNumber];
-
ContactEmailAddress[]
emailsThe email addresses of the contact.
By default, this attribute is set to an empty array.
Since: 4.0
Code example:
var contactInit = {}; var email = new tizen.ContactEmailAddress("deedee@ramones.com"); contactInit.emails = [email];
-
ContactInstantMessenger[]
messengersThe instant messenger addresses of the contact.
By default, this attribute is set to an empty array.
Since: 4.0
Code example:
var contactInit = {}; var messenger = new tizen.ContactInstantMessenger("user@example.com"); contactInit.messengers = [messenger];
-
ContactRelationship[]
relationshipsThe 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: 4.0
Code example:
var contactInit = {}; /* Contact is brother of "Anna". */ var relationship = new tizen.ContactRelationship("Anna", "BROTHER"); contactInit.relationships = [relationship];
-
ContactExtension[]
extensionsThe extended data of the contact.
By default, this attribute is set to an empty array.
Since: 4.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: 4.0
Code example:
var contactInit = {}; contactInit.birthday = new Date(1996, 4, 15);
-
ContactAnniversary[]
anniversariesThe 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: 4.0
Code example:
var contactInit = {}; var marriage_anniv = new tizen.ContactAnniversary(new Date(1976, 11, 2), "Marriage"); contactInit.anniversaries = [marriage_anniv];
-
ContactOrganization[]
organizationsThe 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: 4.0
-
DOMString[]
notesThe 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: 4.0
-
ContactWebSite[]
urlsThe 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: 4.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: 4.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: 4.0
-
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: 4.0
-
ContactGroupId[]
groupIdsThe 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: 4.0
Methods
-
convertToString
-
Converts the Contact item to a string format.
DOMString convertToString(optional ContactTextFormat? format);
Since: 4.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); }
-
format [optional] [nullable]:
Format to use for export
-
clone
-
Creates a clone of the Contact object, detached from any address book.
Contact clone();
Since: 4.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);
- WebAPIException
2.7. ContactRef
[Constructor(AddressBookId addressBookId, ContactId contactId)] interface ContactRef { attribute AddressBookId addressBookId; attribute ContactId contactId; };
Since: 4.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 addressBookIdThe address book identifier.
Since: 4.0
-
ContactId contactIdThe contact identifier inside the address book.
Since: 4.0
2.8. ContactNameInit
dictionary ContactNameInit { DOMString prefix; DOMString suffix; DOMString firstName; DOMString middleName; DOMString lastName; DOMString[] nicknames; DOMString phoneticFirstName; DOMString phoneticMiddleName; DOMString phoneticLastName; };
Since: 4.0
See the ContactName interface for more information about the members.
2.9. ContactName
[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: 4.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: 4.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: 4.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: 4.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: 4.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: 4.0
Code example:
contact.name.lastName = "Colvin";
-
DOMString[]
nicknamesThe 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: 4.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: 4.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: 4.0
-
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: 4.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: 4.0
2.10. ContactOrganizationInit
dictionary ContactOrganizationInit { DOMString name; DOMString department; DOMString title; DOMString role; DOMString logoURI; };
Since: 4.0
See ContactOrganization interface for information about members.
2.11. ContactOrganization
[Constructor(optional ContactOrganizationInit? orgInitDict)] interface ContactOrganization { attribute DOMString? name; attribute DOMString? department; attribute DOMString? title; attribute DOMString? role; attribute DOMString? logoURI; };
Since: 4.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: 4.0
-
DOMString department [nullable]The organizational unit name.
For more details, see RFC 2426, Section 3.5.5.
Since: 4.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: 4.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: 4.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: 4.0
2.12. ContactWebSite
[Constructor(DOMString url, optional DOMString type)] interface ContactWebSite { attribute DOMString url; attribute DOMString type; };
Since: 4.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
Attributes
-
DOMString urlThe URL for the contact's web site.
Since: 4.0
-
DOMString typeThe 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: 4.0
2.13. ContactAnniversary
[Constructor(Date date, optional DOMString? label)] interface ContactAnniversary { attribute Date date; attribute DOMString? label; };
Since: 4.0
Code example:
var contactInit = {}; var marriage_anniv = new tizen.ContactAnniversary(new Date(1976, 11, 2), "Marriage"); contactInit.anniversaries = [marriage_anniv];
Constructors
Attributes
-
Date dateThe date of an anniversary.
Since: 4.0
-
DOMString label [nullable]The text describing an anniversary.
By default, this attribute is set to null.
Since: 4.0
2.14. ContactAddressInit
dictionary ContactAddressInit { DOMString country; DOMString region; DOMString city; DOMString streetAddress; DOMString additionalInformation; DOMString postalCode; boolean isDefault; DOMString[] types; DOMString label; };
Since: 4.0
See ContactAddress interface for more information about the members.
2.15. ContactAddress
[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: 4.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: 4.0
-
DOMString region [nullable]The name of a country subdivision.
For example, State (United States) or Province (Spain).
Since: 4.0
-
DOMString city [nullable]The name of the locality. For example, the city, county, town, or village.
Since: 4.0
-
DOMString streetAddress [nullable]The street address, for example, building number and street name/number.
Since: 4.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: 4.0
-
DOMString postalCode [nullable]The postal code of the location (also known as the zip code in the US).
Since: 4.0
-
boolean isDefaultThe 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: 4.0
-
DOMString[]
typesThe 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: 4.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: 4.0
2.16. ContactPhoneNumber
[Constructor(DOMString number, optional DOMString[] types, optional boolean isDefault)] interface ContactPhoneNumber { attribute DOMString number; attribute boolean isDefault; attribute DOMString[] types; attribute DOMString? label; };
Since: 4.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
Attributes
-
DOMString numberThe full phone number.
Since: 4.0
-
boolean isDefaultThe 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: 4.0
-
DOMString[]
typesThe 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: 4.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: 4.0
2.17. ContactEmailAddress
[Constructor(DOMString email, optional DOMString[] types, optional boolean isDefault)] interface ContactEmailAddress { attribute DOMString email; attribute boolean isDefault; attribute DOMString[] types; attribute DOMString? label; };
Since: 4.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
Attributes
-
DOMString emailThe full email address.
Since: 4.0
-
boolean isDefaultThe 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: 4.0
-
DOMString[]
typesThe 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: 4.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: 4.0
2.18. ContactInstantMessenger
[Constructor(DOMString imAddress, optional ContactInstantMessengerType? type)] interface ContactInstantMessenger { attribute DOMString imAddress; attribute ContactInstantMessengerType type; attribute DOMString? label; };
Since: 4.0
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 imAddressThe full instant messenger address.
Since: 4.0
-
ContactInstantMessengerType typeThe instant messenger provider type.
By default, this attribute is set to "OTHER".
Since: 4.0
-
DOMString label [nullable]The instant messenger label, can hold a custom messenger type.
By default, this attribute is initialized to null.
Since: 4.0
2.19. ContactGroup
[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: 4.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
Attributes
-
readonly
ContactGroupId id [nullable]The identifier of a group.
By default, this attribute is set to null.
Since: 4.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: 4.0
-
DOMString nameThe name of a group.
Since: 4.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: 4.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: 4.0
-
readonly
DOMString readOnlyThe 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: 4.0
2.20. ContactRelationship
[Constructor(DOMString relativeName, optional ContactRelationshipType? type)] interface ContactRelationship { attribute DOMString relativeName; attribute ContactRelationshipType type; attribute DOMString? label; };
Since: 4.0
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 relativeNameThe name of the person in a particular relationship.
Since: 4.0
-
ContactRelationshipType typeThe relationship type.
By default, this attribute is set to "OTHER".
Since: 4.0
-
DOMString label [nullable]The relationship label, can hold a custom relationship type.
By default, this attribute is initialized to null.
Since: 4.0
2.21. ContactExtensionInit
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: 4.0
See ContactExtension interface for more information about the members.
2.22. ContactExtension
[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: 4.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 data1The extended data of a contact.
Since: 4.0
-
DOMString data2 [nullable]The extended data of a contact.
Since: 4.0
-
DOMString data3 [nullable]The extended data of a contact.
Since: 4.0
-
DOMString data4 [nullable]The extended data of a contact.
Since: 4.0
-
DOMString data5 [nullable]The extended data of a contact.
Since: 4.0
-
DOMString data6 [nullable]The extended data of a contact.
Since: 4.0
-
DOMString data7 [nullable]The extended data of a contact.
Since: 4.0
-
DOMString data8 [nullable]The extended data of a contact.
Since: 4.0
-
DOMString data9 [nullable]The extended data of a contact.
Since: 4.0
-
DOMString data10 [nullable]The extended data of a contact.
Since: 4.0
-
DOMString data11 [nullable]The extended data of a contact.
Since: 4.0
-
DOMString data12 [nullable]The extended data of a contact.
Since: 4.0
2.23. PersonArraySuccessCallback
[Callback=FunctionOnly, NoInterfaceObject] interface PersonArraySuccessCallback { void onsuccess(Person[] persons); };
Since: 4.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: 4.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
[Callback=FunctionOnly, NoInterfaceObject] interface ContactArraySuccessCallback { void onsuccess(Contact[] contacts); };
Since: 4.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: 4.0
Parameters:
- contacts: List of contacts. The Contacts that were successfully saved must have their identifiers set.
2.25. AddressBookArraySuccessCallback
[Callback=FunctionOnly, NoInterfaceObject] interface AddressBookArraySuccessCallback { void onsuccess(AddressBook[] addressbooks); };
Since: 4.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: 4.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
[Callback, NoInterfaceObject] interface AddressBookChangeCallback { void oncontactsadded(Contact[] contacts); void oncontactsupdated(Contact[] contacts); void oncontactsremoved(ContactId[] contactIds); };
Since: 4.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: 4.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: 4.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: 4.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
[Callback, NoInterfaceObject] interface PersonsChangeCallback { void onpersonsadded(Person[] persons); void onpersonsupdated(Person[] persons); void onpersonsremoved(PersonId[] personIds); };
Since: 4.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: 4.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: 4.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: 4.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
To guarantee the running of the application on a device with Account feature, declare the following feature requirement in the config file:
To guarantee the running of the application on a device with Contact feature, declare the following feature requirement in the config file:
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; readonly 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); }; };