Difference between revisions of "Kotlin Android Broadcast Intents and Broadcast Receivers"

Revision as of 20:01, 30 November 2017

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

val intent = Intent()
intent.action = "com.example.Broadcast"
intent.putExtra("MyData", 1000)
sendBroadcast(intent)

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:

val intent = Intent()
intent.action = "com.example.Broadcast"
intent.putExtra("MyData", 1000)
intent.flags = Intent.FLAG_INCLUDE_STOPPED_PACKAGES
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 automatically start up the broadcast receiver before calling the onReceive() method.

The following code outlines a template Broadcast Receiver subclass:

package com.ebookfrenzy.sendbroadcast
 
import android.content.BroadcastReceiver
import android.content.Context
import android.content.Intent
 
class MyReceiver : BroadcastReceiver() {
 
    override fun onReceive(context: Context, intent: Intent) {
        // TODO: This method is called when the BroadcastReceiver is receiving
        // an Intent broadcast.
        throw UnsupportedOperationException("Not yet implemented")
    }
}

When registering a broadcast receiver within a manifest file, a <receiver> entry must be added for the receiver.

The following example manifest file registers the above example broadcast receiver:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.broadcastdetector.broadcastdetector"
    android:versionCode="1"
    android:versionName="1.0" >
 
    <uses-sdk android:minSdkVersion="17" />
 
    <application
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name" >
        <receiver android:name="MyReceiver" >
        </receiver>
    </application>
</manifest>

When running on versions of Android older than Android 8.0, the intent filters associated with a receiver can be placed within the receiver element of the manifest file as follows:

<receiver android:name="MyReceiver" >
    <intent-filter>
        <action android:name="com.example.Broadcast" >
        </action>
    </intent-filter>
</receiver>

On Android 8.0 or later, the receiver must be registered in code using the registerReceiver() method of the Activity class together with an appropriately configured IntentFilter object:

val filter = IntentFilter()
filter.addAction("com.example.Broadcast")
val receiver: MyReceiver = MyReceiver()
registerReceiver(receiver, filter)

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:

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

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 any time 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 Android Studio based 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 Android device when the broadcast is detected. Finally, the broadcast receiver will be modified to detect notification by the system that external power has been disconnected from the device.

Creating the Example Application

Launch Android Studio and create a new project, entering SendBroadcast into the Application name field and ebookfrenzy.com as the Company Domain setting before clicking on the Next button.

On the form factors screen, enable the Phone and Tablet option and set the minimum SDK setting to API 14: Android 4.0 (IceCreamSandwich). Continue to proceed through the screens, requesting the creation of an Empty Activity named SendBroadcastActivity with a corresponding layout resource file named activity_send_broadcast.

Once the new project has been created, locate and load the activity_send_broadcast.xml layout file located in the Project tool window under app -> res -> layout and, with the Layout Editor tool in Design mode, replace the TextView object with a Button view and set the text property so that it reads “Send Broadcast”. Once the text value has been set, follow the usual steps to extract the string to a resource named send_broadcast.

With the button still selected in the layout, locate the onClick property in the Attributes panel and configure it to call a method named broadcastIntent.

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.kt 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.support.v7.app.AppCompatActivity
import android.os.Bundle
import android.content.Intent
import android.view.View
 
class SendBroadcastActivity : AppCompatActivity() {
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_send_broadcast)
    }
    
    fun broadcastIntent(view: View)
    {
       val intent = Intent()
       intent.action = "com.ebookfrenzy.sendbroadcast"
       intent.flags = Intent.FLAG_INCLUDE_STOPPED_PACKAGES
       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. Within the Project tool window, navigate to app -> java and right-click on the package name. From the resulting menu, select the New -> Other -> Broadcast Receiver menu option, name the class MyReceiver and make sure the Exported and Enabled options are selected. These settings allow the Android system to launch the receiver when needed and ensure that the class can receive messages sent by other applications on the device. With the class configured, click on Finish.

Once created, Android Studio will automatically load the new MyReceiver.kt class file into the editor where it should read as follows:

package com.ebookfrenzy.sendbroadcast
 
import android.content.BroadcastReceiver
import android.content.Context
import android.content.Intent
 
class MyReceiver : BroadcastReceiver() {
 
    override fun onReceive(context: Context, intent: Intent) {
        // TODO: This method is called when the BroadcastReceiver is receiving
        // an Intent broadcast.
        throw UnsupportedOperationException("Not yet implemented")
    }
}

As can be seen in the code, Android Studio has generated a template for the new class and generated a stub for the onReceive() method. A number of changes now need to be made to the class to implement the required behavior. Remaining in the MyReceiver.kt file, therefore, modify the code so that it reads as follows:

package com.ebookfrenzy.sendbroadcast
 
import android.content.BroadcastReceiver
import android.content.Context
import android.content.Intent
import android.widget.Toast
 
class MyReceiver : BroadcastReceiver() {
 
    override fun onReceive(context: Context, intent: Intent) {
        // TODO: This method is called when the BroadcastReceiver is receiving
        // an Intent broadcast.
        throw UnsupportedOperationException("Not yet implemented")
 
        Toast.makeText(context, "Broadcast Intent Detected.",
                Toast.LENGTH_LONG).show()
    }
}

The code for the broadcast receiver is now complete.

Registering the Broadcast Receiver

The file needs to publicize the presence of the broadcast receiver and must include an intent filter to specify the broadcast intents in which the receiver is interested. When the BroadcastReceiver class was created in the previous section, Android Studio automatically added a <receiver> element to the manifest file. All that remains, therefore, is to add code within the SendBroadcastActivity.kt file to create an intent filter and to register the receiver:

package com.ebookfrenzy.sendbroadcast
 
import android.support.v7.app.AppCompatActivity
import android.os.Bundle
import android.content.Intent
import android.view.View
import android.content.IntentFilter
import android.content.BroadcastReceiver
 
class SendBroadcastActivity : AppCompatActivity() {
 
    var receiver: BroadcastReceiver? = null
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_send_broadcast)
        configureReceiver()
    }
 
    private fun configureReceiver() {
        val filter = IntentFilter()
        filter.addAction("com.ebookfrenzy.sendbroadcast")
        receiver = MyReceiver()
        registerReceiver(receiver, filter)
    }
.
.
}

It is also important to unregister the broadcast receiver when it is no longer needed:

override fun onDestroy() {
    super.onDestroy()
    unregisterReceiver(receiver)
}

Testing the Broadcast Example

In order to test the broadcast sender and receiver, run the SendBroadcast app on a 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.

Listening for System Broadcasts

The final stage of this example is to modify the intent filter for the broadcast receiver to listen also for the system intent that is broadcast when external power is disconnected from the device. That action is android.intent.action.ACTION_POWER_DISCONNECTED. Modify the onCreate() method in the SendBroadcastActivity.kt file to add this additional filter:

private fun configureReceiver() {
    val filter = IntentFilter()
    filter.addAction("com.ebookfrenzy.sendbroadcast")
    filter.addAction("android.intent.action.ACTION_POWER_DISCONNECTED")
    receiver = MyReceiver()
    registerReceiver(receiver, filter)
} 

Since the onReceive() method is now going to be listening for two types of broadcast intent, it is worthwhile to modify 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:

override fun onReceive(context: Context, intent: Intent) {
 
    val message = "Broadcast intent detected " + intent.action
    
    Toast.makeText(context, message,
            Toast.LENGTH_LONG).show()
}

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:

Broadcast intent detected com.ebookfrenzy.sendbroadcast

Next, remove the USB connector that is currently supplying power to the Android device, at which point the receiver should report the following in the toast message. If the app is running on an emulator, display the extended controls, select the Battery option and change the Charger connection setting to None.

Broadcast intent detected android.intent.action.ACTION_POWER_DISCONNECTED

To avoid this message appearing every time the device is disconnected from a power supply launch the Settings app on the device and select the Apps option. Select the BroadcastReceiver app from the resulting list and taps the Uninstall button.

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.