Helper for the common pattern of implementing a BroadcastReceiver
that receives a device wakeup event and then passes the work off
to a Service, while ensuring that the
device does not go back to sleep during the transition.

Class Overview

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 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
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 cannot 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 run 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 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
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.

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 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 ICE_CREAM_SANDWICH, you
can also safely restrict the broadcast to a single application with
Intent.setPackage

None of these issues exist when using
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.

Receiver Lifecycle

A 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 a 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.

Process Lifecycle

A process that is currently executing a 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 a BroadcastReceiver to keep
the containing process active for the entire time of your operation.

Returns true if the receiver is currently processing the initial
value of a sticky broadcast -- that is, the value that was last
broadcast and is currently held in the sticky cache, so this is
not directly the result of a broadcast right now.

Returns

This can be called by an application in onReceive(Context, Intent) to allow
it to keep the broadcast active after returning from that function.
This does not change the expectation of being relatively
responsive to the broadcast (finishing it within 10s), but does allow
the implementation to move work related to it over to another thread
to avoid glitching the main UI thread due to disk IO.

public
final
boolean
isInitialStickyBroadcast()

Returns true if the receiver is currently processing the initial
value of a sticky broadcast -- that is, the value that was last
broadcast and is currently held in the sticky cache, so this is
not directly the result of a broadcast right now.

public
final
boolean
isOrderedBroadcast()

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. This method
is always called within the main thread of its process, unless you
explicitly asked for it to be scheduled on a different thread using
registerReceiver(BroadcastReceiver, IntentFilter, String, android.os.Handler). When it runs on the main
thread 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
startService(Intent) instead of
bindService(Intent, ServiceConnection, int). If you wish
to interact with a service that is already running, you can use
peekService(Context, Intent).

The Intent filters used in registerReceiver(BroadcastReceiver, IntentFilter)
and in application manifests are not guaranteed to be exclusive. They
are hints to the operating system about how to find suitable recipients. It is
possible for senders to force delivery to specific recipients, bypassing filter
resolution. For this reason, onReceive()
implementations should respond only to known actions, ignoring any unexpected
Intents that they may receive.

public
final
void
setDebugUnregister(boolean debug)

Control inclusion of debugging help for mismatched
calls to Context.registerReceiver().
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.

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.

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 RESULT_CANCELED and
RESULT_OK constants, though the
actual meaning of this value is ultimately up to the broadcaster.

Parameters

See Also

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).