| Base class for code that will receive intents sent by sendBroadcast().
If you don't need to send broadcasts across applications, consider using
this class with {@link android.support.v4.content.LocalBroadcastManager} instead
of the more general facilities described below. This will give you a much
more efficient implementation (no cross-process communication needed) and allow
you to avoid thinking about any security issues related to other applications
being able to receive or send your broadcasts.
You can either dynamically register an instance of this class with
{@link Context#registerReceiver Context.registerReceiver()}
or statically publish an implementation through the
{@link android.R.styleable#AndroidManifestReceiver <receiver>}
tag in your AndroidManifest.xml.
Note:
If registering a receiver in your
{@link android.app.Activity#onResume() Activity.onResume()}
implementation, you should unregister it in
{@link android.app.Activity#onPause() Activity.onPause()}.
(You won't receive intents when paused,
and this will cut down on unnecessary system overhead). Do not unregister in
{@link android.app.Activity#onSaveInstanceState(android.os.Bundle) 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 {@link Context#sendBroadcast(Intent)
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 cannot use the result or abort
APIs included here.
- Ordered broadcasts (sent with {@link Context#sendOrderedBroadcast(Intent, String)
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 run in can be controlled with the
{@link android.R.styleable#AndroidManifestIntentFilter_priority
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 still
cannot 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
{@link Context#startActivity Context.startActivity()}.
There is no way for a 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 {@link android.R.styleable#AndroidManifestReceiver <receiver>}
tag) is an important part of an
application's overall lifecycle.
Topics covered here:
- Security
- Receiver Lifecycle
- Process Lifecycle
Developer Guides
For information about how to use this class to receive and resolve intents, read the
Intents and Intent Filters
developer guide.
Security
Receivers used with the {@link Context} APIs are by their nature a
cross-application facility, so you must consider how other applications
may be able to abuse your use of them. Some things to consider are:
The Intent namespace is global. Make sure that Intent action names and
other strings are written in a namespace you own, or else you may inadvertently
conflict with other applications.
When you use {@link Context#registerReceiver(BroadcastReceiver, IntentFilter)},
any application may send broadcasts to that registered receiver. You can
control who can send broadcasts to it through permissions described below.
When you publish a receiver in your application's manifest and specify
intent-filters for it, any other application can send broadcasts to it regardless
of the filters you specify. To prevent others from sending to it, make it
unavailable to them with android:exported="false".
When you use {@link Context#sendBroadcast(Intent)} or related methods,
normally any other application can receive these broadcasts. You can control who
can receive such broadcasts through permissions described below. Alternatively,
starting with {@link android.os.Build.VERSION_CODES#ICE_CREAM_SANDWICH}, you
can also safely restrict the broadcast to a single application with
{@link Intent#setPackage(String) Intent.setPackage}
None of these issues exist when using
{@link android.support.v4.content.LocalBroadcastManager}, since intents
broadcast it never go outside of the current process.
Access permissions can be enforced by either the sender or receiver
of a broadcast.
To enforce a permission when sending, you supply a non-null
permission argument to
{@link Context#sendBroadcast(Intent, String)} or
{@link Context#sendOrderedBroadcast(Intent, String, BroadcastReceiver, android.os.Handler, int, String, Bundle)}.
Only receivers who have been granted this permission
(by requesting it with the
{@link android.R.styleable#AndroidManifestUsesPermission <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
{@link Context#registerReceiver(BroadcastReceiver, IntentFilter, String, android.os.Handler)}
or in the static
{@link android.R.styleable#AndroidManifestReceiver <receiver>}
tag in your AndroidManifest.xml. Only broadcasters who have
been granted this permission (by requesting it with the
{@link android.R.styleable#AndroidManifestUsesPermission <uses-permission>}
tag in their AndroidManifest.xml) will be able to send an
Intent to the receiver.
See the Security and Permissions
document for more information on permissions and security in general.
Receiver Lifecycle
A BroadcastReceiver object is only valid for the duration of the call
to {@link #onReceive}. 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
{@link #onReceive} 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 a BroadcastReceiver. For the former, you should instead use the
{@link android.app.NotificationManager} API. For the latter, you can
use {@link android.content.Context#startService Context.startService()} to
send a command to the service.
Process Lifecycle
A process that is currently executing a BroadcastReceiver (that is,
currently running the code in its {@link #onReceive} 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 {@link android.app.Service} in conjunction with a BroadcastReceiver to keep
the containing process active for the entire time of your operation. | 