From 94f5840bed5f853713ceaeea184f0e4b13682293 Mon Sep 17 00:00:00 2001 From: Suprabh Shukla Date: Tue, 29 Jun 2021 16:18:31 -0700 Subject: [PATCH] Improve javadocs for repeating alarms Specifically, mentioning that the alarm count can only be included with the alarm if the supplied pending intent is mutable. Test: make offline-sdk-docs Fixes: 178413211 Change-Id: I2914bceebeed8b52b0de11d70960aa33e6837b13 --- .../framework/java/android/app/AlarmManager.java | 8 ++++++++ core/java/android/content/Intent.java | 12 ++++++++++-- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/apex/jobscheduler/framework/java/android/app/AlarmManager.java b/apex/jobscheduler/framework/java/android/app/AlarmManager.java index 4843415fdbdda..f1ac3da52d211 100644 --- a/apex/jobscheduler/framework/java/android/app/AlarmManager.java +++ b/apex/jobscheduler/framework/java/android/app/AlarmManager.java @@ -494,6 +494,9 @@ public class AlarmManager { * exact alarms, rescheduling each time as described above. Legacy applications * whose {@code targetSdkVersion} is earlier than API 19 will continue to have all * of their alarms, including repeating alarms, treated as exact. + *

Apps targeting {@link Build.VERSION_CODES#S} will need to set the flag + * {@link PendingIntent#FLAG_MUTABLE} on the {@link PendingIntent} being used to set this alarm, + * if they want the alarm count to be supplied with the key {@link Intent#EXTRA_ALARM_COUNT}. * * @param type type of alarm. * @param triggerAtMillis time in milliseconds that the alarm should first @@ -516,6 +519,7 @@ public class AlarmManager { * @see #ELAPSED_REALTIME_WAKEUP * @see #RTC * @see #RTC_WAKEUP + * @see Intent#EXTRA_ALARM_COUNT */ public void setRepeating(@AlarmType int type, long triggerAtMillis, long intervalMillis, PendingIntent operation) { @@ -1004,6 +1008,9 @@ public class AlarmManager { * been available since API 3, your application can safely call it and be * assured that it will get similar behavior on both current and older versions * of Android. + *

Apps targeting {@link Build.VERSION_CODES#S} will need to set the flag + * {@link PendingIntent#FLAG_MUTABLE} on the {@link PendingIntent} being used to set this alarm, + * if they want the alarm count to be supplied with the key {@link Intent#EXTRA_ALARM_COUNT}. * * @param type type of alarm. * @param triggerAtMillis time in milliseconds that the alarm should first @@ -1038,6 +1045,7 @@ public class AlarmManager { * @see #INTERVAL_HOUR * @see #INTERVAL_HALF_DAY * @see #INTERVAL_DAY + * @see Intent#EXTRA_ALARM_COUNT */ public void setInexactRepeating(@AlarmType int type, long triggerAtMillis, long intervalMillis, PendingIntent operation) { diff --git a/core/java/android/content/Intent.java b/core/java/android/content/Intent.java index 688483a5c9694..9e35a32638a86 100644 --- a/core/java/android/content/Intent.java +++ b/core/java/android/content/Intent.java @@ -5736,12 +5736,20 @@ public class Intent implements Parcelable, Cloneable { public static final String EXTRA_REPLACING = "android.intent.extra.REPLACING"; /** - * Used as an int extra field in {@link android.app.AlarmManager} intents + * Used as an int extra field in {@link android.app.AlarmManager} pending intents * to tell the application being invoked how many pending alarms are being - * delievered with the intent. For one-shot alarms this will always be 1. + * delivered with the intent. For one-shot alarms this will always be 1. * For recurring alarms, this might be greater than 1 if the device was * asleep or powered off at the time an earlier alarm would have been * delivered. + * + *

Note: You must supply a mutable {@link android.app.PendingIntent} to + * {@code AlarmManager} while setting your alarms to be able to read this value on receiving + * them. Mutability of pending intents must be explicitly specified by apps targeting + * {@link Build.VERSION_CODES#S} or higher. + * + * @see android.app.PendingIntent#FLAG_MUTABLE + * */ public static final String EXTRA_ALARM_COUNT = "android.intent.extra.ALARM_COUNT";