© 2013 Samsung Electronics Co., Ltd. All rights reserved.
This API is for managing Address Books.
A contact is a set of information that describes a contact. The contact contains information, such as phone numbers, e-mail addresses, etc.
RFC 2426 vCard MIME Directory Profile defines a format for exchanging contacts. Contact API refers to this specification to provide a mapping of the specified contact attributes.
A person is a set of information that describes a person. Two different contacts that indicate the same person will have the same person ID. A person has a display contact ID that indicates a contact that represents information of the person. A person is automatically created when a new contact is added.
This API provides functionality to read, create, remove, and update contacts in specific address books. Address books can be obtained using the getAddressBooks() method, which returns an array of AddressBook objects.
For more information on the Contact features, see Contact Guide.
Interface | Method |
---|---|
ContactManagerObject | |
ContactManager | void getAddressBooks(AddressBookArraySuccessCallback successCallback, ErrorCallback? errorCallback) AddressBook getUnifiedAddressBook() AddressBook getDefaultAddressBook() AddressBook getAddressBook(AddressBookId addressBookId) Person get(PersonId personId) void update(Person person) void updateBatch(Person[] persons, SuccessCallback? successCallback, ErrorCallback? errorCallback) void remove(PersonId personId) void removeBatch(PersonId[] personIds, SuccessCallback? successCallback, ErrorCallback? errorCallback) void find(PersonArraySuccessCallback successCallback, ErrorCallback? errorCallback, AbstractFilter? filter, SortMode? sortMode) long addChangeListener(PersonsChangeCallback successCallback) void removeChangeListener(long watchId) |
AddressBook | Contact get(ContactId id) void add(Contact contact) void addBatch(Contact[] contacts, ContactArraySuccessCallback? successCallback, ErrorCallback? errorCallback) void update(Contact contact) void updateBatch(Contact[] contacts, SuccessCallback? successCallback, ErrorCallback? errorCallback) void remove(ContactId id) void removeBatch(ContactId[] ids, SuccessCallback? successCallback, ErrorCallback? errorCallback) void find(ContactArraySuccessCallback successCallback, ErrorCallback? errorCallback, AbstractFilter? filter, SortMode? sortMode) long addChangeListener(AddressBookChangeCallback successCallback, ErrorCallback? errorCallback) void removeChangeListener(long watchId) ContactGroup getGroup(ContactGroupId groupId) void addGroup(ContactGroup group) void updateGroup(ContactGroup group) void removeGroup(ContactGroupId groupId) ContactGroup[] getGroups() |
Person | void link(PersonId personId) Person unlink(ContactId contactId) |
ContactInit | |
Contact | DOMString convertToString(ContactTextFormat? format) Contact clone() |
ContactRef | |
ContactNameInit | |
ContactName | |
ContactOrganizationInit | |
ContactOrganization | |
ContactWebSite | |
ContactAnniversary | |
ContactAddressInit | |
ContactAddress | |
ContactPhoneNumber | |
ContactEmailAddress | |
ContactGroup | |
PersonArraySuccessCallback | void onsuccess(Person[] persons) |
ContactArraySuccessCallback | void onsuccess(Contact[] contacts) |
AddressBookArraySuccessCallback | void onsuccess(AddressBook[] addressbooks) |
AddressBookChangeCallback | void oncontactsadded(Contact[] contacts) void oncontactsupdated(Contact[] contacts) void oncontactsremoved(ContactId[] contactIds) |
PersonsChangeCallback | void onpersonsadded(Person[] persons) void onpersonsupdated(Person[] persons) void onpersonsremoved(PersonId[] personIds) |
The address book identifier.
typedef DOMString AddressBookId;
The contact identifier.
typedef DOMString ContactId;
The person identifier.
typedef DOMString PersonId;
The group identifier.
typedef DOMString ContactGroupId;
An enumerator that indicates the contact format that is used for export. * The possible values are:
enum ContactTextFormat {"VCARD_30"};
Currently, vCard v3.0 is the only format supported.
Defines what is instantiated by the webapis object.
[NoInterfaceObject] interface ContactManagerObject { readonly attribute ContactManager contact; };
WebAPIs implements ContactManagerObject;
There is a webapis.contact object that allows access to the Contact API functionality.
This interface provides access to the API functionality.
[NoInterfaceObject] interface ContactManager { void getAddressBooks(AddressBookArraySuccessCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); AddressBook getUnifiedAddressBook() raises(WebAPIException); AddressBook getDefaultAddressBook() raises(WebAPIException); AddressBook getAddressBook(AddressBookId addressBookId) raises(WebAPIException); Person get(PersonId personId) raises(WebAPIException); void update(Person person) raises(WebAPIException); void updateBatch(Person[] persons, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void remove(PersonId personId) raises(WebAPIException); void removeBatch(PersonId[] personIds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void find(PersonArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional AbstractFilter? filter, optional SortMode? sortMode) raises(WebAPIException); long addChangeListener(PersonsChangeCallback successCallback) raises(WebAPIException); void removeChangeListener(long watchId) raises(WebAPIException); };
This interface offers a method to retrieve the address books objects. The address book objects can be manipulated with the provided functionalities to add, remove, and update the contained information.
getAddressBooks
Gets the available address books.
void getAddressBooks(AddressBookArraySuccessCallback successCallback, optional ErrorCallback? errorCallback);
If the operation completes successfully, the successCallback must be invoked with the phone address book and the SIM address book (if any). Other address books present in the device should also be returned.
If no address book is present, the successCallback will be invoked with an empty array.
The errorCallback is launched with these error types:
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if this functionality is not allowed.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
var addressbook; // Define the error callback for all the asynchronous calls function errorCB(err) { console.log( 'The following error occurred: ' + err.name); } function contactsFoundCB(contacts) { // The contact has been successfully found // Let's try to change the first name contacts[0].name.firstName = 'Jeffrey Ross'; try { addressbook.update(contacts[0]); } catch (err) { console.log( 'The following error occurred while updating: ' + err.name); } console.log('First contact was updated'); } // Define the success callback for retrieving all the // Address Books function addressBooksCB(addressbooks) { if(addressbooks.length > 0) { addressbook = addressbooks[0]; console.log('The addressbook type is ' + addressbook.type + ' and name ' + addressbook.name); var contact = new webapis.Contact( {name: new webapis.ContactName({firstName:'Jeffrey', lastName:'Hyman', nicknames:['joey ramone']}), emails:[new webapis.ContactEmailAddress('user@domain.com')], phoneNumbers:[new webapis.ContactPhoneNumber('123456789')]}); addressbook.add(contact); // The contact has been successfully added // Checks whether the added contact can be retrieved from the address book or not. // If the address book is empty, only the item added through saveContact // should be returned var filter = new webapis.AttributeFilter('name.firstName', 'CONTAINS', 'Jeffrey'); try { addressbook.find(contactsFoundCB, errorCB, filter); } catch (err) { console.log( 'The following error occurred while finding: ' + err.name); } } } // Get a list of available address books. webapis.contact.getAddressBooks(addressBooksCB, errorCB);
getUnifiedAddressBook
Gets the aggregation of all address books.
AddressBook getUnifiedAddressBook();
The unified address book is a logical address book that represents an aggregation of all address books that are obtained by getAddressBooks() and contains all contacts in the address books. Note that the unified address book does not have an address book ID and it is set to null.
with error type UnknownError in any other error case.
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if the functionality is not allowed.
var addressbook; // Define the error callback function errorCB(err) { console.log( 'The following error occurred: ' + err.name); } function contactsFoundCB(contacts) { // The contact has been successfully found // Let's try to change the first name contacts[0].name.firstName = 'Jeffrey Ross'; try { addressbook.update(contacts[0]); console.log('First contact was updated'); } catch (err) { console.log( 'The following error occurred while updating: ' + err.name); } } // Get unified address book. addressbook = webapis.contact.getUnifiedAddressBook(); // Add a new contact var contact = new webapis.Contact( {name: new webapis.ContactName({firstName:'Jeffrey', lastName:'Hyman', nicknames:['joey ramone']}), emails:[new webapis.ContactEmailAddress('user@domain.com')], phoneNumbers:[new webapis.ContactPhoneNumber('123456789')]}); try { addressbook.add(contact); } catch (err) { console.log( 'The following error occurred while adding: ' + err.name); } // The contact has been successfully added // Let's try to check if we can retrieve the added // contact from the address book. If the address book // was empty only the item added through saveContact should // be returned var filter = new webapis.AttributeFiilter('name.firstName', 'CONTAINS', 'Jeffrey'); try { addressbook.find(contactsFoundCB, errorCB, filter); } catch (err) { console.log( 'The following error occurred while finding: ' + err.name); }
getDefaultAddressBook
Gets the default address book.
AddressBook getDefaultAddressBook();
The default address book is the appointed addressbook from platform or operator. This is one of addressBooks and it has the address book ID.
If the operation completes successfully, it must return the default address book.
with error type UnknownError in any other error case.
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if the functionality is not allowed.
var addressbook; // Define the error callback function errorCB(err) { console.log( 'The following error occurred: ' + err.name); } function contactsFoundCB(contacts) { // The contact has been successfully found // Let's try to change the first name contacts[0].name.firstName = 'Jeffrey Ross'; try { addressbook.update(contacts[0]); console.log('First contact was updated'); } catch (err) { console.log( 'The following error occurred while updating: ' + err.name); } } // Get default address book. addressbook = webapis.contact.getDefaultAddressBook(); // Add a new contact var contact = new webapis.Contact( {name: new webapis.ContactName({firstName:'Jeffrey', lastName:'Hyman', nicknames:['joey ramone']}), emails:[new webapis.ContactEmailAddress('user@domain.com')], phoneNumbers:[new webapis.ContactPhoneNumber('123456789')]}); try { addressbook.add(contact); } catch (err) { console.log( 'The following error occurred while adding: ' + err.name); } // The contact has been successfully added // Checks whether the added contact can be retrieved from the address book or not. // If the address book is empty, only the item added // through em>saveContact /em>should be returned var filter = new webapis.AttributeFiilter('name.firstName', 'CONTAINS', 'Jeffrey'); try { addressbook.find(contactsFoundCB, errorCB, filter); } catch (err) { console.log( 'The following error occurred while finding: ' + err.name); }
getAddressBook
Gets the address book with the specified identifier.
AddressBook getAddressBook(AddressBookId addressBookId);
If the operation completes successfully, it must return the address book with the specified identifier.
with error type UnknownError in any other error case.
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if the functionality is not allowed.
with error type InvalidValuesError, if any of the input parameters contain an invalid value.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type NotFoundError, if there is no address book with the given identifier.
var contactRef; // ContactRef supposed to be initialized try { // Retrieves the Contact corresponding to a given ContactRef. var addressBook = webapis.contact.getAddressBook(contactRef.addressBookId); var contact = addressBook.get(contactRef.contactId); console.log("Successfully resolved contact with id: " + contactRef.contactId); } catch(err) { console.log("Error: " + err.name); }
get
Gets the person with the specified identifier.
Person get(PersonId personId);
If the operation completes successfully, it must return the person with the specified identifier.
with error type UnknownError in any other error case.
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if the functionality is not allowed.
with error type InvalidValuesError, if any of the input parameters contain an invalid value.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type NotFoundError, if there is no person with the given identifier.
var contactRef; // ContactRef supposed to be initialized try { // Retrieves the Person corresponding to a Contact. var addressBook = webapis.contact.getAddressBook(contactRef.addressBookId); var contact = addressBook.get(contactRef.contactId); var person = webapis.contact.get(contact.personId); console.log("Successfully resolved person with id: " + contact.personId); } catch(err) { console.log("Error: " + err.name); }
update
Updates a person in the address book synchronously.
void update(Person person);
with error type UnknownError, if the person could not be updated to an unknown error.
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if the functionality is not allowed.
with error type InvalidValuesError, if any input parameter contains invalid values.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type NotFoundError, if the identifier does not match.
// Define the error callback function errorCB(err) { console.log( 'The following error occurred: ' + err.name); } function personsFoundCB(persons) { // The person has been successfully found // Let's try to change the isFavorite attribute persons[0].isFavorite = true; try { webapis.contact.update(persons[0]); console.log('First person was updated'); } catch (err) { console.log( 'The following error occurred while updating: ' + err.name); } } try { webapis.contact.find(personsFoundCB, errorCB); } catch (err) { console.log( 'The following error occurred while finding: ' + err.name); }
updateBatch
Updates several existing persons in the contact DB asynchronously.
void updateBatch(Person[] persons, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
The errorCallback() is launched with these error types:
If the details of any persons cannot be updated, the error callback function that was passed in the invocation will be called.
with error type NotSupportedError, if this feature is not supported.
with error type SecurityError, if this functionality is not allowed.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
// Define the error callback for all the asynchronous calls function errorCB(err) { console.log('The following error occurred: ' + err.name); } function personsUpdatedCB() { console.log('Contacts were updated'); } function personsFoundCB(persons) { // The person has been successfully found for(var i = 0; i < persons.length; i++) { persons[i].isFavorite = true; } try { webapis.contact.updateBatch(persons, personsUpdatedCB, errorCB); } catch (err) { console.log('The following error occurred while updating: ' + err.name); } } try { webapis.contact.find(personsFoundCB, errorCB); } catch (err) { console.log('The following error occurred while finding: ' + err.name); }
remove
Removes a person from the contact DB synchronously.
void remove(PersonId personId);
Removes the person that corresponds to the specified identifier and the contacts related to the person as well. This function will throw an exception if it fails to remove the specified person.
with error type UnknownError, if the person could not be removed to an unknown error.
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if the functionality is not allowed.
with error type InvalidValuesError, if any input parameter contains invalid values.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type NotFoundError, if the identifier does not match any persons.
// Define the error callback function errorCB(err) { console.log('The following error occurred: ' + err.name); } function personsFoundCB(persons) { // The person has been successfully found if(persons.length > 0) { try { webapis.contact.remove(persons[0].id); console.log('First person was removed'); } catch (err) { console.log('The following error occurred while removing: ' + err.name); } } else { console.log( 'No persons.'); } } try { webapis.contact.find(personsFoundCB, errorCB); } catch (err) { console.log( 'The following error occurred while finding: ' + err.name); }
removeBatch
Removes persons from contact DB asynchronously.
void removeBatch(PersonId[] personIds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
Removes the persons that correspond to the specified identifiers as well as the contacts related to them.
The errorCallback() is launched with these error types:
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if the functionality is not allowed.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
// Define the error callback function errorCB(err) { console.log( 'The following error occurred: ' + err.name); } function personsRemovedCB() { console.log('Contacts were removed'); } function personsFoundCB(persons) { // The person has been successfully found if(persons.length > 2) { try { webapis.contact.removeBatch([persons[0].id, persons[1].id], personsRemovedCB, errorCB); } catch (err) { console.log( 'The following error occurred while removing: ' + err.name); } } else { console.log( 'Not enough persons.'); } } try { webapis.contact.find(personsFoundCB, errorCB); } catch (err) { console.log( 'The following error occurred while finding: ' + err.name); }
find
Gets an array of all Person objects from the contact DB or the ones that match the optionally supplied filter.
void find(PersonArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional AbstractFilter? filter, optional SortMode? sortMode);
If the filter is passed and contains valid values, only those values in the address book that match the filter criteria as specified in the AbstractFilter interface will be returned in the successCallback. If no filter is passed, the filter contains any invalid values, the filter is null or undefined, then the implementation must return the full list of contact items in the successCallback. If no persons are available in the contact DB or no person matches the filter criteria, the successCallback will be invoked with an empty array.
The errorCallback() is launched with these error types:
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if the functionality is not allowed.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
// Define the error callback. function errorCB(err) { console.log( 'The following error occurred: ' + err.name); } // Define the person search success callback. function personsFoundCB(persons) { console.log(persons.length + ' results found.'); } // Finds all the persons in the contact DB that have the word Ramone in their display name var filter = new webapis.AttributeFilter('displayName', 'CONTAINS', 'Ramone'); // The persons returned by the find() query will be sorted in the ascending order of their display name. var sortingMode = new webapis.SortMode('displayName', 'ASC'); try { webapis.contact.find(personsFoundCB, errorCB, filter, sortingMode); } catch (err) { console.log( 'The following error occurred while finding: ' + err.name); }
addChangeListener
Subscribes to receive notifications about persons' changes.
long addChangeListener(PersonsChangeCallback successCallback);
When executed, the implementation must immediately return a subscription identifier that identifies the watch operation. After returning the identifier, the watch operation is started asynchronously.
with error type UnknownError in any other case.
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if the functionality is not allowed.
with error type InvalidValuesError, if any of the input parameters contain an invalid value.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
var watcherId = 0; // watcher identifier var watcher = { onpersonsadded: function(persons) { console.log(persons.length + ' persons were added'); }, onpersonsupdated: function(persons) { console.log(persons.length + ' persons were updated'); }, onpersonsremoved: function(ids) { console.log(ids.length + ' persons were deleted'); } }; // registers to be notified when the persons' changes watcherId = webapis.contact.addChangeListener(watcher);
removeChangeListener
Unsubscribes a persons' changes watch operation.
void removeChangeListener(long watchId);
If the watchId argument is valid and corresponds to a subscription already in place, the watch process must immediately stop and no further callbacks MUST be invoked. If the watchId argument is not valid or does not correspond to a valid subscription, the method should return without any further action.
with error type UnknownError in any other error case.
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if the functionality is not allowed.
with error type NotFoundError, if there is no listener with the given identifier.
with error type InvalidValuesError, if any of the input parameters contain an invalid value.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
var watcherId = 0; // watcher identifier // Receives persons' changes var watcher = { onpersonsadded: function(persons) { console.log(persons.length + ' persons were added'); }, onpersonsupdated: function(persons) { console.log(persons.length + ' persons were updated'); }, onpersonsremoved: function(ids) { console.log(ids.length + ' persons were removed'); } }; // Cancel the watch operation function cancelWatch() { webapis.contact.removeChangeListener(watcherId); } // registers to be notified when the persons' changes watcherId = webapis.contact.addChangeListener(watcher);
This interface provides methods to manage an address book.
[NoInterfaceObject] interface AddressBook { readonly attribute AddressBookId? id; readonly attribute DOMString name; readonly attribute boolean readOnly; Contact get(ContactId id) raises(WebAPIException); void add(Contact contact) raises(WebAPIException); void addBatch(Contact[] contacts, optional ContactArraySuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void update(Contact contact) raises(WebAPIException); void updateBatch(Contact[] contacts, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void remove(ContactId id) raises(WebAPIException); void removeBatch(ContactId[] ids, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void find(ContactArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional AbstractFilter? filter, optional SortMode? sortMode) raises(WebAPIException); long addChangeListener(AddressBookChangeCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void removeChangeListener(long watchId) raises(WebAPIException); ContactGroup getGroup(ContactGroupId groupId) raises(WebAPIException); void addGroup(ContactGroup group) raises(WebAPIException); void updateGroup(ContactGroup group) raises(WebAPIException); void removeGroup(ContactGroupId groupId) raises(WebAPIException); ContactGroup[] getGroups() raises(WebAPIException); };
An address book is a collection of contacts and groups. This interface offers methods to manage the address book and to manipulate contacts within the address book, such as:
This interface also offers methods to manipulate groups within the address book, such as:
readonly
AddressBookId? id
An attribute to uniquely identify the address book.
The value of this attribute shall be null if the address book is the unified address book.
readonly
DOMString name
The address book descriptive name.
readonly
boolean readOnly
An attribute to indicate if the address book is read-only.
Some on line address books cannot be edited and will have this flag set to true.
get
Gets the contact with the specified identifier.
Contact get(ContactId id);
If the operation completes successfully, it must return the contact with the specified identifier.
with error type UnknownError in any other error case.
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if the functionality is not allowed.
with error type InvalidValuesError, if any of the input parameters contain an invalid value.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type NotFoundError, if there is no contact with the given identifier.
var contactRef; // ContactRef supposed to be initialized try { // Retrieves the Contact corresponding to a given ContactRef. var addressBook = webapis.contact.getAddressBook(contactRef.addressBookId); var contact = addressBook.get(contactRef.contactId); console.log("Successfully resolved contact with id: " + contactRef.contactId); } catch(err) { console.log("Error: " + err.name); }
add
Adds a contact to the address book synchronously.
void add(Contact contact);
If the contact is successfully inserted in the addressbook, the Contact object will have its identifier (id attribute) set when the function returns. This operation is done successfully, new person object is also generated automatically.
If you wish to update an existing contact, call the update() method instead. If you wish to add a copy of an existing Contact object, call Contact.clone() method first and pass the clone to the add() method.
The contact shall be added to default address book if the address book is the unified address book.
with error type UnknownError, if any other error occurs while trying to insert the contact.
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if the functionality is not allowed.
with error type InvalidValuesError, if any input parameter contains invalid values.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
var addressbook; // Get default address book addressbook = webapis.contact.getDefaultAddressBook(); try { var contact = new webapis.Contact({name: new webapis.ContactName({firstName:'Jeffrey', lastName:'Hyman', nicknames:['joey ramone']}), emails:[new webapis.ContactEmailAddress('user@domain.com')], phoneNumbers:[new webapis.ContactPhoneNumber('123456789')]}); addressbook.add(contact); console.log('Contact added with id ' + contact.id); } catch (err) { console.log( 'The following error occurred while adding: ' + err.name); }
addBatch
Adds several contacts to the address book asynchronously.
void addBatch(Contact[] contacts, optional ContactArraySuccessCallback? successCallback, optional ErrorCallback? errorCallback);
If all the contacts are successfully added to the address book, the success callback will be invoked, passing the list of Contact objects that were added, with their identifier set (id attribute).
The errorCallback() is launched with these error types:
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.
with error type NotSupportedError, if this feature is not supported.
with error type SecurityError, if this functionality is not allowed.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
var addressbook; // Define the error callback function errorCB(err) { console.log( 'The following error occurred: ' + err.name); } // Define the add contact success callback function contactsAddedCB(contacts) { console.log( contacts.length + ' contact(s) were successfully added to an Address Book' ); }; // Get default address book addressbook = webapis.contact.getDefaultAddressBook(); var c1 = new webapis.Contact({name: new webapis.ContactName({firstName:'Jeffrey', lastName:'Hyman', nicknames:['joey ramone']}), emails:[new webapis.ContactEmailAddress('user1@domain.com')], phoneNumbers:[new webapis.ContactPhoneNumber('123456789')]}); var c2 = new webapis.Contact({name: new webapis.ContactName({firstName:'Elton', lastName:'John', nicknames:['El']}), emails:[new webapis.ContactEmailAddress('user2@domain.com')], phoneNumbers:[new webapis.ContactPhoneNumber('987654321')]}); try { addressbook.addBatch([c1, c2], contactsAddedCB, errorCB); } catch (err) { console.log( 'The following error occurred while adding: ' + err.name); }
update
Updates a contact in the address book synchronously.
void update(Contact contact);
with error type UnknownError, if the contact could not be updated to an unknown error.
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if the functionality is not allowed.
with error type InvalidValuesError, if any input parameter contains invalid values.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type NotFoundError, if the identifier does not match.
var addressbook; // Define the error callback function errorCB(err) { console.log( 'The following error occurred: ' + err.name); } function contactsFoundCB(contacts) { // The contact has been successfully found // Let's try to change the first name contacts[0].name.firstName = 'Christopher'; try { addressbook.update(contacts[0]); console.log('First contact was updated'); } catch (err) { console.log( 'The following error occurred while updating: ' + err.name); } } // Get default address book. addressbook = webapis.contact.getDefaultAddressBook(); var filter = new webapis.AttributeFilter('name.firstName', 'CONTAINS', 'Chris'); try { addressbook.find(contactsFoundCB, errorCB, filter); } catch (err) { console.log( 'The following error occurred while finding: ' + err.name); }
updateBatch
Updates several existing contacts in the address book asynchronously.
void updateBatch(Contact[] contacts, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
The errorCallback() is launched with these error types:
If any of the contacts could not be updated, the error callback function that was passed in the invocation will be called.
with error type NotSupportedError, if this feature is not supported.
with error type SecurityError, if this functionality is not allowed.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
var addressbook; // Define the error callback for all the asynchronous calls function errorCB(err) { console.log('The following error occurred: ' + err.name); } function contactsUpdatedCB() { console.log('Contacts were updated'); } function contactsFoundCB(contacts) { // The contact has been successfully found for(var i = 0; i < contacts.length; i++) { contacts[i].name.firstName = 'Christopher'; } try { addressbook.updateBatch(contacts, contactsUpdatedCB, errorCB); } catch (err) { console.log('The following error occurred while updating: ' + err.name); } } // Get default address book. addressbook = webapis.contact.getDefaultAddressBook(); var filter = new webapis.AttributeFilter('name.firstName', 'CONTAINS', 'Chris'); try { addressbook.find(contactsFoundCB, errorCB, filter); } catch (err) { console.log('The following error occurred while finding: ' + err.name); }
remove
Removes a contact from the address book synchronously.
void remove(ContactId id);
Removes the contact in the address book that corresponds to the specified identifier. This function will throw an exception if it failed to remove the specified contact.
with error type UnknownError, if the contact could not be removed to an unknown error.
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if the functionality is not allowed.
with error type InvalidValuesError, if any input parameter contains invalid values.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type NotFoundError, if the identifier does not match any contact in the address book.
var addressbook; // Define the error callback function errorCB(err) { console.log('The following error occurred: ' + err.name); } function contactsFoundCB(contacts) { // The contact has been successfully found if(contacts.length > 0) { try { addressbook.remove(contacts[0].id); console.log('First contact was removed'); } catch (err) { console.log('The following error occurred while removing: ' + err.name); } } else { console.log( 'No contacts.'); } } // Get default address book. addressbook = webapis.contact.getDefaultAddressBook(); var filter = new webapis.AttributeFilter('name.firstName', 'CONTAINS', 'Chris'); try { addressbook.find(contactsFoundCB, errorCB, filter); } catch (err) { console.log( 'The following error occurred while finding: ' + err.name); }
removeBatch
Removes several contacts from the address book asynchronously.
void removeBatch(ContactId[] ids, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
The errorCallback() is launched with these error types:
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if the functionality is not allowed.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
var addressbook; // Define the error callback function errorCB(err) { console.log( 'The following error occurred: ' + err.name); } function contactsRemovedCB() { console.log('Contacts were removed'); } function contactsFoundCB(contacts) { // The contact has been successfully found if(contacts.length > 2) { try { addressbook.removeBatch([contacts[0].id, contacts[1].id], contactsRemovedCB, errorCB); } catch (err) { console.log( 'The following error occurred while removing: ' + err.name); } } else { console.log( 'Not enough contacts.'); } } // Get default address book. addressbook = webapis.contact.getDefaultAddressBook(); var filter = new webapis.AttributeFilter('name.firstName', 'CONTAINS', 'Chris'); try { addressbook.find(contactsFoundCB, errorCB, filter); } catch (err) { console.log( 'The following error occurred while finding: ' + err.name); }
find
Finds an array of all Contact objects from the specified address book or an array of Contact objects that match the optionally supplied filter.
void find(ContactArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional AbstractFilter? filter, optional SortMode? sortMode);
If the filter is passed and contains valid values, only those values in the address book that match the filter criteria as specified in the AbstractFilter interface will be returned in the successCallback. If no filter is passed, the filter contains any invalid values, the filter is null or undefined, then the implementation MUST return the full list of contact items in the successCallback. If no contacts are available in the address book or no contact matches the filter criteria, the successCallback will be invoked with an empty array.
The errorCallback() is launched with these error types:
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if the functionality is not allowed.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
var addressbook; // Define the error callback. function errorCB(err) { console.log( 'The following error occurred: ' + err.name); } // Define the contact search success callback. function contactsFoundCB(contacts) { console.log(contacts.length + ' results found.'); } // Get default address book addressbook = webapis.contact.getDefaultAddressBook(); // Find all contacts in the address book that have "Ramone" in the nick name. var filter = new webapis.AttributeFilter('name.nicknames', 'CONTAINS', 'Ramone'); // The contacts returned by the find() query will be sorted by // ascending last name. var sortingMode = new webapis.SortMode('name.lastName', 'ASC'); try { addressbook.find(contactsFoundCB, errorCB, filter, sortingModes); } catch (err) { console.log( 'The following error occurred while finding: ' + err.name); }
addChangeListener
Subscribes to receive notifications about address book changes.
long addChangeListener(AddressBookChangeCallback successCallback, optional ErrorCallback? errorCallback);
When executed, the implementation must immediately return a subscription identifier that identifies the watch operation. After returning the identifier, the watch operation is started asynchronously.
with error type UnknownError in any other case.
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if the functionality is not allowed.
with error type InvalidValuesError, if any of the input parameters contain an invalid value.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
var watcherId = 0; // watcher identifier var addressbook; // This example assumes addressbook is initialized var watcher = { oncontactsadded: function(contacts) { console.log(contacts.length + ' contacts were added'); }, oncontactsupdated: function(contacts) { console.log(contacts.length + ' contacts were updated'); }, oncontactsremoved: function(ids) { console.log(ids.length + ' contacts were deleted'); } }; // Registers to be notified when the address book changes watcherId = addressbook.addChangeListener(watcher);
removeChangeListener
Unsubscribes an address book changes watch operation.
void removeChangeListener(long watchId);
If the watchId argument is valid and corresponds to a subscription already in place, the watch process MUST immediately stop and no further callbacks MUST be invoked. If the watchId argument is not valid or does not correspond to a valid subscription, the method should return without any further action.
with error type UnknownError in any other error case.
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if the functionality is not allowed.
with error type NotFoundError, if there is no listener with the given identifier.
with error type InvalidValuesError, if any of the input parameters contain an invalid value.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
var watcherId = 0; // watcher identifier var addressbook; // This example assumes addressbook is initialized // Receives address book changes var watcher = { oncontactsadded: function(contacts) { console.log(contacts.length + ' contacts were added'); }, oncontactsupdated: function(contacts) { console.log(contacts.length + ' contacts were updated'); }, oncontactsremoved: function(ids) { console.log(ids.length + ' contacts were removed'); } }; // Cancel the watch operation function cancelWatch() { addressbook.removeChangeListener(watcherId); } // registers to be notified when the address book changes watcherId = addressbook.addChangeListener(watcher);
getGroup
Gets the group with the specified identifier.
ContactGroup getGroup(ContactGroupId groupId);
If the operation completes successfully, it must return the group with the given identifier.
with error type UnknownError in any other error case.
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if the functionality is not allowed.
with error type InvalidValuesError, if any of the input parameters contain an invalid value.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type NotFoundError, if there is no contact with the given identifier.
try { // Retrieves the Person corresponding to a Contact. var addressBook = webapis.contact.getAddressBook(contactRef.addressBookId); var contact = addressBook.get(contactRef.contactId); var group = addressBook.getGroup(contact.groupIds[0].id); console.log("Successfully resolved group with id: " + contact.groupIds[0].id); } catch(err) { console.log("Error: " + err.name); }
addGroup
Adds a group to the address book.
void addGroup(ContactGroup group);
If the group is successfully inserted in the addressbook, the Group object will have its identifier (id attribute) set when the function returns.
The group shall be added to local phone address book if the address book is the default address book.
with error type UnknownError, if any other error occurs while trying to insert the contact.
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if the functionality is not allowed.
with error type InvalidValuesError, if any input parameter contains invalid values.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
var addressbook; // Get address book var addressbooks = webapis.contact.getAddressBooks(); addressbook = addressbooks[0]; try { var group = new webapis.ContactGroup('Company'); addressbook.addGroup(group); console.log('Group added with id ' + group.id); } catch (err) { console.log( 'The following error occurred while adding: ' + err.name); }
updateGroup
Updates a group in the address book.
void updateGroup(ContactGroup group);
with error type UnknownError, if the group could not be updated to an unknown error.
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if the functionality is not allowed.
with error type InvalidValuesError, if any input parameter contains invalid values.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
var addressbook; // Get address book. var addressbooks = webapis.contact.getAddressBooks(); addressbook = addressbooks[0]; try { groups = addressbook.getGroups(); groups[0].name = 'Friends'; addressbook.updateGroup(groups[0]); console.log('First group was updated'); } catch (err) { console.log( 'The following error occurred while adding: ' + err.name); }
removeGroup
Removes a group from the address book.
void removeGroup(ContactGroupId groupId);
Removes the group in the address book that corresponds to the specified identifier. This method will throw an exception if it failed to remove the specified group.
with error type UnknownError, if the group could not be removed to an unknown error.
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if the functionality is not allowed.
with error type InvalidValuesError, if any input parameter contains invalid values.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type NotFoundError, if the identifier does not match any contact in the address book.
var addressbook; // Get default address book. var addressbooks = webapis.contact.getAddressBooks(); addressbook = addressbooks[0]; try { groups = addressbook.getGroups(); addressbook.removeGroup(groups[0].id); console.log('First group was removed'); } catch (err) { console.log( 'The following error occurred while finding: ' + err.name); }
getGroups
Gets an array of all ContactGroup objects from the specified address book.
ContactGroup[] getGroups();
with error type UnknownError, if the group could not be retrieved due to an unknown error.
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if the functionality is not allowed.
with error type InvalidValuesError, if any input parameter contains invalid values.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type NotFoundError, if the identifier does not match any contact in the address book.
var addressbook; // Get default address book. var addressbooks = webapis.contact.getAddressBooks(); addressbook = addressbooks[0]; try { groups = addressbook.getGroups(); console.log('Number of groups is ' + groups.length); } catch (err) { console.log( 'The following error occurred while finding: ' + err.name); }
The person object.
[NoInterfaceObject] interface Person { readonly attribute PersonId id; readonly attribute DOMString displayName; readonly attribute long contactCount; readonly attribute boolean hasPhoneNumber; readonly attribute boolean hasEmail; attribute boolean isFavorite; attribute DOMString? photoURI; attribute DOMString? ringtoneURI; attribute ContactId displayContactId; void link(PersonId personId) raises(WebAPIException); Person unlink(ContactId contactId) raises(WebAPIException); };
readonly
PersonId id
The identifier of the person.
readonly
DOMString displayName
An attribute to identify a person by storing the display name in a string. It is selected from the contacts' display names.
readonly
long contactCount
An attribute to count the number of the contacts that belong to a person.
readonly
boolean hasPhoneNumber
An attribute to indicate if a person has a phone number.
readonly
boolean hasEmail
An attribute to indicate if the person has an email addresses.
boolean isFavorite
An attribute to indicate whether the contact is a favorite or not.
Indicates if the person was marked as Favorite or not.
By default, this attribute is set to false.
DOMString? photoURI
The URI of a picture of a person.
This attribute is used to store a URI that points to an image that can represent the person object. This attribute only contains a local file URI. Person's photoURI is bounded to linked contacts' valid photoURI. It means that if photoURI is existed, it can't become null and except linked contact's photoURI, any file can't be set as photoURI
By default, this attribute is set to null.
DOMString? ringtoneURI
An attribute to specify and store the URI of a custom ringtone for a contact.
By default, this attribute is initialized to null. This attribute only contains a local file URI.
ContactId displayContactId
The ID of a contact that represents information of the person.
The contact, this value is indicating, is used to show detailed information of the person.
link
Aggregates another person to this person.
void link(PersonId personId);
Person is a meta object which aggregates contacts and to make a person, user should combine related contacts. For this operation, link method is provided. If "Person A" is linked to "Person B", contacts related to "Person A" are aggregated to "Person B". After this function returns, the target "Person A" is removed from DB.
with error type UnknownError, if any other error occurs while trying to insert the contact.
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if the functionality is not allowed.
with error type InvalidValuesError, if any input parameter contains invalid values.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
// Define the error callback for all the asynchronous calls function errorCB(err) { console.log( 'The following error occurred: ' + err.name); } function personsFoundCB(persons) { // The persons has been successfully found try { persons[0].link(persons[1].id); console.log('Second person was merged to the first person.'); } catch (err) { console.log( 'The following error occurred while updating: ' + err.name); } } try { webapis.contact.find(personsFoundCB, errorCB); } catch (err) { console.log( 'The following error occurred while adding: ' + err.name); }
unlink
Separates a contact from this person.
Person unlink(ContactId contactId);
Person is aggregated contacts and if a user wants to detach one contact from person, unlink method is provided. Unlink is basically detaching a contact object from linked contacts so only a contact Id linked to the person can be used as the input parameter. This function returns a newly created Person object that indicates the separated contact.
with error type UnknownError, if any other error occurs while trying to insert the contact.
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if the functionality is not allowed.
with error type InvalidValuesError, if any input parameter contains invalid values.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
var myPersonId = '1'; //ID of modified var addressbook; // Default addressbook var person; // Existing person obtained from addressbook var newPerson; // New person, which will be created during unlink // Define the error callback. function errorCB(err) { console.log( 'The following error occurred: ' + err.name); } // Define the contact search success callback. function contactsFoundCB(contacts) { if (contacts.length > 1) { try { // unlink first contact newPerson = person.unlink(contacts[0].id); } catch (err) { console.log( 'The following error occurred while unlink: ' + err.name); } } else { console.log( 'Not enough contacts '); } } try { // Get person person = webapis.contact.get(myPersonId); // Get default address book addressbook = webapis.contact.getDefaultAddressBook(); // Find all contacts in the default address book that personId // is exactly myPersonId var filter = new webapis.AttributeFilter('personId', 'EXACTLY', myPersonId); addressbook.find(contactsFoundCB, errorCB, filter); } catch (err) { console.log( 'The following error occurred while processing: ' + err.name); }
Provides a dictionary for specifying contact attributes upon contact creation.
dictionary ContactInit { ContactName name; ContactAddress[] addresses; DOMString photoURI; ContactPhoneNumber[] phoneNumbers; ContactEmailAddress[] emails; Date birthday; ContactAnniversary[] anniversaries; ContactOrganization[] organizations; DOMString[] notes; ContactWebSite[] urls; DOMString ringtoneURI; ContactGroupId[] groupIds; };
This dictionary is used to input parameters when contacts are created.
This interface is used to create a Contact object.
[Constructor(optional ContactInit? ContactInitDict), Constructor(DOMString stringRepresentation)] interface Contact { readonly attribute ContactId? id; readonly attribute PersonId? personId; readonly attribute AddressBookId? addressBookId; readonly attribute Date? lastUpdated; readonly attribute boolean isFavorite; attribute ContactName? name setraises(WebAPIException); attribute ContactAddress[] addresses setraises(WebAPIException); attribute DOMString? photoURI setraises(WebAPIException); attribute ContactPhoneNumber[] phoneNumbers setraises(WebAPIException); attribute ContactEmailAddress[] emails setraises(WebAPIException); attribute Date? birthday setraises(WebAPIException); attribute ContactAnniversary[] anniversaries setraises(WebAPIException); attribute ContactOrganization[] organizations setraises(WebAPIException); attribute DOMString[] notes setraises(WebAPIException); attribute ContactWebSite[] urls setraises(WebAPIException); attribute DOMString? ringtoneURI setraises(WebAPIException); attribute ContactGroupId[] groupIds setraises(WebAPIException); DOMString convertToString(optional ContactTextFormat? format) raises(WebAPIException); Contact clone() raises(WebAPIException); };
// Get the default address book var addressbook = webapis.contact.getDefaultAddressBook(); var contact = null; try { contact = new webapis.Contact( "BEGIN:VCARD\n"+ "VERSION:3.0\n"+ "N:Gump;Forrest\n"+ "FN:Forrest Gump\n"+ "ORG:Bubba Gump Shrimp Co.\n"+ "TITLE:Shrimp Man\n"+ "TEL;WORK:(111) 555-1212\n"+ "TEL;HOME:(404) 555-1212\n"+ "EMAIL;WORK;PREF:forrestgump@example.com\n"+ "END:VCARD"); } catch (err) { console.log( 'The following error occurred while converting: ' + err.name); } try { if (contact) { addressbook.add(contact); console.log('Contact was added with ID ' + contact.id); } } catch (err) { console.log( 'The following error occurred while adding: ' + err.name); }
readonly
ContactId? id
An attribute to identify a raw contact.
By default, this attribute is set to null.
readonly
PersonId? personId
The identifier of the person corresponding to the raw contact.
By default, this attribute is set to null.
readonly
AddressBookId? addressBookId
The identifier of the address book that corresponds to the raw contact. By default, this attribute is set to null.
readonly
Date? lastUpdated
The timestamp for the last update of a contact.
Specifies revision information about the contact.
By default, this attribute is set to null. Initially, once a contact is added to an address book, this value is the same as the creation date. For more details, see RFC 2426, Section 3.6.4.
readonly
boolean isFavorite
An attribute to indicate whether a contact is favorite or not.
This value is associated with the isFavorite attribute of Person that this contact indicates.
By default, this attribute is set to false.
if (contact.isFavorite) { // ... }
ContactName? name
An attribute to store the name of a contact.
ContactAddress[] addresses
The contact addresses.
By default, this attribute is set to an empty array.
var contactInit = {}; var contactAddr = new webapis.ContactAddres({streetAddress:'Gran Via, 32', postalCode:'50013',city:'Zaragoza',country:'ES'}); contactInit.addresses = [contactAddr];
DOMString? photoURI
The URI to the picture of the contact.
This attribute is used to store a URI that points to an image that can represent the contact object. This attribute only contains a local file URI. See RFC 2426, Section 3.1.4.
By default, this attribute is set to null.
var contactInit = {}; contactInit.photoURI = 'file:///opt/media/Downloads/mypicture.jpg';
ContactPhoneNumber[] phoneNumbers
The telephone numbers of the contact.
By default, this attribute is set to empty array.
var contactInit = {}; var phoneNumber = new webapis.ContactPhoneNumber('123456789'); contactInit.phoneNumbers = [phoneNumber];
ContactEmailAddress[] emails
The email addresses of the contact.
By default, this attribute is set to empty array.
var contactInit = {}; var email = new webapis.ContactEmailAddress('deedee@ramones.com'); contactInit.emails = [email];
Date? birthday
The birthday of the contact.
Defines specify the birthday of the contact (see RFC 2426 - Section 3.1.5).
By default, this attribute is set to null.
var contactInit = {}; contactInit.birthday = new Date(1996, 4, 15);
ContactAnniversary[] anniversaries
The list of anniversaries for the contact.
Defines specify arbitrary anniversaries for the contact (in addition to the birthday).
By default, this attribute is set to empty array.
var contactInit = {}; var marriage_anniv = new webapis.ContactAnniversary(new Date(1976, 11, 2), 'Marriage'); contactInit.anniversaries = [marriage_anniv];
ContactOrganization[] organizations
The organizations the contact belongs to.
Contains information related to the contact's company or organization.
For more details, see RFC 2426, Section 3.5.
DOMString[] notes
The notes associated to the contact.
To specify supplemental information or a comment related to the contact.
For more details, see RFC 2426, Section 3.6.2.
ContactWebSite[] urls
The URLs associated to the contact.
By default, this attribute is initialized to an empty array.
In case multiple URLs are available, the first one is the default one. For more details, see RFC 2426, Section 3.6.8.
DOMString? ringtoneURI
The URI to the custom ringtone for the contact.
To specify a custom ringtone for the contact.
By default, this attribute is initialized to null. This attribute only contains a local file URI scheme; For more details, see RFC 2426, Section 3.6.6.
ContactGroupId[] groupIds
The groups the contact belongs to.
To associate groups to the contact.
By default, this attribute is initialized to an empty array.
In a case where multiple categories are available, the first one is the default one. See RFC 2426, Section 3.6.1.
convertToString
Converts the Contact item to a string format.
DOMString convertToString(optional ContactTextFormat? format);
A textual representation for the contact will be generated and returned synchronously. The export format is set via the format parameter.
with error type UnknownError in any other error case.
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if the functionality is not allowed.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
var addressbook; // Define the error callback. function errorCB(err) { console.log( 'The following error occurred: ' + err.name); } // Define the contact find success callback. function contactsFoundCB(contacts) { try { // Convert the first contact to vCard 3.0 format var vcard = contacts[0].convertToString("VCARD_30"); console.log('textual representation of the contact is: ' + vcard); } catch (err) { console.log( 'The following error occurred while converting: ' + err.name); } } // Get the default address book addressbook = webapis.contact.getDefaultAddressBook(); // Find all contact in the address book whose first name contains the string 'Chris'. var filter = new webapis.AttributeFilter('firstName', 'CONTAINS', 'Chris'); try { addressbook.find(contactsFoundCB, errorCB, filter); } catch (err) { console.log( 'The following error occurred while finding: ' + err.name); }
clone
Contact clone();
Creates a clone of the Contact object, detached from any address book.
The Contact object returned by the clone() method will have its identifier set to null and will be detached from any address book.
with error type UnknownError in any other error case.
with error type NotSupportedError, if the feature is not supported.
with error type SecurityError, if the functionality is not allowed.
// Get default address book. var addressbook = webapis.contact.getDefaultAddressBook(); var bob = new webapis.Contact(); bob.name = new webapis.ContactName({firstName:'Bob', lastName:'Smith'}); addressbook.add(bob); var alice = bob.clone(); contact.name.firstName = "Alice"; // Bob's wife addressbook.add(alice);
The fully-defined contact reference.
[Constructor(AddressBookId addressBookId, ContactId contactId)] interface ContactRef { attribute AddressBookId addressBookId; attribute ContactId contactId; };
It contains both the identifier of the address book which the contact is in, and the contact identifier within this address book.
This interface is used by other APIs to uniquely and globally identify contacts.
AddressBookId addressBookId
The address book identifier.
ContactId contactId
The contact identifier inside the address book.
The properties of a ContactName, to pass to the ContactName constructor.
dictionary ContactNameInit { DOMString prefix; DOMString suffix; DOMString firstName; DOMString middleName; DOMString lastName; DOMString[] nicknames; DOMString phoneticFirstName; DOMString phoneticLastName; };
See ContactName interface for more information about the members.
This interface contains all information related to a contact name.
[Constructor(optional ContactNameInit? nameInitDict)] interface ContactName { attribute DOMString? prefix; attribute DOMString? suffix; attribute DOMString? firstName; attribute DOMString? middleName; attribute DOMString? lastName; attribute DOMString[] nicknames; attribute DOMString? phoneticFirstName; attribute DOMString? phoneticLastName; readonly attribute DOMString? displayName; };
DOMString? prefix
The name prefix of a contact.
By default, this attribute is initialized to null. See also RFC 2426, Section 3.1.1.
contact.name.prefix = "Dr.";
DOMString? suffix
The name suffix of a contact.
By default, this attribute is initialized to null. See also RFC 2426, Section 3.1.1.
contact.name.suffix = "Jr.";
DOMString? firstName
The first (given) name of a contact.
By default, this attribute is initialized to null. See also RFC 2426, Section 3.1.1.
contact.name.firstName = 'Douglas';
DOMString? middleName
The middle name of a contact.
By default, this attribute is initialized to null. See also RFC 2426, Section 3.1.1.
contact.name.middleName = 'Glenn';
DOMString? lastName
The last (family) name of a contact.
By default, this attribute is initialized to null. See also RFC 2426, Section 3.1.1.
contact.name.lastName = 'Colvin';
DOMString[] nicknames
The nicknames of a contact.
The nickname is a name used instead of, or in addition to, the given name of a contact, place, or thing. It can also be used to specify a familiar form of a proper name.
By default, this attribute is initialized to an empty array.
In case multiple nicknames are available the first one is the default. See RFC 2426, Section 3.1.3.
contact.name.nickNames = ['Dee Dee'];
DOMString? phoneticFirstName
The phonetic first name of a contact.
Describes how the first name should be pronounced. This is very important in some languages, such as Japanese, because the same 'Kanji' may have several pronunciations.
By default, this attribute is set to null.
DOMString? phoneticLastName
The phonetic last name of a contact.
Describes how the last name should be pronounced. This is very important in some languages, such as Japanese, because the same 'Kanji' may have several pronunciations.
By default, this attribute is set to null.
readonly
DOMString? displayName
The display name of a contact.
The string which can be displayed to identify the contact. It is composed of the first and last names if available, otherwise, it will fall back to the most adequate field available to identify the contact (such as nickname).
By default, this attribute is set to null. Initially, once a contact is added to an address book, this value is composed.
The properties of a ContactOrganization, to pass to the ContactOrganization constructor.
dictionary ContactOrganizationInit { DOMString name; DOMString department; DOMString title; DOMString role; DOMString logoURI; };
See ContactOrganization interface for information about members.
This interface contains the information about the organization or company that a contact belongs to.
[Constructor(optional ContactOrganizationInit? orgInitDict)] interface ContactOrganization { attribute DOMString? name; attribute DOMString? department; attribute DOMString? title; attribute DOMString? role; attribute DOMString? logoURI; };
By default, each of the attributes of this interface are null.
For more details, see RFC 2426, Section 3.5.
var organization = new webapis.ContactOrganization({name: "Samsung", role: "SW Engineer"});
DOMString? name
The name of an organization.
For more details, see RFC 2426, Section 3.5.5.
DOMString? department
The organizational unit name.
For more details, see RFC 2426, Section 3.5.5.
DOMString? title
The job title.
To specify the job title, functional position or function (such as 'Director, Research and Development').
For more details, see RFC 2426, Section 3.5.1.
DOMString? role
An attribute to store the role, occupation, or business category (such as 'Programmer').
For more details, see RFC 2426, Section 3.5.2.
DOMString? logoURI
The URI to the logo of a company.
To specify a graphic image of a logo associated with an organization. This attribute only contains file URI Scheme; remote pictures could be loaded to local with Download API. For more details, see RFC 2426, Section 3.5.3.
The ContactWebSite object that contains the URL and the type of web site.
[Constructor(DOMString url, optional DOMString type)] interface ContactWebSite { attribute DOMString url; attribute DOMString type; };
For more details, see RFC 2426, Section 3.6.8.
var contactInit = {} var blog = new webapis.ContactWebSite('http://www.domain.com', 'BLOG'); contactInit.urls = [blog];
DOMString url
The URL for the contact's web site.
DOMString type
The type of web site.
At least the following values must be supported:
By default, this attribute is set to HOMEPAGE.
This interface implements the ContactAnniversary object that contains the date and description of an anniversary.
[Constructor(Date date, optional DOMString? label)] interface ContactAnniversary { attribute Date date; attribute DOMString? label; };
var contactInit = {} var marriage_anniv = new webapis.ContactAnniversary(new Date(1976, 11, 2), 'Marriage'); contactInit.anniversaries = [marriage_anniv];
Date date
The date of an anniversary.
DOMString? label
The text describing an anniversary.
By default, this attribute is set to null.
The properties of a ContactAddress to pass to the ContactAddress constructor.
dictionary ContactAddressInit { DOMString country; DOMString region; DOMString city; DOMString streetAddress; DOMString additionalInformation; DOMString postalCode; boolean isDefault; DOMString[] types; };
See ContactAddress interface for more information about the members.
This interface contains a set of attributes that represent a particular point on the Earth's surface.
[Constructor(optional ContactAddressInit? addressInitDict)] interface ContactAddress { attribute DOMString? country; attribute DOMString? region; attribute DOMString? city; attribute DOMString? streetAddress; attribute DOMString? additionalInformation; attribute DOMString? postalCode; attribute boolean isDefault; attribute DOMString[] types; };
Except isDefault and types attributes, each of the attributes of this interface are set to null by default.
For more details, see RFC 2426, Section 3.2.1.
var contactInit = {}; var contactAddress = new webapis.ContactAddress({streetAddress:'Gran Via, 32', postalCode:'50013', city:'Zaragoza', country:'ES', types:['WORK']}); contactInit.contactAddress = [contactAddress];
DOMString? country
The country of the address.
It is recommended that the country is specified using the two-letter [ISO 3166-1] code.
DOMString? region
The name of a country subdivision.
For example, State (United States) or Province (Spain).
DOMString? city
The name of the locality. For example, the city, county, town, or village.
DOMString? streetAddress
The street address, for example, building number and street name/number.
DOMString? additionalInformation
An attribute to capture any other address details that are required for an accurate address. For example, floor number, apartment number, suite name, the name of an office occupant, etc.
DOMString? postalCode
The postal code of the location (also known as the zip code in the US).
boolean isDefault
The default state of an address.
Indicates if the address was marked as default or not for the contact. The only one among addresses for a person can have default property, so that this attribute might be changed without explicit modification according to the policy of platform.
It deals with the 'pref' TYPE on RFC 2426, Section 3.2.1
By default, this attribute is set to false.
DOMString[] types
The case insensitive list of address types.
For more details, see RFC 2426, Section 3.2.1.
At least the following values must be supported:
By default, this attribute is set to HOME.
The ContactPhoneNumber object that contains the number and the type of phone number.
[Constructor(DOMString number, optional DOMString[] types, optional boolean isDefault)] interface ContactPhoneNumber { attribute DOMString number; attribute boolean isDefault; attribute DOMString[]? types; };
This interface provides the phone number and the type of number, for example, work, home, car, etc., or the device subtype, for example, fax, fixed, or mobile.
For more details, see RFC 2426, Section 3.3.1
var contactInit = {}; var phoneNumber = new webapis.ContactPhoneNumber('123456789', ['WORK','VOICE'], true); contactInit.phoneNumbers = [phoneNumber];
DOMString number
The full phone number.
boolean isDefault
The default state of the phone number.
Indicates if the phone number was marked as default or not for the contact. The only one among phone numbers for a person can have default property, so that this attribute might be changed without explicit modification according to the policy of platform.
It deals with the 'pref' TYPE on RFC 2426, Section 3.3.1
By default, this attribute is set to false.
DOMString[]? types
The case insensitive list of phone types, as defined in RFC 2426.
Specifies the intended use of the phone number.
At least the following values must be supported:
The ContactEmailAddress object that contains the email address and the type of email address.
[Constructor(DOMString email, optional DOMString[] types, optional boolean isDefault)] interface ContactEmailAddress { attribute DOMString email; attribute boolean isDefault; attribute DOMString[] types; };
For more details, see RFC 2426, Section 3.3.2.
var contactInit = {}; var email = new webapis.ContactEmailAddress('user@domain.com', ['WORK']); contactInit.emails = [email];
DOMString email
The full email address.
boolean isDefault
The default state of an email address.
Indicates if the email address was marked as default or not for the contact. The only one among email addresses for a person can have default property, so that this attribute might be changed without explicit modification according to the policy of platform.
It deals with the 'pref' TYPE on RFC 2426, Section 3.3.2
By default, this attribute is set to null.
DOMString[] types
The case insensitive list of email types.
Specifies the intended use of the email address.
At least the following values must be supported:
By default, this attribute is set to WORK.
The group object.
[Constructor(DOMString name, optional DOMString? ringtoneURI, optional DOMString? photoURI)] interface ContactGroup { readonly attribute ContactGroupId? id; readonly attribute AddressBookId? addressBookId; attribute DOMString name; attribute DOMString? ringtoneURI; attribute DOMString? photoURI; readonly attribute DOMString readOnly; };
var addressbook = null; var group = null; // Define the error callback for all the asynchronous calls function errorCB(err) { console.log( 'The following error occurred: ' + err.name); } // Define the success callback for retrieving all the // Address Books function addressBooksCB(addressbooks) { addressbook = addressbooks[0]; try { group = new webapis.ContactGroup('Family', 'file://opt/media/Downloads/ring.mp3'); } catch (err) { console.log( 'The following error occurred while converting: ' + err.name); } try { if (group) { addressbook.addGroup(group); console.log('Group was added with ID ' + group.id); } } catch (err) { console.log( 'The following error occurred while adding: ' + err.name); } } webapis.contact.getAddressBooks(addressBooksCB, errorCB);
readonly
ContactGroupId? id
The identifier of a group.
By default, this attribute is set to null.
readonly
AddressBookId? addressBookId
The identifier of the address book that the group belongs to.
By default, this attribute is set to null.
DOMString name
The name of a group.
DOMString? ringtoneURI
The URI to the custom ringtone for a group.
To specify a custom ringtone for a group.
By default, this attribute is initialized to null. This attribute only contains a local file URI.
DOMString? photoURI
An attribute to store a URI that points to an image that can represent the Group object. This attribute only contains a local file URI.
By default, this attribute is set to null.
readonly
DOMString readOnly
The flag indicating if the group can be modified / removed or not. Some groups cannot be edited if this flag sets to true.
By default, this attribute is set to false.
The success callback that is used for retrieving a list of persons.
[Callback=FunctionOnly, NoInterfaceObject] interface PersonArraySuccessCallback { void onsuccess(Person[] persons); };
The success callback that takes an array of persons as an input argument. It is used in the asynchronous operation to get or save a list of persons.
onsuccess
The method invoked when a list of persons is retrieved successfully.
void onsuccess(Person[] persons);
The success callback that is used for saving and retrieving a list of contacts.
[Callback=FunctionOnly, NoInterfaceObject] interface ContactArraySuccessCallback { void onsuccess(Contact[] contacts); };
The success callback that takes an array of contacts as an input argument. It is used in the asynchronous operation to get or save a list of contacts.
onsuccess
The method invoked when a list of contacts is retrieved successfully.
void onsuccess(Contact[] contacts);
The success callback when retrieving a list of AddressBooks.
[Callback=FunctionOnly, NoInterfaceObject] interface AddressBookArraySuccessCallback { void onsuccess(AddressBook[] addressbooks); };
The success callback that takes an array of AddressBooks as an input argument. It is used in the asynchronous operation to get address books.
onsuccess
The method invoked when a list of address books is retrieved successfully.
void onsuccess(AddressBook[] addressbooks);
The interface for specifying the methods to be called for address book change notifications.
[Callback, NoInterfaceObject] interface AddressBookChangeCallback { void oncontactsadded(Contact[] contacts); void oncontactsupdated(Contact[] contacts); void oncontactsremoved(ContactId[] contactIds); };
This interface specifies a set of functions that will be invoked every time an address book change occurs (contact addition/update/deletion).
oncontactsadded
The method invoked when contacts are added to the address book.
void oncontactsadded(Contact[] contacts);
oncontactsupdated
The method invoked when contacts are updated in the address book.
void oncontactsupdated(Contact[] contacts);
oncontactsremoved
The method invoked when contacts are deleted from the address book.
void oncontactsremoved(ContactId[] contactIds);
The interface for specifying the methods to be called for change notifications.
[Callback, NoInterfaceObject] interface PersonsChangeCallback { void onpersonsadded(Person[] persons); void onpersonsupdated(Person[] persons); void onpersonsremoved(PersonId[] personIds); };
This interface specifies a set of functions that will be invoked every time person's list change occurs (person addition/update/deletion).
onpersonsadded
The method invoked when persons are added to the person list.
void onpersonsadded(Person[] persons);
onpersonsupdated
The method invoked when persons are updated in the person list.
void onpersonsupdated(Person[] persons);
onpersonsremoved
The method invoked when persons are deleted from the person list.
void onpersonsremoved(PersonId[] personIds);
module Contact { typedef DOMString AddressBookId; typedef DOMString ContactId; typedef DOMString PersonId; typedef DOMString ContactGroupId; enum ContactTextFormat {"VCARD_30"}; [NoInterfaceObject] interface ContactManagerObject { readonly attribute ContactManager contact; }; WebAPIs implements ContactManagerObject; [NoInterfaceObject] interface ContactManager { void getAddressBooks(AddressBookArraySuccessCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); AddressBook getUnifiedAddressBook() raises(WebAPIException); AddressBook getDefaultAddressBook() raises(WebAPIException); AddressBook getAddressBook(AddressBookId addressBookId) raises(WebAPIException); Person get(PersonId personId) raises(WebAPIException); void update(Person person) raises(WebAPIException); void updateBatch(Person[] persons, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void remove(PersonId personId) raises(WebAPIException); void removeBatch(PersonId[] personIds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void find(PersonArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional AbstractFilter? filter, optional SortMode? sortMode) raises(WebAPIException); long addChangeListener(PersonsChangeCallback successCallback) raises(WebAPIException); void removeChangeListener(long watchId) raises(WebAPIException); }; [NoInterfaceObject] interface AddressBook { readonly attribute AddressBookId? id; readonly attribute DOMString name; readonly attribute boolean readOnly; Contact get(ContactId id) raises(WebAPIException); void add(Contact contact) raises(WebAPIException); void addBatch(Contact[] contacts, optional ContactArraySuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void update(Contact contact) raises(WebAPIException); void updateBatch(Contact[] contacts, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void remove(ContactId id) raises(WebAPIException); void removeBatch(ContactId[] ids, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void find(ContactArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional AbstractFilter? filter, optional SortMode? sortMode) raises(WebAPIException); long addChangeListener(AddressBookChangeCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void removeChangeListener(long watchId) raises(WebAPIException); ContactGroup getGroup(ContactGroupId groupId) raises(WebAPIException); void addGroup(ContactGroup group) raises(WebAPIException); void updateGroup(ContactGroup group) raises(WebAPIException); void removeGroup(ContactGroupId groupId) raises(WebAPIException); ContactGroup[] getGroups() raises(WebAPIException); }; [NoInterfaceObject] interface Person { readonly attribute PersonId id; readonly attribute DOMString displayName; readonly attribute long contactCount; readonly attribute boolean hasPhoneNumber; readonly attribute boolean hasEmail; attribute boolean isFavorite; attribute DOMString? photoURI; attribute DOMString? ringtoneURI; attribute ContactId displayContactId; void link(PersonId personId) raises(WebAPIException); Person unlink(ContactId contactId) raises(WebAPIException); }; dictionary ContactInit { ContactName name; ContactAddress[] addresses; DOMString photoURI; ContactPhoneNumber[] phoneNumbers; ContactEmailAddress[] emails; Date birthday; ContactAnniversary[] anniversaries; ContactOrganization[] organizations; DOMString[] notes; ContactWebSite[] urls; DOMString ringtoneURI; ContactGroupId[] groupIds; }; [Constructor(optional ContactInit? ContactInitDict), Constructor(DOMString stringRepresentation)] interface Contact { readonly attribute ContactId? id; readonly attribute PersonId? personId; readonly attribute AddressBookId? addressBookId; readonly attribute Date? lastUpdated; readonly attribute boolean isFavorite; attribute ContactName? name setraises(WebAPIException); attribute ContactAddress[] addresses setraises(WebAPIException); attribute DOMString? photoURI setraises(WebAPIException); attribute ContactPhoneNumber[] phoneNumbers setraises(WebAPIException); attribute ContactEmailAddress[] emails setraises(WebAPIException); attribute Date? birthday setraises(WebAPIException); attribute ContactAnniversary[] anniversaries setraises(WebAPIException); attribute ContactOrganization[] organizations setraises(WebAPIException); attribute DOMString[] notes setraises(WebAPIException); attribute ContactWebSite[] urls setraises(WebAPIException); attribute DOMString? ringtoneURI setraises(WebAPIException); attribute ContactGroupId[] groupIds setraises(WebAPIException); DOMString convertToString(optional ContactTextFormat? format) raises(WebAPIException); Contact clone() raises(WebAPIException); }; [Constructor(AddressBookId addressBookId, ContactId contactId)] interface ContactRef { attribute AddressBookId addressBookId; attribute ContactId contactId; }; dictionary ContactNameInit { DOMString prefix; DOMString suffix; DOMString firstName; DOMString middleName; DOMString lastName; DOMString[] nicknames; DOMString phoneticFirstName; DOMString phoneticLastName; }; [Constructor(optional ContactNameInit? nameInitDict)] interface ContactName { attribute DOMString? prefix; attribute DOMString? suffix; attribute DOMString? firstName; attribute DOMString? middleName; attribute DOMString? lastName; attribute DOMString[] nicknames; attribute DOMString? phoneticFirstName; attribute DOMString? phoneticLastName; readonly attribute DOMString? displayName; }; dictionary ContactOrganizationInit { DOMString name; DOMString department; DOMString title; DOMString role; DOMString logoURI; }; [Constructor(optional ContactOrganizationInit? orgInitDict)] interface ContactOrganization { attribute DOMString? name; attribute DOMString? department; attribute DOMString? title; attribute DOMString? role; attribute DOMString? logoURI; }; [Constructor(DOMString url, optional DOMString type)] interface ContactWebSite { attribute DOMString url; attribute DOMString type; }; [Constructor(Date date, optional DOMString? label)] interface ContactAnniversary { attribute Date date; attribute DOMString? label; }; dictionary ContactAddressInit { DOMString country; DOMString region; DOMString city; DOMString streetAddress; DOMString additionalInformation; DOMString postalCode; boolean isDefault; DOMString[] types; }; [Constructor(optional ContactAddressInit? addressInitDict)] interface ContactAddress { attribute DOMString? country; attribute DOMString? region; attribute DOMString? city; attribute DOMString? streetAddress; attribute DOMString? additionalInformation; attribute DOMString? postalCode; attribute boolean isDefault; attribute DOMString[] types; }; [Constructor(DOMString number, optional DOMString[] types, optional boolean isDefault)] interface ContactPhoneNumber { attribute DOMString number; attribute boolean isDefault; attribute DOMString[]? types; }; [Constructor(DOMString email, optional DOMString[] types, optional boolean isDefault)] interface ContactEmailAddress { attribute DOMString email; attribute boolean isDefault; attribute DOMString[] types; }; [Constructor(DOMString name, optional DOMString? ringtoneURI, optional DOMString? photoURI)] interface ContactGroup { readonly attribute ContactGroupId? id; readonly attribute AddressBookId? addressBookId; attribute DOMString name; attribute DOMString? ringtoneURI; attribute DOMString? photoURI; readonly attribute DOMString readOnly; }; [Callback=FunctionOnly, NoInterfaceObject] interface PersonArraySuccessCallback { void onsuccess(Person[] persons); }; [Callback=FunctionOnly, NoInterfaceObject] interface ContactArraySuccessCallback { void onsuccess(Contact[] contacts); }; [Callback=FunctionOnly, NoInterfaceObject] interface AddressBookArraySuccessCallback { void onsuccess(AddressBook[] addressbooks); }; [Callback, NoInterfaceObject] interface AddressBookChangeCallback { void oncontactsadded(Contact[] contacts); void oncontactsupdated(Contact[] contacts); void oncontactsremoved(ContactId[] contactIds); }; [Callback, NoInterfaceObject] interface PersonsChangeCallback { void onpersonsadded(Person[] persons); void onpersonsupdated(Person[] persons); void onpersonsremoved(PersonId[] personIds); }; };