android.content
Class BroadcastReceiver

java.lang.Object
  android.content.BroadcastReceiver

Direct Known Subclasses:

AccountMonitor, SyncManager.SyncAlarmIntentReceiver, SyncManager.SyncPollAlarmReceiver

public abstract class BroadcastReceiver
extends Object

Base class for code that will receive intents sent by sendBroadcast(). You can either dynamically register an instance of this class with Context.registerReceiver() or statically publish an implementation through the <receiver> tag in your AndroidManifest.xml. Note: If registering a receiver in your Activity.onResume() implementation, you should unregister it in Activity.onPause(). (You won't receive intents when paused, and this will cut down on unnecessary system overhead). Do not unregister in Activity.onSaveInstanceState(), because this won't be called if the user moves back in the history stack.

There are two major classes of broadcasts that can be received:

• Normal broadcasts (sent with Context.sendBroadcast) are completely asynchronous. All receivers of the broadcast are run, in an undefined order, often at the same time. This is more efficient, but means that receivers can not use the result or abort APIs included here.
• Ordered broadcasts (sent with Context.sendOrderedBroadcast) are delivered to one receiver at a time. As each receiver executes in turn, it can propagate a result to the next receiver, or it can completely abort the broadcast so that it won't be passed to other receivers. The order receivers runs in can be controlled with the android:priority attribute of the matching intent-filter; receivers with the same priority will be run in an arbitrary order.

Even in the case of normal broadcasts, the system may in some situations revert to delivering the broadcast one receiver at a time. In particular, for receivers that may require the creation of a process, only one will be run at a time to avoid overloading the system with new processes. In this situation, however, the non-ordered semantics hold: these receivers can not return results or abort their broadcast.

Note that, although the Intent class is used for sending and receiving these broadcasts, the Intent broadcast mechanism here is completely separate from Intents that are used to start Activities with Context.startActivity(). There is no way for an BroadcastReceiver to see or capture Intents used with startActivity(); likewise, when you broadcast an Intent, you will never find or start an Activity. These two operations are semantically very different: starting an Activity with an Intent is a foreground operation that modifies what the user is currently interacting with; broadcasting an Intent is a background operation that the user is not normally aware of.

The BroadcastReceiver class (when launched as a component through a manifest's <receiver> tag) is an important part of an application's overall lifecycle.

Topics covered here:

1. Receiver Lifecycle
2. Permissions
3. Process Lifecycle

Receiver Lifecycle

A BroadcastReceiver object is only valid for the duration of the call to onReceive(android.content.Context, android.content.Intent). Once your code returns from this function, the system considers the object to be finished and no longer active.

This has important repercussions to what you can do in an onReceive(android.content.Context, android.content.Intent) implementation: anything that requires asynchronous operation is not available, because you will need to return from the function to handle the asynchronous operation, but at that point the BroadcastReceiver is no longer active and thus the system is free to kill its process before the asynchronous operation completes.

In particular, you may not show a dialog or bind to a service from within an BroadcastReceiver. For the former, you should instead use the NotificationManager API. For the latter, you can use Context.startService() to send a command to the service.

Permissions

Access permissions can be enforced by either the sender or receiver of an Intent.

To enforce a permission when sending, you supply a non-null permission argument to Context.sendBroadcast(Intent, String) or Context.sendOrderedBroadcast(Intent, String, BroadcastReceiver, android.os.Handler, int, String, Bundle). Only receivers who have been granted this permission (by requesting it with the <uses-permission> tag in their AndroidManifest.xml) will be able to receive the broadcast.

To enforce a permission when receiving, you supply a non-null permission when registering your receiver -- either when calling Context.registerReceiver(BroadcastReceiver, IntentFilter, String, android.os.Handler) or in the static <receiver> tag in your AndroidManifest.xml. Only broadcasters who have been granted this permission (by requesting it with the <uses-permission> tag in their AndroidManifest.xml) will be able to send an Intent to the receiver.

See the Security Model document for more information on permissions and security in general.

Process Lifecycle

A process that is currently executing an BroadcastReceiver (that is, currently running the code in its onReceive(android.content.Context, android.content.Intent) method) is considered to be a foreground process and will be kept running by the system except under cases of extreme memory pressure.

Once you return from onReceive(), the BroadcastReceiver is no longer active, and its hosting process is only as important as any other application components that are running in it. This is especially important because if that process was only hosting the BroadcastReceiver (a common case for applications that the user has never or not recently interacted with), then upon returning from onReceive() the system will consider its process to be empty and aggressively kill it so that resources are available for other more important processes.

This means that for longer-running operations you will often use a Service in conjunction with an BroadcastReceiver to keep the containing process active for the entire time of your operation.

Constructor Summary

BroadcastReceiver()

Method Summary

void	abortBroadcast() Sets the flag indicating that this receiver should abort the current broadcast; only works with broadcasts sent through Context.sendOrderedBroadcast.
(package private) void	checkSynchronousHint()
void	clearAbortBroadcast() Clears the flag indicating that this receiver should abort the current broadcast.
boolean	getAbortBroadcast() Returns the flag indicating whether or not this receiver should abort the current broadcast.
boolean	getDebugUnregister() Return the last value given to setDebugUnregister(boolean).
int	getResultCode() Retrieve the current result code, as set by the previous receiver.
String	getResultData() Retrieve the current result data, as set by the previous receiver.
Bundle	getResultExtras(boolean makeMap) Retrieve the current result extra data, as set by the previous receiver.
abstract void	onReceive(Context context, Intent intent) This method is called when the BroadcastReceiver is receiving an Intent broadcast.
void	setDebugUnregister(boolean debug) Control inclusion of debugging help for mismatched calls to .
void	setOrderedHint(boolean isOrdered) For internal use, sets the hint about whether this BroadcastReceiver is running in ordered mode.
void	setResult(int code, String data, Bundle extras) Change all of the result data returned from this broadcasts; only works with broadcasts sent through Context.sendOrderedBroadcast.
void	setResultCode(int code) Change the current result code of this broadcast; only works with broadcasts sent through Context.sendOrderedBroadcast.
void	setResultData(String data) Change the current result data of this broadcast; only works with broadcasts sent through Context.sendOrderedBroadcast.
void	setResultExtras(Bundle extras) Change the current result extras of this broadcast; only works with broadcasts sent through Context.sendOrderedBroadcast.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BroadcastReceiver

public BroadcastReceiver()

Method Detail

onReceive

public abstract void onReceive(Context context,
                               Intent intent)

This method is called when the BroadcastReceiver is receiving an Intent broadcast. During this time you can use the other methods on BroadcastReceiver to view/modify the current result values. The function is normally called from the main thread of its process, so you should never perform long-running operations in it (there is a timeout of 10 seconds that the system allows before considering the receiver to be blocked and a candidate to be killed). You cannot launch a popup dialog in your implementation of onReceive().

If this BroadcastReceiver was launched through a <receiver> tag, then the object is no longer alive after returning from this function. This means you should not perform any operations that return a result to you asynchronously -- in particular, for interacting with services, you should use Context.startService(Intent) instead of Context.bindService(Intent, ServiceConnection, int).

Parameters:

context - The Context in which the receiver is running.

intent - The Intent being received.

setResultCode

public final void setResultCode(int code)

Change the current result code of this broadcast; only works with broadcasts sent through Context.sendOrderedBroadcast. Often uses the Activity Activity.RESULT_CANCELED and Activity.RESULT_OK constants, though the actual meaning of this value is ultimately up to the broadcaster.

This method does not work with non-ordered broadcasts such as those sent with Context.sendBroadcast

Parameters:

code - The new result code.

See Also:

setResult(int, String, Bundle)

getResultCode

public final int getResultCode()

Retrieve the current result code, as set by the previous receiver.

Returns:

int The current result code.

setResultData

public final void setResultData(String data)

Change the current result data of this broadcast; only works with broadcasts sent through Context.sendOrderedBroadcast. This is an arbitrary string whose interpretation is up to the broadcaster.

This method does not work with non-ordered broadcasts such as those sent with Context.sendBroadcast

Parameters:

data - The new result data; may be null.

See Also:

setResult(int, String, Bundle)

getResultData

public final String getResultData()

Retrieve the current result data, as set by the previous receiver. Often this is null.

Returns:

String The current result data; may be null.

setResultExtras

public final void setResultExtras(Bundle extras)

Change the current result extras of this broadcast; only works with broadcasts sent through Context.sendOrderedBroadcast. This is a Bundle holding arbitrary data, whose interpretation is up to the broadcaster. Can be set to null. Calling this method completely replaces the current map (if any).

This method does not work with non-ordered broadcasts such as those sent with Context.sendBroadcast

Parameters:

extras - The new extra data map; may be null.

See Also:

setResult(int, String, Bundle)

getResultExtras

public final Bundle getResultExtras(boolean makeMap)

Retrieve the current result extra data, as set by the previous receiver. Any changes you make to the returned Map will be propagated to the next receiver.

Parameters:

makeMap - If true then a new empty Map will be made for you if the current Map is null; if false you should be prepared to receive a null Map.

Returns:

Map The current extras map.

setResult

public final void setResult(int code,
                            String data,
                            Bundle extras)

Change all of the result data returned from this broadcasts; only works with broadcasts sent through Context.sendOrderedBroadcast. All current result data is replaced by the value given to this method.

This method does not work with non-ordered broadcasts such as those sent with Context.sendBroadcast

Parameters:

code - The new result code. Often uses the Activity Activity.RESULT_CANCELED and Activity.RESULT_OK constants, though the actual meaning of this value is ultimately up to the broadcaster.

data - The new result data. This is an arbitrary string whose interpretation is up to the broadcaster; may be null.

extras - The new extra data map. This is a Bundle holding arbitrary data, whose interpretation is up to the broadcaster. Can be set to null. This completely replaces the current map (if any).

getAbortBroadcast

public final boolean getAbortBroadcast()

Returns the flag indicating whether or not this receiver should abort the current broadcast.

Returns:

True if the broadcast should be aborted.

abortBroadcast

public final void abortBroadcast()

Sets the flag indicating that this receiver should abort the current broadcast; only works with broadcasts sent through Context.sendOrderedBroadcast. This will prevent any other intent receivers from receiving the broadcast. It will still call onReceive(android.content.Context, android.content.Intent) of the BroadcastReceiver that the caller of Context.sendOrderedBroadcast passed in.

This method does not work with non-ordered broadcasts such as those sent with Context.sendBroadcast

clearAbortBroadcast

public final void clearAbortBroadcast()

Clears the flag indicating that this receiver should abort the current broadcast.

setOrderedHint

public final void setOrderedHint(boolean isOrdered)

For internal use, sets the hint about whether this BroadcastReceiver is running in ordered mode.

setDebugUnregister

public final void setDebugUnregister(boolean debug)

Control inclusion of debugging help for mismatched calls to . If called with true, before given to registerReceiver(), then the callstack of the following Context.unregisterReceiver() call is retained, to be printed if a later incorrect unregister call is made. Note that doing this requires retaining information about the BroadcastReceiver for the lifetime of the app, resulting in a leak -- this should only be used for debugging.

getDebugUnregister

public final boolean getDebugUnregister()

Return the last value given to setDebugUnregister(boolean).

checkSynchronousHint

void checkSynchronousHint()