As well as being used in conjunction with Activites and Services Intents can also be used as broadcast Intents.
1. The Broadcast Intent Model
-
Any Application can send a broadcast Intent.
-
To receive broadcast Intents an Application must register a BroadcastReceiver.
-
An Application can register multiple BroadcastReceivers.
-
An Application can register BroadcastReceivers statically and/or dynamically.
-
A BroadcastReceiver can be registered with an associated Intent Filter.
-
The Intent Filter is used to specify which broadcast Intents the BroadcastReceiver wishes to receive.
-
A normal broadcast Intent is sent asynchronously and the ordering of its delivery to the set of BroadcastReceivers eligible to receive it is undefined.
-
An ordered broadcast Intent is delivered sequentially to each member of the set of BroadcastReceivers eligible to receive it in the order defined by the priority of the associated IntentFilters.
-
An ordered broadcast Intent can have additional data associated with it in the form of
-
a code (an int),
-
data (a String), and
-
extras (a Bundle)
-
The initial values of the additional data can be specified by the sender of the ordered broadcast Intent
-
The current values of the additional data can be read and/or replaced by each BroadcastReceiver which receives the ordered broadcast Intent
-
Any BroadcastReceiver which receives an ordered broadcast Intent can stop the sending process
-
The sender of an ordered broadcast Intent can specify that it be notified when the broadcast has completed
-
The sender of an ordered broadcast Intent can access the final values of the additional data when it is notified that the broadcast has completed.
-
A broadcast Intent can be specified to be sticky in which case it will be retained by the system after it has been sent.
-
A sticky broadcast Intent can be removed after it has been sent.
-
BroadcastReceivers dynamically registered after a sticky broadcast Intent has been sent, and not subsequently removed, will still receive it if all other the criteria for receiving it have been met.
-
A sticky broadcast Intent can be retrieved at any time after it has been sent without registering a BroadcastReceiver.
-
An Application can specify a permission when sending a normal or ordered broadcast Intent.
-
A BroadcastReceiver cannot receive a normal or ordered broadcast Intent sent with an associated permission if the Application that registered the BroadcastReceiver has not been granted that permission.
-
An Application can specify a permission when registering a BroadcastReceiver.
-
A BroadcastReceiver registered with an associated permission cannot receive any normal or ordered broadcast Intent sent by an Application which has not been granted that permission.
When used in this way Intents are effectively Events and BroadcastReceivers are Event Handlers/Listeners.
2. The BroadcastReceiver Class
The class
android.content.BroadcastReceiver
is abstract. To receive broadcast Intents a sub-class must be defined which implements the method
public abstract void onReceive(Context context, Intent intent)
It is this method which is invoked when a broadcast Intent satisfies the criteria the BroadcastReceiver was registered with.
3. Registering Broadcast Receivers Statically
An Application can declare Broadcast Receivers in its manifest (the AndroidManifest.xml file), by defining one or more
receiver
elements, as children of the
application
element.
3.1 The receiver Element
3.1.1 Attributes
3.1.1.1 The enabled Attribute
The enabled attribute is optional. If present its value can be either “true” or “false”
If the value is “true” then the System can create instances of the BroadcastReceiver and it can function normally.
If the value is “false” then the System cannot create instances of the BroadcastReceiver and it is not functional.
The default value is “true”.
If the Application itself is not enabled then the BroadcastReceiver is not functional.
3.1.1.2 The exported Attribute
The exported attribute is optional. If present its value can be either “true” or “false”.
If the value is “true” then the BroadcastReceiver can, if all other criteria are met, receive broadcast Intents from any Application.
If the value is “false” then the BroadcastReceiver can only receive broadcast Intents from the registering Application or other Applications with the same User Id even if the other specified criteria are met.
The default value is “true” if the registered BroadcastReceiver has one or more IntentFilters associated with it. Otherwise it is “false”.
3.1.1.3 The icon Attribute
The icon attribute is optional. If present it should specify a Drawable resource. This will be used by the System to visually identify the BroadcastReceiver to the User if necessary.
3.1.1.4 The label Attribute
The label attribute is optional. If present it should specify a String resource. This will be used by the System to identify the BroadcastReceiver to the User if necessary.
3.1.1.5 The name Attribute
The name attribute is mandatory. It specifies the name of the BroadcastReceiver class.
The documentation for this attribute states
This should be a fully qualified class name (such as, “com.example.project.ReportReceiver”). However, as a shorthand, if the first character of the name is a period (for example, “. ReportReceiver”), it is appended to the package name specified in the <manifest> element.
Which is true as far as it goes.
By default the Android ADT Eclipse plugin actually generates receiver elements that look like this
<receiver android:name="XperBroadcastReceiver"></receiver>
The attribute value is simply the unqualified class name and this also works.
3.1.1.6 The permission Attribute
The permission attribute is optional. If present then the BroadcastReceiver cannot receive broadcast Intents sent by Applications which have not been granted the specified permission.
3.1.1.7 The process Attribute
The process attribute is optional. If present it specifies the process in which the Systen should create the BroadcastReceiver when necessary.
3.1.2 Child Elements
The receiver element can have two child elements
intent-filter
and
meta-data
Both elements are optional. If present both elements can occur multiple times.
4. Registering And Unregistering BroadcastReceivers Dynamically
4.1 Registration
A BroadcastReceiver can be registered dynamically using an implementation of the android.content.Context
public abstract Intent registerReceiver(
BroadcastReceiver receiver,
IntentFilter filter,
String broadcastPermission,
Handler scheduler)
method.
If the broadcastPermission argument is non-null then the registered BroadcastReceiver cannot receive broadcast Intents from any Application which has not been granted the specified permission.
If the scheduler argument is non-null then the registered BroadcastReceiver’s onReceive() method will be executed in the context of the specified Handler.
If it is not necessary to specify either a permission or a Handler then an implementation of the
android.content.Context
public abstract Intent registerReceiver(
BroadcastReceiver receiver,
IntentFilter filter)
method can be used instead.
Both methods will return either a broadcast Intent which was sent in sticky mode which matches the given IntentFilter, or null. (See also).
Both methods can also be used to access a stick broadcast Intent directly.
The same BroadcastReceiver can be registered multiple times with different IntentFilters.
4.2 Unregistration
A dynamically registered BroadcastReceiver can be unregistered using an implementation of the android.content.Context
public abstract void unregisterReceiver(BroadcastReceiver receiver)
The effect of this method is undo the effects of all calls to either of the registerReceiver() methods used to register the given BroadcastReceiver.
5. BroadcastReceiver Lifecycles
The lifecycle of a BroadcastReceiver differs depending upon whether it was registered statically or dynamically.
5.1 The Static BroadcastReceiver Lifecycle
The lifecycle of a statically registered BroadcastReceiver is under the control of the System.
When a broadcast Intent is to be delivered to a statically registered BroadcastReceiver the System will
-
create the appropriate process in which to run it if necessary
-
create an instance of the BroadcastReceiver and invoke its onReceive() method
Once the onReceive() method has returned the System may stop the process used to run it.
The transient nature of a statically registered BroadcastReceiver means that its onReceive() method cannot use any functionality which is asynchronous, for example, binding to a Service.
This constraint is enforced by the implementation of the Context passed to the method at runtime. For example, its implementation of the bindService() method throws a RuntimeException.
5.2 The Dynamic BroadcastReceiver Lifecycle
The lifecycle of a dyamically registered BroadcastReceiver is under the control of the Application.
An Application can create BroadcastReceivers and register and unregister them as and when it chooses.
There are no constraints on the functionality that can be used by the implementation of the onReceive() method of a dynamically registered BroadcastReceiver.
6. BroadcastReceivers And Intent Resolution
If an Intent explicitly specifies a component then the Intent resolves to that Component if it is a BroadcastReceiver. If the specified Component is not a BroadcastReceiver it is equivalent to the case where the Intent cannot be resolved to any BroadcastReceiver(s).
Otherwise a search is made for all BroadcastReceivers with an associated IntentFilter which matches the given Intent, as defined by the IntentFilter.match() method.
If the Intent specifies a package then the search is confined to the Services in that Application package.
An Application can determine the BroadcastReceivers to which a given Intent resolves by using an implementation od the android.content.pm.PackageManager
public abstract List queryBroadcastReceivers (Intent intent, int flags)
The list is sorted in order from high to low priority as defined by the associated IntentFilters.
7. Broadcasting
A normal broadcast Intent can be sent using an implementation of the android.content.Context
public abstract void sendBroadcast(Intent intent, String receiverPermission)
method.
If the receiverPermission argument is non-null then a BroadcastReceiver cannot receive the broadcast Intent being sent unless it was declared by an Application which has been granted the given permission.
The method is asynchronous. It returns immediately, and the delivery of the broadcast Intent to the set of eligible BroadcastReceivers executes independently of the method’s caller.
If it is not necessary to specify a permission then an implementation of the android.content.Context
public abstract void sendBroadcast(Intent intent)
can be used instead.
8. Ordered Broadcasting
A simple ordered broadcast Intent can be sent using an implementation of the android.content.Context
public abstract void sendOrderedBroadcast(
Intent intent,
String receiverPermission)
method.
If the receiverPermission argument is non-null then a BroadcastReceiver cannot receive the broadcast Intent being sent unless it was declared by an Application which has been granted the given permission.
The method is asynchronous. It returns immediately, and the process of sending the ordered broadcast Intent executes independently of the method’s caller.
An implementation of the android.content.Context method
public abstract void sendOrderedBroadcast(
Intent intent,
String receiverPermission,
BroadcastReceiver resultReceiver,
Handler scheduler,
int initialCode,
String initialData,
Bundle initialExtras)
can be used to send an ordered broadcast Intent with associated data and obtain a result.
If the receiverPermission argument is non-null then the broadcast Intent being sent cannot be received by any BroadcastReceiver registered by an Application which has not been granted the specified permission.
If the resultReceiver argument is non-null it specifies a BroadcastReceiver whose onReceive() method will be invoked when the sending of the ordered broadcast Intent completes.
If the scheduler argument is non-null and the resultReceiver argument is also non-null then the onReceive() method of the BroadcastReceiver will be run in the context of the specified Handler.
The
-
initialCode
-
initialData
-
initialExtras
arguments specify the initial values of the
elements respectively of the additional data associated with the sending of the ordered broadcast Intent.
The method is asynchronous. It returns immediately, and the process of sending the ordered broadcast Intent executes independently of the method’s caller.
8.2.1 BroadcastReceivers And Ordered Broadcast Intents
The BroadcastReceiver class defines a number of methods related to ordered broadcast Intents which can be used by an implementation of the onReceive() method.
8.2.1.1 Determining The “Type” Of A Broadcast Intent
The
public final boolean isOrderedBroadcast()
method will return true if the onReceive()method has been invoked with an ordered broadcast Intent.
8.2.1.2 Getting The Ordered Broadcast Intent “Result” Data
The methods
-
public final int getResultCode()
-
public final String getResultData()
-
public final Bundle getResultExtras(boolean makeMap)</p
will return the current values of the
respectively.
If the code is not defined then the default value is -1.
If the data is not defined then the default value is null.
If the extras are not defined then the default value is null unless the makeMap argument is true in which case an empty Bundle is created and returned.
These methods can be called when the onReceive() method was not invoked on an ordered broadcast Intent and they will return the default values as above.
8.2.1.3 Setting The Ordered Broadcast Intent “Result” Data
The methods
-
public final void setResultCode(int code)
-
public final void setResultData(String data)
-
public final void setResultExtras (Bundle extras)
will set the current values of the
respectively.
Alternatively all three can be set simultaneously using the
public final void setResult(int code, String data, Bundle extras)
method.
Using any of these methods when the onReceive() method has not been invoked on an ordered broadcast Intent will result in a RuntimeException, except in one situation.
8.2.1.4 Stopping The Process Of Sending Of An Ordered Broadcast Intent
A BroadcastReceiver can stop the process of sending an ordered broadcast Intent by calling the
public final void abortBroadcast()
method.
Any BroadcastReceivers of the same priority that have not already received the Intent and all those with a lower priority than the current BroacastReceiver will not receive the Intent.
Using this method when the onReceive() method has not been invoked on an ordered broadcast Intent will result in a RuntimeException, except in one situation.
8.3 Ordered Broadcast Intent Examples
There are four BroadcastReceivers registered statically as follows
<receiver
android:name = "OrderedBroadcastReceiverOne">
<intent-filter
android:priority = "1">
<action
android:name = "xper.example.ORDERED_BROADCAST_INTENT"/>
<action
android:name = "xper.example.ORDERED_BROADCAST_INTENT_ONE"/>
<action
android:name = "xper.example.ORDERED_BROADCAST_INTENT_TWO"/>
</intent-filter>
</receiver>
<receiver
android:name = "OrderedBroadcastReceiverTwoA">
<intent-filter
android:priority = "2">
<action
android:name = "xper.example.ORDERED_BROADCAST_INTENT"/>
<action
android:name = "xper.example.ORDERED_BROADCAST_INTENT_ONE"/>
<action
android:name = "xper.example.ORDERED_BROADCAST_INTENT_TWO"/>
</intent-filter>
</receiver>
<receiver
android:name = "OrderedBroadcastReceiverTwoB">
<intent-filter
android:priority = "2">
<action
android:name = "xper.example.ORDERED_BROADCAST_INTENT"/>
<action
android:name = "xper.example.ORDERED_BROADCAST_INTENT_ONE"/>
<action
android:name = "xper.example.ORDERED_BROADCAST_INTENT_TWO"/>
</intent-filter>
</receiver>
<receiver
android:name = "OrderedBroadcastReceiverThree">
<intent-filter
android:priority = "3">
<action
android:name = "xper.example.ORDERED_BROADCAST_INTENT"/>
<action
android:name = "xper.example.ORDERED_BROADCAST_INTENT_ONE"/>
<action
android:name = "xper.example.ORDERED_BROADCAST_INTENT_TWO"/>
</intent-filter>
</receiver>
Their respective onReceive() methods are defined as follows
// OrderedBroadcastReceiverOne.onReceive()
public void onReceive(Context context, Intent intent)
{
System.out.println("One: " + intent);
System.out.println("\tgetResultCode() => " + getResultCode());
System.out.println("\tgetResultData() => " + getResultData());
setResultCode(getResultCode() + 1);
setResultData(getResultData() + ", One");
Bundle extras = getResultExtras(true);
extras.putString("One.value", "One");
setResultExtras(extras);
System.out.println("One Done");
}
...
// OrderedBroadcastReceiverTwoA.onReceive()
public void onReceive(Context context, Intent intent)
{
System.out.println("TwoA");
System.out.println(intent);
System.out.println("\tgetResultCode() => " + getResultCode());
System.out.println("\tgetResultData() => " + getResultData());
setResultCode(getResultCode() + 20);
setResultData(getResultData() + ", TwoA");
Bundle extras = getResultExtras(true);
extras.putString("TwoA.value", "TwoA");
setResultExtras(extras);
if ("xper.example.ORDERED_BROADCAST_INTENT_TWO".equals(intent.getAction()))
{
abortBroadcast();
}
System.out.println("TwoA done");
}
...
// OrderedBroadcastReceiverTwoB.onReceive()
public void onReceive(Context context, Intent intent)
{
System.out.println("TwoB");
System.out.println(intent);
System.out.println("\tgetResultCode() => " + getResultCode());
System.out.println("\tgetResultData() => " + getResultData());
setResultCode(getResultCode() + 20);
setResultData(getResultData() + ", TwoB");
Bundle extras = getResultExtras(true);
extras.putString("TwoB.value", "TwoB");
setResultExtras(extras);
if ("xper.example.ORDERED_BROADCAST_INTENT_TWO".equals(intent.getAction()))
{
abortBroadcast();
}
System.out.println("TwoB done");
}
...
// OrderedBroadcastReceiverThree.onReceive()
public void onReceive(Context context, Intent intent)
{
System.out.println("Three");
System.out.println(intent);
System.out.println("\tgetResultCode() => " + getResultCode());
System.out.println("\tgetResultData() => " + getResultData());
setResultCode(getResultCode() + 300);
setResultData(getResultData() + ", Three");
Bundle extras = getResultExtras(true);
extras.putString("Three.value", "Three");
setResultExtras(extras);
System.out.println("Three done");
}
There is a class ResultReceiver which is a sub-class of the class BroadcastReceiver.
Its onReceive() method is defined as follows.
public void onReceive(Context context, Intent intent)
{
System.out.println("ResultReceiver");
System.out.println(intent);
System.out.println("\tgetResultCode() => " + getResultCode());
System.out.println("\tgetResultData() => " + getResultData());
Bundle extras = getResultExtras(true);
System.out.println("\tBegin Extras");
for (String key : extras.keySet())
{
System.out.print("\t\t");
System.out.print(key);
System.out.print("\t=> ");
System.out.println(extras.get(key));
}
System.out.println("\tEnd Extras");
System.out.println("ResultReceiver done");
}
8.3.1 Example One
Sending an ordered broadcast Intent which is handled by all the registered BroadcastReceivers.
This example illustrates the delivery of the broadcast Intent to the BroadcastReceivers in priority order, and the use of result data
8.3.1.1 Stage One: Sending The Intent
The Intent is sent as follows
sendOrderedBroadcast(
new Intent(
"xper.example.ORDERED_BROADCAST_INTENT"),
null,
new ResultReceiver(),
null,
0,
"ExampleOne",
null);
8.3.1.2 Stage Two: The Broadcast Intent Is Received By OrderedBroadcastReceiverThree
The OrderedBroadcastReceiverThree.onReceive() method prints
Three
Intent { act=xper.example.ORDERED_BROADCAST_INTENT cmp=xper.example.three/.OrderedBroadcastReceiverThree }
getResultCode() => 0
getResultData() => ExampleOne
Three done
8.3.1.3 Stage Three: The Broadcast Intent Is Received By OrderedBroadcastReceiverTwoA
The OrderedBroadcastReceiverTwoA.onReceive() method prints
TwoA
Intent { act=xper.example.ORDERED_BROADCAST_INTENT cmp=xper.example.two.a/.OrderedBroadcastReceiverTwoA }
getResultCode() => 300
getResultData() => ExampleOne, Three
TwoA done
8.3.1.4 Stage Four: The Broadcast Intent Is Received By OrderedBroadcastReceiverTwoB
The OrderedBroadcastReceiverTwoB.onReceive() method prints
TwoB
Intent { act=xper.example.ORDERED_BROADCAST_INTENT cmp=xper.example.two.b/.OrderedBroadcastReceiverTwoB }
getResultCode() => 320
getResultData() => ExampleOne, Three, TwoA
TwoB done
8.3.1.5 Stage Five: The Broadcast Intent Is Received By OrderedBroadcastReceiverOne
The OrderedBroadcastReceiverOne.onReceive() method prints
One: Intent { act=xper.example.ORDERED_BROADCAST_INTENT cmp=xper.example.one/.OrderedBroadcastReceiverOne }
getResultCode() => 340
getResultData() => ExampleOne, Three, TwoA, TwoB
One Done
8.3.1.6 Stage Six: ResultReceiver onReceive() Method Called
The ResultReceiver.onReceive() method prints
ResultReceiver
Intent { act=xper.example.ORDERED_BROADCAST_INTENT }
getResultCode() => 341
getResultData() => ExampleOne, Three, TwoA, TwoB, One
Begin Extras
Three.value => Three
TwoB.value => TwoB
TwoA.value => TwoA
One.value => One
End Extras
ResultReceiver done
8.3.2 Example Two
Sending an ordered broadcast Intent which is handled by all the registered BroadcastRecivers but one of them stops the sending process.
8.3.2.1 Stage One: Sending The Intent
The Intent is sent as follows
sendOrderedBroadcast(
new Intent(
"xper.example.ORDERED_BROADCAST_INTENT_TWO"),
null,
new ResultReceiver(),
null,
0,
"ExampleTwo",
null);
8.3.2.2 Stage Two: The Broadcast Intent Is Received By OrderedBroadcastReceiverThree
The OrderedBroadcastReceiverThree.onReceive() method prints
Three
Intent { act=xper.example.ORDERED_BROADCAST_INTENT_TWO cmp=xper.example.three/.OrderedBroadcastReceiverThree }
getResultCode() => 0
getResultData() => ExampleTwo
Three done
8.3.2.3 Stage Three: The Broadcast Intent Is Received By OrderedBroadcastReceiverTwoA
The OrderedBroadcastReceiverTwoA.onReceive() method prints
TwoA
Intent { act=xper.example.ORDERED_BROADCAST_INTENT_TWO cmp=xper.example.two.a/.OrderedBroadcastReceiverTwoA }
getResultCode() => 300
getResultData() => ExampleTwo, Three
TwoA done
and stops the sending of the broadcast Intent.
8.3.2.4 Stage Four: ResultReceiver onReceive() Method Called
The ResultReceiver.onReceive() method prints
ResultReceiver
Intent { act=xper.example.ORDERED_BROADCAST_INTENT_TWO }
getResultCode() => 320
getResultData() => ExampleTwo, Three, TwoA
Begin Extras
Three.value => Three
TwoA.value => TwoA
End Extras
ResultReceiver done
8.3.3 Example Three
Sending an ordered broadcast Intent which is not handled by any of the registered BroadcastReecivers.
8.3.3.1 Stage One: Sending The Intent
The Intent is sent as follows
sendOrderedBroadcast(
new Intent(
"xper.example.ORDERED_BROADCAST_INTENT_FOUR"),
null,
new ResultReceiver(),
null,
-3,
"ExampleThree",
null);
8.3.3.2 Stage Two: ResultReceiver onReceive() Method Called
The ResultReceiver.onReceive() method prints
ResultReceiver
Intent { act=xper.example.ORDERED_BROADCAST_INTENT_FOUR }
getResultCode() => -3
getResultData() => ExampleThree
Begin Extras
End Extras
ResultReceiver done
9. Sticky Broadcast Intents
Both normal and ordered broadcasts can also be performed in sticky mode.
To send a broadcast Intent in sticky mode an Application must have been granted the BROADCAST_STICKY permission.
9.1 Sending A Sticky Broadcast Intent
A normal broadcast Intent can be sent in sticky mode using an implementation of the android.content.Context
public abstract void sendStickyBroadcast(Intent intent)
method.
This works in the same way as the short-form method for sending a normal broadcast Intent.
9.2 Sending A Sticky Ordered Broadcast Intent
An ordered broadcast Intent can be sent in sticky mode using an implementation of the android.content.Context
public abstract void sendStickyOrderedBroadcast(
Intent intent,
BroadcastReceiver resultReceiver,
Handler scheduler,
int initialCode,
String initialData,
Bundle initialExtras)
method.
This works in the same way as the long-form method for sending an ordered broadcast Intent.
9.3 Sticky Broadcast Intent “Replacement”
If when a broadcast Intent is sent in sticky mode it is found to match a sticky broadcast Intent sent previously then it will replace
the existing one. The Intent.filterEquals() method is used to determine whether Intents match.
One implication of this is that there can be multiple sticky broadcast Intents with, for example, the same action but different
data URIs, since these will not match.
Conversely, broadcast Intents that differ only in their extras will match.
Note also that an ordered broadcast Intent sent in sticky mode can replace a normal broadcast Intent sent in sticky mode, and vice-versa.
For example, the following
IntentFilter f = new IntentFilter("xper.sticky.BROADCAST_INTENT");
sendStickyBroadcast(
new Intent(
"xper.sticky.BROADCAST_INTENT").
putExtra(
"Type",
"Normal"));
System.out.println(registerReceiver(null, f).getStringExtra("Type"));
sendStickyOrderedBroadcast(
new Intent(
"xper.sticky.BROADCAST_INTENT").
putExtra(
"Type",
"Ordered"),
null,
null,
0,
null,
null);
System.out.println(registerReceiver(null, f).getStringExtra("Type"));
sendStickyBroadcast(
new Intent(
"xper.sticky.BROADCAST_INTENT").
putExtra(
"Type",
"Normal"));
System.out.println(registerReceiver(null, f).getStringExtra("Type"));
will print
Normal
Ordered
Normal
9.4 Accessing A Sticky Broadcast Intent Directly
Both registerReceiver() methods can be passed a receiver argument of null. As in the non-null receiver argument case if one or more sticky broadcast Intents match the supplied IntentFilter then one of them will be returned from the method.
For example, although it is not documented as such the broadcast Intent with the action
android.net.conn.CONNECTIVITY_CHANGE
is sent in sticky mode and hence is accesible in this way.
On the emulator the following code
IntentFilter f = new IntentFilter(ConnectivityManager.CONNECTIVITY_ACTION);
Intent i = registerReceiver(null, f);
System.out.println(i);
Bundle b = i.getExtras();
for (String key : b.keySet())
{
System.out.print(key);
System.out.print(" => ");
System.out.println(b.get(key));
}
prints
Intent { act=android.net.conn.CONNECTIVITY_CHANGE flg=0x10000000 (has extras) }
networkInfo => NetworkInfo: type: mobile[UMTS], state: CONNECTED/CONNECTED, reason: simLoaded, ... [elided]
reason => simLoaded
extraInfo => internet
inetCondition => 0
Although it is possible to use the long-form of the registerReceiver() method in this way there is effectively no point since the permission argument has no effect.
For example, replacing the line
Intent i = registerReceiver(null, f);
in the example above with
Intent i = registerReceiver(null, f, "xper.permission.NO_SUCH_PERMISSION", null);
does not change the behaviour at all.
9.5 Removing A Sticky Broadcast Intent
A sticky broadcast Intent can be removed by calling an implementation of the android.content.Context method
public abstract void removeStickyBroadcast(Intent intent)
To remove a sticky broadcast Intent an Application must have been granted the BROADCAST_STICKY permission.
The method will remove the sticky broadcast Intent, if any, which matches, as determined by the Intent.filterEquals() method, the Intent passed as the intent argument.
9.6 Sticky Broadcast Intents And Dynamically Registered BroadcastReceivers
9.6.1 Registration
When a BroadcastReceiver is registered dynamically using the short-form registerReceiver() method, then, if the associated IntentFilter matches one or more sticky broadcast Intents
-
one of the matching Intents will be returned by the method, and then, at some point
-
the BroadcastReceiver’s onReceive() method will be invoked for each matching sticky broadcast Intent
For example, if we define the class StickyBroadcastReceiver as follows
public class StickyBroadcastReceiver
extends
BroadcastReceiver
{
@Override
public void onReceive(Context context, Intent intent)
{
System.out.println("StickyBroadcastReceiver.onReceive(...)");
System.out.println(intent);
System.out.println("\tisInitialStickyBroadcast() => " + isInitialStickyBroadcast());
System.out.println("StickyBroadcastReceiver.onReceive(...) done");
}
}
then the following code
Intent i = registerReceiver(
new StickyBroadcastReceiver(),
new IntentFilter(
ConnectivityManager.CONNECTIVITY_ACTION));
System.out.println("registerReceiver() => " + i);
prints
registerReceiver() => Intent { act=android.net.conn.CONNECTIVITY_CHANGE flg=0x10000000 (has extras) }
and then the onReceive() method prints
StickyBroadcastReceiver.onReceive(...)
Intent { act=android.net.conn.CONNECTIVITY_CHANGE flg=0x10000000 (has extras) }
isInitialStickyBroadcast() => true
StickyBroadcastReceiver.onReceive(...) done
When a BroadcastReceiver is registered dynamically using the long-form registerReceiver() method then, if the associated IntentFilter matches one or more sticky broadcast Intents, the exact behaviour depends on whether or not a permission is specified.
The method will return one of the matching Intents irrespective of whether or not a permission was specified.
However, once the method has returned, if a permission was specified, then the BroadcastReceiver’s onReceive() method will not be invoked on any sticky broadcast Intent sent by an Application which has not been granted that permission.
For example, modifying the previous example, then the following code
Intent i = registerReceiver(
new StickyBroadcastReceiver(),
new IntentFilter(
ConnectivityManager.CONNECTIVITY_ACTION),
"xper.permission.NO_SUCH_PERMISSION",
null);
prints
registerReceiver() => Intent { act=android.net.conn.CONNECTIVITY_CHANGE flg=0x10000000 (has extras) }
and that is it. The onReceive() method is not invoked.
The behaviour with respect to the onReceive() method is consistent with the way permissions work, it is really the behaviour of the registerReceiver() method which is anomalous.
9.6.2 The onReceive() Method
A dynamically registered BroadcastReceiver can determine whether it is being invoked on a sticky broadcast Intent by calling the
public final boolean isInitialStickyBroadcast()
method.
If it is then the behaviour of some of the methods defined by the BroadcastReceiver class for use with ordered broadcast Intents is slightly different.
-
The isOrderedBroadcast() method always returns false
-
The methods for setting result data do not throw RuntimeExceptions, they are simply no-ops
-
The abortBroadcast() method does not throw a RuntimeException, it is simply a no-op
10. Broadcast Intents And Intent Flags
There are two Intent class constants which define flags specifically for use with broadcast Intents.
10.1 FLAG_RECEIVER_REGISTERED_ONLY
If this flag is set in a broadcast Intent then it will only be delivered to those eligible BroadcastReceivers which were dynamically registered.
10.2 FLAG_RECEIVER_REPLACE_PENDING
If this flag is set in a broadcast Intent then it will replace any broadcast Intent which matches it, as defined by Intent.filterEquals(), which is currently in the process of being delivered to any eligible BroadcastReceivers.
This effect is not atomic. Some BroadcastReceivers may receive both the original and the replacement broadcast Intent, others only the replacement, as the following rather contrived example demonstrates.
We define two static BroadcastReceivers
<receiver
android:name="Sole">
<intent-filter>
<action
android:name="xper.receiver.intent.RECEIVER_SOLE_INTENT"/>
<action
android:name="xper.receiver.intent.RECEIVER_SEA_AREA_INTENT"/>
</intent-filter>
</receiver>
<receiver
android:name="Fastnet">
<intent-filter>
<action
android:name="xper.receiver.intent.RECEIVER_FASTNET_INTENT"/>
<action
android:name="xper.receiver.intent.RECEIVER_SEA_AREA_INTENT"/>
</intent-filter>
</receiver>
each in a separate Application, and one dynamic BroadcastReceiver registered by a third Application as follows
IntentFilter f = new IntentFilter();
f.addAction("xper.receiver.intent.RECEIVER_LUNDY_INTENT");
f.addAction("xper.receiver.intent.RECEIVER_SEA_AREA_INTENT");
registerReceiver(new Lundy(), f);
We define their respective onReceive() methods to be
// Sole
public void onReceive(Context context, Intent intent)
{
System.out.println("Sole.onReceive(..., " + intent + ")");
System.out.println("Sole.onReceive(...) N == " + intent.getStringExtra("N"));
}
...
// Fastnet
public void onReceive(Context context, Intent intent)
{
System.out.println("Fastnet.onReceive(..., " + intent + ")");
System.out.println("Fastnet.onReceive(...) N == " + intent.getStringExtra("N"));
}
...
// Lundy
public void onReceive(Context context, Intent intent)
{
System.out.println("Lundy.onReceive(..., " + intent + ")");
System.out.println("Lundy.onReceive(...) N == " + intent.getStringExtra("N"));
}
If we execute the following
sendBroadcast(
new Intent(
"xper.receiver.intent.RECEIVER_SEA_AREA_INTENT").
setFlags(
Intent.FLAG_RECEIVER_REPLACE_PENDING).
putExtra(
"N",
"One"));
sendBroadcast(
new Intent(
"xper.receiver.intent.RECEIVER_SEA_AREA_INTENT").
setFlags(
Intent.FLAG_RECEIVER_REPLACE_PENDING).
putExtra(
"N",
"Two"));
sendBroadcast(
new Intent(
"xper.receiver.intent.RECEIVER_SEA_AREA_INTENT").
setFlags(
Intent.FLAG_RECEIVER_REPLACE_PENDING).
putExtra(
"N",
"Three"));
then we get (output slightly reformatted)
Lundy.onReceive(..., Intent { act=xper.receiver.intent.RECEIVER_SEA_AREA_INTENT flg=0x20000000 (has extras) })
Lundy.onReceive(...) N == One
Fastnet.onReceive(..., Intent { act=xper.receiver.intent.RECEIVER_SEA_AREA_INTENT \
flg=0x20000000 cmp=xper.receiver.fastnet/.Fastnet (has extras) })
Fastnet.onReceive(...) N == One
Lundy.onReceive(..., Intent { act=xper.receiver.intent.RECEIVER_SEA_AREA_INTENT flg=0x20000000 (has extras) })
Lundy.onReceive(...) N == Two
Lundy.onReceive(..., Intent { act=xper.receiver.intent.RECEIVER_SEA_AREA_INTENT flg=0x20000000 (has extras) })
Lundy.onReceive(...) N == Three
Sole.onReceive(..., Intent { act=xper.receiver.intent.RECEIVER_SEA_AREA_INTENT \
flg=0x20000000 cmp=xper.receiver.sole/.Sole (has extras) })
Sole.onReceive(...) N == One
Fastnet.onReceive(..., Intent { act=xper.receiver.intent.RECEIVER_SEA_AREA_INTENT \
flg=0x20000000 cmp=xper.receiver.fastnet/.Fastnet (has extras) })
Fastnet.onReceive(...) N == Three
Sole.onReceive(..., Intent { act=xper.receiver.intent.RECEIVER_SEA_AREA_INTENT \
flg=0x20000000 cmp=xper.receiver.sole/.Sole (has extras) })
Sole.onReceive(...) N == Three
11. Sending A Broadcast Intent To A Specific BroadcastReceiver
Both normal and ordered broadcast Intents can be sent to a specific BroadcastReceiver by setting the broadcast Intent’s component explicitly.
For example, assuming the Application package is
xper.specific
and the BroadcastReceiver is declared as follows
<receiver
android:name = "SpecificBroadcastReceiver">
<intent-filter>
<action android:name = "xper.specific.SPECIFIC_BROADCAST_INTENT"/>
</intent-filter>
</receiver>
then a normal broadcast Intent can be sent to it as follows.
sendBroadcast(
new Intent(
"xper.specific.BROADCAST_INTENT").
setClassName(
"xper.specific",
"xper.specific.SpecificBroadcastReceiver"));
Note that, as in this example, the Intent does not have to match the IntentFilter(s) associated with the BroadcastReceiver, which has some interesting implications.
Although specifying the BroadcastReceiver explicitly when sending the broadcast Intent overrides the BroadcastReceiver’s IntentFilter(s) both sender and/or receiver permissions, if specified, still apply.
It is not possible to send a broadcast Intent to a specific BroadcastReceiver in sticky mode. Attempting to do so results in a SecurityException.
12. Anonymous BroadcastReceivers
It is possible to statically register a BroadcastReceiver without any IntentFilters. For example.
<receiver
android:name = "AnonymousBroadcastReceiver"/>
Broadcast Intents can still be sent to it by specifying the BroadcastReceiver explicitly.
In this can it can only be done from the registering Application since in the BroadcastReceiver has not been exported.
It is of course possible to export it as well
<receiver
android:name = "AnonymousBroadcastReceiver"
android:exported = "true"/>
Copyright (c) 2011 By Simon Lewis. All Rights Reserved.
Just An Application 