Contacts API 2.0 and above | Android Developer Tutorial

Starting from Android 2.0 (API Level 5), the Android platform provides an improved Contacts API for managing and integrating contacts from multiple accounts and from other data sources. To handle overlapping data from multiple sources, the contacts content provider aggregates similar contacts and presents them to users as a single entity. This article describes how to use the new API to manage (insert, update, delete, view) contacts.

The new Contacts API is defined in the android.provider.ContactsContract and related classes. The older API is still supported, although deprecated.

We need to understand the underlying structure of storage to better manipulate the contacts. We have three distinct types of tables – Contacts, Raw Contacts and Data.

All data related to a contact is stored in this generic data table with each row telling what is the data it stores through its MIME type. So we could have a Phone.CONTENT_ITEM_TYPE as the MIME type of the data row, it contains Phone data. Similarly, if we have Email.CONTENT_ITEM_TYPE as the row’s MIME type, then it stores email data. Like this lot of data rows are associated with a single Raw Contact.

Each Raw Contact refers to a specific contact’s data coming from one single source – say, you gmail account or your office Microsoft account.

The Contact is the topmost in the hierarchy which aggregates similar looking data from various sources into one single contact – a very handy feature when you have redundant data coming about the same contact from you various accounts – like a facebook account, orkut account, yahoo account and goggle account.  So the hierarchy looks like this:

So, when we want to insert a new contact, we always insert a Raw Contact. When we want to update an existing contact, we most often deal with the data tables which are accessible through a series of CommonDataKind classes. Because this would be to update particular types of data like phone or email.

Coming to the example:

I create an activity with four buttons to View, Add, Modify and Delete Contacts.

           Button view = (Button)findViewById(R.id.viewButton);

            Button add = (Button)findViewById(R.id.createButton);

            Button modify = (Button)findViewById(R.id.updateButton);

            Button delete = (Button)findViewById(R.id.deleteButton);

           

           

            view.setOnClickListener(new OnClickListener() {

                  public void onClick(View v){

                        displayContacts();

                        Log.i("NativeContentProvider", "Completed Displaying Contact list");

                  }

            });

On the click of each of the buttons I invoke their respective methods: like displayContacts(), createContact(), updatecContact() and deleteContact(). We will now see each of these methods.

displayContacts() is pretty straightforward. Access to each of the tables mentioned above is through a content URI. I use the topmost level ‘Contacts’ URI to iterate through all the existing contacts and display their names and phone numbers (Toast them).

We know Contacts is a ContentProvider and hence we need to query through a ContentResolver which returns all the data of the contacts.

   private voiddisplayContacts() {

     

      ContentResolver cr = getContentResolver();

        Cursor cur = cr.query(ContactsContract.Contacts.CONTENT_URI,

                null, null, null, null);

        if (cur.getCount() > 0) {

            while (cur.moveToNext()) {

                  String id = cur.getString(cur.getColumnIndex(ContactsContract.Contacts._ID));

                  String name = cur.getString(cur.getColumnIndex(ContactsContract.Contacts.DISPLAY_NAME));

                  if (Integer.parseInt(cur.getString(

                        cur.getColumnIndex(ContactsContract.Contacts.HAS_PHONE_NUMBER))) > 0) {

                     Cursor pCur = cr.query(

                               ContactsContract.CommonDataKinds.Phone.CONTENT_URI,

                               null,

                               ContactsContract.CommonDataKinds.Phone.CONTACT_ID +" = ?",

                               new String[]{id}, null);

                     while (pCur.moveToNext()) {

                         String phoneNo = pCur.getString(pCur.getColumnIndex(ContactsContract.CommonDataKinds.Phone.NUMBER));

                         Toast.makeText(NativeContentProvider.this, "Name: " + name + ", Phone No: " + phoneNo, Toast.LENGTH_SHORT).show();

                     }

                    pCur.close();

                }

            }

        }

    }

I will try to briefly explain the above method.  Line 1 gets a handle to the ContentResolver. Line 2 queries the Contacts URI (ContactsContract.Contacts.CONTENT_URI ) without any mention of the specific columns or “where” clause of an SQL query. Notice all the 4 parameters are null. This means that we are not making any conditional query into the contacts table and hence all data is returned into the cursor.

Next, I check that the cursor is not empty and iterate through the cursor data. I retrieve the _ID and DISPLAY_NAME from the Contacts and then, I check for the flag if the contact has a phone number. This information is available in contacts table itself. But the Phone number details are in the data tables. Hence after checking for the flag, I query the CommonDataKings.Phone.CONTENT_URI for the phone data of that specific ID. From this new cursor named pCur, I retrieve the Phone Number. If there are multiple phone number for one contact, all of them will be retrieved and toasted one after another.

Now, let us see how to create or insert a new contact.

In the createContact() method which is called when you click on the “Add Contact” button, I first query to see if the hardcoded name “Sample Name” already exists. If so, I toast a message stating the same. If not, then I get into actually inserting the name along with a phone number. The first part of the check you can view in the complete source code available for download. Only the second part of inserting a contact is explained here. For this, we need to use a ContentResolveralways.

A ContentResolverprovides an applyBatch(…) method which takes an array of ContentProviderOperation classes as a parameter. All the data built into the ContentProviderOperations are committed or inserted into the ContentProvider that we are working on. IN this case, the ContentProvider we are working on are Contacts and the authority associated with the same is ContactsContract.AUTHORITY

Here is the code for the same:

        ArrayList<ContentProviderOperation> ops = newArrayList<ContentProviderOperation>();

        ops.add(ContentProviderOperation.newInsert(ContactsContract.RawContacts.CONTENT_URI)

                .withValue(ContactsContract.RawContacts.ACCOUNT_TYPE, "accountname@gmail.com")

                .withValue(ContactsContract.RawContacts.ACCOUNT_NAME, "com.google")

                .build());

        ops.add(ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)

                .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0)

                .withValue(ContactsContract.Data.MIMETYPE,

                        ContactsContract.CommonDataKinds.StructuredName.CONTENT_ITEM_TYPE)

                .withValue(ContactsContract.CommonDataKinds.StructuredName.DISPLAY_NAME, name)

                .build());

        ops.add(ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)

                .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0)

                .withValue(ContactsContract.Data.MIMETYPE,

                        ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE)

                .withValue(ContactsContract.CommonDataKinds.Phone.NUMBER, phone)

                .withValue(ContactsContract.CommonDataKinds.Phone.TYPE, ContactsContract.CommonDataKinds.Phone.TYPE_HOME)

                .build());

       

        try {

                  cr.applyBatch(ContactsContract.AUTHORITY, ops);

….

In the first element in the ops array, I am setting the details of the account to which I want to add the contact. In this case the gmail account type is accontname@gmail.com and the account name is “com.google”. The latter has to be unique and hence it is recommended to use the internet URLs of the source of data.

In the second element, I am adding the name of the contact and in the third the phone data. You notice that I use .withValueBackReference(..) as we still have not created the Raw contact and hence we do not have the Id. The first row creates the id and hands over the id to the next rows of data. 

This array ops is passed into the ContentResolverand thus the data is inserted.

For updating the phone number of an existing contact, I again use the ContentResolverwith the ContentProviderOperation array. However, now, I pass the where clause and the parameters of the where clause – specifically indicating that only the phone number of the “Sample Name” contact has to be updated.

            ops.add(ContentProviderOperation.newUpdate(ContactsContract.Data.CONTENT_URI)

                    .withSelection(where, params)

                    .withValue(ContactsContract.CommonDataKinds.Phone.DATA, phone)

                    .build());

Notice the .withSelection(where, params). The where and params look like this:

        String where = ContactsContract.Data.DISPLAY_NAME + " = ? AND " +

                        ContactsContract.Data.MIMETYPE + " = ? AND " +

                        String.valueOf(ContactsContract.CommonDataKinds.Phone.TYPE) + " = ? ";

       

String[] params = new String[] {name,

                  ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE,

                  String.valueOf(ContactsContract.CommonDataKinds.Phone.TYPE_HOME)};

Delete too is done in a very similar manner with no values but only the selection criteria is provided for which contact to be deleted.

      ContentResolver cr = getContentResolver();

      String where = ContactsContract.Data.DISPLAY_NAME + " = ? ";

      String[] params = new String[] {name};

   

        ArrayList<ContentProviderOperation> ops = newArrayList<ContentProviderOperation>();

        ops.add(ContentProviderOperation.newDelete(ContactsContract.RawContacts.CONTENT_URI)

              .withSelection(where, params)

              .build());

        try {

                  cr.applyBatch(ContactsContract.AUTHORITY, ops);

            } catch (RemoteException e) {

….

The complete source code is downloadable here.

I really scouted the internet a lot to find a comprehensive tutorial on the new Contacts Content Provider API but could not find anything that easily. Hope this helps all who of you who are looking for the same.

NOTE: Many have been asking me questions on why the contacts that have just been added through this app are not visible in the phone contacts. All your contacts on phone are linked to your google account on the phone. However, the contacts from the above code have got added to psuedo google account and hence will not be visible directly. You search for the just added contact and you will be able to find it.


Hope this helps.

Broadcast Receivers | Android Developer Tutorial (Part 11)

The concept of Broadcast Receivers, one of the fundamental blocks of Android, is very simple. These are applications that will respond to any intent that is broadcast by other applications. Provided the broadcast intent matches the intent specified against the receiver in the AndroidManifest.xml

This goes to automatically imply that many activities, events, services or the like can broadcast intents expecting the appropriate action to be automatically taken. So, to begin with, let us see the various Broadcast events that are given by the platform itself. Here is a standard list obtained from the android documentation:

·         ACTION_TIME_TICK

·         ACTION_TIME_CHANGED

·         ACTION_TIMEZONE_CHANGED

·         ACTION_BOOT_COMPLETED

·         ACTION_PACKAGE_ADDED

·         ACTION_PACKAGE_CHANGED

·         ACTION_PACKAGE_REMOVED

·         ACTION_PACKAGE_RESTARTED

·         ACTION_PACKAGE_DATA_CLEARED

·         ACTION_UID_REMOVED

·         ACTION_BATTERY_CHANGED

·         ACTION_POWER_CONNECTED

·         ACTION_POWER_DISCONNECTED

·         ACTION_SHUTDOWN

For details on when each of these intents get broadcasted, please see the android documentation. I have chosen the BROADCAST event ACTION_TIME_CHANGED as I can simulate a time change in the emulator. How to simulate the time change from adb shell is given at the end of this tutorial.

Now let us get on to the example of a broadcast receiver. You can download the complete code here.

Any activity that intends to respond to broadcasts has to extend the android.content.BroadcastReceiverclass and implement the single method onReceive().

In my example, I just notify on the status bar that the time has changed and the moment the user clicks on the status bar and sees the details, clicks on the details, the notification is removed from the status bar.

When the user clicks on the detailed portion, I take the user to the contacts application, just for anything better. Ideally this should take to an activity relevant to the application. So, if you see the onReceive()method, it is nothing but a notification example. That is all.

      private NotificationManager mNotificationManager;

      private int SIMPLE_NOTFICATION_ID;

     

      @Override

      public void onReceive(Context context, Intent intent) {

        mNotificationManager = (NotificationManager)context.getSystemService(Context.NOTIFICATION_SERVICE);

      Notification notifyDetails = new Notification(R.drawable.android,"Time Reset!",System.currentTimeMillis());

      PendingIntent myIntent = PendingIntent.getActivity(context, 0, new Intent(Intent.ACTION_VIEW, People.CONTENT_URI), 0);

      notifyDetails.setLatestEventInfo(context, "Time has been Reset", "Click on me to view Contacts", myIntent);

      notifyDetails.flags |= Notification.FLAG_AUTO_CANCEL;

      mNotificationManager.notify(SIMPLE_NOTFICATION_ID, notifyDetails);

            Log.i(getClass().getSimpleName(),"Sucessfully Changed Time");

      }

Once this class is ready, start the android emulator in eclipse. Then, simulate a time changed from the command prompt as given below. You will see the notification come up.

Simulating a time change in the emulator:

To start the adb shell type (in windows, assuming the path has been set to the tools folder of android sdk installation):

C:\> adb shell

#date –- 2009-10-01 14:24:59

20070325.123456

#date –s 20070325.123456

The first step date –-gives the time in seconds since Jan 1^st 1970. Take the result and give it as a parameter to date –s, the time is reset in adb and within a minute on the android emulator. This broadcasts the event that time has been changed in the emulator and kicks off the Broadcast Receiver program that has been executed.

Content Provider - Android Developer Tutorial (Part 10)

Content Providers are again one of the fundamental building blocks of the Android Platform. So far, we have looked at Activities, Services, which are basic building blocks. We have also looked at intents, notificationsand variations of the same. None of these have dealt with stored data. Content Provider brings us to the concept of how to deal with data stored in the Android mobile esp. if the data has to be shared across applications.

Before we move on to shared data, let us understand the basics of data storage support provided by Android. 

There are 4 ways we can store data:

• 1.    Preferences
• 2.    Files
• 3.    RDBMS (SQLite)
• 4.    Network

Preferences– Preferences are used to store user preferences for a single application or across applications in a mobile. They are typically name-value pairs accessible to the context.

Files– Files can be stored directly on to the mobile or to extended storage mediums. They are by default not accessible to applications other than the one that created it.

Database(RDBMS) – Android support creation of databases based on SQLite. These are again private to the application that created it.

Network– Android provides API support to store data over the network on to a server, probably

Note that all these are various forms of storing data and most often for a single application. Irrespective of how data is stored, if it has to be shared across applications, Here comes the concept of Content Providers.

Content Providers are the only way to share data across Android applications. They store and retrieve data thus making it accessible to all. Android platform provides default implementations of content providers for data types like audio, video, images, contact information etc.

In the sample I would like to first show how to work with existing content providers like the contact information. We will first view the existing contacts on the phone. We will insert a new contact (hardcoded name and phone number), update the same contact and delete the same contact, in this example. Note that the update and delete will not work till we create a contact through this example.

Introduction to Content Providers:

Irrespective of how the data is stored, Content Providers give a uniform interface to access the data. Data is exposed as a simple table with rows and columns where row is a record and column is a particular data type with a specific meaning. Like a row could be about a single person and the columns could be the person’s first name, number, address, email id etc.

Each record is identified by a unique _ID field which is the key to the record. Each content provider exposes a unique URI that identifies its data set uniquely. This URI is equivalent to a table name in a database. The URI consists of various parts: eg: content://com.colllabera.labs.sai/tasks/123is a unique URI. content:// is a standard prefix. com.collabera.labs.saiis the authority, tasks is the table name, 123 is the unique _ID.

For the native content providers, these unique URIs are declared as constants in an interface. So, in our program we will be using constants like People.CONTENT_URI which internally translates to content://contacts/people

Let us now look at the code to view all the existing contacts:

//Here is the button to click for viewing the contacts

Button view = (Button)findViewById(R.id.viewButton);

…

//The method / class that gets invoked when the View button is clicked

view.setOnClickListener(new OnClickListener() {

    public void onClick(View v){

       displayContacts();

       Log.i("NativeContentProvider", "Completed Displaying Contact list");

    }

});

…

//Here is the displayContacts() method

private void displayContacts() {

      String[] columns = new String[] {People.NAME,People.NUMBER};

      Uri mContacts = People.CONTENT_URI;

      Cursor mCur = managedQuery(mContacts, // Contact URI

                  columns,    // Which columns to return

                  null,       // Which rows to return

                  null,       // Where clause parameters

                  null        // Order by clause

                  );

      if (mCur.moveToFirst()) {

            String name = null;

            String phoneNo = null;

            do {

              name = mCur.getString(mCur.getColumnIndex(People.NAME));

              phoneNo = mCur.getString(mCur.getColumnIndex(People.NUMBER));

              Toast.makeText(NativeContentProvider.this, name + " " + phoneNo, Toast.LENGTH_SHORT).show();

            } while (mCur.moveToNext());

      }

}

Here we are using the Activity.managedQuery(..)to create and execute a query against the provided URI. The comments against the parameters in the code is self-explanatory. This returns a cursorobject that can be iterated using the two methods moveToFirst()and moveToNext(). For simplicity sake, I have just toasted the contact name and phone number retrieved. An advanced tutorial can start a new activity that can display this in a ListView.

Now, we can move on to creating a new contact. While the button related code will be very similar to the above, let us look at the actual createContact() method.

    private voidcreateContact(String name, String phone) {

      ContentValues contact = new ContentValues();

      contact.put(People.NAME, name);

      insertUri = getContentResolver().insert(People.CONTENT_URI, contact);

      Log.d(getClass().getSimpleName(),insertUri.toString());

      Uri phoneUri = Uri.withAppendedPath(insertUri, People.Phones.CONTENT_DIRECTORY);

      contact.clear();

      contact.put(People.Phones.TYPE, People.TYPE_MOBILE);

      contact.put(People.NUMBER, phone);

      updateUri = getContentResolver().insert(phoneUri, contact);

      Toast.makeText(NativeContentProvider.this, "Created a new contact: " + name + " " + phone, Toast.LENGTH_SHORT).show();

      Log.d(getClass().getSimpleName(),updateUri.toString());

    }

Here we need to understand 2 new classes: ContentResolverand ContentValues. A ContentResolverprovides applications access to the content data / model. We can get a handle to a ContentResolverby calling the getContentResolver() method within the Activity. This provides methods to insert, update and delete data. In order to insert data, we need to provide it through a ContentValuesobject. A ContentValues Object is nothing but a name, value pair where the name of the column is to be mentioned. So, we pass the URI and the ContentValuesto insert()method which returns a unique URI with the new ID created. Once we get the ID of the new person/contact inserted, we insert his/her mobile phone details into the related Phones table by using the returned insertUri. The insertUriwhich is unique to the new record is stored as a class variable to use it in the delete method later. The phoneUri is also stored for updating the same in the updateContact() method later.

Note that Peopleis a class that has implemented various interfaces like android.priovider.BaseColumns, android.provider.Contacts.Phones, android.provider.Contact.PeopleColumnsetc. These constants come from the interfaces.

With the above understanding let us see the update and delete methods:

   private voidupdateContact(String phone) {

      if (updateUri == null) {

            Toast.makeText(NativeContentProvider.this, "There is nothing to update, Please create a contact and then click update", Toast.LENGTH_LONG).show();

      } else {

            ContentValues newPhone = new ContentValues();

            newPhone.put(People.Phones.TYPE, People.TYPE_MOBILE);

            newPhone.put(People.NUMBER, phone);

            getContentResolver().update(updateUri, newPhone, null,null);

            Toast.makeText(NativeContentProvider.this, "Updated the phone number to: " + phone, Toast.LENGTH_SHORT).show();

            Log.i(getClass().getSimpleName(), "Updated the phone number");

      }

    }

   

    private void deleteContact() {

      if (updateUri == null) {

            Toast.makeText(NativeContentProvider.this, "Please create a contact by clicking create button, then I can delete the same", Toast.LENGTH_LONG).show();

           

      } else {

            getContentResolver().delete(insertUri, null, null);

            Toast.makeText(NativeContentProvider.this, "Deleted contact at: " + insertUri.toString(), Toast.LENGTH_SHORT).show();

            updateUri = null;

            insertUri = null;

            Log.i(getClass().getSimpleName(),"Deleted the contact inserted by this program");

      }

    }

These methods only manipulate the freshly created record, for simplicity sake. They call upon the update() and delete() method on the ContentResolver.

The complete code for this example is available here.

Please note that you must add the following permissions to the AndroidManifest.xml file to be able to access the contacts.

<uses-permission android:name="android.permission.READ_CONTACTS"></uses-permission>

<uses-permission android:name="android.permission.WRITE_CONTACTS"></uses-permission>

Otherwise you get a SecurityException.

UPDATE: Please note that the article talks about the Contacts API before SDK 2.0. For the newer updated version, please check this article on New Content Provider