Back
Overview | Project

Contacts Sample Overview

Mobile native

The Contacts sample application demonstrates how you can manage contacts using the Contacts API. The source code shows how to use the contacts database for creating and deleting contacts, making contacts favorites, viewing and changing contact information, creating and deleting contacts categories, adding contacts to categories, and viewing the favorites list.

The following figure illustrates the main screens of the application.

Figure: Contacts main views

Contacts main views

The application opens with the Contacts screen, which displays a list of existing contacts. On the screen:

  • To create a new contact, click Create, fill in the contact details, and click Save. To select the address book into which the new contact is added, click >.
  • To view the details of a contact, click the contact in the list. The detail screen displays the contact details. On this screen:
    • To edit an existing contact, click Edit.
    • To delete the contact, click Delete.
    • To change the favorite status of the contact, click Fav on the top-right corner.
  • To view the category list of the default address book, press the device menu key, and click Categories. On the Categories screen, you can view the members of the existing category by clicking the category, or add new categories by clicking Create. After clicking a category, the category member screen opens. On this screen:
    • To add a new member to the category, click Add Member.
    • To remove a member from the category, click Remove Member.
    • To delete the category, click Delete.
  • To view the favorite persons list, press the device menu key, and click Favorites.

The application uses the contacts-svc module to work with the contacts database and the elementary module to support the UI requirements.

Prerequisites

To ensure proper application execution, the following privileges must be set:

  • http://tizen.org/privilege/contact.write
  • http://tizen.org/privilege/contact.read

Source Files

You can create and view the sample application project including the source files in the IDE.

Table: Source files
Category File name Description
General main.c Provides the entry point in the application. Initializes application main data.
main-app.c Provides the implementation for Tizen main callbacks. Launches the creation of the window and navigation bar.
Model common.c Provides common utilities for the application, such as work with strings or conversion of time.
contact-details.c Provides functions to toggle favorite flags or get the favorite status for a contact.
create-group.c Provides functions to simplify group creation.
edit-contact.c Provides functions to simplify the contact creation process: for construction and destruction of contact structures, getting values from the database, and saving the contact.
group-edit-member.c Provides functions for adding members to a group, to remove members from a group, to get contacts in a group.
Model/Contacts-utils contacts-db-utils.c Provides functions to connect to the database, to disconnect from the database, and to check the connection status.
contacts-list-utils.c Provides useful functions to work with the contacts list, database queries, and filters. Hides the complexity of the work with the database.
contact-record-utils.c Provides functions to work with records. Hides the complexity of the work with the database.
Utils logger.c Provides functions to log information through the application.
ui-utils.c Provides functions to create a navigation bar, layout, toolbar, and popup buttons.
View contact-details-view.c Provides functions to create the Contact details view. The file contains code that retrieves the contact information and shows it in the genlist.
create-group-view.c Provides functions to create the Create group view. The file contains code that creates a new group in the database with a specific name.
edit-contact-view.c Provides functions to create the Edit contact view. The file contains code to retrieve contact information from the database, to show and edit the information, to delete or save the contact.
favourites-view.c Provides functions to create the Favorite contacts view. The file contains code that gets the favorite contacts and shows the information in a list.
group-details-view.c Provides functions to create the Group details view. The file contains code to get and show group details and to remove the group.
group-edit-member-view.c Provides functions to create the Edit group member view. The file contains code to add members to the group and to remove members from the group.
group-list-view.c Provides functions to create the Groups list view. The file contains code to create a list of groups saved on the device, to set up the callback on click on group, to move to the Group details or Create group views.
person-list-view.c Provides functions to create the Contacts list view. The file contains code to create a list of contacts, to set up a callback on click on contact, to set up a callback for the menu key and to move to the Categories list or Favorites list views.
window.c Provides functions to create or destroy the main application window and to set the host layout.

Displaying and Retrieving Contacts

Figure: Contacts and favorites

Contacts and favorites

To display contacts:

  1. Initialize the application by creating the window, naviframe and the Person list view. 
    static bool 
app_create_cb(void *user_data)
{
   app_data *ad = user_data;
   RETVM_IF(NULL == ad, false, "ad is null");

   ad->win = win_create();
   RETVM_IF(NULL == ad->win, false, "win is null");
    
   ad->navi = _app_navi_add(ad);
   RETVM_IF(NULL == ad->navi, false, "navi is null");

   sc_plist_view_add(ad->navi);

   return true;
}
  2. Display the contacts list.

    Contact retrieval is implemented in the <person-list-view.c> file. The sc_plist_view_add() function invokes the _plist_view_fill() function to retrieve the contact list from the database. These contacts fill the elm_list.

    static void 
_plist_view_fill(list_view_data *data)
{
   RETM_IF(NULL == data, "data is null");
   contacts_record_h record = NULL;

   contacts_list_h person_list = NULL;
   if (sc_db_utils_is_success(contacts_db_get_all_records(_contacts_person._uri, 0, 0, &person_list)))
   {
      CONTACTS_LIST_FOREACH(person_list, record)
      {
         char *name = NULL;
         int id = 0;
         if (sc_db_utils_is_success(contacts_record_get_str_p(record,
                                                              _contacts_person.display_name, 
                                                              &name))
             && sc_db_utils_is_success(contacts_record_get_int(record,
                                                               _contacts_person.id, &id)))
         {
            elm_list_item_append(data->list, reduced_name, NULL, NULL, _plist_view_sel_cb, (void *)id);
         }
      }
   }
}
  3. Display the favorites list.

    Favorites retrieval is implemented in the <favourites-view.c> file. The sc_favourites_view_add() function invokes the _favourites_view_fill() function to get the favorites list from the database, and these contacts fill the elm_list.

    static void 
_favourites_view_fill(favourites_view_data *data)
{
   RETM_IF(!data, "data is null");
   contacts_record_h record = NULL;

   data->fav_list = sc_list_utils_get_records_list_bool_filter(_contacts_person._uri,
                                                               _contacts_person.is_favorite, true);
   RETM_IF(!data->fav_list, "Favourite list is not retrieved");

   CONTACTS_LIST_FOREACH(data->fav_list, record)
   {
      char *name = NULL;
      if (sc_db_utils_is_success(contacts_record_get_str_p(record,
                                                           _contacts_person.display_name, 
                                                           &name)))
      {
         elm_list_item_append(data->list, name, NULL, NULL, _favourites_view_sel_cb, record);
      }
   }
}

Managing Contacts

Figure: Managing contacts

Managing contacts

To manage contacts:

  1. Initialize contact details.

    When the user clicks on a contact in the contacts list, the contact details view opens using the sc_cdetails_view_add() function . Then it fills the contact details using the _cdetails_view_fill() function.

    static void 
_cdetails_view_fill(contact_details_view_data *data)
{
   RETM_IF(!data, "data is null");
   Elm_Genlist_Item_Class *itc = _cdetails_view_create_item_class();

   evas_object_data_set(data->genlist, CT_DETAILS_VIEW_DATA, data);
   for (sc_common_contact_fields i = CF_PHONE_NUMBER; i < CF_MAX; ++i)
   {
      elm_genlist_item_append(data->genlist, itc, (void *)i, NULL,
                              ELM_GENLIST_ITEM_NONE, NULL, NULL);
   }

   elm_genlist_item_class_free(itc);
}
  2. Initialize a new contact and edit the contact view.

    To create a contact, the user presses the Create button in the Contacts list view. To edit a contact, the user can click Edit in the contact details view. In both cases, the sc_ec_view_add() function is invoked. It creates the new contact or edits the current one.

    void 
sc_ec_view_add(Evas_Object *parent, int contact_id)
{
   if (contact_id > 0)
   {
      data->contact_id = contact_id;
      data->data = sc_ec_create_edit_contact(data->contact_id);
   }
   else
   {
      data->contact_id = 0;
      data->data = sc_ec_create_new_contact();
   }
  3. Edit the contact using the sc_ec_create_edit_contact() function in the <edit-contact.c> file, which creates the database handle for the current contact. 
    sc_ec_contact_edit *sc_ec_create_edit_contact(int contact_id)
{
   bool is_ok = false;
   sc_ec_contact_edit *edit_contact = malloc(sizeof(sc_ec_contact_edit));
   if (edit_contact)
   {
      is_ok = sc_db_utils_is_success(contacts_db_get_record(_contacts_contact._uri, contact_id, &edit_contact->contact_record));
      edit_contact->is_new_contact = false;
   }

   if (!is_ok)
   {
      sc_ec_destruct_edit_contact(edit_contact);
   }

   return edit_contact;
}
  4. Create a new contact using the sc_ec_create_new_contact() function in the <edit-contact.c> file, which creates the new database handle for the new contact. 
    sc_ec_contact_edit *sc_ec_create_new_contact()
{
   bool is_ok = false;
   sc_ec_contact_edit *edit_contact = malloc(sizeof(sc_ec_contact_edit));
   if (edit_contact)
   {
      is_ok = sc_db_utils_is_success(contacts_record_create(_contacts_contact._uri, &edit_contact->contact_record));
      edit_contact->is_new_contact = true;
   }

   if (!is_ok)
   {
      sc_ec_destruct_edit_contact(edit_contact);
   }

   return edit_contact;
}
  5. Fill a contact to the elm_genlist. 
    static void 
_ec_view_fill(contact_edit_view_data *data)
{
   for (sc_common_contact_fields i = CF_FIRST_NAME; i < CF_MAX; ++i)
   {
      if (CF_BIRTHDAY == i)
      {
         elm_genlist_item_append(data->genlist, itc_birthday, (void *)i, NULL,
                                 ELM_GENLIST_ITEM_NONE, NULL, NULL);
      }
      else
      {
         elm_genlist_item_append(data->genlist, itc_entry, (void *)i, NULL,
                                 ELM_GENLIST_ITEM_NONE, NULL, NULL);
      }
   }
}

Managing Categories

To manage categories:

  1. Create categories.

    The category creation is implemented in the <create-group.c> file.

    When the user clicks Create on the Categories screen, the Create Category view opens and the user can enter a category name. When the user clicks Save, the _gcreate_view_create_group_cb() smart callback is invoked. That callback calls the sc_gcreate_db_create_group() function to add the category to the specified address book.

    bool 
sc_gcreate_db_create_group(const char *group_name)
{
   bool result = false;
   contacts_record_h record = NULL;
   result = sc_db_utils_is_success(contacts_record_create(_contacts_group._uri, &record));
   if (result)
   {
      Result = sc_db_utils_is_success(contacts_record_set_str(record, _contacts_group.name, group_name));
      if (result)
      {
         result = sc_db_utils_is_success(contacts_db_insert_record(record, NULL));
      }
      contacts_record_destroy(record, true);
   }

   return result;
}
  2. Edit category members.

    The category member addition and removal are implemented in the <group-edit-member-view.> file.

    When the user clicks Add Member on a specific category screen, the Add Member screen opens and the user can select a contact to add to the category. When the user clicks Add Member, the contacts_group_add_contact() function adds the selected contact to the category.

    When the user clicks Remove Member on a specific category screen, the Remove Member screen opens and the user can select a member to remove from the category. When the user clicks Remove, the contacts_group_remove_contact() function removes the selected member from the category.

    static void 
_gedit_member_view_edit_cb(void *data, Evas_Object *obj, void *event_info)
{
   RETM_IF(!data, "data is null");
   group_edit_member_view_data *member_data = data;

   if (member_data->type == EDIT_MEMBER_TYPE_ADD)
   {
      contacts_group_add_contact(member_data->group_id, check_data->contact_id);
   }
   else if (member_data->type == EDIT_MEMBER_TYPE_REMOVE)
   {
      contacts_group_remove_contact(member_data->group_id, _data->contact_id);
   }
}