Darker Corners of Android: BroadcastReceivers and Intents

Not all in Android-land is lightness and brightness. A few dark corners and cul de sacs await the unwary, ready to trap us in sticky tarbaby snares of mystery debugging. One such is a case we recently encountered in relation to BroadcastReceivers and the way Intents get delivered to them.

I've written previously about implicit Intents versus explicit Intents in the context of describing a useful code-pattern for preparing Intents. To briefly recap, explicit Intents name the class of the component they are aimed at whilst implicit Intents simply describe the desired action they intend to trigger and allow the Android intent-delivery system to find the best-matching component to handle the Intent. Indeed, a better naming scheme might have been "broadcast Intent" for implicit Intents and "unicast Intent" for explicit Intents.

BroadcastReceivers can be registered for receiving broadcast Intents in one of two ways, either through a declaration in the Android manifest file, or via a dynamic registration by another component.

If you register a BroadcastReceiver via a manifest declaration, then you must provide the class-name of the receiver implementation. To communicate with the receiver, you broadcast an Intent – either one that matches the receiver's intent-filter (if it was declared to have one) or an Intent that specifies the class-name of the receiver. In this latter case it's hardly a broadcast, really, since the Intent is directed at a specific target receiver. Nevertheless, this is a perfectly valid way to send events and information to a BroadcastReceiver.

If you dynamically register a BroadcastReceiver – by calling Context.registerReceiver() – you supply a BroadcastReceiver instance and an IntentFilter describing the sorts of Intents that should be passed to the receiver. And herein lies a small gotcha. You register an instance.

If you try to send an Intent to the receiver by naming the class of the BroadcastReceiver, it will never get delivered. Sending the Intent using something like

Intent i = new Intent( this, MessageReceiver.class );
sendBroadcast( i );

won't work. The Android system will not match the Intent you declared to the class of the BroadcastReceiver instance you registered. The only way to send Intents to dynamically registered BroadcastReceivers is by having them match the IntentFilter attached to the receiver when it gets registered.

Explicit Intent matching just doesn't work in this case.

I've put some example code on github that demonstrates all this. There's a simple BroadcastReceiver (the MessageReceiver class) that gets registered dynamically by the MainActivity. The MainActivity instance then tries to send Intents to this receiver instance using two different methods. First it sends an Intent that matches the Action declared in the receiver's intent-filter. That Intent gets through successfully. Then it tries to send an Intent that explicitly names the MessageReceiver class. It never arrives.

As much as I love the eventful nature of Android software architecture I view this as a bug (Come on guys... How hard would it be to do a getClass() on the instance that gets registered?) but it is what it is. It took us a day or so to figure out why Intents were mysteriously failing to be delivered to an otherwise perfectly ordinary BroadcastReceiver, so I thought I'd save you, Dear Reader, the trouble. It's pretty straightforward to cope with (rely on Intent actions rather than explicit Intents) once you know of this issue, but I have not seen it documented anywhere in the Android reference materials^ε.

Share and Enjoy.

---

^ε If anyone does spot a description of this in the official docs, please do let me know!