java.lang.Object | ||
android.content.BroadcastReceiver |
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.
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:
An BroadcastReceiver object is only valid for the duration of the call to onReceive(Context, 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(Context, 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.
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
sendBroadcast(Intent, String) or
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
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.
A process that is currently executing an BroadcastReceiver (that is, currently running the code in its onReceive(Context, 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.
BroadcastReceiver() |
final | void | abortBroadcast() | ||||
Sets the flag indicating that this receiver should abort the current broadcast. | ||||||
final | void | clearAbortBroadcast() | ||||
Clears the flag indicating that this receiver should abort the current broadcast. | ||||||
final | boolean | getAbortBroadcast() | ||||
Returns the flag indicating whether or not this receiver should abort the current broadcast. | ||||||
final | boolean | getDebugUnregister() | ||||
Return the last value given to setDebugUnregister(boolean). | ||||||
final | int | getResultCode() | ||||
Retrieve the current result code, as set by the previous receiver. | ||||||
final | String | getResultData() | ||||
Retrieve the current result data, as set by the previous receiver. | ||||||
final | 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. | ||||||
final | void | setDebugUnregister(boolean debug) | ||||
Control inclusion of debugging help for mismatched calls to {@ Context#registerReceiver(BroadcastReceiver, IntentFilter) Context.registerReceiver()}. | ||||||
final | void | setOrderedHint(boolean isOrdered) | ||||
For internal use, sets the hint about whether this BroadcastReceiver is running in ordered mode. | ||||||
final | void | setResult(int code, String data, Bundle extras) | ||||
final | void | setResultCode(int code) | ||||
Change the current result code of this broadcast. | ||||||
final | void | setResultData(String data) | ||||
Change the current result data of this broadcast. | ||||||
final | void | setResultExtras(Bundle extras) | ||||
Change the current result extras of this broadcast. |
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. |
---|
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 startService(Intent) instead of bindService(Intent, ServiceConnection, int).
context | The Context in which the receiver is running. |
---|---|
intent | The Intent being received. |
code | The new result code. |
---|
data | The new result data; may be null. |
---|
extras | The new extra data map; may be null. |
---|
Copyright 2007 Google Inc. | Build 0.9_r1-98467 - 14 Aug 2008 18:48 |