Contact: Managing Contacts and Handling Contact Information

This tutorial demonstrates how you can manage address books in the device to access, modify, add, and remove contacts within a specified address book on the device.

This feature is supported in mobile applications only.

Warm-up

Become familiar with the Contact API basics by learning about:

• Address book
  • Creating an Address Book

    Create a new address book using the AddressBook constructor.

  • Getting Address Books

    Access the address books in which contacts are listed.

• Single contacts
  • Adding a Contact

    Add a contact to an address book.

  • Managing a Contact

    Find, update, and delete an existing contact item.

  • Receiving Notifications on Contact Changes

    Receive notifications when contacts are added, updated, or deleted.

  • Importing Contacts

    Import contacts with the help of the vCard format.

  • Exporting Contacts

    Export contacts with the help of the vCard format.

• Multiple contacts
  • Adding Multiple Contacts in the Batch Mode

    Add multiple contacts to an address book in the batch mode.

  • Managing Multiple Contacts in the Batch Mode

    Find, update, and delete multiple contact items in the batch mode.

  • Managing Contact Groups

    Add, get, update, and remove groups.

• Persons
  • Managing Persons

    Find and link existing persons.

Creating an Address Book

Creating a new address book is a basic contact management skill:

Note
The created address book is associated with a specified account. Therefore, you must retrieve the account before creating a new address book.

1. Declare a variable to store the created address book:

   var myAddressBook = null;

2. Define a success callback for the getAccounts() method. The callback receives a list of Account objects. Use the first account ID to construct a new AddressBook object.

   Add the new address book to the system using the addAddressBook() method of the ContactManager interface:

   function getAccountsSuccess(accounts)
   {
      var account = accounts[0];
      if (account)
      {
         /* New address book can be created and added */
         myAddressBook = new tizen.AddressBook(account.id, "remote address book");
         tizen.contact.addAddressBook(myAddressBook);
         console.log("New address book created with ID=" + myAddressBook.id);
      }
   }

3. To retrieve available accounts, use the getAccounts() method. The following method call invokes the getAccountsSuccess event handler defined above.

   tizen.account.getAccounts(getAccountsSuccess, function(err));
   

Getting Address Books

To create engaging applications with various contacts features, you must learn to access the address books in which the contacts are listed:

1. To get the default address book, use the getDefaultAddressBook() method of the ContactManager interface to retrieve the default address book as an AddressBook object:

   var myAddressbook;
   
   /* Get the default address book */
   myAddressbook = tizen.contact.getDefaultAddressBook();
   

2. To get all available address books, use the getAddressBooks() method. This method passes an array of AddressBook objects to the success event handler.

   var addressBook;
   
   function addressBooksCB(addressBooks)
   {
      if (addressBooks.length > 0)
      {
         addressBook = addressBooks[0];
         console.log("The addressbook name is " + addressBook.name);
      }
   }
   
   /* Get the list of available address books */
   tizen.contact.getAddressBooks(addressBooksCB);
   

   All available address books on the device are retrieved. You can use an AddressBook object ID to select a specific address book with the getAddressBook() method, if you know the ID of the address book in advance.

Adding a Contact

To create engaging applications with various contacts features, you must learn to add a contact to an address book:

1. Retrieve the default system address book using the getDefaultAddressBook() method of the ContactManager interface:

   var addressbook = tizen.contact.getDefaultAddressBook();
   

2. Create a Contact object and define its properties as a ContactInit object (the parameter of the Contact constructor):

   var contact = new tizen.Contact
   ({
      name: new tizen.ContactName({firstName: "Jeffrey", lastName: "Hyman"}),
      emails: [new tizen.ContactEmailAddress("user@example.com")]
   });
   

3. Add the Contact object to the default address book with the add() method of the AddressBook interface:

   addressbook.add(contact);

Managing a Contact

To create engaging applications with various contacts features, you must learn to manage a contact in your address book:

1. To retrieve a single contact, use the get() method of the AddressBook interface with the ContactID as a parameter:

   The following example uses the object of the ContactRef interface. The ContactRef object contains both AddressBook ID and Contact ID.

   /* contactRef is retrieved by other APIs */
   var contactRef;
   try
   {
      /* Retrieve the contact corresponding to the given reference */
      var addressBook = tizen.contact.getAddressBook(contactRef.addressBookId);
      var contact = addressBook.get(contactRef.contactId);
   }
   

2. To manage a single contact:

   1. Retrieve the default address book using the getDefaultAddressBook() method of the ContactManager interface.

      var addressbook = tizen.contact.getDefaultAddressBook();
      

   2. Retrieve contacts stored in the address book by using the find() method of the AddressBook interface:

      var filter = new tizen.AttributeFilter("name.firstName", "CONTAINS", "Chris");
      var sortMode = new tizen.SortMode("name.lastName", "ASC");
      
      try
      {
         addressbook.find(contactsFoundCB, null, filter, sortMode);
      }

      Note

      To retrieve a specific contact, you can specify a filter and sorting order for the search operation through the filter and sortMode parameters (for attributes supported in the filter, see Contact Filter Attributes). In this example, contacts whose first name contains "Chris" are retrieved and sorted in the ascending order based on their last name. The filter includes the standard English characters in the uppercase and lowercase. The entire list consists of ASCII characters from 32 to 126, and from 160 to 255.

      The contacts that match the filter are passed as an array to the registered success event handler in the selected sorting order.

   3. Update or delete the found contact inside the contactsFoundCB event handler.

      In this example, the first name of the first contact is changed and the contact is updated in the address book using the update() method. The second contact is deleted using the remove() method.

      /* Define the event success callback */
      function contactsFoundCB(contacts)
      {
         contacts[0].name.firstName = "Christopher";
         try
         {
            /* Update the first found contact */
            addressbook.update(contacts[0]);
      
            /* Delete the second found contact */
            addressbook.remove(contacts[1].id);
         }
      }

Receiving Notifications on Contact Changes

To create engaging applications with various contacts features, you must learn to receive notifications when contacts are added, updated, or removed:

1. Define the needed variables:

   /* Watcher identifier */
   var watcherId = 0;
   
   /* This example assumes that the address book is initialized */
   var addressbook;
   

2. Define the event handlers for different notifications about changes in the selected address book using the AddressBookChangeCallback listener interface:

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

3. Register the listener to use the defined event handlers:

   watcherId = addressbook.addChangeListener(watcher);
   

4. To stop the notifications, use the removeChangeListener() method of the AddressBook interface:

   addressbook.removeChangeListener(watcherId);
   

Importing Contacts

To create engaging applications with various contacts features, you must learn to import contacts with the help of the vCard format:

1. Retrieve the default system address book using the getDefaultAddressBook() method of the ContactManager interface:

   var addressbook = tizen.contact.getDefaultAddressBook();
   

2. Create a new Contact object from the vCard string and add it to the default address book:

   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");
   
      addressbook.add(contact);
      console.log("Contact was added with ID " + contact.id);
   }

To convert multiple strings and import them to an address book, convert the strings one by one and then use the addBatch() method of the AddressBook interface to add all the contacts at once in the batch mode.

Exporting Contacts

To create engaging applications with various contacts features, you must learn to export contacts with the help of the vCard format:

1. Retrieve the default system address book using the getDefaultAddressBook() method of the ContactManager interface and find all contacts with "Chris" in the first name:

   var addressbook;
   
   var addressbook = tizen.contact.getDefaultAddressBook();
   
   /* Define a filter */
   var filter = new tizen.AttributeFilter("name.firstName", "CONTAINS", "Chris");
   
   /* Search for the contacts */
   addressbook.find(contactsFoundCB, errorCB, filter);
   

2. Convert a contact to a vCard string in the success event handler of the find() method.

   In the following example, the first found contact is exported by converting it to the vCard version 3.0 format.

   function contactsFoundCB(contacts)
   {
      /* Convert the first contact */
      var vcard = contacts[0].convertToString("VCARD_30");
   }

Adding Multiple Contacts in the Batch Mode

To create engaging applications with various contacts features, you must learn to add multiple contacts to an address book in the batch mode:

1. Retrieve the default system address book using the getDefaultAddressBook() method of the ContactManager interface:

   addressbook = tizen.contact.getDefaultAddressBook();
   

2. Define the items to be added as an array:

   var c1 = new tizen.Contact(
   {
      name: new tizen.ContactName({firstName:"Jeffrey", lastName:"Hyman"}),
      emails: [new tizen.ContactEmailAddress("user1@example.com")]
   });
   
   var c2 = new tizen.Contact(
   {
      name: new tizen.ContactName({firstName:"Elton", lastName:"John"}),
      emails: [new tizen.ContactEmailAddress("user2@example.com")]
   });
   

3. Use the addBatch() method of the AddressBook interface to add the contacts in the array to the address book:

   addressbook.addBatch([c1, c2]);
   

   Note
   The addBatch(), updateBatch(), and removeBatch() methods are asynchronous. Provide success and error callbacks with them.

Managing Multiple Contacts in the Batch Mode

To create engaging applications with various contacts features, you must learn to manage multiple contacts in your address books in the batch mode:

1. Retrieve the default address book using the getDefaultAddressBook() method of the ContactManager interface.

   var addressbook = tizen.contact.getDefaultAddressBook();
   

2. Retrieve contacts stored in the address book by using the find() method of the AddressBook interface:

   var filter = new tizen.AttributeFilter("name.firstName", "CONTAINS", "Chris"};
   var sortMode = new tizen.SortMode("name.lastName", "ASC");
   
   try
   {
      addressbook.find(contactsFoundCB, null, filter, sortMode);
   }

3. To update contacts:

   1. Define the contact changes to be made in the success event handler of the find() method:

      function contactsFoundCB(contacts)
      {
         /* Change the first names of all the found contacts */
         for (var i=0; i<contacts.length; i++)
         {
            contacts[i].name.firstName = "Christopher";
         }
      

   2. Use the updateBatch() method to update multiple contacts asynchronously:

         /* Update all found contacts */
         addressbook.updateBatch(contacts);
      }
      

4. To delete contacts, use the removeBatch() method in the success event handler of the find() method to delete multiple contacts asynchronously:

   function contactsFoundCB(contacts)
   {
      /* Delete the first 2 found contacts */
      addressbook.removeBatch([contacts[0].id, contacts[1].id]);
   }
   

Managing Contact Groups

To create engaging applications with various contact features, you must learn to manage contact groups:

1. Retrieve the default system address book using the getDefaultAddressBook() method of the ContactManager interface:

   var addressbook = tizen.contact.getDefaultAddressBook();

2. To create a ContactGroup object and add the newly create group to the system, use the constructor and the addGroup() method of the AddressBook interface:

   var group;
   try 
   {
      group = new tizen.ContactGroup("Company");
      addressbook.addGroup(group)
      console.log("Group added with ID " + group.id);
   }
   

3. To manage groups:

   • To retrieve all the contact groups from the address book, use the getGroups() method of the AddressBook interface:

     var groups;
     try 
     {
        groups = addressbook.getGroups();
     }
     

   • To change the name of the group, assign the name property a new value and use the updateGroup() method of the AddressBook interface:

     try 
     {
        groups[0].name = "Friends";
        addressbook.updateGroup(groups[0]);
        console.log("First group updated");
     }
     

   • To retrieve a specific group, use the getGroup() method of the AddressBook interface:

     try 
     {
        group = addressbook.getGroup(group.id);
     }
     

   • To remove a group from the address book, use the removeGroup() method of the AddressBook interface:

     try 
     {
        addressbook.removeGroup(group.id);
        console.log("Group was removed");
     }
     

Managing Persons

To create engaging applications with various contacts features, you must learn to manage persons in your contact database:

1. To manage a single person:

   1. To retrieve persons, use the find() method of the ContactManager interface:

      tizen.contact.find(personsFoundCB);

   2. Update or delete the found persons in the personsFoundCB() event handler. In this example, the favorite flag of the first person is changed and the contact is updated using the update() method. The second person is deleted using the remove() method.

      /* Define the event success callback */
      function personsFoundCB(persons)
      {
         persons[0].isFavorite = true;
         try
         {
            /* Update the first found person */
            tizen.contact.update(persons[0]);
      
            /* Delete the second found person */
            tizen.contact.remove(persons[1].id);
         }
      }

2. To merge multiple persons into a single person item:
   1. Retrieve the persons as described above.

   2. Define the persons to be merged in the personsFoundCB() event handler:

      function personsFoundCB(persons)
      {
         var sourcePerson = persons[0];
         var targetPerson = persons[1];

   3. Use the link() method to link contacts that are linked to the other person:

         /* Link 2 persons, contacts from sourcePerson are added to targetPerson and sourcePerson is removed */
         targetPerson.link(sourcePerson.id);
      }