Add info about sticky in broadcasts.md

Also in the Javadoc of BroadcastDispatcher

Test: no test
Fixes: 151641451
Change-Id: Id19f5192c9c0c17b7405853960258b43053630d1

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 (