In addition to providing a mechanism for launching application activities, intents are also used 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, 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)Code language: Kotlin (kotlin)

The above code would successfully launch the corresponding broadcast receiver on an Android device earlier than 3.0. On more recent versions of Android, however, the broadcast receiver would not receive the intent. 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)Code language: Kotlin (kotlin)

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 within code (for example, within an activity) or 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 to perform any necessary tasks before returning. It is important to note that a broadcast receiver does not need to run continuously. If a matching intent is detected, the Android runtime system automatically starts 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")
    }
}Code language: Kotlin (kotlin)

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>Code language: HTML, XML (xml)

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>Code language: HTML, XML (xml)

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)Code language: Kotlin (kotlin)

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)Code language: Kotlin (kotlin)

It is important to remember 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:

https://developer.android.com/reference/android/content/Intent

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. If 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 sequentially to each broadcast receiver with a registered interest.

The sendOrderedBroadcast() method is called several 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 interested broadcast receivers. A broadcast intent can, however, be defined as being “sticky”. A sticky intent and the data contained therein remain 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 creating an Android Studio-based example of broadcast intents in action. In the first instance, a simple application will be created to issue a custom broadcast intent. A corresponding broadcast receiver will then be created to 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

Select the New Project option from the welcome screen and, within the resulting new project dialog, choose the Empty Views Activity template before clicking on the Next button.

Enter SendBroadcast into the Name field and specify com.ebookfrenzy.sendbroadcast as the package name. Before clicking on the Finish button, change the Minimum API level setting to API 26: Android 8.0 (Oreo) and the Language menu to Kotlin.

Once the new project has been created, locate and load the activity_main.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 MainActivity.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 androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.content.Intent
import android.view.View
 
class MainActivity : 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)
    }
}Code language: Kotlin (kotlin)

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, the intent filter declaration must 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

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 -> kotlin+java and right-click on the package name. Select the New -> Other -> Broadcast Receiver menu option from the resulting menu, name the class MyReceiver, and ensure 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. 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) {
        // This method is called when the BroadcastReceiver is receiving an Intent broadcast.
        TODO("MyReceiver.onReceive() is not implemented")
    }
}Code language: Kotlin (kotlin)

As seen in the code, Android Studio generated a template for the new class and a stub for the onReceive() method. Some 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()
    }
}Code language: Kotlin (kotlin)

The code for the broadcast receiver is now complete.

Registering the Broadcast Receiver

The project 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 MainActivity.kt file to create an intent filter and to register the receiver:

package com.ebookfrenzy.sendbroadcast
 
import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.content.Intent
import android.view.View
import android.content.IntentFilter
import android.content.BroadcastReceiver
 
class MainActivity : AppCompatActivity() {
 
    private 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)
    }
.
.
}Code language: Kotlin (kotlin)

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

override fun onDestroy() {
    super.onDestroy()
    unregisterReceiver(receiver)
}Code language: Kotlin (kotlin)

Testing the Broadcast Example

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 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 configureReceiver() method in the MainActivity.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)
}Code language: Kotlin (kotlin)

Since the onReceive() method in the MyReceiver.kt file will now 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()
}Code language: Kotlin (kotlin)

Test the receiver by re-installing the modified SendBroadcast 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.sendbroadcastCode language: plaintext (plaintext)

Next, remove the USB connector currently supplying power to the Android device, at which point the receiver should report the following in the toast message (the message may be truncated on devices in portrait orientation). 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_DISCONNECTEDCode language: plaintext (plaintext)

To avoid this message appearing whenever the device is disconnected from a power supply, launch the Settings app and select the Apps option. Select the SendBroadcast app from the resulting list and tap 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. The Android system also uses broadcast intents 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 implementing a broadcast receiver to listen for both custom and system broadcast intents.