Android Broadcast Intents and Broadcast Receivers

From Techotopia
Revision as of 18:01, 6 July 2012 by Neil (Talk | contribs) (New page: 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...)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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 topics of this chapter.


Contents


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 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 Java package name syntax. For example, the following code fragment creates and sends a broadcast intent including a unique action string and data:

Intent intent = new Intent();
intent.setAction("com.ebookfrenzy.Broadcast");
intent.putExtra("HighScore", 1000);
sendBroadcast(intent);

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 start up the broadcast receiver before calling the onReceive() method.

The following code outlines a template Broadcast Receiver subclass:

package com.ebookfrenzy.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
	}
}

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 strings of the broadcast intents 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.ebookfrenzy.Broadcast:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.ebookfrenzy.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.ebookfrenzy.Broadcast" >
                    </action>
            </intent-filter>
        </receiver>
    </application>
</manifest>

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:

IntentFilter filter = new IntentFilter("com.ebookfrenzy.Broadcast");

MyReceiver receiver = new MyReceiver();
registerReceiver(receiver, filter);

When a broadcast receiver registered in code is no longer required it may 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:

unRegisterReceiver(receiver);

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


Obtaining Results from a Broadcast

When an 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 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.

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 Kindle Fire device when the broadcast is detected. Finally, the broadcast receiver will be modified to detect the system notification of external power being disconnected from 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. Start Eclipse and create a new project named SendBroadcast with the appropriate SDK selection made and the Create Activity option selected. When prompted, enter an appropriate package name, or use com.example.SendBroadcast.

Once the new project has been created, locate and load the main.xml layout file and either in the Graphical Layout tool or XML editor replace the TextView object with a Button view. Right-click (Ctrl-click on Mac OS X) 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 creating 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 specificied 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:

package com.ebookfrenzy.SendBroadcast;

import android.app.Activity;
import android.content.Intent;
import android.os.Bundle;
import android.view.View;

public class SendBroadcastActivity extends Activity {
    /** Called when the activity is first created. */
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
    }
    
    public void broadcastIntent(View view)
    {
    	  Intent intent = new Intent();
        intent.setAction("com.ebookfrenzy.SendBroadcast");
        sendBroadcast(intent);
    }
    
}

Note that, in this instance, the action string for the intent is com.ebookfrenzy.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 ReceiveBroadcast with an appropriate package name, this time switching off the Create Activity option.

Add a new class to the project by selecting the ReceiveBroadcast project name in the Project Explorer panel and selecting the File -> New -> Class menu option. Use the Browse… button to the right of the Package Name field to select the package name of this project and then name the class MyReceiver. 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:

package com.ebookfrenzy.ReceiveBroadcast;

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

	}

}

As can been 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 more meaningful names:

package com.ebookfrenzy.ReceiveBroadcast;

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();
	}

}

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, ReceiveBroadcast has associated with it a manifest file named AndroidManifest.xml. At present this file probably contains the following XML structure:

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

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

    <application
        android:icon="@drawable/ic_launcher"
        android:label="@string/app_name" >
        <activity
            android:label="@string/app_name"
            android:name=".ReceiveBroadcastActivity" >
            <intent-filter >
              <action android:name="android.intent.action.MAIN" />
              <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>

</manifest>

This file now needs to be modified to publicize the presence of the broadcast receiver and to add an intent filter to specify which broadcast intents the receiver is interested in. Since this project does not include an activity, the <activity> section of the file needs to be replaced by a <receiver> section containing an <intent-filter> configured for the custom action string:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.ebookfrenzy.ReceiveBroadcast"
    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.ebookfrenzy.SendBroadcast" >
                </action>
            </intent-filter>
        </receiver>
    </application>
</manifest>

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 ReceiveBroadcast application a physical Kindle Fire device, or on an AVD 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:

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

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 ReceiveBroadcast 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 ReceiveBroadcast to also listen 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:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.ebookfrenzy.ReceiveBroadcast"
    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.ebookfrenzy.SendBroadcast" >
                </action>
                <action android:name="android.intent.action.ACTION_POWER_DISCONNECTED" >          
                </action>
            </intent-filter>
        </receiver>
    </application>

</manifest>

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:

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();
}

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

Broadcast intent detected com.ebookfrenzy.SendBroadcast

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

Broadcast intent detected android.intent.action.ACTION_POWER_DISCONNECTED

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.