This lesson teaches you to
You should also read
- Intents and Intent Filters
- The section Broadcast receivers in the Application Components API guide.
Try it out
ThreadSample.zip
This lesson shows you how to report the status of a work request run in a background service
to the component that sent the request. This allows you, for example, to report the status of
the request in an
Activity
object's UI. The recommended way to send and
receive status is to use a
LocalBroadcastManager
, which
limits broadcast
Intent
objects to components in your own app.
Report Status From an IntentService
To send the status of a work request in an
IntentService
to other
components, first create an
Intent
that contains the status in its
extended data. As an option, you can add an action and data URI to this
Intent
.
Next, send the
Intent
by calling
LocalBroadcastManager.sendBroadcast()
. This sends the
Intent
to any
component in your application that has registered to receive it.
To get an instance of
LocalBroadcastManager
, call
getInstance()
.
For example:
public final class Constants { ... // Defines a custom Intent action public static final String BROADCAST_ACTION = "com.example.android.threadsample.BROADCAST"; ... // Defines the key for the status "extra" in an Intent public static final String EXTENDED_DATA_STATUS = "com.example.android.threadsample.STATUS"; ... } public class RSSPullService extends IntentService { ... /* * Creates a new Intent containing a Uri object * BROADCAST_ACTION is a custom Intent action */ Intent localIntent = new Intent(Constants.BROADCAST_ACTION) // Puts the status into the Intent .putExtra(Constants.EXTENDED_DATA_STATUS, status); // Broadcasts the Intent to receivers in this app. LocalBroadcastManager.getInstance(this).sendBroadcast(localIntent); ... }
The next step is to handle the incoming broadcast
Intent
objects in
the component that sent the original work request.
Receive Status Broadcasts from an IntentService
To receive broadcast
Intent
objects, use a subclass of
BroadcastReceiver
. In the subclass, implement the
BroadcastReceiver.onReceive()
callback
method, which
LocalBroadcastManager
invokes when it receives
an
Intent
.
LocalBroadcastManager
passes the incoming
Intent
to
BroadcastReceiver.onReceive()
.
For example:
// Broadcast receiver for receiving status updates from the IntentService private class ResponseReceiver extends BroadcastReceiver { // Prevents instantiation private DownloadStateReceiver() { } // Called when the BroadcastReceiver gets an Intent it's registered to receive @ public void onReceive(Context context, Intent intent) { ... /* * Handle Intents here. */ ... } }
Once you've defined the
BroadcastReceiver
, you can define filters
for it that match specific actions, categories, and data. To do this, create
an
IntentFilter
. This first snippet shows how to define the filter:
// Class that displays photos public class DisplayActivity extends FragmentActivity { ... public void onCreate(Bundle stateBundle) { ... super.onCreate(stateBundle); ... // The filter's action is BROADCAST_ACTION IntentFilter mStatusIntentFilter = new IntentFilter( Constants.BROADCAST_ACTION); // Adds a data filter for the HTTP scheme mStatusIntentFilter.addDataScheme("http"); ...
To register the
BroadcastReceiver
and the
IntentFilter
with the system, get an instance of
LocalBroadcastManager
and call its
registerReceiver()
method. This next snippet shows how to register the
BroadcastReceiver
and its
IntentFilter
:
// Instantiates a new DownloadStateReceiver DownloadStateReceiver mDownloadStateReceiver = new DownloadStateReceiver(); // Registers the DownloadStateReceiver and its intent filters LocalBroadcastManager.getInstance(this).registerReceiver( mDownloadStateReceiver, mStatusIntentFilter); ...
A single
BroadcastReceiver
can handle more than one type of broadcast
Intent
object, each with its own action. This feature allows you to
run different code for each action, without having to define a separate
BroadcastReceiver
for each action. To define another
IntentFilter
for the same
BroadcastReceiver
, create the
IntentFilter
and
repeat the call to
registerReceiver()
.
For example:
/* * Instantiates a new action filter. * No data filter is needed. */ statusIntentFilter = new IntentFilter(Constants.ACTION_ZOOM_IMAGE); ... // Registers the receiver with the new filter LocalBroadcastManager.getInstance(getActivity()).registerReceiver( mDownloadStateReceiver, mIntentFilter);
Sending an broadcast
Intent
doesn't start or resume an
Activity
. The
BroadcastReceiver
for an
Activity
receives and processes
Intent
objects even
when your app is in the background, but doesn't force your app to the foreground. If you
want to notify the user about an event that happened in the background while your app was not
visible, use a
Notification
.
Never
start an
Activity
in response to an incoming broadcast
Intent
.