diff options
| -rw-r--r-- | packages/SystemUI/docs/broadcasts.md | 15 | ||||
| -rw-r--r-- | packages/SystemUI/src/com/android/systemui/broadcast/BroadcastDispatcher.kt | 2 |
2 files changed, 14 insertions, 3 deletions
diff --git a/packages/SystemUI/docs/broadcasts.md b/packages/SystemUI/docs/broadcasts.md index 28657f28e53b..6c8488b332c2 100644 --- a/packages/SystemUI/docs/broadcasts.md +++ b/packages/SystemUI/docs/broadcasts.md @@ -30,10 +30,21 @@ Additionally, the dispatcher supports the following: If introducing a new `BroadcastReceiver` (not declared in `AndroidManifest`) that satisfies the constraints above, use the dispatcher to reduce the load on `system_server`. -Do not use the dispatcher to obtain the last broadcast (by passing a null `BroadcastReceiver`). `BroadcastDispatcher#registerReceiver` **does not** return the last sticky Intent. - Additionally, if listening to some broadcast is latency critical (beyond 100ms of latency), consider registering with Context instead. +### A note on sticky broadcasts + +Sticky broadcasts are those that have been sent using `Context#sendStickyBroadcast` or `Context#sendStickyBroadcastAsUser`. In general they behave like regular broadcasts, but they are also cached (they may be replaced later) to provide the following two features: + * They may be returned by `Context#registerReceiver` if the broadcast is matched by the `IntentFilter`. In case that multiple cached broadcast match the filter, any one of those may be returned. + * All cached sticky broadcasts that match the filter will be sent to the just registered `BroadcastReceiver#onReceive`. + +Sticky broadcasts are `@Deprecated` since API 24 and the general recommendation is to use regular broadcasts and API that allows to retrieve last known state. + +Because of this and in order to provide the necessary optimizations, `BroadcastDispatcher` does not offer support for sticky intents: + +* Do not use the dispatcher to obtain the last broadcast (by passing a null `BroadcastReceiver`). `BroadcastDispatcher#registerReceiver` **does not** return the last sticky Intent. +* Do not expect cached sticky broadcasts to be delivered on registration. This may happen but it's not guaranteed. + ## How do I use the dispatcher? Acquire the dispatcher by using `@Inject` to obtain a `BroadcastDispatcher`. Then, use the following methods in that instance. diff --git a/packages/SystemUI/src/com/android/systemui/broadcast/BroadcastDispatcher.kt b/packages/SystemUI/src/com/android/systemui/broadcast/BroadcastDispatcher.kt index 319a6e09d4d1..4269605cef12 100644 --- a/packages/SystemUI/src/com/android/systemui/broadcast/BroadcastDispatcher.kt +++ b/packages/SystemUI/src/com/android/systemui/broadcast/BroadcastDispatcher.kt @@ -60,7 +60,7 @@ private const val DEBUG = true * * Use only for IntentFilters with actions and optionally categories. It does not support, * permissions, schemes, data types, data authorities or priority different than 0. - * Cannot be used for getting sticky broadcasts. + * Cannot be used for getting sticky broadcasts (either as return of registering or as re-delivery). */ @Singleton open class BroadcastDispatcher @Inject constructor ( |