Samsung Web API enables you to manage the contacts and persons listed in your address books using the Contact API. A Contact object is always associated with a specific address book. A Person object is an aggregation of one or more contacts associated with the same person.
The main features of the Contact API include:
- Address book management
To access a contact, you must first retrieve the Contact object from the applicable address book. To access the device address books, you can use the getDefaultAddressBook() method of the ContactManager interface to retrieve the default address book, or the getAddressBooks() method to retrieve all the available address books as an array. To get a specific address book, use the getAddressBook() method.
- Contact management
You can create and manage multiple contacts simultaneously by using the applicable batch methods: addBatch(), updateBatch(), and removeBatch(). The batch mode provides faster, optimized processing of multiple contacts.
Note The batch mode does not provide progress information about operations. To ensure that you can view the progress, break the batch operation down into multiple smaller batch operations. For example, break down a batch of 100 update requests into 10 batch operations that update 10 records at a time. Additionally, breaking down a batch operation helps you avoid blocking other database operations, such as add or remove.
- Contact change notifications
You can keep the address book in your application synchronized with external contact manager by receiving notifications in your application when contact information changes.
The addChangeListener() method of the Addressbook interface registers an event listener, which starts asynchronously once the addChangeListener() method returns the subscription identifier for the listener. You can use the AddressBookChangeCallback interface to define listener event handlers for receiving the notifications.
Note The listener object that is the first argument of the addChangeListener() method must have at least 1 event handler defined. If no handlers are defined, a TypeMismatchError error occurs.
Every change made to the address book triggers an event for which you can define a notification. For batch mode operations, each operation generates a separate event.
- Person management
You can manage persons, including searching, updating, and deleting, by using the applicable methods of the ContactManager interface. When managing a single person at a time, the operations are handled in a synchronous mode.
You can handle multiple persons simultaneously using the applicable batch methods: updateBatch() and removeBatch().
Persons are automatically added or modified when contacts are added to or unlinked from existing persons. You cannot add persons directly.
When searching for persons, you can filter and sort the search results based on specific filter attributes.
- vCard format conversions
The vCard (RFC 2426) file format (.vcf or .vcard) is a standard for electronic business cards, which contain contact information, such as name, address, phone numbers, email addresses, URLs, logos, photographs, and audio clips.
The Contact API supports vCard version 3.0.