View source for Android Broadcast Intents and Broadcast Receivers

<table border="0" cellspacing="0">
<tr>
<td width="20%">[[Android Implicit Intents – A Worked Example|Previous]]<td align="center">[[Android 4 App Development Essentials|Table of Contents]]<td width="20%" align="right">[[A Basic Overview of Android Threads and Thread handlers|Next]]</td>
<tr>
<td width="20%">Android Implicit Intents – A Worked Example<td align="center"><td width="20%" align="right">A Basic Overview of Android Threads and Thread handlers</td>
</table>
<hr>


<htmlet>android44</htmlet>


In addition to providing a mechanism for launching application activities, intents are also used as a way to broadcast system wide messages to other components on the system. This involves the implementation of Broadcast Intents and Broadcast Receivers, both of which are the topic of this chapter.

== An Overview of Broadcast Intents ==

Broadcast intents are Intent objects that are broadcast via a call to the sendBroadcast(), sendStickyBroadcast() or sendOrderedBroadcast() methods of the Activity class (the latter being used when results are required from the broadcast). In addition to providing a messaging and event system between application components, broadcast intents are also used by the Android system to notify interested applications about key system events (such as the external power supply or headphones being connected or disconnected). 

When a broadcast intent is created, it must include an action string in addition to optional data and a category string. As with standard intents, data is added to a broadcast intent using key-value pairs in conjunction with the putExtra() method of the intent object. The optional category string may be assigned to a broadcast intent via a call to the addCategory() method.

The action string, which identifies the broadcast event, must be unique and typically uses the application’s Java package name syntax. For example, the following code fragment creates and sends a broadcast intent including a unique action string and data:

<pre>
Intent intent = new Intent();
intent.setAction("com.example.Broadcast");
intent.putExtra("HighScore", 1000);
sendBroadcast(intent);
</pre>

The above code would successfully launch the corresponding broadcast receiver on a device running  an Android version earlier than 3.0. On more recent versions of Android, however, the intent would not be received by the broadcast receiver. This is because Android 3.0 introduced a launch control security measure that prevents components of stopped applications from being launched via an intent. An application is considered to be in a stopped state if the application has either just been installed and not previously launched, or been manually stopped by the user using the application manager on the device. To get around this, however, a flag can be added to the intent before it is sent to indicate that the intent is to be allowed to start a component of a stopped application. This flag is FLAG_INCLUDE_STOPPED_PACKAGES and would be used as outlined in the following adaptation of the previous code fragment:

<pre>
Intent intent = new Intent();
intent.addFlags(Intent.FLAG_INCLUDE_STOPPED_PACKAGES);
intent.setAction("com.example.Broadcast");
intent.putExtra("HighScore", 1000);
sendBroadcast(intent);
</pre>

== An Overview of Broadcast Receivers ==

An application listens for specific broadcast intents by registering a broadcast receiver. Broadcast receivers are implemented by extending the Android BroadcastReceiver class and overriding the onReceive() method. The broadcast receiver may then be registered, either within code (for example within an activity), or within a manifest file. Part of the registration implementation involves the creation of intent filters to indicate the specific broadcast intents the receiver is required to listen for. This is achieved by referencing the action string of the broadcast intent. When a matching broadcast is detected, the onReceive() method of the broadcast receiver is called, at which point the method has 5 seconds within which to perform any necessary tasks before returning. It is important to note that a broadcast receiver does not need to be running all the time. In the event that a matching intent is detected, the Android runtime system will automatically start up the broadcast receiver before calling the onReceive() method.

The following code outlines a template Broadcast Receiver subclass:

<pre>
package com.example.BroadcastDetector;

import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;

public class MyReceiver extends BroadcastReceiver {
	
	@Override
	public void onReceive(Context context, Intent intent) {
		 // Implement code here to be performed when 
            // broadcast is detected
	}
}
</pre>

When registering a broadcast receiver within a manifest file, a <receiver> entry must be added containing one or more intent filters, each containing the action string of the broadcast intent for which the receiver is required to listen.

The following example manifest file registers the above example broadcast receiver to listen for broadcast intents containing an action string of com.example.Broadcast:

<pre>
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.BroadcastDetector"
    android:versionCode="1"
    android:versionName="1.0" >

    <uses-sdk android:minSdkVersion="10" />

    <application
        android:icon="@drawable/ic_launcher"
        android:label="@string/app_name" >
        <receiver android:name="MyReceiver" >
            <intent-filter>
                <action android:name="com.example.Broadcast" >
                    </action>
            </intent-filter>
        </receiver>
    </application>
</manifest>
</pre>

The same effect can be achieved by registering the broadcast receiver in code using the registerReceiver() method of the Activity class together with an appropriately configured IntentFilter object:

<pre>
IntentFilter filter = new IntentFilter("com.example.Broadcast");

MyReceiver receiver = new MyReceiver();
registerReceiver(receiver, filter);
</pre>

When a broadcast receiver registered in code is no longer required, it may be unregistered via a call to the unregisterReceiver() method of the activity class, passing through a reference to the receiver object as an argument. For example, the following code will unregister the above broadcast receiver:

<pre>
unregisterReceiver(receiver);
</pre>

It is important to keep in mind that some system broadcast intents can only be detected by a broadcast receiver if it is registered in code rather than in the manifest file. Check the Android Intent class documentation for a detailed overview of the system broadcast intents and corresponding requirements online at:

[http://developer.android.com/reference/android/content/Intent.html http://developer.android.com/reference/android/content/Intent.html]

== Obtaining Results from a Broadcast ==

When a broadcast intent is sent using the sendBroadcast() method, there is no way for the initiating activity to receive results from any broadcast receivers that pick up the broadcast. In the event that return results are required, it is necessary to use the sendOrderedBroadcast() method instead. When a broadcast intent is sent using this method, it is delivered in sequential order to each broadcast receiver with a registered interest. 

The sendOrderedBroadcast() method is called with a number of arguments including a reference to another broadcast receiver (known as the result receiver) which is to be notified when all other broadcast receivers have handled the intent, together with a set of data references into which those receivers can place result data. When all broadcast receivers have been given the opportunity to handle the broadcast, the onReceive() method of the result receiver is called and passed the result data.

<htmlet>android44</htmlet>

== Sticky Broadcast Intents ==

By default, broadcast intents disappear once they have been sent and handled by any interested broadcast receivers. A broadcast intent can, however, be defined as being “sticky”. A sticky intent, and the data contained therein, remains present in the system after it has completed. The data stored within a sticky broadcast intent can be obtained via the return value of a call to the registerReceiver() method, using the usual arguments (references to the broadcast receiver and intent filter object). Many of the Android system broadcasts are sticky, a prime example being those broadcasts relating to battery level status.

A sticky broadcast may be removed at anytime via a call to the removeStickyBroadcast() method, passing through as an argument a reference to the broadcast intent to be removed.

== The Broadcast Intent Example ==

The remainder of this chapter will work through the creation of an example of broadcast intents in action. In the first instance, a simple application will be created for the purpose of issuing a custom broadcast intent. A corresponding broadcast receiver will then be created that will display a message on the display of the device when the broadcast is detected. Finally, the broadcast receiver will be modified to detect the system notification of external power being disconnected from the device.

== Creating the Example Application ==

The first step in this exercise is to create an application, the purpose of which is to send a custom broadcast intent. 

Within the Eclipse environment, create a new Android Application project. Name the project SendBroadcast, with the appropriate package name and SDK selections.

Request the creation of a blank activity and the use of the default launcher icons. On the New Blank Activity screen of the New Android Application wizard, set the Activity Name to SendBroadcastActivity and the Layout and Fragment to activity_send_broadcast and fragment_send_broadcast respectively.

Click Finish to create the new project.

Once the new project has been created, locate and load the fragment_send_broadcast.xml layout file and either in the Graphical Layout tool or XML editor replace the TextView object with a Button view. Move the button to the center of the display and change the text so that it reads “Send Broadcast”. Right-click on the button in the Graphical Layout tool and select the Other Properties -> All by Name -> onClick… menu option and enter the method name broadcastIntent into the resulting dialog.

== Creating and Sending the Broadcast Intent ==

Having created the framework for the SendBroadcast application, it is now time to implement the code to send the broadcast intent. This involves implementing the broadcastIntent() method specified previously as the onClick target of the Button view in the user interface. Locate and double click on the SendBroadcastActivity.java file and modify it to add the code to create and send the broadcast intent. Once modified, the source code for this class should read as follows:

<pre>
package com.example.sendbroadcast;

import android.app.Activity;
import android.app.ActionBar;
import android.app.Fragment;
import android.os.Bundle;
import android.view.LayoutInflater;
import android.view.Menu;
import android.view.MenuItem;
import android.view.View;
import android.view.ViewGroup;
import android.os.Build;
import android.content.Intent;

public class SendBroadcastActivity extends Activity {
.
.
.	
      public void broadcastIntent(View view)
      {
          Intent intent = new Intent();
          intent.setAction("com.example.SendBroadcast");
          intent.addFlags(Intent.FLAG_INCLUDE_STOPPED_PACKAGES);
          sendBroadcast(intent);
      }
.
.
.
}
</pre>

Note that, in this instance, the action string for the intent is com.example.SendBroadcast. When the broadcast receiver class is created in later sections of this chapter, it is essential that the intent filter declaration match this action string.

This concludes the creation of the application to send the broadcast intent. All that remains is to build a matching broadcast receiver.

== Creating the Broadcast Receiver ==

In order to create the broadcast receiver, a new class needs to be created which subclasses the BroadcastReceiver superclass. Create a new project named BroadcastReceiver with an appropriate package name, this time switching off the Create Activity option in the Configure Project screen.

Add a new class to the project by right-clicking on the BroadcastReceiver project name in the Package Explorer panel and selecting the New -> Class menu option. In the Package: field, name the package com.example.broadcastreceiver. Name the class MyReceiver and enter or select android.content.BroadcastReceiver as the superclass and click on Finish to create the new class.

Navigate to the new MyReceiver.java file and double click on it to load it into an editing panel where it should read as follows:

<pre>
package com.example.broadcastreceiver;

import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;

public class MyReceiver extends BroadcastReceiver {

	@Override
	public void onReceive(Context arg0, Intent arg1) {
		// TODO Auto-generated method stub

	}

}
</pre>

As can be seen in the code, Eclipse has already auto-generated for us the onReceive() method which will be called when a matching broadcast intent is detected. This needs to be modified to display a message to the user using the Toast class. The argument names (arg0 and arg1) should also be changed to names that are more meaningful:

<pre>
package com.example.broadcastreceiver;

import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;
import android.widget.Toast;

public class MyReceiver extends BroadcastReceiver {

	@Override
	public void onReceive(Context context, Intent intent) {
		// TODO Auto-generated method stub
		Toast.makeText(context, "Broadcast Intent Detected.",
				Toast.LENGTH_LONG).show();
	}
}
</pre>

The code for the broadcast receiver is now complete. In order for the receiver to listen for the correct broadcast intents, however, a change to the manifest file is required.

== Configuring a Broadcast Receiver in the Manifest File ==

In common with other Android projects, BroadcastReceiver has associated with it a manifest file named AndroidManifest.xml. At present, this file probably contains the following XML structure:

<pre>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.broadcastreceiver"
    android:versionCode="1"
    android:versionName="1.0" >

    <uses-sdk
        android:minSdkVersion="19"
        android:targetSdkVersion="19" />

    <application
        android:allowBackup="true"
        android:icon="@drawable/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/AppTheme" >
    </application>
</manifest>
</pre>

This file now needs to be modified to publicize the presence of the broadcast receiver and to add an intent filter to specify the broadcast intents in which the receiver is interested. This involves adding a <receiver> section containing an <intent-filter> element configured for the custom action string:

<pre>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.broadcastreceiver"
    android:versionCode="1"
    android:versionName="1.0" >

    <uses-sdk
        android:minSdkVersion="19"
        android:targetSdkVersion="19" />

    <application
        android:allowBackup="true"
        android:icon="@drawable/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/AppTheme" >
        <receiver android:name="MyReceiver" >
            <intent-filter>
                <action android:name="com.example.SendBroadcast" >
                </action>
            </intent-filter>
        </receiver>
    </application>

</manifest>
</pre>

With the manifest file completed, the broadcast example is ready to be tested.

== Testing the Broadcast Example ==

In order to test the broadcast sender and receiver, begin by running the BroadcastReceiver application a physical Android device, or on an AVD emulator instance. The receiver will install silently on the device with nothing appearing on the display. A successful installation will be reflected by output to the Eclipse console similar to the following:

<pre>
[2012-07-05 14:40:29 - BroadcastReceiver] Uploading BroadcastReceiver.apk onto device '74CE000600000001'
[2012-07-05 14:40:29 - BroadcastReceiver] Installing BroadcastReceiver.apk...
[2012-07-05 14:40:30 - BroadcastReceiver] Success!
[2012-07-05 14:40:30 - BroadcastReceiver] \BroadcastReceiver\bin\BroadcastReceiver.apk installed on device
[2012-07-05 14:40:30 - BroadcastReceiver] Done!
</pre>

Once the receiver is installed, run the SendBroadcast application on the same device or AVD and wait for it to appear on the display. Once running, touch the button, at which point the toast message reading “Broadcast Intent Detected.” should pop up for a few seconds before fading away.

In the event that the toast message does not appear, double check that the BroadcastReceiver application installed correctly and that the intent filter in the manifest file matches the action string used when the intent was broadcast.

== Listening for System Broadcasts ==

The final stage of this example is to modify the intent filter for BroadcastReceiver to listen also for the system intent that is broadcast when external power is disconnected from the device. The action that the receiver needs to be listening for in this context is android.intent.action.ACTION_POWER_DISCONNECTED. The modified manifest file should, therefore, now read as follows:

<pre>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.broadcastreceiver"
    android:versionCode="1"
    android:versionName="1.0" >

    <uses-sdk
        android:minSdkVersion="19"
        android:targetSdkVersion="19" />

    <application
        android:allowBackup="true"
        android:icon="@drawable/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/AppTheme" >
        <receiver android:name="MyReceiver" >
            <intent-filter>
                <action android:name="com.example.SendBroadcast" >
                </action>
<action android:name="android.intent.action.ACTION_POWER_DISCONNECTED" >          
                </action>
            </intent-filter>
        </receiver>
    </application>
</manifest>
</pre>

Since the onReceive() method is now going to be listening for two types of broadcast intent, it is worthwhile modifying the code so that the action string of the current intent is also displayed in the toast message. This string can be obtained via a call to the getAction() method of the intent object passed as an argument to the onReceive() method:

<pre>
public void onReceive(Context context, Intent intent) {
		// TODO Auto-generated method stub
		
		String message = "Broadcast intent detected " 
                      + intent.getAction();
		
		Toast.makeText(context, message,
				Toast.LENGTH_LONG).show();
}
</pre>

Test the receiver by re-installing the modified BroadcastReceiver package. Touching the button in the SendBroadcast application should now result in a new message containing the custom action string:

<pre>
Broadcast intent detected com.example.SendBroadcast
</pre>

Next, remove the USB connector that is currently supplying power to the device, at which point the receiver should report the following in the toast message:

<pre>
Broadcast intent detected android.intent.action.ACTION_POWER_DISCONNECTED
</pre>

== Summary ==

Broadcast intents are a mechanism by which an intent can be issued for consumption by multiple components on an Android system. Broadcasts are detected by registering a Broadcast Receiver, which, in turn, is configured to listen for intents that match particular action strings. In general, broadcast receivers remain dormant until woken up by the system when a matching intent is detected. Broadcast intents are also used by the Android system to issue notifications of events such as a low battery warning or the connection or disconnection of external power to the device.

In addition to providing an overview of Broadcast intents and receivers, this chapter has also worked through an example of sending broadcast intents and the implementation of a broadcast receiver to listen for both custom and system broadcast intents.


<htmlet>android44</htmlet>


<htmlet>ezoicbottom</htmlet>
<hr>
<table border="0" cellspacing="0">
<tr>
<td width="20%">[[Android Implicit Intents – A Worked Example|Previous]]<td align="center">[[Android 4 App Development Essentials|Table of Contents]]<td width="20%" align="right">[[A Basic Overview of Android Threads and Thread handlers|Next]]</td>
<tr>
<td width="20%">Android Implicit Intents – A Worked Example<td align="center"><td width="20%" align="right">A Basic Overview of Android Threads and Thread handlers</td>
</table>