From 03ade186725d01c77542e936b419024dd04bfc21 Mon Sep 17 00:00:00 2001 From: Suprabh Shukla Date: Thu, 15 Apr 2021 15:02:50 -0700 Subject: [PATCH] A WorkSource version of AlarmManager#setExact Inexact alarms will have a minimum length window enforced starting with API S, so we need a clearer separate system API for apps that set alarms on behalf of others. Test: atest CtsAlarmManagerTestCases:BasicApiTests Bug: 185530825 Change-Id: Ica8399b21421572e30a554f9897a352ce5fff557 --- .../java/android/app/AlarmManager.java | 52 +++++++++++++++++-- core/api/system-current.txt | 3 +- 2 files changed, 50 insertions(+), 5 deletions(-) diff --git a/apex/jobscheduler/framework/java/android/app/AlarmManager.java b/apex/jobscheduler/framework/java/android/app/AlarmManager.java index 9ea6f7946fcff..01f31e43989ec 100644 --- a/apex/jobscheduler/framework/java/android/app/AlarmManager.java +++ b/apex/jobscheduler/framework/java/android/app/AlarmManager.java @@ -19,6 +19,7 @@ package android.app; import android.Manifest; import android.annotation.IntDef; import android.annotation.NonNull; +import android.annotation.Nullable; import android.annotation.RequiresPermission; import android.annotation.SdkConstant; import android.annotation.SystemApi; @@ -591,8 +592,8 @@ public class AlarmManager { * in milliseconds. The alarm will be delivered no later than this many * milliseconds after {@code windowStartMillis}. Note that this parameter * is a duration, not the timestamp of the end of the window. - * @param tag string describing the alarm, used for logging and battery-use - * attribution + * @param tag Optional. A string describing the alarm, used for logging and battery-use + * attribution. * @param listener {@link OnAlarmListener} instance whose * {@link OnAlarmListener#onAlarm() onAlarm()} method will be * called when the alarm time is reached. A given OnAlarmListener instance can @@ -605,9 +606,8 @@ public class AlarmManager { @SystemApi @RequiresPermission(Manifest.permission.SCHEDULE_PRIORITIZED_ALARM) public void setPrioritized(@AlarmType int type, long windowStartMillis, long windowLengthMillis, - @NonNull String tag, @NonNull Executor executor, @NonNull OnAlarmListener listener) { + @Nullable String tag, @NonNull Executor executor, @NonNull OnAlarmListener listener) { Objects.requireNonNull(executor); - Objects.requireNonNull(tag); Objects.requireNonNull(listener); setImpl(type, windowStartMillis, windowLengthMillis, 0, FLAG_PRIORITIZE, null, listener, tag, executor, null, null); @@ -782,6 +782,50 @@ public class AlarmManager { targetHandler, workSource, null); } + /** + * Exact version of {@link #set(int, long, long, long, OnAlarmListener, Handler, WorkSource)}. + * This equivalent to calling the aforementioned API with {@code windowMillis} and + * {@code intervalMillis} set to 0. + * One subtle difference is that this API requires {@code workSource} to be non-null. If you + * don't want to attribute this alarm to another app for battery consumption, you should use + * {@link #setExact(int, long, String, OnAlarmListener, Handler)} instead. + * + *

+ * Note that using this API requires you to hold + * {@link Manifest.permission#SCHEDULE_EXACT_ALARM}, unless you are on the system's power + * allowlist. This can be set, for example, by marking the app as {@code } + * within the system config. + * + * @param type type of alarm + * @param triggerAtMillis The exact time in milliseconds, that the alarm should be delivered, + * expressed in the appropriate clock's units (depending on the alarm + * type). + * @param listener {@link OnAlarmListener} instance whose + * {@link OnAlarmListener#onAlarm() onAlarm()} method will be called when + * the alarm time is reached. + * @param executor The {@link Executor} on which to execute the listener's onAlarm() + * callback. + * @param tag Optional. A string tag used to identify this alarm in logs and + * battery-attribution. + * @param workSource A {@link WorkSource} object to attribute this alarm to the app that + * requested this work. + * @hide + */ + @SystemApi + @RequiresPermission(allOf = { + Manifest.permission.UPDATE_DEVICE_STATS, + Manifest.permission.SCHEDULE_EXACT_ALARM}, conditional = true) + public void setExact(@AlarmType int type, long triggerAtMillis, @Nullable String tag, + @NonNull Executor executor, @NonNull WorkSource workSource, + @NonNull OnAlarmListener listener) { + Objects.requireNonNull(executor); + Objects.requireNonNull(workSource); + Objects.requireNonNull(listener); + setImpl(type, triggerAtMillis, WINDOW_EXACT, 0, 0, null, listener, tag, executor, + workSource, null); + } + + private void setImpl(@AlarmType int type, long triggerAtMillis, long windowMillis, long intervalMillis, int flags, PendingIntent operation, final OnAlarmListener listener, String listenerTag, Handler targetHandler, WorkSource workSource, diff --git a/core/api/system-current.txt b/core/api/system-current.txt index fb6c457ecbd67..419eeff08c3b1 100644 --- a/core/api/system-current.txt +++ b/core/api/system-current.txt @@ -438,7 +438,8 @@ package android.app { public class AlarmManager { method @RequiresPermission(android.Manifest.permission.UPDATE_DEVICE_STATS) public void set(int, long, long, long, android.app.PendingIntent, android.os.WorkSource); method @RequiresPermission(android.Manifest.permission.UPDATE_DEVICE_STATS) public void set(int, long, long, long, android.app.AlarmManager.OnAlarmListener, android.os.Handler, android.os.WorkSource); - method @RequiresPermission(android.Manifest.permission.SCHEDULE_PRIORITIZED_ALARM) public void setPrioritized(int, long, long, @NonNull String, @NonNull java.util.concurrent.Executor, @NonNull android.app.AlarmManager.OnAlarmListener); + method @RequiresPermission(allOf={android.Manifest.permission.UPDATE_DEVICE_STATS, android.Manifest.permission.SCHEDULE_EXACT_ALARM}, conditional=true) public void setExact(int, long, @Nullable String, @NonNull java.util.concurrent.Executor, @NonNull android.os.WorkSource, @NonNull android.app.AlarmManager.OnAlarmListener); + method @RequiresPermission(android.Manifest.permission.SCHEDULE_PRIORITIZED_ALARM) public void setPrioritized(int, long, long, @Nullable String, @NonNull java.util.concurrent.Executor, @NonNull android.app.AlarmManager.OnAlarmListener); } public class AppOpsManager {