diff options
Diffstat (limited to 'packages/SystemUI/docs/broadcasts.md')
| -rw-r--r-- | packages/SystemUI/docs/broadcasts.md | 15 |
1 files changed, 13 insertions, 2 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. |