Problem

Your application is running in the background, with no currently visible interface to the user, but must notify the user of an important event that has occurred.

Solution

(API Level 4)

Use NotificationManager to post a status bar notification. Notifications provide an unobtrusive way of indicating that you want the user’s attention. Perhaps new messages have arrived, an update is available, or a long-running job is complete; notifications are perfect for accomplishing these tasks.

How It Works

A notification can be posted to the NotificationManager from just about any system component, such as a Service, BroadcastReceiver, or Activity. In Listing 7-1, we will look at an activity that posts a series of different notification types when the user leaves the activity and goes to the home screen.

Listing 7-1. Activity Firing a Notification

public class NotificationActivity extends Activity {
 
    //Unique notification id values
    public static final int NOTE_BASIC = 100;
    public static final int NOTE_BIGTEXT = 200;
    public static final int NOTE_PICTURE = 300;
    public static final int NOTE_INBOX = 400;
 
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        TextView tv = new TextView(this);
        tv.setText("When You Leave Here, Notifications Will Post");
        tv.setGravity(Gravity.CENTER);
         
        setContentView(tv);
    }
 
    @Override
    public void onStop() {
        super.onStop();
         
        NotificationManager manager =
                (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
 
        //Post 4 unique notifications
        Notification note = buildNotification(NOTE_BASIC);
        manager.notify(NOTE_BASIC, note);
        note = buildNotification(NOTE_BIGTEXT);
        manager.notify(NOTE_BIGTEXT, note);
        note = buildNotification(NOTE_PICTURE);
        manager.notify(NOTE_PICTURE, note);
        note = buildNotification(NOTE_INBOX);
        manager.notify(NOTE_INBOX, note);
    }
     
    private Notification buildNotification(int type) {
        Intent launchIntent =
                new Intent(this, NotificationActivity.class);
        PendingIntent contentIntent =
                PendingIntent.getActivity(this, 0, launchIntent, 0);
         
 
        // Create notification using a builder
        NotificationCompat.Builder builder = new NotificationCompat.Builder(
                NotificationActivity.this);
         
         
        builder.setSmallIcon(R.drawable.ic_launcher)
                .setTicker("Something Happened")
                .setWhen(System.currentTimeMillis())
                .setAutoCancel(true)
                .setDefaults(Notification.DEFAULT_SOUND)
                .setContentTitle("We're Finished!")
                .setContentText("Click Here!")
                .setContentIntent(contentIntent);
         
        switch (type) {
            case NOTE_BASIC:
                //Return the simple notification
                return builder.build();
            case NOTE_BIGTEXT:
                //Include two actions
                builder.addAction(android.R.drawable.ic_menu_call,
                        "Call", contentIntent);
                builder.addAction(android.R.drawable.ic_menu_recent_history,
                        "History", contentIntent);
                //Use the BigTextStyle when expanded
                NotificationCompat.BigTextStyle textStyle =
                        new NotificationCompat.BigTextStyle(builder);
                textStyle.bigText(
                        "Here is some additional text to be displayed when the notification is "
                        +"in expanded mode.  I can fit so much more content into this giant view!");
                 
                return textStyle.build();
            case NOTE_PICTURE:
                //Add one additional action
                builder.addAction(android.R.drawable.ic_menu_compass,
                        "View Location", contentIntent);
                //Use the BigPictureStyle when expanded
                NotificationCompat.BigPictureStyle pictureStyle =
                        new NotificationCompat.BigPictureStyle(builder);
                pictureStyle.bigPicture(BitmapFactory.decodeResource(getResources(), R.drawable.dog));
                 
                return pictureStyle.build();
            case NOTE_INBOX:
                //Use the InboxStyle when expanded
                NotificationCompat.InboxStyle inboxStyle =
                        new NotificationCompat.InboxStyle(builder);
                inboxStyle.setSummaryText("4 New Tasks");
                inboxStyle.addLine("Make Dinner");
                inboxStyle.addLine("Call Mom");
                inboxStyle.addLine("Call Wife First");
                inboxStyle.addLine("Pick up Kids");
                 
                return inboxStyle.build();
            default:
                throw new IllegalArgumentException("Unknown Type");
        }
    }
}

A series of new notification elements are created using Notification.Builder when the user leaves the activity. We will discuss the expanded types shortly, and just focus on the basic type for now. An icon resource and title string may be provided, and these items will display in the status bar at the time the notification occurs. In addition, we pass a time value (in milliseconds) to display in the notification list as the event time. Here, we are setting that value to the time the notification fired, but it may take on a different meaning in your application.

Prior to creating the notification, we can fill it out with some other useful parameters, such as more-detailed text to be displayed in the notifications list when the user pulls down the status bar.

One of the parameters passed to the builder is a PendingIntent that points back to our activity. This Intent makes the notification interactive, allowing the user to tap it in the list and launch the activity.

To enhance the notification beyond the visual animation in the status bar, the notification defaults are modified to include that the system’s default notification sound be played when the notification fires. Values such as Notification.DEFAULT_VIBRATION and Notification.DEFAULT_LIGHTS may also be added.

We finally add a series of flags to the notification for further customization. This example uses setAutoCancel() in the builder to enable Notification.FLAG_AUTO_CANCEL, which cancels or removes the notification from the list as soon as the user selects it. Without this flag, the notification remains in the list until it is manually dismissed or canceled programmatically by calling NotificationManager.cancel() or NotificationManager.cancelAll(). Another helpful flag to set with the builder is setOngoing(), which disables any user ability to remove the notification. It can be cancelled only programmatically. This is useful for notifying the user of background operations currently running, such as music playing or location tracking underway.

Additionally, here are some other useful flags to apply that do not have methods inside the builder. These flags can be set directly on the notification after it is constructed:

• FLAG_INSISTENT: Repeats the notification sounds until the user responds.
• FLAG_NO_CLEAR: Does not allow the notification to be cleared with the user’s Clear Notifications button, but only through a call to cancel(). Once the notification is prepared, it is posted to the user with NotificationManager.notify(), which takes an ID parameter as well. Each notification type in your application should have a unique ID. The manager will allow only one notification with the same ID in the list at a time, and new instances with the same ID will take the place of those existing. In addition, the ID is required to cancel a specific notification manually.

When we run this example, an activity displays with instructions to leave the application immediately. Upon leaving, you can see the notification set post sometime later, even though the activity is no longer visible (see Figure 7-1).

//Create notification with the time it was fired
NotificationCompat.Builder builder =
        new NotificationCompat.Builder(NotificationActivity.this);
 
builder.setSmallIcon(R.drawable.icon)
       .setTicker("Something Happened")
       .setWhen(System.currentTimeMillis())
       .setAutoCancel(true)
       .setDefaults(Notification.DEFAULT_SOUND)
       .setContentTitle("We're Finished!")
       .setContentText("Click Here!")
       .setContentIntent(contentIntent);
 
//Add some custom actions
builder.addAction(android.R.id.drawable.ic_menu_call, "Call Back", contentIntent);
builder.addAction(android.R.id.drawable.ic_menu_recent_history,
        "Call History", contentIntent);
 
//Apply an expanded style
NotificationCompat.BigTextStyle expandedStyle =
        new NotificationCompat.BigTextStyle(builder);
expandedStyle.bigText("Here is some additional text to be displayed when"
    + " the notification is in expanded mode.  "
    + " I can fit so much more content into this giant view!");
 
Notification note = expandedStyle.build();

//Create notification with the time it was fired
NotificationCompat.Builder builder =
        new NotificationCompat.Builder(NotificationActivity.this);
 
builder.setSmallIcon(R.drawable.icon)
       .setTicker("Something Happened")
       .setWhen(System.currentTimeMillis())
       .setAutoCancel(true)
       .setDefaults(Notification.DEFAULT_SOUND)
       .setContentTitle("We're Finished!")
       .setContentText("Click Here!")
       .setContentIntent(contentIntent);
 
//Add some custom actions
builder.addAction(android.R.id.drawable.ic_menu_compass,
        "View Location", contentIntent);
 
//Apply an expanded style
NotificationCompat.BigPictureStyle expandedStyle =
        new NotificationCompat.BigPictureStyle(builder);
expandedStyle.bigPicture(
        BitmapFactory.decodeResource(getResources(), R.drawable.icon) );
 
Notification note = expandedStyle.build();

//Create notification with the time it was fired
NotificationCompat.Builder builder =
        new NotificationCompat.Builder(NotificationActivity.this);
 
builder.setSmallIcon(R.drawable.icon)
       .setTicker("Something Happened")
       .setWhen(System.currentTimeMillis())
       .setAutoCancel(true)
       .setDefaults(Notification.DEFAULT_SOUND)
       .setContentTitle("We're Finished!")
       .setContentText("Click Here!")
       .setContentIntent(contentIntent);
 
//Apply an expanded style
NotificationCompat.InboxStyle expandedStyle =
        new NotificationCompat.InboxStyle(builder);
expandedStyle.setSummaryText("4 New Tasks");
expandedStyle.addLine("Make Dinner");
expandedStyle.addLine("Call Mom");
expandedStyle.addLine("Call Wife First");
expandedStyle.addLine("Pick up Kids");
 
Notification note = expandedStyle.build();

public class MonitorService extends NotificationListenerService {
    private static final String TAG = "RecipesMonitorService";
     
    @Override
    public void onNotificationPosted(StatusBarNotification sbn) {
        //Validate the notification came from this application
        if (!TextUtils.equals(sbn.getPackageName(), getPackageName())) {
            return;
        }
         
        Log.i(TAG, "Notification "+sbn.getId()+" Posted");
    }
 
    @Override
    public void onNotificationRemoved(StatusBarNotification sbn) {
        //Validate the notification came from this application
        if (!TextUtils.equals(sbn.getPackageName(), getPackageName())) {
            return;
        }
        //We are looking for the basic notification
        if (NotificationActivity.NOTE_BASIC != sbn.getId()) {
            return;
        }
         
        //If the basic notification cancels, dismiss all of ours
        for (StatusBarNotification note : getActiveNotifications()) {
            if (TextUtils.equals(note.getPackageName(), getPackageName())) {
                cancelNotification(note.getPackageName(),
                        note.getTag(),
                        note.getId());
            }
        }
    }
 
}

<service android:name=".MonitorService"
    android:permission="android.permission.BIND_NOTIFICATION_LISTENER_SERVICE">
    <intent-filter>
        <action android:name="android.service.notification.NotificationListenerService" />
    </intent-filter>
</service>

Problem

Your application needs to run an operation on a timer, such as updating the UI on a scheduled basis.

Solution

(API Level 1)

Use the timed operations provided by Handler. With Handler, operations can efficiently be scheduled to occur at a specific time or after a specified delay.

How It Works

Let’s look at an example activity that displays the current time in a TextView. See Listing 7-7.

Listing 7-7. Activity Updated with a Handler

public class TimingActivity extends Activity {
     
    TextView mClock;
     
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        mClock = new TextView(this);
        setContentView(mClock);
    }
     
    private Handler mHandler = new Handler();
    private Runnable timerTask = new Runnable() {
        @Override
        public void run() {
            Calendar now = Calendar.getInstance();
            mClock.setText(String.format("%02d:%02d:%02d",
                    now.get(Calendar.HOUR),
                    now.get(Calendar.MINUTE),
                    now.get(Calendar.SECOND)) );
            //Schedule the next update in one second
            mHandler.postDelayed(timerTask,1000);
        }
    };
     
    @Override
    public void onResume() {
        super.onResume();
        mHandler.post(timerTask);
    }
     
    @Override
    public void onPause() {
        super.onPause();
        mHandler.removeCallbacks(timerTask);
    }
}

Here we’ve wrapped up the operation of reading the current time and updating the UI into a Runnable named timerTask, which will be triggered by the Handler that has also been created. When the activity becomes visible, the task is executed as soon as possible with a call to Handler.post(). After the TextView has been updated, the final operation of timerTask is to invoke the Handler to schedule another execution 1 second (1,000 milliseconds) from now by using Handler.postDelayed().

As long as the activity remains uninterrupted, this cycle will continue, with the UI being updated every second. As soon as the activity is paused (the user leaves or something else grabs his or her attention), Handler.removeCallbacks() removes all pending operations and ensures the task will not be called further until the activity becomes visible once more.

Problem

Your application needs to register to run a task periodically, such as checking a server for updates or reminding the user to do something.

Solution

(API Level 1)

Utilize the AlarmManager to manage and execute your task. AlarmManager is useful for scheduling future single or repeated operations that need to occur even if your application is not running. AlarmManager is handed a PendingIntent to fire whenever an alarm is scheduled. This Intent can point to any system component, such as an Activity, BroadcastReceiver, or Service, that can be executed when the alarm triggers.

It should be noted that this method is best suited to operations that need to occur even when the application code may not be running. The AlarmManager requires too much overhead to be useful for simple timing operations that may be needed while an application is in use. These are better handled using the postAtTime() and postDelayed() methods of a Handler.

How It Works

Let’s take a look at how AlarmManager can be used to trigger a BroadcastReceiver on a regular basis. See Listings 7-8 through 7-10.

Listing 7-8. BroadcastReceiver to Be Triggered

public class AlarmReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        //Perform an interesting operation, we'll just display the current time
        Calendar now = Calendar.getInstance();
        DateFormat formatter = SimpleDateFormat.getTimeInstance();
        Toast.makeText(context, formatter.format(now.getTime()),
            Toast.LENGTH_SHORT).show();
    }
}

Listing 7-9. res/layout/main.xml

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="vertical"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
    <Button
        android:id="@+id/start"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="Start Alarm" />
    <Button
        android:id="@+id/stop"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="Cancel Alarm" />
</LinearLayout>

Listing 7-10. Activity to Register/Unregister Alarms

public class AlarmActivity extends Activity implements View.OnClickListener {
     
    private PendingIntent mAlarmIntent;
     
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
        //Attach the listener to both buttons
        findViewById(R.id.start).setOnClickListener(this);
        findViewById(R.id.stop).setOnClickListener(this);
        //Create the launch sender
        Intent launchIntent = new Intent(this, AlarmReceiver.class);
        mAlarmIntent = PendingIntent.getBroadcast(this, 0, launchIntent, 0);
    }
 
    @Override
    public void onClick(View v) {
        AlarmManager manager = (AlarmManager)getSystemService(Context.ALARM_SERVICE);
        long interval = 5*1000; //5 seconds
         
        switch(v.getId()) {
        case R.id.start:
            Toast.makeText(this, "Scheduled", Toast.LENGTH_SHORT).show();
            manager.setRepeating(AlarmManager.ELAPSED_REALTIME,
                    SystemClock.elapsedRealtime()+interval,
                    interval,
                    mAlarmIntent);
            break;
        case R.id.stop:
            Toast.makeText(this, "Canceled", Toast.LENGTH_SHORT).show();
            manager.cancel(mAlarmIntent);
            break;
        default:
            break;
        }
    }
}

In this example, we have provided a very basic BroadcastReceiver that, when triggered, will simply display the current time as a Toast. That receiver must be registered in the application’s manifest with a <receiver> tag. Otherwise, AlarmManager—which is external to your application—will not be aware of how to trigger it. The sample activity presents two buttons: one to begin firing regular alarms, and the other to cancel them.

The operation to trigger is referenced by a PendingIntent, which will be used to both set and cancel the alarms. We create an Intent referencing the application’s BroadcastReceiver directly, and then we wrap that Intent inside a PendingIntent obtained with getBroadcast() (because we are creating a reference to a BroadcastReceiver).

When the Start button is pressed, the activity registers a repeating alarm by using AlarmManager.setRepeating(). In addition to PendingIntent, this method takes some parameters to determine when to trigger the alarms. The first parameter defines the alarm type, in terms of the units of time to use and whether the alarm should occur when the device is in sleep mode. In the example, we chose ELAPSED_REALTIME, which indicates a value (in milliseconds) since the last device boot. In addition, there are three other modes that may be used:

• ELAPSED_REALTIME_WAKEUP: The alarm times are referenced to time elapsed and will wake the device to trigger if it is asleep.
• RTC: The alarm times are referenced to UTC time.
• RTC_WAKEUP: The alarm times are referenced to UTC time and will wake the device to trigger if it is asleep. The remaining parameters (respectively) refer to the first time the alarm will trigger and the interval on which it should repeat. Because the chosen alarm type is ELAPSED_REALTIME, the start time must also be relative to elapsed time; SystemClock.elapsedRealtime() provides the current time in this format.

The alarm in the example is registered to trigger 5 seconds after the button is pressed, and then every 5 seconds after that. Every 5 seconds, a Toast will come onscreen with the current time value, even if the application is no longer running or in front of the user. When the user displays the activity and presses the Stop button, any pending alarms matching our PendingIntent are immediately canceled and will stop the flow of Toasts.

long oneDay = 24*3600*1000; //24 hours
long firstTime;
 
//Get a Calendar (defaults to today)
//Set the time to 09:00:00
Calendar startTime = Calendar.getInstance();
startTime.set(Calendar.HOUR_OF_DAY, 9);
startTime.set(Calendar.MINUTE, 0);
startTime.set(Calendar.SECOND, 0);
 
//Get a Calendar at the current time
Calendar now = Calendar.getInstance();
 
if(now.before(startTime)) {
    //It's not 9AM yet, start today
    firstTime = startTime.getTimeInMillis();
} else {
    //Start 9AM tomorrow
    startTime.add(Calendar.DATE, 1);
    firstTime = startTime.getTimeInMillis();
}
 
//Set the alarm
 manager.setRepeating(AlarmManager.RTC_WAKEUP,
                firstTime,
                oneDay,
                mAlarmIntent);

Problem

Your application needs to execute one or more background operations that will run to completion even if the user suspends the application.

Solution

(API Level 3)

Create an IntentService to handle the work. IntentService is a wrapper around Android’s base service implementation, the key component to doing work in the background without interaction from the user. IntentService queues incoming work (expressed using Intents), processing each request in turn, and then stops itself when the queue is empty.

IntentService also handles creation of the worker thread needed to do the work in the background, so it is not necessary to use AsyncTask or Java threads to ensure that the operation is properly in the background.

This recipe provides an example of using IntentService to create a central manager of background operations. In the example, the manager will be invoked externally with calls to Context.startService(). The manager will queue up all requests received, and process them individually with a call to onHandleIntent().

How It Works

Let’s take a look at how to construct a simple IntentService implementation to handle a series of background operations. See Listing 7-12.

Listing 7-12. IntentService Handling Operations

public class OperationsManager extends IntentService {
 
    public static final String ACTION_EVENT = "ACTION_EVENT";
    public static final String ACTION_WARNING = "ACTION_WARNING";
    public static final String ACTION_ERROR = "ACTION_ERROR";
    public static final String EXTRA_NAME = "eventName";
 
    private static final String LOGTAG = "EventLogger";
     
    private IntentFilter matcher;
     
    public OperationsManager() {
        super("OperationsManager");
        //Create the filter for matching incoming requests
        matcher = new IntentFilter();
        matcher.addAction(ACTION_EVENT);
        matcher.addAction(ACTION_WARNING);
        matcher.addAction(ACTION_ERROR);
    }
 
    @Override
    protected void onHandleIntent(Intent intent) {
        //Check for a valid request
        if(!matcher.matchAction(intent.getAction())) {
            Toast.makeText(this, "OperationsManager: Invalid Request",
                    Toast.LENGTH_SHORT).show();
            return;
        }
 
        //Handle each request directly in this method. Don't create more threads.
        if(TextUtils.equals(intent.getAction(), ACTION_EVENT)) {
            logEvent(intent.getStringExtra(EXTRA_NAME));
        }
        if(TextUtils.equals(intent.getAction(), ACTION_WARNING)) {
            logWarning(intent.getStringExtra(EXTRA_NAME));
        }
        if(TextUtils.equals(intent.getAction(), ACTION_ERROR)) {
            logError(intent.getStringExtra(EXTRA_NAME));
        }
    }
     
    private void logEvent(String name) {
        try {
            //Simulate a long network operation by sleeping
            Thread.sleep(5000);
            Log.i(LOGTAG, name);
        } catch (InterruptedException e) {
            e.printStackTrace();
        }
    }
     
    private void logWarning(String name) {
        try {
            //Simulate a long network operation by sleeping
            Thread.sleep(5000);
            Log.w(LOGTAG, name);
        } catch (InterruptedException e) {
            e.printStackTrace();
        }
    }
     
    private void logError(String name) {
        try {
            //Simulate a long network operation by sleeping
            Thread.sleep(5000);
            Log.e(LOGTAG, name);
        } catch (InterruptedException e) {
            e.printStackTrace();
        }
    }
}

IntentService does not have a default constructor (one that takes no parameters), so a custom implementation must implement a constructor that calls through to super with a service name. This name is of little technical importance, as it is useful only for debugging; Android uses the name provided to name the worker thread that it creates.

All requests are processed by the service through the onHandleIntent() method. This method is called on the provided worker thread, so all work should be done directly here; no new threads or operations should be created. When onHandleIntent() returns, this is the signal to the IntentService to begin processing the next request in the queue.

This example provides three logging operations that can be requested using different action strings on the request Intents. For demonstration purposes, each operation writes the provided message out to the device log by using a specific logging level (INFO, WARNING, or ERROR). Note that the message itself is passed as an extra of the request Intent. Use the data and extra fields of each Intent to hold any parameters for the operation, leaving the action field to define the operation type.

The service in the example maintains an IntentFilter, which is used for convenience to determine whether a valid request has been made. All of the valid actions are added to the filter when the service is created, allowing us to call IntentFilter.matchAction() on any incoming request to determine whether it includes an action we can process here.

Listings 7-13 and 7-14 reveal an example including an activity calling in to this service to perform work.

Listing 7-13. AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.examples.sticky"
    android:versionCode="1"
    android:versionName="1.0">
    <uses-sdk android:minSdkVersion="3" />
 
    <application android:icon="@drawable/icon" android:label="@string/app_name">
        <activity android:name=".ReportActivity"
                  android:label="@string/app_name">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
        <service android:name=".OperationsManager"></service>
    </application>
</manifest>

Listing 7-14. Activity Calling IntentService

public class ReportActivity extends Activity {
     
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        logEvent("CREATE");
    }
     
    @Override
    public void onStart() {
        super.onStart();
        logEvent("START");
    }
     
    @Override
    public void onResume() {
        super.onResume();
        logEvent("RESUME");
    }
     
    @Override
    public void onPause() {
        super.onPause();
        logWarning("PAUSE");
    }
     
    @Override
    public void onStop() {
        super.onStop();
        logWarning("STOP");
    }
     
    @Override
    public void onDestroy() {
        super.onDestroy();
        logWarning("DESTROY");
    }
     
    private void logEvent(String event) {
        Intent intent = new Intent(this, OperationsManager.class);
        intent.setAction(OperationsManager.ACTION_EVENT);
        intent.putExtra(OperationsManager.EXTRA_NAME, event);
         
        startService(intent);
    }
     
    private void logWarning(String event) {
        Intent intent = new Intent(this, OperationsManager.class);
        intent.setAction(OperationsManager.ACTION_WARNING);
        intent.putExtra(OperationsManager.EXTRA_NAME, event);
         
        startService(intent);
    }
}

This activity isn’t much to look at, as all the interesting events are sent out through the device log instead of to the user interface. Nevertheless, it helps illustrate the queue-processing behavior of the service we created in the previous example. As the activity becomes visible, it will call through all of its normal life-cycle methods, resulting in three requests made of the logging service. As each request is processed, a line will output to the log and the service will move on.

Notice also that when the service is finished with all three requests, a notification is logged out that the service has been stopped. IntentServices are around in memory for only as long as required to complete the job; this is a very useful feature for your services to have, making them good citizens of the system.

Pressing either the HOME or BACK buttons will cause more of the life-cycle methods to generate requests of the service, and the Pause/Stop/Destroy portion calls a separate operation in the service, causing their messages to be logged as warnings; simply setting the action string of the request Intent to a different value controls this.

Notice that messages continue to be output to the log, even after the application is no longer visible (or even if another application is opened instead). This is the power of the Android service component at work. These operations are protected from the system until they are complete, regardless of user behavior.

Problem

Your application has a component that must be running in the background indefinitely, performing some operation or monitoring certain events to occur.

Solution

(API Level 1)

Build the component into a service. Services are designed as background components that an application may start and leave running for an indefinite amount of time. Services are also given elevated status above other background processes in terms of protection from being killed in low-memory conditions.

Services may be started and stopped explicitly for operations that do not require a direct connection to another component (like an activity). However, if the application must interact directly with the service, a binding interface is provided to pass data. In these instances, the service may be started and stopped implicitly by the system as is required to fulfill its requested bindings.

The key thing to remember with service implementations is to always be user-friendly. An indefinite operation most likely should not be started unless the user explicitly requests it. The overall application should probably contain an interface or setting that allows the user to control enabling or disabling such a service.

How It Works

Listing 7-15 is an example of a persisted service that is used to track and log the user’s location over a certain period.

Listing 7-15. Persistent Tracking Service

public class TrackerService extends Service implements LocationListener {
 
    private static final String LOGTAG = "TrackerService";
     
    private LocationManager manager;
    private ArrayList<Location> storedLocations;
     
    private boolean isTracking = false;
     
    /* Service Setup Methods */
    @Override
    public void onCreate() {
        manager = (LocationManager)getSystemService(LOCATION_SERVICE);
        storedLocations = new ArrayList<Location>();
        Log.i(LOGTAG, "Tracking Service Running...");
    }
 
    @Override
    public void onDestroy() {
        manager.removeUpdates(this);
        Log.i(LOGTAG, "Tracking Service Stopped...");
    }
 
    public void startTracking() {
        if(!manager.isProviderEnabled(LocationManager.GPS_PROVIDER)) {
            return;
        }
        Toast.makeText(this, "Starting Tracker", Toast.LENGTH_SHORT).show();
        manager.requestLocationUpdates(LocationManager.GPS_PROVIDER, 30000, 0, this);
         
        isTracking = true;
    }
     
    public void stopTracking() {
        Toast.makeText(this, "Stopping Tracker", Toast.LENGTH_SHORT).show();
        manager.removeUpdates(this);
        isTracking = false;
    }
     
    public boolean isTracking() {
        return isTracking;
    }
     
    /* Service Access Methods */
    public class TrackerBinder extends Binder {
        TrackerService getService() {
            return TrackerService.this;
        }
    }
     
    private final IBinder binder = new TrackerBinder();
     
    @Override
    public IBinder onBind(Intent intent) {
        return binder;
    }
     
    public int getLocationsCount() {
        return storedLocations.size();
    }
     
    public ArrayList<Location> getLocations() {
        return storedLocations;
    }
     
    /* LocationListener Methods */
    @Override
    public void onLocationChanged(Location location) {
        Log.i("TrackerService", "Adding new location");
        storedLocations.add(location);
    }
 
    @Override
    public void onProviderDisabled(String provider) { }
 
    @Override
    public void onProviderEnabled(String provider) { }
 
    @Override
    public void onStatusChanged(String provider, int status, Bundle extras) { }
}

This service monitors and tracks the updates it receives from the LocationManager. When the service is created, it prepares a blank list of Location items and waits to begin tracking. An external component, such as an activity, can call startTracking() and stopTracking() to enable and disable the flow of location updates to the service. In addition, methods are exposed to access the list of locations that the service has logged.

Because this service requires direct interaction from an activity or other component, a Binder interface is required. The Binder concept can get complex when a service has to communicate across process boundaries, but for instances like this, where everything is local to the same process, a very simple Binder is created with one method, getService(), to return the service instance itself to the caller. We’ll look at this in more detail from the activity’s perspective in a moment.

When tracking is enabled on the service, it registers for updates with LocationManager, and it stores every update received in its locations list. Notice that requestLocationUpdates() was called with a minimum time of 30 seconds. Because this service is expected to be running for a long time, it is prudent to space out the updates to give the GPS (and consequently the battery) a little rest.

Now let’s take a look at a simple activity that allows the user access into this service. See Listings 7-16 through 7-18.

Listing 7-16. AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.examples.service"
    android:versionCode="1"
    android:versionName="1.0">
    <uses-sdk android:minSdkVersion="1" />
    <application android:icon="@drawable/icon" android:label="@string/app_name">
        <activity android:name=".ServiceActivity"
                  android:label="@string/app_name">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
        <service android:name=".TrackerService"></service>
    </application>
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
</manifest>

Listing 7-17. res/layout/main.xml

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="vertical"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
    <Button
        android:id="@+id/enable"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="Start Tracking" />
    <Button
        android:id="@+id/disable"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="Stop Tracking" />
    <TextView
        android:id="@+id/status"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />
</LinearLayout>

Listing 7-18. Activity Interacting with Service

public class ServiceActivity extends Activity implements View.OnClickListener {
     
    Button enableButton, disableButton;
    TextView statusView;
     
    TrackerService trackerService;
    Intent serviceIntent;
     
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
        enableButton = (Button)findViewById(R.id.enable);
        enableButton.setOnClickListener(this);
        disableButton = (Button)findViewById(R.id.disable);
        disableButton.setOnClickListener(this);
        statusView = (TextView)findViewById(R.id.status);
         
        serviceIntent = new Intent(this, TrackerService.class);
    }
     
    @Override
    public void onResume() {
        super.onResume();
        //Starting the service makes it stick, regardless of bindings
        startService(serviceIntent);
        //Bind to the service
        bindService(serviceIntent, serviceConnection, Context.BIND_AUTO_CREATE);
    }
     
    @Override
    public void onPause() {
        super.onPause();
        if(!trackerService.isTracking()) {
            //Stopping the service lets it die once unbound
            stopService(serviceIntent);
        }
        //Unbind from the service
        unbindService(serviceConnection);
    }
     
    @Override
    public void onClick(View v) {
        switch(v.getId()) {
        case R.id.enable:
            trackerService.startTracking();
            break;
        case R.id.disable:
            trackerService.stopTracking();
            break;
        default:
            break;
        }
        updateStatus();
    }
     
    private void updateStatus() {
        if(trackerService.isTracking()) {
            statusView.setText(
                String.format("Tracking enabled. %d locations
                    logged.",trackerService.getLocationsCount()));
        } else {
            statusView.setText("Tracking not currently enabled.");
        }
    }
     
    private ServiceConnection serviceConnection = new ServiceConnection() {
        public void onServiceConnected(ComponentName className, IBinder service) {
            trackerService = ((TrackerService.TrackerBinder)service).getService();
            updateStatus();
        }
 
        public void onServiceDisconnected(ComponentName className) {
            trackerService = null;
        }
    };
}

Figure 7-6 displays the basic activity with two buttons for the user to enable and disable location-tracking behavior, and a text display for the current service status.

While the activity is visible, it is bound to the TrackerService. This is done with the help of the ServiceConnection interface, which provides callback methods when the binding and unbinding operations are complete. With the service bound to the activity, you can now make direct calls on all the public methods exposed by the service.

However, bindings alone will not allow the service to run for the long term; accessing the service solely through its Binder interface causes it to be created and destroyed automatically along with the life cycle of this activity. In this case, we want the service to persist beyond when this activity is in memory. In order to accomplish this, the service is explicitly started via startService() before it is bound. There is no harm in sending start commands to a service that is already running, so we can safely do this in onResume() as well.

The service will now continue running in memory, even after the activity unbinds itself. In onPause(), the example always checks whether the user has activated tracking, and if not, it stops the service first. This allows the service to die if it is not required for tracking, which keeps the service from perpetually hanging out in memory if it has no real work to do.

Running this example and pressing the Start Tracking button will spin up the persisted service and the LocationManager. The user may leave the application at this point, and the service will remain running, all the while logging all incoming location updates from the GPS. Upon returning to this application, the user can see that the service is still running, and the current number of stored location points is displayed. Pressing Stop Tracking will end the process and allow the service to die as soon as the user leaves the activity once more.

Problem

Your application requires a specific function that another application on the device is already programmed to do. Instead of overlapping functionality, you would like to launch the other application for the job instead.

Solution

(API Level 1)

Use an implicit Intent to tell the system what you are looking to do, and determine whether any applications exist to meet the need. Most often, developers use Intents in an explicit fashion to start another activity or service, like so:

Intent intent = new Intent(this, NewActivity.class);
startActivity(intent);

By declaring the specific component we want to launch, the Intent is very explicit in its delivery. We also have the power to define an Intent in terms of its action, category, data, and type to define a more implicit requirement of what task we want to accomplish.

External applications are always launched within the same Android task as your application when fired in this fashion, so once the operation is complete (or if the user backs out), the user is returned to your application. This keeps the experience seamless, allowing multiple applications to act as one from the user’s perspective.

How It Works

When defining Intents in this fashion, it can be unclear what information you must include, because there is no published standard and it is possible for two applications offering the same service (reading a PDF file, for example) to define slightly different filters to listen for incoming Intents. You want to make sure to provide enough information for the system (or the user) to pick the best application to handle the required task.

The core piece of information to define on almost any implicit Intent is the action: a string value that is passed either in the constructor or via Intent.setAction(). This value tells Android what you want to do, whether it is to view a piece of content, send a message, select a choice, and so on. From there, the fields provided are scenario specific, and often multiple combinations can arrive at the same result. Let’s take a look at some useful examples.

private void viewPdf(Uri file) {
        Intent intent;
        intent = new Intent(Intent.ACTION_VIEW);
        intent.setDataAndType(file, "application/pdf");
        try {
            startActivity(intent);
        } catch (ActivityNotFoundException e) {
            //No application to view, ask to download one
            AlertDialog.Builder builder = new AlertDialog.Builder(this);
            builder.setTitle("No Application Found");
            builder.setMessage("We could not find an application to view PDFs."
                    +"  Would you like to download one from Android Market?");
            builder.setPositiveButton("Yes, Please",
                new DialogInterface.OnClickListener() {
                @Override
                public void onClick(DialogInterface dialog, int which) {
                    Intent marketIntent = new Intent(Intent.ACTION_VIEW);
                    marketIntent.setData(
                            Uri.parse("market://details?id=com.adobe.reader"));
                    startActivity(marketIntent);
                }
            });
            builder.setNegativeButton("No, Thanks", null);
            builder.create().show();
        }
    }

String filename = NAME_OF YOUR_FILE;
File internalFile = getFileStreamPath(filename);
Uri internal = Uri.fromFile(internalFile);

String filename = NAME_OF YOUR_FILE;
File externalFile = new File(Environment.getExternalStorageDirectory(), filename);
Uri external = Uri.fromFile(externalFile);

private void shareContent(String update) {
    Intent intent = new Intent(Intent.ACTION_SEND);
    intent.setType("text/plain");
    intent.putExtra(Intent.EXTRA_TEXT, update);
    startActivity(Intent.createChooser(intent, "Share..."));
}

<menu xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:id="@+id/menu_share"
        android:showAsAction="ifRoom"
        android:title="Share"
        android:actionProviderClass="android.widget.ShareActionProvider"/>
</menu>

@Override
public boolean onCreateOptionsMenu(Menu menu) {
    //Inflate the menu
    getMenuInflater().inflate(R.menu.options, menu);
 
    //Find the item and set the share Intent
    MenuItem item = menu.findItem(R.id.menu_share);
    ShareActionProvider provider = (ShareActionProvider) item.getActionProvider();
 
    Intent intent = new Intent(Intent.ACTION_SEND);
    intent.setType("text/plain");
    intent.putExtra(Intent.EXTRA_TEXT, update);
    provider.setShareIntent(intent);
 
    return true;
}

Problem

Your application requires a specific function that one of the system applications on the device is already programmed to do. Instead of overlapping functionality, you would like to launch the system application for the job instead.

Solution

(API Level 1)

Use an implicit Intent to tell the system which application you are interested in. Each system application subscribes to a custom Uri scheme that can be inserted as data into an implicit Intent to signify the specific application you need to launch.

External applications are always launched in the same task as your application when fired in this fashion, so once the task is complete (or if the user backs out), the user is returned to your application. This keeps the experience seamless, allowing multiple applications to act as one from the user’s perspective.

How It Works

All of the following examples will construct Intents that can be used to launch system applications in various states. Once constructed, you should launch these applications by passing the Intent to startActivity().

Intent pageIntent = new Intent();
pageIntent.setAction(Intent.ACTION_VIEW);
pageIntent.setData(Uri.parse("http://WEB_ADDRESS_TO_VIEW"));
 
startActivity(pageIntent);

Intent searchIntent = new Intent();
searchIntent.setAction(Intent.ACTION_WEB_SEARCH);
searchIntent.putExtra(SearchManager.QUERY, STRING_TO_SEARCH);
 
startActivity(searchIntent);

Intent dialIntent = new Intent();
dialIntent.setAction(Intent.ACTION_DIAL);
dialIntent.setData(Uri.Parse("tel:8885551234");
 
startActivity(dialIntent);

Intent mapIntent = new Intent();
mapIntent.setAction(Intent.ACTION_VIEW);
mapIntent.setData(Uri.parse("geo:latitude,longitude"));
 
startActivity(mapIntent);

"geo:37.422,122.084"

Intent mapIntent = new Intent();
mapIntent.setAction(Intent.ACTION_VIEW);
mapIntent.setData(Uri.parse("geo:0,0?q=ADDRESS"));
 
startActivity(mapIntent);

"geo:0,0?q=1600 Amphitheatre Parkway, Mountain View, CA 94043"

Intent mapIntent = new Intent();
mapIntent.setAction(Intent.ACTION_VIEW);
mapIntent.setData(Uri.parse("http://maps.google.com/maps?saddr=lat,lng&daddr=lat,lng"));
 
startActivity(mapIntent);

"http://maps.google.com/maps?&daddr=37.422,122.084"

Intent mailIntent = new Intent();
mailIntent.setAction(Intent.ACTION_SEND);
mailIntent.setType("message/rfc822");
mailIntent.putExtra(Intent.EXTRA_EMAIL, new String[] {"[email protected]"});
mailIntent.putExtra(Intent.EXTRA_CC, new String[] {"[email protected]"});
mailIntent.putExtra(Intent.EXTRA_BCC, new String[] {"[email protected]"});
mailIntent.putExtra(Intent.EXTRA_SUBJECT, "Email Subject");
mailIntent.putExtra(Intent.EXTRA_TEXT, "Body Text");
mailIntent.putExtra(Intent.EXTRA_STREAM, URI_TO_FILE);
 
startActivity(mailIntent);

Intent mailIntent = new Intent();
mailIntent.setAction(Intent.ACTION_SEND_MULTIPLE);
mailIntent.setType("message/rfc822");
mailIntent.putExtra(Intent.EXTRA_EMAIL, new String[] {"[email protected]"});
mailIntent.putExtra(Intent.EXTRA_CC, new String[] {"[email protected]"});
mailIntent.putExtra(Intent.EXTRA_BCC, new String[] {"[email protected]"});
mailIntent.putExtra(Intent.EXTRA_SUBJECT, "Email Subject");
mailIntent.putExtra(Intent.EXTRA_TEXT, "Body Text");
 
ArrayList<Uri> files = new ArrayList<Uri>();
files.add(URI_TO_FIRST_FILE);
files.add(URI_TO_SECOND_FILE);
//...Repeat add() as often as necessary to add all the files you need
mailIntent.putParcelableArrayListExtra(Intent.EXTRA_STREAM, files);
 
startActivity(mailIntent);

Intent smsIntent = new Intent();
smsIntent.setAction(Intent.ACTION_VIEW);
smsIntent.setType("vnd.android-dir/mms-sms");
smsIntent.putExtra("address", "8885551234");
smsIntent.putExtra("sms_body", "Body Text");
 
startActivity(smsIntent);

static final int REQUEST_PICK = 100;
 
Intent pickIntent = new Intent();
pickIntent.setAction(Intent.ACTION_PICK);
pickIntent.setData(URI_TO_CONTACT_TABLE);
 
startActivityForResult(pickIntent, REQUEST_PICK);

android.provider.Contacts.People.CONTENT_URI

android.provider.ContactsContract.Contacts.CONTENT_URI

Intent marketIntent = new Intent();
marketIntent.setAction(Intent.ACTION_VIEW);
marketIntent.setData(Uri.parse("market://details?id=PACKAGE_NAME_HERE");
 
startActivity(marketIntent);

Intent marketIntent = new Intent();
marketIntent.setAction(Intent.ACTION_VIEW);
marketIntent.setData(Uri.parse("market://search?q=SEARCH_QUERY"));
 
startActivity(marketIntent);

Problem

You’ve created an application that is absolutely the best at doing a specific task, and you would like to expose an interface for other applications on the device to be able to run your application.

Solution

(API Level 1)

Create an IntentFilter on the activity or service you would like to expose. Then publicly document the actions, data types, and extras that are required to access it properly. Recall that the action, category, and data/type of an Intent can all be used as criteria to match requests to your application. Any additional required or optional parameters should be passed in as extras.

How It Works

Let’s say you have created an application that includes an activity to play a video and will marquee the video’s title at the top of the screen during playback. You want to allow other applications to play video using your application, so we need to define a useful Intent structure for applications to pass in the required data and then create an IntentFilter on the activity in the application’s manifest to match.

This hypothetical activity requires two pieces of data to do its job:

• The Uri of a video, either local or remote
• A string representing the video’s title

If the application specializes in a certain type of video, we could define that a generic action (such as ACTION_VIEW) be used and filter more specifically on the data type of the video content we want to handle. Listing 7-23 is an example of how the activity would be defined in the manifest to filter Intents in this manner.

Listing 7-23. AndroidManifest.xml <activity> Element with Data Type Filter

<activity android:name=".PlayerActivity">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="video/h264" />
    </intent-filter>
</activity>

This filter will match any Intent with Uri data that is either explicitly declared as an H.264 video clip or is determined to be H.264 upon inspecting the Uri file. An external application would then be able to call on this activity to play a video by using the following lines of code:

Uri videoFile = A_URI_OF_VIDEO_CONTENT;
Intent playIntent = new Intent(Intent.ACTION_VIEW);
playIntent.setDataAndType(videoFile, "video/h264");
playIntent.putExtra(Intent.EXTRA_TITLE, "My Video");
startActivity(playIntent);

In some cases, it may be more useful for an external application to directly reference this player as the target, regardless of the type of video they want to pass in. In this case, we would create a unique custom action string for Intents to implement. The filter attached to the activity in the manifest would then need to match only the custom action string. See Listing 7-24.

Listing 7-24. AndroidManifest.xml <activity> Element with Custom Action Filter

<activity android:name=".PlayerActivity">
    <intent-filter>
        <action android:name="com.examples.myplayer.PLAY" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

An external application could call on this activity to play a video by using the following code:

Uri videoFile = A_URI_OF_VIDEO_CONTENT;
Intent playIntent = new Intent("com.examples.myplayer.PLAY");
playIntent.setData(videoFile);
playIntent.putExtra(Intent.EXTRA_TITLE, "My Video");
startActivity(playIntent);

public class PlayerActivity extends Activity {
 
    public static final String ACTION_PLAY = "com.examples.myplayer.PLAY";
 
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
         
        //Inspect the Intent that launched us
        Intent incoming = getIntent();
        //Get the video URI from the data field
        Uri videoUri = incoming.getData();
        //Get the optional title extra, if it exists
        String title;
        if(incoming.hasExtra(Intent.EXTRA_TITLE)) {
            title = incoming.getStringExtra(Intent.EXTRA_TITLE);
        } else {
            title = "";
        }
         
        /* Begin playing the video and displaying the title */
    }
 
    /* Remainder of the Activity Code */
 
}

Problem

Your application needs to interact directly with the ContentProvider exposed by Android to the user’s contacts to add, view, change, or remove information from the database.

Solution

(API Level 5)

Use the interface exposed by ContactsContract to access the data. ContactsContract is a vast ContentProvider API that attempts to aggregate the contact information stored in the system from multiple user accounts into a single data store. The result is a maze of Uris, tables, and columns, from which data may be accessed and modified.

The Contact structure is a hierarchy with three tiers: Contacts, RawContacts, and Data:

• A Contact conceptually represents a person, and it is an aggregation of all RawContacts believed by Android to represent that same person.
• RawContacts represents a collection of data stored in the device from a specific device account, such as the user’s e-mail address book or Facebook account.
• Data elements are the specific pieces of information attached to RawContacts, such as an e-mail address, phone number, or postal address.

The complete API has too many combinations and options for us to cover them all here, so consult the SDK documentation for all possibilities. We will investigate how to construct the basic building blocks for performing queries and making changes to the Contacts data set.

How It Works

The Android Contacts API boils down to a complex database with multiple tables and joins. Therefore, the methods for accessing the data are no different than those used to access any other SQLite database from an application.

public class ContactsActivity extends FragmentActivity {
 
    private static final int ROOT_ID = 100;
     
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        FrameLayout rootView = new FrameLayout(this);
        rootView.setId(ROOT_ID);
         
        setContentView(rootView);
         
        //Create and add a new list fragment
        getSupportFragmentManager().beginTransaction()
            .add(ROOT_ID, ContactsFragment.newInstance())
            .commit();
    }
     
    public static class ContactsFragment extends ListFragment
            implements AdapterView.OnItemClickListener, LoaderManager.LoaderCallbacks<Cursor> {
         
        public static ContactsFragment newInstance() {
            return new ContactsFragment();
        }
         
        private SimpleCursorAdapter mAdapter;
 
        @Override
        public void onActivityCreated(Bundle savedInstanceState) {
            super.onActivityCreated(savedInstanceState);
 
            // Display all contacts in a ListView
            mAdapter = new SimpleCursorAdapter(getActivity(),
                    android.R.layout.simple_list_item_1, null,
                    new String[] { ContactsContract.Contacts.DISPLAY_NAME },
                    new int[] { android.R.id.text1 },
                    0);
            setListAdapter(mAdapter);
            // Listen for item selections
            getListView().setOnItemClickListener(this);
             
            getLoaderManager().initLoader(0, null, this);
        }
 
        @Override
        public Loader<Cursor> onCreateLoader(int id, Bundle args) {
            // Return all contacts, ordered by name
            String[] projection = new String[] {
                    ContactsContract.Contacts._ID,
                    ContactsContract.Contacts.DISPLAY_NAME
            };
 
            return new CursorLoader(getActivity(),
                    ContactsContract.Contacts.CONTENT_URI,
                    projection, null, null,
                    ContactsContract.Contacts.DISPLAY_NAME);
        }
 
        @Override
        public void onLoadFinished(Loader<Cursor> loader, Cursor data) {
            mAdapter.swapCursor(data);
        }
 
        @Override
        public void onLoaderReset(Loader<Cursor> loader) {
            mAdapter.swapCursor(null);
        }
 
        @Override
        public void onItemClick(AdapterView<?> parent, View v,
                int position, long id) {
            final Cursor contacts = mAdapter.getCursor();
            if (contacts.moveToPosition(position)) {
                int selectedId = contacts.getInt(0); // _ID column
                // Gather email data from email table
                Cursor email = getActivity().getContentResolver()
                        .query(ContactsContract.CommonDataKinds.Email.CONTENT_URI,
                                new String[] {ContactsContract.CommonDataKinds.Email.DATA},
                                ContactsContract.Data.CONTACT_ID
                                        + " = " + selectedId,
                                null, null);
                // Gather phone data from phone table
                Cursor phone = getActivity().getContentResolver()
                        .query(ContactsContract.CommonDataKinds.Phone.CONTENT_URI,
                                new String[] {ContactsContract.CommonDataKinds.Phone.NUMBER},
                                ContactsContract.Data.CONTACT_ID
                                        + " = " + selectedId,
                                null, null);
                // Gather addresses from address table
                Cursor address = getActivity().getContentResolver()
                        .query(ContactsContract.CommonDataKinds.StructuredPostal.CONTENT_URI,
                                new String[] {ContactsContract.CommonDataKinds
                                        .StructuredPostal.FORMATTED_ADDRESS},
                                ContactsContract.Data.CONTACT_ID
                                        + " = " + selectedId,
                                null, null);
 
                // Build the dialog message
                StringBuilder sb = new StringBuilder();
                sb.append(email.getCount() + " Emails
");
                if (email.moveToFirst()) {
                    do {
                        sb.append("Email: " + email.getString(0));
                        sb.append('
'),
                    } while (email.moveToNext());
                    sb.append('
'),
                }
                sb.append(phone.getCount() + " Phone Numbers
");
                if (phone.moveToFirst()) {
                    do {
                        sb.append("Phone: " + phone.getString(0));
                        sb.append('
'),
                    } while (phone.moveToNext());
                    sb.append('
'),
                }
                sb.append(address.getCount() + " Addresses
");
                if (address.moveToFirst()) {
                    do {
                        sb.append("Address:
"
                                + address.getString(0));
                    } while (address.moveToNext());
                    sb.append('
'),
                }
 
                AlertDialog.Builder builder = new AlertDialog.Builder(getActivity());
                builder.setTitle(contacts.getString(1)); // Display name
                builder.setMessage(sb.toString());
                builder.setPositiveButton("OK", null);
                builder.create().show();
 
                // Finish temporary cursors
                email.close();
                phone.close();
                address.close();
            }
        }
    }
}

public class ContactsEditActivity extends FragmentActivity {
 
    private static final String TEST_EMAIL = "[email protected]";
    private static final int ROOT_ID = 100;
     
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        FrameLayout rootView = new FrameLayout(this);
        rootView.setId(ROOT_ID);
         
        setContentView(rootView);
         
        //Create and add a new list fragment
        getSupportFragmentManager().beginTransaction()
            .add(ROOT_ID, ContactsEditFragment.newInstance())
            .commit();
    }
     
    public static class ContactsEditFragment extends ListFragment implements
            AdapterView.OnItemClickListener,
            DialogInterface.OnClickListener,
            LoaderManager.LoaderCallbacks<Cursor> {
 
        public static ContactsEditFragment newInstance() {
            return new ContactsEditFragment();
        }
         
        private SimpleCursorAdapter mAdapter;
        private Cursor mEmail;
        private int selectedContactId;
 
        @Override
        public void onActivityCreated(Bundle savedInstanceState) {
            super.onActivityCreated(savedInstanceState);
 
            // Display all contacts in a ListView
            mAdapter = new SimpleCursorAdapter(getActivity(),
                    android.R.layout.simple_list_item_1, null,
                    new String[] { ContactsContract.Contacts.DISPLAY_NAME },
                    new int[] { android.R.id.text1 },
                    0);
            setListAdapter(mAdapter);
            // Listen for item selections
            getListView().setOnItemClickListener(this);
             
            getLoaderManager().initLoader(0, null, this);
        }
 
        @Override
        public Loader<Cursor> onCreateLoader(int id, Bundle args) {
            // Return all contacts, ordered by name
            String[] projection = new String[] { ContactsContract.Contacts._ID,
                    ContactsContract.Contacts.DISPLAY_NAME };
            //List only contacts visible to the user
            return new CursorLoader(getActivity(),
                    ContactsContract.Contacts.CONTENT_URI,
                    projection, ContactsContract.Contacts.IN_VISIBLE_GROUP+" = 1",
                    null,
                    ContactsContract.Contacts.DISPLAY_NAME);
        }
         
        @Override
        public void onLoadFinished(Loader<Cursor> loader, Cursor data) {
            mAdapter.swapCursor(data);
        }
 
        @Override
        public void onLoaderReset(Loader<Cursor> loader) {
            mAdapter.swapCursor(null);
        }
         
        @Override
        public void onItemClick(AdapterView<?> parent, View v, int position, long id) {
            final Cursor contacts = mAdapter.getCursor();
            if (contacts.moveToPosition(position)) {
                selectedContactId = contacts.getInt(0); // _ID column
                // Gather email data from email table
                String[] projection = new String[] {
                        ContactsContract.Data._ID,
                        ContactsContract.CommonDataKinds.Email.DATA };
                mEmail = getActivity().getContentResolver().query(
                        ContactsContract.CommonDataKinds.Email.CONTENT_URI,
                        projection,
                        ContactsContract.Data.CONTACT_ID + " = " + selectedContactId,
                        null,
                        null);
 
                AlertDialog.Builder builder = new AlertDialog.Builder(getActivity());
                builder.setTitle("Email Addresses");
                builder.setCursor(mEmail, this, ContactsContract.CommonDataKinds.Email.DATA);
                builder.setPositiveButton("Add", this);
                builder.setNegativeButton("Cancel", null);
                builder.create().show();
            }
        }
 
        @Override
        public void onClick(DialogInterface dialog, int which) {
            //Data must be associated with a RAW contact, retrieve the first raw ID
            Cursor raw = getActivity().getContentResolver().query(
                    ContactsContract.RawContacts.CONTENT_URI,
                    new String[] { ContactsContract.Contacts._ID },
                    ContactsContract.Data.CONTACT_ID + " = " + selectedContactId, null, null);
            if(!raw.moveToFirst()) {
                return;
            }
 
            int rawContactId = raw.getInt(0);
            ContentValues values = new ContentValues();
            switch(which) {
                case DialogInterface.BUTTON_POSITIVE:
                    //User wants to add a new email
                    values.put(ContactsContract.CommonDataKinds.Email.RAW_CONTACT_ID, rawContactId);
                    values.put(ContactsContract.Data.MIMETYPE, ContactsContract
                            .CommonDataKinds.Email.CONTENT_ITEM_TYPE);
                    values.put(ContactsContract.CommonDataKinds.Email.DATA, TEST_EMAIL);
                    values.put(ContactsContract.CommonDataKinds.Email.TYPE,
                            ContactsContract.CommonDataKinds.Email.TYPE_OTHER);
                    getActivity().getContentResolver()
                            .insert(ContactsContract.Data.CONTENT_URI, values);
                    break;
                default:
                    //User wants to edit selection
                    values.put(ContactsContract.CommonDataKinds.Email.DATA, TEST_EMAIL);
                    values.put(ContactsContract.CommonDataKinds.Email.TYPE,
                            ContactsContract.CommonDataKinds.Email.TYPE_OTHER);
                    getActivity().getContentResolver()
                            .update(ContactsContract.Data.CONTENT_URI, values,
                                    ContactsContract.Data._ID+" = "+mEmail.getInt(0), null);
                    break;
            }
 
            //Don't need the email cursor anymore
            mEmail.close();
        }
    }
}

ContactsContract.Contacts.IN_VISIBLE_GROUP+" = 1"

Problem

Your application needs to import a user-selected document item (such as a text file, audio, video, or image) for display or playback.

Solution

(API Level 1)

Use an implicit Intent targeted with Intent.ACTION_GET_CONTENT to bring up a picker interface from a specific application. Firing this Intent with a matching content type for the media of interest (audio, video, or image are the most common) will present the user with a picker interface to select an item, and the Intent result will include a content Uri pointing to the selection the user made.

(API Level 19)

Use an implicit Intent targeted with Intent.ACTION_OPEN_DOCUMENT to bring up the system’s document picker interface. This is a single common interface where all applications that support the requested content type will list the items the user may select. The content that populates this interface comes from applications that expose DocumentProvider for the requested type. These provider elements can come from the system or other applications. We will look at how to create one of your own later in this chapter.

How It Works

Let’s take a look at this technique used in the context of an example activity. See Listings 7-28 and 7-29.

Listing 7-28. res/layout/main.xml

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="vertical"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
    <Button
        android:id="@+id/imageButton"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="Images" />
    <Button
         android:id="@+id/videoButton"
         android:layout_width="match_parent"
         android:layout_height="wrap_content"
         android:text="Video" />
    <Button
        android:id="@+id/audioButton"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="Audio" />
</LinearLayout>

Listing 7-29. Activity to Pick Media

public class MediaActivity extends Activity implements View.OnClickListener {
 
    private static final int REQUEST_AUDIO = 1;
    private static final int REQUEST_VIDEO = 2;
    private static final int REQUEST_IMAGE = 3;
     
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
         
        Button images = (Button)findViewById(R.id.imageButton);
        images.setOnClickListener(this);
        Button videos = (Button)findViewById(R.id.videoButton);
        videos.setOnClickListener(this);
        Button audio = (Button)findViewById(R.id.audioButton);
        audio.setOnClickListener(this);
         
    }
 
    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        
        if(resultCode == Activity.RESULT_OK) {
            //Uri to user selection returned in the Intent
            Uri selectedContent = data.getData();
             
            if(requestCode == REQUEST_IMAGE) {
                //Pass an InputStream to BitmapFactory
            }
            if(requestCode == REQUEST_VIDEO) {
                //Pass the Uri or a FileDescriptor to MediaPlayer
            }
            if(requestCode == REQUEST_AUDIO) {
                //Pass the Uri or a FileDescriptor to MediaPlayer
            }
        }
    }
     
    @Override
    public void onClick(View v) {
        Intent intent = new Intent();
        //Use the proper Intent action
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT) {
            intent.setAction(Intent.ACTION_OPEN_DOCUMENT);
        } else {
            intent.setAction(Intent.ACTION_GET_CONTENT);
        }
        //Only return files to which we can open a stream
        intent.addCategory(Intent.CATEGORY_OPENABLE);
 
        //Set correct MIME type and launch
        switch(v.getId()) {
        case R.id.imageButton:
            intent.setType("image/*");
            startActivityForResult(intent, REQUEST_IMAGE);
            return;
        case R.id.videoButton:
            intent.setType("video/*");
            startActivityForResult(intent, REQUEST_VIDEO);
            return;
        case R.id.audioButton:
            intent.setType("audio/*");
            startActivityForResult(intent, REQUEST_AUDIO);
            return;
        default:
            return;
        }
    }
}

This example has three buttons for the user to press, each targeting a specific type of media. When the user presses any one of these buttons, an Intent with the appropriate action for the platform level is fired to the system. On devices running 4.4 and later, this will display the system document picker. Previous devices will launch the proper picker activity from the necessary application, showing a chooser if multiple applications can handle the content type. We have also included CATEGORY_OPENABLE to this Intent, which indicates to the system that only items our application can open a stream to will be displayed in the picker.

If the user selects a valid item, a content Uri pointing to that item is returned in the result Intent with a status of RESULT_OK. If the user cancels or otherwise backs out of the picker, the status will be RESULT_CANCELED and the Intent’s data field will be null.

With the Uri of the media received, the application is now free to play or display the content as deemed appropriate. Classes such as MediaPlayer and VideoView will take a Uri directly to play media content, while most others will take either an InputStream or a FileDescriptor reference. Both of these can be obtained from the Uri by using ContentResolver.openInputStream() and ContentResolver.openFileDescriptor(), respectively.

Problem

Your application would like to create new documents or media and insert them into the device’s global providers so that they are visible to all applications.

Solution

(API Level 1)

Utilize the ContentProvider interface exposed by MediaStore to perform inserts or media content. In addition to the media content itself, this interface allows you to insert metadata to tag each item, such as a title, description, or time created. The result of the ContentProvider insert operation is a Uri that the application may use as a destination for the new media.

(API Level 19)

On Android 4.4+ devices, we can also trigger an implicit Intent targeted with Intent.ACTION_CREATE_DOCUMENT to save a new document in any of the device’s registered DocumentProvider instances. This can be any type of document content, including (but not restricted to) media files. However, it is not meant to supersede MediaStore,  which is still the best method for saving directly to the system’s core ContentProvider. If you instead need to involve the user more directly in saving the content (including media), the document framework is a better path here.

How It Works

Let’s take a look at an example of inserting an image or video clip into MediaStore. See Listings 7-30 and 7-31.

Listing 7-30. res/layout/save.xml

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    android:orientation="vertical" >
    <Button
        android:id="@+id/imageButton"
        android:layout_width="fill_parent"
        android:layout_height="wrap_content"
        android:text="Images" />
    <Button
        android:id="@+id/videoButton"
        android:layout_width="fill_parent"
        android:layout_height="wrap_content"
        android:text="Video" />
    <Button
        android:id="@+id/textButton"
        android:layout_width="fill_parent"
        android:layout_height="wrap_content"
        android:text="Text Document" />
 
</LinearLayout>

Listing 7-31. Activity Saving Data in the MediaStore

public class StoreActivity extends Activity implements View.OnClickListener {
 
    private static final int REQUEST_CAPTURE = 100;
    private static final int REQUEST_DOCUMENT = 101;
     
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.save);
         
        Button images = (Button) findViewById(R.id.imageButton);
        images.setOnClickListener(this);
        Button videos = (Button) findViewById(R.id.videoButton);
        videos.setOnClickListener(this);
 
        //We can only create new documents above API Level 19
        Button text = (Button) findViewById(R.id.textButton);
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT) {
            text.setOnClickListener(this);
        } else {
            text.setVisibility(View.GONE);
        }
    }
     
    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        if (requestCode == REQUEST_CAPTURE && resultCode == Activity.RESULT_OK) {
            Toast.makeText(this, "All Done!", Toast.LENGTH_SHORT).show();
        }
        if (requestCode == REQUEST_DOCUMENT && resultCode == Activity.RESULT_OK) {
            //Once the user has selected where to save the new document,
            // we can write the contents into it
            Uri document = data.getData();
            writeDocument(document);
        }
    }
     
    private void writeDocument(Uri document) {
        try {
            ParcelFileDescriptor pfd = getContentResolver().openFileDescriptor(document, "w");
            FileOutputStream out = new FileOutputStream(pfd.getFileDescriptor());
            //Construct some content for our file
            StringBuilder sb = new StringBuilder();
            sb.append("Android Recipes Log File:");
            sb.append("
");
            sb.append("Last Written at: ");
            sb.append(DateFormat.getLongDateFormat(this).format(new Date()));
 
            out.write(sb.toString().getBytes());
             
            // Let the document provider know you're done by closing the stream.
            out.flush();
            out.close();
            // Close our file handle
            pfd.close();
        } catch (FileNotFoundException e) {
            Log.w("AndroidRecipes", e);
        } catch (IOException e) {
            Log.w("AndroidRecipes", e);
        }
    }
     
    @Override
    public void onClick(View v) {
        ContentValues values;
        Intent intent;
        Uri storeLocation;
        final long nowMillis = System.currentTimeMillis();
         
        switch(v.getId()) {
        case R.id.imageButton:
            //Create any metadata for image
            values = new ContentValues(5);
            values.put(MediaStore.Images.ImageColumns.DATE_TAKEN, nowMillis);
            values.put(MediaStore.Images.ImageColumns.DATE_ADDED, nowMillis / 1000);
            values.put(MediaStore.Images.ImageColumns.DATE_MODIFIED, nowMillis / 1000);
            values.put(MediaStore.Images.ImageColumns.DISPLAY_NAME, "Android Recipes Image Sample");
            values.put(MediaStore.Images.ImageColumns.TITLE, "Android Recipes Image Sample");
             
            //Insert metadata and retrieve Uri location for file
            storeLocation = getContentResolver()
                    .insert(MediaStore.Images.Media.EXTERNAL_CONTENT_URI, values);
            //Start capture with new location as destination
            intent = new Intent(MediaStore.ACTION_IMAGE_CAPTURE);
            intent.putExtra(MediaStore.EXTRA_OUTPUT, storeLocation);
            startActivityForResult(intent, REQUEST_CAPTURE);
            return;
        case R.id.videoButton:
            //Create any metadata for video
            values = new ContentValues(7);
            values.put(MediaStore.Video.VideoColumns.DATE_TAKEN, nowMillis);
            values.put(MediaStore.Video.VideoColumns.DATE_ADDED, nowMillis / 1000);
            values.put(MediaStore.Video.VideoColumns.DATE_MODIFIED, nowMillis / 1000);
            values.put(MediaStore.Video.VideoColumns.DISPLAY_NAME, "Android Recipes Video Sample");
            values.put(MediaStore.Video.VideoColumns.TITLE, "Android Recipes Video Sample");
            values.put(MediaStore.Video.VideoColumns.ARTIST, "Yours Truly");
            values.put(MediaStore.Video.VideoColumns.DESCRIPTION, "Sample Video Clip");
             
            //Insert metadata and retrieve Uri location for file
            storeLocation = getContentResolver()
                    .insert(MediaStore.Video.Media.EXTERNAL_CONTENT_URI, values);
            //Start capture with new location as destination
            intent = new Intent(MediaStore.ACTION_VIDEO_CAPTURE);
            intent.putExtra(MediaStore.EXTRA_OUTPUT, storeLocation);
            startActivityForResult(intent, REQUEST_CAPTURE);
            return;
        case R.id.textButton:
            //Create a new document
            intent = new Intent(Intent.ACTION_CREATE_DOCUMENT);
            intent.addCategory(Intent.CATEGORY_OPENABLE);
             
            //This is a text document
            intent.setType("text/plain");
            //Optional title to pre-set on document
            intent.putExtra(Intent.EXTRA_TITLE, "Android Recipes");
            startActivityForResult(intent, REQUEST_DOCUMENT);
        default:
            return;
        }
    }
}

In this example, when the user clicks the Image or Video button, metadata associated with the media are inserted into a ContentValues instance. Some of the more common metadata columns to both image and video are the following:

• TITLE: String value for the content title. Displayed in the gallery applications as the content name.
• DISPLAY_NAME: Name displayed in most selection interfaces such as the system document picker.
• DATE_TAKEN: Integer value describing the date the media item was captured. Note this value is in milliseconds.
• DATE_ADDED: Integer value describing when the media was added to MediaStore. Note this value is in seconds, not milliseconds.
• DATE_MODIFIED: Integer value describing the last change to the media. This is used to sort items in the system document picker. Note this value is also in seconds.

The ContentValues are then inserted into the MediaStore by using the appropriate CONTENT_URI reference. Notice that the metadata are inserted before the media item itself is actually captured. The return value from a successful insert is a fully qualified Uri that the application may use as the destination for the media content.

In the previous example, we are using the simplified methods from Chapter 5 of capturing audio and video by requesting that the system applications handle this process. Recall from Chapter 5 that both the audio and video capture Intent can be passed with an extra, declaring the destination for the result. This is where we pass the Uri that was returned from the insert.

Upon a successful return from the capture activity, there is nothing more for the application to do. The external application has saved the captured image or video into the location referenced by our MediaStore insert. This data is now visible to all applications, including the system’s Gallery application.

Problem

You need to query the ContentProvider of locally saved information on the device for sent and received SMS/MMS messages.

Solution

(API Level 19)

Use the contract interface exposed via the Telephony framework. The inner classes of Telephony define all the Uris and data columns used to read SMS messages, MMS messages, and additional metadata.

The Telephony provider exposes an interface for the following blocks of data:

• Telephony.Sms: Contains the message content and recipient/delivery metadata for all SMS messages.
• Telephony.Mms: Contains the message content and recipient/delivery metadata for all MMS messages.
• Telephony.MmsSms: Contains the combined messages for SMS and MMS. Also includes custom Uris for requesting a list of conversations, drafts, and searching messages.
• Telephony.Threads: Provides additional metadata about conversations, such as the message count and read status of the conversation thread.

Text-based SMS messages are relatively straightforward, with their entire content housed within a few columns in the Telephony.Sms tables. Even if a message has multiple recipients, those are broken up into multiple messages with the same text content. MMS messages, however, are composed of multiple parts that are all stored separately in individual tables:

• Mms.Addr: Contains metadata about all the recipients involved in each MMS message. Each message can have a unique group of recipients.
• Mms.Part: Contains the contents of each piece included in the MMS message. The message text is stored as one part with any image, video, or other attachments stored as additional pieces. A MIME string designates the content type of each part.

Displaying a single SMS message can be done with a single query to the Telephony.Sms content Uri. Displaying a single MMS message, however, requires iterating through all of these subparts in Telephony.Mms to collect the data we need.

How It Works

In this example, we will create a simple messaging application that reads conversation data from the Telephony provider and displays it in a list. Let’s start with the code to query and parse the data coming from the provider. In Listing 7-32, we’ve created a custom AsyncTaskLoader implementation that allows us to query the provider on a background thread and return the result easily to the UI.

Listing 7-32. Loader for Conversation Data

public class ConversationLoader extends AsyncTaskLoader<List<MessageItem>> {
     
    public static final String[] PROJECTION = new String[] {
        //Determine if message is SMS or MMS
        MmsSms.TYPE_DISCRIMINATOR_COLUMN,
        //Base item ID
        BaseColumns._ID,
        //Conversation (thread) ID
        Conversations.THREAD_ID,
        //Date values
        Sms.DATE,
        Sms.DATE_SENT,
        // For SMS only
        Sms.ADDRESS,
        Sms.BODY,
        Sms.TYPE,
        // For MMS only
        Mms.SUBJECT,
        Mms.MESSAGE_BOX
    };
     
    //Thread ID of the conversation we are loading
    private long mThreadId;
    //This device's number
    private String mDeviceNumber;
     
    public ConversationLoader(Context context) {
        this(context, -1);
    }
     
    public ConversationLoader(Context context, long threadId) {
        super(context);
        mThreadId = threadId;
        //Obtain the phone number of this device, if available
        TelephonyManager manager =
                (TelephonyManager) context.getSystemService(Context.TELEPHONY_SERVICE);
        mDeviceNumber = manager.getLine1Number();
    }
 
    @Override
    protected void onStartLoading() {
        //Reload on every init request
        forceLoad();
    }
     
    @Override
    public List<MessageItem> loadInBackground() {
        Uri uri;
        String[] projection;
        if (mThreadId < 0) {
            //Load all conversations
            uri = MmsSms.CONTENT_CONVERSATIONS_URI;
            projection = null;
        } else {
            //Load just the requested thread
            uri = ContentUris.withAppendedId(MmsSms.CONTENT_CONVERSATIONS_URI, mThreadId);
            projection = PROJECTION;
        }
         
        Cursor cursor = getContext().getContentResolver().query(
                uri,
                projection,
                null,
                null,
                null);
         
        return MessageItem.parseMessages(getContext(), cursor, mDeviceNumber);
    }
}

AysncTaskLoader is fairly simply to customize. You just need to provide an implementation of loadInBackground() to do the interesting work, and include some logic in onStartLoading() to get the process running. In the framework, results are usually cached, and forceLoad() is called only if the content has changed, but for simplicity we are loading data from the provider on every request.

Our ConversationLoader will be used to obtain two message lists: a list of all conversations present, and a list of all the messages for a selected conversation (or thread). So when ConversationLoader is instantiated, the ID of the conversation thread is either passed in or ignored to determine the output results. We also obtain the phone number of our device from TelephonyManager for use later. This step is not integral to reading the provider, but will help us clean up the display later.

In both request modes, we are making a query of the MmsSms.CONTENT_CONVERSATIONS_URI in the combined message table. This Uri is convenient for getting a conversation overview because it will return a list of all the known conversation threads by returning the latest message in each thread. This makes it easy to display the results directly to the user.

When listing all the conversations, we don’t need to provide a customized projection, which will return all the columns. However, when looking at a specific thread, we pass in a specific column subset to inspect. This is mainly so we can obtain the MmsSms.TYPE_DISCRIMINATOR_COLUMN value, which tells us whether each message is SMS or MMS. This column is not available for the main conversations list, and it also isn’t returned by default for a null projection.

After we have successfully queried the provider, we want to parse the contents into a common model object that we can easily display in a list. To do this, we pass the result Cursor to a factory method in a MessageItem class we’ve created, which you can see in Listing 7-33.

Listing 7-33. MessageItem Model and Parsing

public class MessageItem {
    /* Message Type Identifiers */
    private static final String TYPE_SMS = "sms";
    private static final String TYPE_MMS = "mms";
     
    static final String[] MMS_PROJECTION = new String[] {
        //Base item ID
        BaseColumns._ID,
        //MIME Type of the content for this part
        Mms.Part.CONTENT_TYPE,
        //Text content of a text/plain part
        Mms.Part.TEXT,
        //Path to binary content of a nontext part
        Mms.Part._DATA
    };
     
    /* Message Id */
    public long id;
    /* Thread (Conversation) Id */
    public long thread_id;
    /* Address string of message */
    public String address;
    /* Body string of message */
    public String body;
    /* Whether this message was sent or received on this device */
    public boolean incoming;
    /* MMS image attachment */
    public Uri attachment;
     
    /*
     * Construct a list of messages from the Cursor data
     * queried by the Loader
     */
    public static List<MessageItem> parseMessages(Context context, Cursor cursor,
            String myNumber) {
 
        List<MessageItem> messages = new ArrayList<MessageItem>();
        if (!cursor.moveToFirst()) {
            return messages;
        }
        //Parse each message based on the type identifiers
        do {
            String type = getMessageType(cursor);
            if (TYPE_SMS.equals(type)) {
                MessageItem item = parseSmsMessage(cursor);
                messages.add(item);
            } else if (TYPE_MMS.equals(type)) {
                MessageItem item = parseMmsMessage(context, cursor, myNumber);
                messages.add(item);
            } else {
                Log.w("TelephonyProvider", "Unknown Message Type");
            }
        } while (cursor.moveToNext());
        cursor.close();
         
        return messages;
    }
     
    /*
     * Read message type, if present in Cursor; otherwise
     * infer it from the column values present in the Cursor
     */
    private static String getMessageType(Cursor cursor) {
        int typeIndex = cursor.getColumnIndex(MmsSms.TYPE_DISCRIMINATOR_COLUMN);
        if (typeIndex < 0) {
            //Type column not in projection, use another discriminator
            String cType = cursor.getString(cursor.getColumnIndex(Mms.CONTENT_TYPE));
            //If a content type is present, this is an MMS message
            if (cType != null) {
                return TYPE_MMS;
            } else {
                return TYPE_SMS;
            }
        } else {
            return cursor.getString(typeIndex);
        }
    }
     
    /*
     * Parse out a MessageItem with contents from an SMS message
     */
    private static MessageItem parseSmsMessage(Cursor data) {
        MessageItem item = new MessageItem();
        item.id = data.getLong(data.getColumnIndexOrThrow(BaseColumns._ID));
        item.thread_id = data.getLong(data.getColumnIndexOrThrow(Conversations.THREAD_ID));
         
        item.address = data.getString(data.getColumnIndexOrThrow(Sms.ADDRESS));
        item.body = data.getString(data.getColumnIndexOrThrow(Sms.BODY));
        item.incoming = isIncomingMessage(data, true);
        return item;
    }
     
    /*
     * Parse out a MessageItem with contents from an MMS message
     */
    private static MessageItem parseMmsMessage(Context context, Cursor data, String myNumber) {
        MessageItem item = new MessageItem();
        item.id = data.getLong(data.getColumnIndexOrThrow(BaseColumns._ID));
        item.thread_id = data.getLong(data.getColumnIndexOrThrow(Conversations.THREAD_ID));
         
        item.incoming = isIncomingMessage(data, false);
         
        long _id = data.getLong(data.getColumnIndexOrThrow(BaseColumns._ID));
 
        //Query the address information for this message
        Uri addressUri = Uri.withAppendedPath(Mms.CONTENT_URI, _id + "/addr");
        Cursor addr = context.getContentResolver().query(
                addressUri,
                null,
                null,
                null,
                null);
        HashSet<String> recipients = new HashSet<String>();
        while (addr.moveToNext()) {
            String address = addr.getString(addr.getColumnIndex(Mms.Addr.ADDRESS));
            //Don't add our own number to the displayed list
            if (myNumber == null || !address.contains(myNumber)) {
                recipients.add(address);
            }
        }
        item.address = TextUtils.join(", ", recipients);
        addr.close();
         
        //Query all the MMS parts associated with this message
        Uri messageUri = Uri.withAppendedPath(Mms.CONTENT_URI, _id + "/part");
        Cursor inner = context.getContentResolver().query(
                messageUri,
                MMS_PROJECTION,
                Mms.Part.MSG_ID + " = ?",
                new String[] {String.valueOf(data.getLong(data.getColumnIndex(Mms._ID)))},
                null);
 
        while(inner.moveToNext()) {
            String contentType = inner.getString(inner.getColumnIndex(Mms.Part.CONTENT_TYPE));
            if (contentType == null) {
                continue;
            } else if (contentType.matches("image/.*")) {
                //Find any part that is an image attachment
                long partId = inner.getLong(inner.getColumnIndex(BaseColumns._ID));
                item.attachment = Uri.withAppendedPath(Mms.CONTENT_URI, "part/" + partId);
            } else if (contentType.matches("text/.*")) {
                //Find any part that is text data
                item.body = inner.getString(inner.getColumnIndex(Mms.Part.TEXT));
            }
        }
         
        inner.close();
        return item;
    }
     
    /*
     * Validate if the message is incoming or outgoing by the
     * type/box information listed in the provider
     */
    private static boolean isIncomingMessage(Cursor cursor, boolean isSms) {
        int boxId;
        if (isSms) {
            boxId = cursor.getInt(cursor.getColumnIndexOrThrow(Sms.TYPE));
            return (boxId == TextBasedSmsColumns.MESSAGE_TYPE_INBOX ||
                    boxId == TextBasedSmsColumns.MESSAGE_TYPE_ALL) ?
                    true : false;
        } else {
            boxId = cursor.getInt(cursor.getColumnIndexOrThrow(Mms.MESSAGE_BOX));
            return (boxId == Mms.MESSAGE_BOX_INBOX || boxId == Mms.MESSAGE_BOX_ALL) ?
                    true : false;
        }
    }
}

The MessageItem itself is a standard placeholder object for the message identifiers, name, text content, and image attachment (for MMS messages). Inside parseMessages(), we iterate through the Cursor data and construct a new MessageItem from each row. SMS and MMS are parsed differently, so we must first determine the message type. When the TYPE_DISCRIMINATOR_COLUMN is present, this is simple and we just check the value. In other cases, we can infer the type based on the column entries for each message.

Parsing an SMS message is straightforward, as we just need to read the ID, thread ID, address, body, and incoming status as columns directly from the main Cursor. Parsing an MMS message is slightly more involved because the message contents are segmented into parts. We can read the ID, thread ID, and incoming status from the main Cursor, but the address and content information need to be retrieved from additional tables.

First, we need to get the recipient information from the Mms.Addr table. MMS messages can be sent to multiple recipients, and each one is represented by a row in this table with a MSG_ID that matches the MMS message. We iterate through these elements and construct a comma-separated list of the results to attach to the MessageItem. Notice also that we are checking for our own number in this list to avoid having it added as well. Each message will also have an Addr entry for the local device number, and we don’t want to display that in our UI each time, so we are filtering it out.

Next we need to parse out the message contents. These values are stored in the Mms.Part table, keyed by the MSG_ID again. MMS messages can have many types of content associated with them (contact data, videos, images, and so forth) but we are interested in displaying only the text or image data that may be present. As we iterate through the parts, we validate the MIME string of the content type to find any text or image components to add to our MessageItem. For image attachments, we simply store the Uri pointing to the content rather than decoding the image and saving it here.

For both SMS and MMS messages, the status of whether the message is incoming or outgoing can be determined by looking at the message’s box type. Messages that are marked in the Inbox or have no designation are considered incoming messages, while all other message box designations (Outbox, Sent, Drafts, and so forth) are considered outgoing.

Now that we have a parsed list of messages, let’s take a look at Listings 7-34 and 7-35 to inspect the user interface implemented in this example.

Listing 7-34. Activity to Display SMS/MMS Messages

public class SmsActivity extends Activity
        implements OnItemClickListener, LoaderCallbacks<List<MessageItem>> {
 
    private MessagesAdapter mAdapter;
     
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        ListView list = new ListView(this);
        mAdapter = new MessagesAdapter(this);
        list.setAdapter(mAdapter);
         
        final Intent intent = getIntent();
         
        if (!intent.hasExtra("threadId")) {
            //Items are clickable if we are not showing a conversation
            list.setOnItemClickListener(this);
        }
        //Load the messages data
        getLoaderManager().initLoader(0, getIntent().getExtras(), this);
         
        setContentView(list);
    }
 
    @Override
    public void onItemClick(AdapterView<?> parent, View view, int position, long id) {
        final MessageItem item = mAdapter.getItem(position);
        long threadId = item.thread_id;
 
        //Launch a new instance to show this conversation
        Intent intent = new Intent(this, SmsActivity.class);
        intent.putExtra("threadId", threadId);
        startActivity(intent);
    }
     
    @Override
    public Loader<List<MessageItem>> onCreateLoader(int id, Bundle args) {
        if (args != null && args.containsKey("threadId")) {
            return new ConversationLoader(this, args.getLong("threadId"));
        } else {
            return new ConversationLoader(this);
        }
    }
 
    @Override
    public void onLoadFinished(Loader<List<MessageItem>> loader,List<MessageItem> data) {
        mAdapter.clear();
        mAdapter.addAll(data);
        mAdapter.notifyDataSetChanged();
    }
 
    @Override
    public void onLoaderReset(Loader<List<MessageItem>> loader) {
        mAdapter.clear();
        mAdapter.notifyDataSetChanged();
    }
     
    private static class MessagesAdapter extends ArrayAdapter<MessageItem> {
 
        int cacheSize = 4 * 1024 * 1024; // 4MiB
        private LruCache<String, Bitmap> bitmapCache = new LruCache<String, Bitmap>(cacheSize) {
            protected int sizeOf(String key, Bitmap value) {
                return value.getByteCount();
            }
        };
         
        public MessagesAdapter(Context context) {
            super(context, 0);
        }
         
        @Override
        public View getView(int position, View convertView, ViewGroup parent) {
            if (convertView == null) {
                convertView = LayoutInflater.from(getContext())
                        .inflate(R.layout.message_item, parent, false);
            }
             
            MessageItem item = getItem(position);
             
            TextView text1 = (TextView) convertView.findViewById(R.id.text1);
            TextView text2 = (TextView) convertView.findViewById(R.id.text2);
            ImageView image = (ImageView) convertView.findViewById(R.id.image);
             
            text1.setText(item.address);
            text2.setText(item.body);
            //Set text style based on incoming/outgoing status
            Typeface tf = item.incoming ?
                    Typeface.defaultFromStyle(Typeface.ITALIC) : Typeface.DEFAULT;
            text2.setTypeface(tf);
            image.setImageBitmap(getAttachment(item));
             
            return convertView;
        }
         
        private Bitmap getAttachment(MessageItem item) {
            if (item.attachment == null) return null;
             
            final Uri imageUri = item.attachment;
            //Pull image thumbnail from cache if we have it
            Bitmap cached = bitmapCache.get(imageUri.toString());
            if (cached != null) {
                return cached;
            }
             
            //Decode the asset from the provider if we don't have it in cache
            try {
                BitmapFactory.Options options = new BitmapFactory.Options();
                options.inJustDecodeBounds = true;
                int cellHeight = getContext().getResources()
                        .getDimensionPixelSize(R.dimen.message_height);
                InputStream is = getContext().getContentResolver().openInputStream(imageUri);
                BitmapFactory.decodeStream(is, null, options);
                 
                options.inJustDecodeBounds = false;
                options.inSampleSize = options.outHeight / cellHeight;
                is = getContext().getContentResolver().openInputStream(imageUri);
                Bitmap bitmap = BitmapFactory.decodeStream(is, null, options);
                 
                bitmapCache.put(imageUri.toString(), bitmap);
                return bitmap;
            } catch (Exception e) {
                return null;
            }
        }
    }
}

Listing 7-35. res/layout/message_item.xml

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:minHeight="@dimen/message_height">
    <ImageView
        android:id="@+id/image"
        android:layout_width="@dimen/message_height"
        android:layout_height="@dimen/message_height"
        android:layout_alignParentRight="true"
        android:layout_centerVertical="true" />
    <TextView
        android:id="@+id/text1"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_toLeftOf="@id/image"
        android:layout_marginLeft="6dp"
        android:textStyle="bold" />
    <TextView
        android:id="@+id/text2"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_below="@id/text1"
        android:layout_toLeftOf="@id/image"
        android:layout_marginLeft="12dp" />
 
</RelativeLayout>

Our activity is used to display both types of message data. Upon creation, the activity calls initLoader() to construct a new ConversationLoader to query the provider. The arguments passed in are the extras received by the activity Intent. When the application first launches, there are no incoming Intent extras, so a ConversationLoader is constructed to load all conversation threads. Later, when the activity is launched with a specific thread ID, ConversationLoader will query all messages in that conversation.

Once the loading is complete, the data is presented in a ListView using our custom MessagesAdapter. This adapter inflates a custom item layout (from Listing 7-35) with two text rows and space for an image. The MessageItem address information is loaded into the top label, and the text content into the bottom label. If the message is MMS and an image attachment is present, we attempt to return the image via getAttachment() and insert it into the ImageView.

Loading these images from disk each time is expensive and a tad slow, so to improve scrolling performance in the list, we have added an LruCache to store recently loaded bitmaps in memory. The cache is set to 4MiB in size, so as to not overinflate the application’s heap over time. Additionally, each image is downsampled when returned from BitmapFactory (via BitmapFactory.Options.inSampleSize) to avoid loading an image that is larger than the space available in the list row and wasting memory.

We now have a basic messaging application that presents a read-only window into the SMS/MMS on our device. When launched, this application will list all the conversations by showing the latest message for each thread. When a conversation is tapped, a new activity will display, showing all the individual messages within that thread. Pressing the Back button will return to the main list so the user can select another conversation to view.