From 30e06bb668f2e4b024c4ebc2a131de91c96de5eb Mon Sep 17 00:00:00 2001 From: Jeff Sharkey Date: Mon, 24 Apr 2017 11:18:03 -0600 Subject: [PATCH] Even more auto-doc work. Update docs based on what new lint detector found. Add new @IntDef to parameters or methods returning constants or flags, and add @RequiresPermission to methods mentioning permissions. Test: make -j32 offline-sdk-docs Bug: 37526420 Change-Id: I7f640f7883fcb66b911a52ae93b83f77306571ec --- .../android/annotation/BroadcastBehavior.java | 5 + core/java/android/app/Activity.java | 2 +- core/java/android/app/ActivityManager.java | 33 +- core/java/android/app/AlarmManager.java | 86 +++-- core/java/android/app/Notification.java | 16 +- .../java/android/app/NotificationChannel.java | 5 +- core/java/android/app/job/JobInfo.java | 70 ++-- core/java/android/app/job/JobScheduler.java | 22 +- core/java/android/content/ComponentName.java | 22 +- core/java/android/content/Context.java | 119 +++--- core/java/android/content/Intent.java | 362 ++++++++++-------- .../android/content/pm/PackageManager.java | 108 +++--- .../java/android/net/ConnectivityManager.java | 111 ++---- core/java/android/os/Parcelable.java | 26 +- core/java/android/os/Vibrator.java | 19 +- 15 files changed, 547 insertions(+), 459 deletions(-) diff --git a/core/java/android/annotation/BroadcastBehavior.java b/core/java/android/annotation/BroadcastBehavior.java index 9b2ca3120290f..70d82cb5151b4 100644 --- a/core/java/android/annotation/BroadcastBehavior.java +++ b/core/java/android/annotation/BroadcastBehavior.java @@ -53,4 +53,9 @@ public @interface BroadcastBehavior { * @see Intent#FLAG_RECEIVER_INCLUDE_BACKGROUND */ boolean includeBackground() default false; + + /** + * This broadcast is protected and can only be sent by the OS. + */ + boolean protectedBroadcast() default false; } diff --git a/core/java/android/app/Activity.java b/core/java/android/app/Activity.java index 1b972f79e48ca..e4d2d132fcedb 100644 --- a/core/java/android/app/Activity.java +++ b/core/java/android/app/Activity.java @@ -5844,7 +5844,7 @@ public class Activity extends ContextThemeWrapper * @return Returns the single SharedPreferences instance that can be used * to retrieve and modify the preference values. */ - public SharedPreferences getPreferences(int mode) { + public SharedPreferences getPreferences(@Context.PreferencesMode int mode) { return getSharedPreferences(getLocalClassName(), mode); } diff --git a/core/java/android/app/ActivityManager.java b/core/java/android/app/ActivityManager.java index 62f2144312e24..1ab45b56e5caa 100644 --- a/core/java/android/app/ActivityManager.java +++ b/core/java/android/app/ActivityManager.java @@ -2350,6 +2350,14 @@ public class ActivityManager { } } + /** @hide */ + @IntDef(flag = true, prefix = { "MOVE_TASK_" }, value = { + MOVE_TASK_WITH_HOME, + MOVE_TASK_NO_USER_ACTION, + }) + @Retention(RetentionPolicy.SOURCE) + public @interface MoveTaskFlags {} + /** * Flag for {@link #moveTaskToFront(int, int)}: also move the "home" * activity along with the task, so it is positioned immediately behind @@ -2370,28 +2378,26 @@ public class ActivityManager { * * @param taskId The identifier of the task to be moved, as found in * {@link RunningTaskInfo} or {@link RecentTaskInfo}. - * @param flags Additional operational flags, 0 or more of - * {@link #MOVE_TASK_WITH_HOME}, {@link #MOVE_TASK_NO_USER_ACTION}. + * @param flags Additional operational flags. */ - public void moveTaskToFront(int taskId, int flags) { + @RequiresPermission(android.Manifest.permission.REORDER_TASKS) + public void moveTaskToFront(int taskId, @MoveTaskFlags int flags) { moveTaskToFront(taskId, flags, null); } /** * Ask that the task associated with a given task ID be moved to the - * front of the stack, so it is now visible to the user. Requires that - * the caller hold permission {@link android.Manifest.permission#REORDER_TASKS} - * or a SecurityException will be thrown. + * front of the stack, so it is now visible to the user. * * @param taskId The identifier of the task to be moved, as found in * {@link RunningTaskInfo} or {@link RecentTaskInfo}. - * @param flags Additional operational flags, 0 or more of - * {@link #MOVE_TASK_WITH_HOME}, {@link #MOVE_TASK_NO_USER_ACTION}. + * @param flags Additional operational flags. * @param options Additional options for the operation, either null or * as per {@link Context#startActivity(Intent, android.os.Bundle) * Context.startActivity(Intent, Bundle)}. */ - public void moveTaskToFront(int taskId, int flags, Bundle options) { + @RequiresPermission(android.Manifest.permission.REORDER_TASKS) + public void moveTaskToFront(int taskId, @MoveTaskFlags int flags, Bundle options) { try { getService().moveTaskToFront(taskId, flags, options); } catch (RemoteException e) { @@ -3637,13 +3643,10 @@ public class ActivityManager { * processes to reclaim memory; the system will take care of restarting * these processes in the future as needed. * - *

You must hold the permission - * {@link android.Manifest.permission#KILL_BACKGROUND_PROCESSES} to be able to - * call this method. - * * @param packageName The name of the package whose processes are to * be killed. */ + @RequiresPermission(Manifest.permission.KILL_BACKGROUND_PROCESSES) public void killBackgroundProcesses(String packageName) { try { getService().killBackgroundProcesses(packageName, @@ -4015,13 +4018,13 @@ public class ActivityManager { * Perform a system dump of various state associated with the given application * package name. This call blocks while the dump is being performed, so should * not be done on a UI thread. The data will be written to the given file - * descriptor as text. An application must hold the - * {@link android.Manifest.permission#DUMP} permission to make this call. + * descriptor as text. * @param fd The file descriptor that the dump should be written to. The file * descriptor is not closed by this function; the caller continues to * own it. * @param packageName The name of the package that is to be dumped. */ + @RequiresPermission(Manifest.permission.DUMP) public void dumpPackageState(FileDescriptor fd, String packageName) { dumpPackageStateStatic(fd, packageName); } diff --git a/core/java/android/app/AlarmManager.java b/core/java/android/app/AlarmManager.java index c561a1908b213..3221c5d895431 100644 --- a/core/java/android/app/AlarmManager.java +++ b/core/java/android/app/AlarmManager.java @@ -16,6 +16,7 @@ package android.app; +import android.annotation.IntDef; import android.annotation.SdkConstant; import android.annotation.SystemApi; import android.content.Context; @@ -34,6 +35,8 @@ import android.util.Log; import libcore.util.ZoneInfoDB; import java.io.IOException; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; /** * This class provides access to the system alarm services. These allow you @@ -78,6 +81,16 @@ import java.io.IOException; public class AlarmManager { private static final String TAG = "AlarmManager"; + /** @hide */ + @IntDef(prefix = { "RTC", "ELAPSED" }, value = { + RTC_WAKEUP, + RTC, + ELAPSED_REALTIME_WAKEUP, + ELAPSED_REALTIME, + }) + @Retention(RetentionPolicy.SOURCE) + public @interface AlarmType {} + /** * Alarm time in {@link System#currentTimeMillis System.currentTimeMillis()} * (wall clock time in UTC), which will wake up the device when @@ -311,8 +324,7 @@ public class AlarmManager { * will be treated as exact. * * - * @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP}, - * {@link #RTC}, or {@link #RTC_WAKEUP}. + * @param type type of alarm. * @param triggerAtMillis time in milliseconds that the alarm should go * off, using the appropriate clock (depending on the alarm type). * @param operation Action to perform when the alarm goes off; @@ -332,7 +344,7 @@ public class AlarmManager { * @see #RTC * @see #RTC_WAKEUP */ - public void set(int type, long triggerAtMillis, PendingIntent operation) { + public void set(@AlarmType int type, long triggerAtMillis, PendingIntent operation) { setImpl(type, triggerAtMillis, legacyExactLength(), 0, 0, operation, null, null, null, null, null); } @@ -346,8 +358,7 @@ public class AlarmManager { * invoked via the specified target Handler, or on the application's main looper * if {@code null} is passed as the {@code targetHandler} parameter. * - * @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP}, - * {@link #RTC}, or {@link #RTC_WAKEUP}. + * @param type type of alarm. * @param triggerAtMillis time in milliseconds that the alarm should go * off, using the appropriate clock (depending on the alarm type). * @param tag string describing the alarm, used for logging and battery-use @@ -360,7 +371,7 @@ public class AlarmManager { * @param targetHandler {@link Handler} on which to execute the listener's onAlarm() * callback, or {@code null} to run that callback on the main looper. */ - public void set(int type, long triggerAtMillis, String tag, OnAlarmListener listener, + public void set(@AlarmType int type, long triggerAtMillis, String tag, OnAlarmListener listener, Handler targetHandler) { setImpl(type, triggerAtMillis, legacyExactLength(), 0, 0, null, listener, tag, targetHandler, null, null); @@ -399,8 +410,7 @@ public class AlarmManager { * whose {@code targetSdkVersion} is earlier than API 19 will continue to have all * of their alarms, including repeating alarms, treated as exact. * - * @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP}, - * {@link #RTC}, or {@link #RTC_WAKEUP}. + * @param type type of alarm. * @param triggerAtMillis time in milliseconds that the alarm should first * go off, using the appropriate clock (depending on the alarm type). * @param intervalMillis interval in milliseconds between subsequent repeats @@ -422,7 +432,7 @@ public class AlarmManager { * @see #RTC * @see #RTC_WAKEUP */ - public void setRepeating(int type, long triggerAtMillis, + public void setRepeating(@AlarmType int type, long triggerAtMillis, long intervalMillis, PendingIntent operation) { setImpl(type, triggerAtMillis, legacyExactLength(), intervalMillis, 0, operation, null, null, null, null, null); @@ -448,8 +458,7 @@ public class AlarmManager { * at precisely-specified times with no acceptable variation, applications can use * {@link #setExact(int, long, PendingIntent)}. * - * @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP}, - * {@link #RTC}, or {@link #RTC_WAKEUP}. + * @param type type of alarm. * @param windowStartMillis The earliest time, in milliseconds, that the alarm should * be delivered, expressed in the appropriate clock's units (depending on the alarm * type). @@ -473,7 +482,7 @@ public class AlarmManager { * @see #RTC * @see #RTC_WAKEUP */ - public void setWindow(int type, long windowStartMillis, long windowLengthMillis, + public void setWindow(@AlarmType int type, long windowStartMillis, long windowLengthMillis, PendingIntent operation) { setImpl(type, windowStartMillis, windowLengthMillis, 0, 0, operation, null, null, null, null, null); @@ -488,7 +497,7 @@ public class AlarmManager { * invoked via the specified target Handler, or on the application's main looper * if {@code null} is passed as the {@code targetHandler} parameter. */ - public void setWindow(int type, long windowStartMillis, long windowLengthMillis, + public void setWindow(@AlarmType int type, long windowStartMillis, long windowLengthMillis, String tag, OnAlarmListener listener, Handler targetHandler) { setImpl(type, windowStartMillis, windowLengthMillis, 0, 0, null, listener, tag, targetHandler, null, null); @@ -508,8 +517,7 @@ public class AlarmManager { * scheduled as exact. Applications are strongly discouraged from using exact * alarms unnecessarily as they reduce the OS's ability to minimize battery use. * - * @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP}, - * {@link #RTC}, or {@link #RTC_WAKEUP}. + * @param type type of alarm. * @param triggerAtMillis time in milliseconds that the alarm should go * off, using the appropriate clock (depending on the alarm type). * @param operation Action to perform when the alarm goes off; @@ -528,7 +536,7 @@ public class AlarmManager { * @see #RTC * @see #RTC_WAKEUP */ - public void setExact(int type, long triggerAtMillis, PendingIntent operation) { + public void setExact(@AlarmType int type, long triggerAtMillis, PendingIntent operation) { setImpl(type, triggerAtMillis, WINDOW_EXACT, 0, 0, operation, null, null, null, null, null); } @@ -542,8 +550,8 @@ public class AlarmManager { * invoked via the specified target Handler, or on the application's main looper * if {@code null} is passed as the {@code targetHandler} parameter. */ - public void setExact(int type, long triggerAtMillis, String tag, OnAlarmListener listener, - Handler targetHandler) { + public void setExact(@AlarmType int type, long triggerAtMillis, String tag, + OnAlarmListener listener, Handler targetHandler) { setImpl(type, triggerAtMillis, WINDOW_EXACT, 0, 0, null, listener, tag, targetHandler, null, null); } @@ -553,8 +561,8 @@ public class AlarmManager { * the given time. * @hide */ - public void setIdleUntil(int type, long triggerAtMillis, String tag, OnAlarmListener listener, - Handler targetHandler) { + public void setIdleUntil(@AlarmType int type, long triggerAtMillis, String tag, + OnAlarmListener listener, Handler targetHandler) { setImpl(type, triggerAtMillis, WINDOW_EXACT, 0, FLAG_IDLE_UNTIL, null, listener, tag, targetHandler, null, null); } @@ -590,8 +598,8 @@ public class AlarmManager { /** @hide */ @SystemApi - public void set(int type, long triggerAtMillis, long windowMillis, long intervalMillis, - PendingIntent operation, WorkSource workSource) { + public void set(@AlarmType int type, long triggerAtMillis, long windowMillis, + long intervalMillis, PendingIntent operation, WorkSource workSource) { setImpl(type, triggerAtMillis, windowMillis, intervalMillis, 0, operation, null, null, null, workSource, null); } @@ -606,8 +614,9 @@ public class AlarmManager { * * @hide */ - public void set(int type, long triggerAtMillis, long windowMillis, long intervalMillis, - String tag, OnAlarmListener listener, Handler targetHandler, WorkSource workSource) { + public void set(@AlarmType int type, long triggerAtMillis, long windowMillis, + long intervalMillis, String tag, OnAlarmListener listener, Handler targetHandler, + WorkSource workSource) { setImpl(type, triggerAtMillis, windowMillis, intervalMillis, 0, null, listener, tag, targetHandler, workSource, null); } @@ -623,15 +632,17 @@ public class AlarmManager { * @hide */ @SystemApi - public void set(int type, long triggerAtMillis, long windowMillis, long intervalMillis, - OnAlarmListener listener, Handler targetHandler, WorkSource workSource) { + public void set(@AlarmType int type, long triggerAtMillis, long windowMillis, + long intervalMillis, OnAlarmListener listener, Handler targetHandler, + WorkSource workSource) { setImpl(type, triggerAtMillis, windowMillis, intervalMillis, 0, null, listener, null, targetHandler, workSource, null); } - private void setImpl(int type, long triggerAtMillis, long windowMillis, long intervalMillis, - int flags, PendingIntent operation, final OnAlarmListener listener, String listenerTag, - Handler targetHandler, WorkSource workSource, AlarmClockInfo alarmClock) { + 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, + AlarmClockInfo alarmClock) { if (triggerAtMillis < 0) { /* NOTYET if (mAlwaysExact) { @@ -728,8 +739,7 @@ public class AlarmManager { * assured that it will get similar behavior on both current and older versions * of Android. * - * @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP}, - * {@link #RTC}, or {@link #RTC_WAKEUP}. + * @param type type of alarm. * @param triggerAtMillis time in milliseconds that the alarm should first * go off, using the appropriate clock (depending on the alarm type). This * is inexact: the alarm will not fire before this time, but there may be a @@ -763,7 +773,7 @@ public class AlarmManager { * @see #INTERVAL_HALF_DAY * @see #INTERVAL_DAY */ - public void setInexactRepeating(int type, long triggerAtMillis, + public void setInexactRepeating(@AlarmType int type, long triggerAtMillis, long intervalMillis, PendingIntent operation) { setImpl(type, triggerAtMillis, WINDOW_HEURISTIC, intervalMillis, 0, operation, null, null, null, null, null); @@ -795,8 +805,7 @@ public class AlarmManager { *

Regardless of the app's target SDK version, this call always allows batching of the * alarm.

* - * @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP}, - * {@link #RTC}, or {@link #RTC_WAKEUP}. + * @param type type of alarm. * @param triggerAtMillis time in milliseconds that the alarm should go * off, using the appropriate clock (depending on the alarm type). * @param operation Action to perform when the alarm goes off; @@ -814,7 +823,8 @@ public class AlarmManager { * @see #RTC * @see #RTC_WAKEUP */ - public void setAndAllowWhileIdle(int type, long triggerAtMillis, PendingIntent operation) { + public void setAndAllowWhileIdle(@AlarmType int type, long triggerAtMillis, + PendingIntent operation) { setImpl(type, triggerAtMillis, WINDOW_HEURISTIC, 0, FLAG_ALLOW_WHILE_IDLE, operation, null, null, null, null, null); } @@ -848,8 +858,7 @@ public class AlarmManager { * device is idle it may take even more liberties with scheduling in order to optimize * for battery life.

* - * @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP}, - * {@link #RTC}, or {@link #RTC_WAKEUP}. + * @param type type of alarm. * @param triggerAtMillis time in milliseconds that the alarm should go * off, using the appropriate clock (depending on the alarm type). * @param operation Action to perform when the alarm goes off; @@ -868,7 +877,8 @@ public class AlarmManager { * @see #RTC * @see #RTC_WAKEUP */ - public void setExactAndAllowWhileIdle(int type, long triggerAtMillis, PendingIntent operation) { + public void setExactAndAllowWhileIdle(@AlarmType int type, long triggerAtMillis, + PendingIntent operation) { setImpl(type, triggerAtMillis, WINDOW_EXACT, 0, FLAG_ALLOW_WHILE_IDLE, operation, null, null, null, null, null); } diff --git a/core/java/android/app/Notification.java b/core/java/android/app/Notification.java index 602cccb1070dc..2b4fb1956c424 100644 --- a/core/java/android/app/Notification.java +++ b/core/java/android/app/Notification.java @@ -676,7 +676,16 @@ public class Notification implements Parcelable * Finally, a notification can be made {@link #VISIBILITY_SECRET}, which will suppress its icon * and ticker until the user has bypassed the lockscreen. */ - public int visibility; + public @Visibility int visibility; + + /** @hide */ + @IntDef(prefix = { "VISIBILITY_" }, value = { + VISIBILITY_PUBLIC, + VISIBILITY_PRIVATE, + VISIBILITY_SECRET, + }) + @Retention(RetentionPolicy.SOURCE) + public @interface Visibility {} /** * Notification visibility: Show this notification in its entirety on all lockscreens. @@ -3545,12 +3554,9 @@ public class Notification implements Parcelable /** * Specify the value of {@link #visibility}. * - * @param visibility One of {@link #VISIBILITY_PRIVATE} (the default), - * {@link #VISIBILITY_SECRET}, or {@link #VISIBILITY_PUBLIC}. - * * @return The same Builder. */ - public Builder setVisibility(int visibility) { + public Builder setVisibility(@Visibility int visibility) { mN.visibility = visibility; return this; } diff --git a/core/java/android/app/NotificationChannel.java b/core/java/android/app/NotificationChannel.java index 9059daa62dc77..2dd33013ab8e4 100644 --- a/core/java/android/app/NotificationChannel.java +++ b/core/java/android/app/NotificationChannel.java @@ -162,10 +162,9 @@ public final class NotificationChannel implements Parcelable { * broadcast. The recommended maximum length is 40 characters; the value may be * truncated if it is too long. * @param importance The importance of the channel. This controls how interruptive notifications - * posted to this channel are. See e.g. - * {@link NotificationManager#IMPORTANCE_DEFAULT}. + * posted to this channel are. */ - public NotificationChannel(String id, CharSequence name, int importance) { + public NotificationChannel(String id, CharSequence name, @Importance int importance) { this.mId = getTrimmedString(id); this.mName = name != null ? getTrimmedString(name.toString()) : null; this.mImportance = importance; diff --git a/core/java/android/app/job/JobInfo.java b/core/java/android/app/job/JobInfo.java index 3538256761aab..007ea88d676cc 100644 --- a/core/java/android/app/job/JobInfo.java +++ b/core/java/android/app/job/JobInfo.java @@ -18,8 +18,10 @@ package android.app.job; import static android.util.TimeUtils.formatDuration; +import android.annotation.IntDef; import android.annotation.NonNull; import android.annotation.Nullable; +import android.annotation.RequiresPermission; import android.content.ClipData; import android.content.ComponentName; import android.net.Uri; @@ -30,6 +32,8 @@ import android.os.Parcelable; import android.os.PersistableBundle; import android.util.Log; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; import java.util.ArrayList; import java.util.Objects; @@ -43,6 +47,18 @@ import java.util.Objects; */ public class JobInfo implements Parcelable { private static String TAG = "JobInfo"; + + /** @hide */ + @IntDef(prefix = { "NETWORK_TYPE_" }, value = { + NETWORK_TYPE_NONE, + NETWORK_TYPE_ANY, + NETWORK_TYPE_UNMETERED, + NETWORK_TYPE_NOT_ROAMING, + NETWORK_TYPE_METERED, + }) + @Retention(RetentionPolicy.SOURCE) + public @interface NetworkType {} + /** Default. */ public static final int NETWORK_TYPE_NONE = 0; /** This job requires network connectivity. */ @@ -64,6 +80,14 @@ public class JobInfo implements Parcelable { */ public static final long MAX_BACKOFF_DELAY_MILLIS = 5 * 60 * 60 * 1000; // 5 hours. + /** @hide */ + @IntDef(prefix = { "BACKOFF_POLICY_" }, value = { + BACKOFF_POLICY_LINEAR, + BACKOFF_POLICY_EXPONENTIAL, + }) + @Retention(RetentionPolicy.SOURCE) + public @interface BackoffPolicy {} + /** * Linearly back-off a failed job. See * {@link android.app.job.JobInfo.Builder#setBackoffCriteria(long, int)} @@ -349,14 +373,8 @@ public class JobInfo implements Parcelable { /** * The kind of connectivity requirements that the job has. - * - * @return One of {@link android.app.job.JobInfo#NETWORK_TYPE_ANY}, - * {@link android.app.job.JobInfo#NETWORK_TYPE_NONE}, - * {@link android.app.job.JobInfo#NETWORK_TYPE_UNMETERED}, - * {@link android.app.job.JobInfo#NETWORK_TYPE_METERED}, or - * {@link android.app.job.JobInfo#NETWORK_TYPE_NOT_ROAMING}, */ - public int getNetworkType() { + public @NetworkType int getNetworkType() { return networkType; } @@ -421,11 +439,9 @@ public class JobInfo implements Parcelable { } /** - * One of either {@link android.app.job.JobInfo#BACKOFF_POLICY_EXPONENTIAL}, or - * {@link android.app.job.JobInfo#BACKOFF_POLICY_LINEAR}, depending on which criteria you set - * when creating this job. + * Return the backoff policy of this job. */ - public int getBackoffPolicy() { + public @BackoffPolicy int getBackoffPolicy() { return backoffPolicy; } @@ -692,6 +708,13 @@ public class JobInfo implements Parcelable { private final Uri mUri; private final int mFlags; + /** @hide */ + @Retention(RetentionPolicy.SOURCE) + @IntDef(flag = true, prefix = { "FLAG_" }, value = { + FLAG_NOTIFY_FOR_DESCENDANTS, + }) + public @interface Flags { } + /** * Flag for trigger: also trigger if any descendants of the given URI change. * Corresponds to the notifyForDescendants of @@ -702,10 +725,9 @@ public class JobInfo implements Parcelable { /** * Create a new trigger description. * @param uri The URI to observe. Must be non-null. - * @param flags Optional flags for the observer, either 0 or - * {@link #FLAG_NOTIFY_FOR_DESCENDANTS}. + * @param flags Flags for the observer. */ - public TriggerContentUri(@NonNull Uri uri, int flags) { + public TriggerContentUri(@NonNull Uri uri, @Flags int flags) { mUri = uri; mFlags = flags; } @@ -720,7 +742,7 @@ public class JobInfo implements Parcelable { /** * Return the flags supplied for the trigger. */ - public int getFlags() { + public @Flags int getFlags() { return mFlags; } @@ -886,7 +908,7 @@ public class JobInfo implements Parcelable { * job. If the network requested is not available your job will never run. See * {@link #setOverrideDeadline(long)} to change this behaviour. */ - public Builder setRequiredNetworkType(int networkType) { + public Builder setRequiredNetworkType(@NetworkType int networkType) { mNetworkType = networkType; return this; } @@ -1067,10 +1089,9 @@ public class JobInfo implements Parcelable { * mode. * @param initialBackoffMillis Millisecond time interval to wait initially when job has * failed. - * @param backoffPolicy is one of {@link #BACKOFF_POLICY_LINEAR} or - * {@link #BACKOFF_POLICY_EXPONENTIAL} */ - public Builder setBackoffCriteria(long initialBackoffMillis, int backoffPolicy) { + public Builder setBackoffCriteria(long initialBackoffMillis, + @BackoffPolicy int backoffPolicy) { mBackoffPolicySet = true; mInitialBackoffMillis = initialBackoffMillis; mBackoffPolicy = backoffPolicy; @@ -1078,13 +1099,12 @@ public class JobInfo implements Parcelable { } /** - * Set whether or not to persist this job across device reboots. This will only have an - * effect if your application holds the permission - * {@link android.Manifest.permission#RECEIVE_BOOT_COMPLETED}. Otherwise an exception will - * be thrown. - * @param isPersisted True to indicate that the job will be written to disk and loaded at - * boot. + * Set whether or not to persist this job across device reboots. + * + * @param isPersisted True to indicate that the job will be written to + * disk and loaded at boot. */ + @RequiresPermission(android.Manifest.permission.RECEIVE_BOOT_COMPLETED) public Builder setPersisted(boolean isPersisted) { mIsPersisted = isPersisted; return this; diff --git a/core/java/android/app/job/JobScheduler.java b/core/java/android/app/job/JobScheduler.java index 23f9eea65abe9..1768828eb76c7 100644 --- a/core/java/android/app/job/JobScheduler.java +++ b/core/java/android/app/job/JobScheduler.java @@ -16,6 +16,7 @@ package android.app.job; +import android.annotation.IntDef; import android.annotation.NonNull; import android.annotation.Nullable; import android.annotation.SystemApi; @@ -24,6 +25,8 @@ import android.content.Intent; import android.os.Bundle; import android.os.PersistableBundle; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; import java.util.List; /** @@ -51,6 +54,14 @@ import java.util.List; * Context.getSystemService(Context.JOB_SCHEDULER_SERVICE)}. */ public abstract class JobScheduler { + /** @hide */ + @IntDef(prefix = { "RESULT_" }, value = { + RESULT_FAILURE, + RESULT_SUCCESS, + }) + @Retention(RetentionPolicy.SOURCE) + public @interface Result {} + /** * Returned from {@link #schedule(JobInfo)} when an invalid parameter was supplied. This can occur * if the run-time for your job is too short, or perhaps the system can't resolve the @@ -70,9 +81,9 @@ public abstract class JobScheduler { * @param job The job you wish scheduled. See * {@link android.app.job.JobInfo.Builder JobInfo.Builder} for more detail on the sorts of jobs * you can schedule. - * @return An int representing ({@link #RESULT_SUCCESS} or {@link #RESULT_FAILURE}). + * @return the result of the schedule request. */ - public abstract int schedule(@NonNull JobInfo job); + public abstract @Result int schedule(@NonNull JobInfo job); /** * Similar to {@link #schedule}, but allows you to enqueue work for a new or existing @@ -107,9 +118,9 @@ public abstract class JobScheduler { * {@link android.app.job.JobInfo.Builder JobInfo.Builder} for more detail on the sorts of jobs * you can schedule. * @param work New work to enqueue. This will be available later when the job starts running. - * @return An int representing ({@link #RESULT_SUCCESS} or {@link #RESULT_FAILURE}). + * @return the result of the enqueue request. */ - public abstract int enqueue(@NonNull JobInfo job, @NonNull JobWorkItem work); + public abstract @Result int enqueue(@NonNull JobInfo job, @NonNull JobWorkItem work); /** * @@ -118,11 +129,10 @@ public abstract class JobScheduler { * used to track battery usage and appIdleState. * @param userId User on behalf of whom this job is to be scheduled. * @param tag Debugging tag for dumps associated with this job (instead of the service class) - * @return {@link #RESULT_SUCCESS} or {@link #RESULT_FAILURE} * @hide */ @SystemApi - public abstract int scheduleAsPackage(@NonNull JobInfo job, @NonNull String packageName, + public abstract @Result int scheduleAsPackage(@NonNull JobInfo job, @NonNull String packageName, int userId, String tag); /** diff --git a/core/java/android/content/ComponentName.java b/core/java/android/content/ComponentName.java index 8aeb22dddd1e2..ea6b7690b4319 100644 --- a/core/java/android/content/ComponentName.java +++ b/core/java/android/content/ComponentName.java @@ -16,6 +16,8 @@ package android.content; +import android.annotation.NonNull; +import android.annotation.Nullable; import android.os.Parcel; import android.os.Parcelable; import android.text.TextUtils; @@ -52,7 +54,7 @@ public final class ComponentName implements Parcelable, Cloneable, Comparablepkg that * implements the component. Can not be null. */ - public ComponentName(String pkg, String cls) { + public ComponentName(@NonNull String pkg, @NonNull String cls) { if (pkg == null) throw new NullPointerException("package name is null"); if (cls == null) throw new NullPointerException("class name is null"); mPackage = pkg; @@ -110,7 +112,7 @@ public final class ComponentName implements Parcelable, Cloneable, Comparablepkg that * implements the component. */ - public ComponentName(Context pkg, String cls) { + public ComponentName(@NonNull Context pkg, @NonNull String cls) { if (cls == null) throw new NullPointerException("class name is null"); mPackage = pkg.getPackageName(); mClass = cls; @@ -124,7 +126,7 @@ public final class ComponentName implements Parcelable, Cloneable, Comparable cls) { + public ComponentName(@NonNull Context pkg, @NonNull Class cls) { mPackage = pkg.getPackageName(); mClass = cls.getName(); } @@ -136,14 +138,14 @@ public final class ComponentName implements Parcelable, Cloneable, Comparable= str.length()) { return null; diff --git a/core/java/android/content/Context.java b/core/java/android/content/Context.java index 1585d2164cd19..42ef871ef3ba8 100644 --- a/core/java/android/content/Context.java +++ b/core/java/android/content/Context.java @@ -85,6 +85,37 @@ import java.lang.annotation.RetentionPolicy; * broadcasting and receiving intents, etc. */ public abstract class Context { + /** @hide */ + @IntDef(flag = true, prefix = { "MODE_" }, value = { + MODE_PRIVATE, + MODE_WORLD_READABLE, + MODE_WORLD_WRITEABLE, + MODE_APPEND, + }) + @Retention(RetentionPolicy.SOURCE) + public @interface FileMode {} + + /** @hide */ + @IntDef(flag = true, prefix = { "MODE_" }, value = { + MODE_PRIVATE, + MODE_WORLD_READABLE, + MODE_WORLD_WRITEABLE, + MODE_MULTI_PROCESS, + }) + @Retention(RetentionPolicy.SOURCE) + public @interface PreferencesMode {} + + /** @hide */ + @IntDef(flag = true, prefix = { "MODE_" }, value = { + MODE_PRIVATE, + MODE_WORLD_READABLE, + MODE_WORLD_WRITEABLE, + MODE_ENABLE_WRITE_AHEAD_LOGGING, + MODE_NO_LOCALIZED_COLLATORS, + }) + @Retention(RetentionPolicy.SOURCE) + public @interface DatabaseMode {} + /** * File creation mode: the default mode, where the created file can only * be accessed by the calling application (or all applications sharing the @@ -720,15 +751,14 @@ public abstract class Context { * @param name Desired preferences file. If a preferences file by this name * does not exist, it will be created when you retrieve an * editor (SharedPreferences.edit()) and then commit changes (Editor.commit()). - * @param mode Operating mode. Use 0 or {@link #MODE_PRIVATE} for the - * default operation. + * @param mode Operating mode. * * @return The single {@link SharedPreferences} instance that can be used * to retrieve and modify the preference values. * * @see #MODE_PRIVATE */ - public abstract SharedPreferences getSharedPreferences(String name, int mode); + public abstract SharedPreferences getSharedPreferences(String name, @PreferencesMode int mode); /** * Retrieve and hold the contents of the preferences file, returning @@ -740,8 +770,7 @@ public abstract class Context { * @param file Desired preferences file. If a preferences file by this name * does not exist, it will be created when you retrieve an * editor (SharedPreferences.edit()) and then commit changes (Editor.commit()). - * @param mode Operating mode. Use 0 or {@link #MODE_PRIVATE} for the - * default operation. + * @param mode Operating mode. * * @return The single {@link SharedPreferences} instance that can be used * to retrieve and modify the preference values. @@ -750,7 +779,7 @@ public abstract class Context { * @see #MODE_PRIVATE * @removed */ - public abstract SharedPreferences getSharedPreferences(File file, int mode); + public abstract SharedPreferences getSharedPreferences(File file, @PreferencesMode int mode); /** * Move an existing shared preferences file from the given source storage @@ -805,9 +834,7 @@ public abstract class Context { * * @param name The name of the file to open; can not contain path * separators. - * @param mode Operating mode. Use 0 or {@link #MODE_PRIVATE} for the - * default operation. Use {@link #MODE_APPEND} to append to an - * existing file. + * @param mode Operating mode. * @return The resulting {@link FileOutputStream}. * @see #MODE_APPEND * @see #MODE_PRIVATE @@ -816,7 +843,7 @@ public abstract class Context { * @see #deleteFile * @see java.io.FileOutputStream#FileOutputStream(String) */ - public abstract FileOutputStream openFileOutput(String name, int mode) + public abstract FileOutputStream openFileOutput(String name, @FileMode int mode) throws FileNotFoundException; /** @@ -1413,26 +1440,21 @@ public abstract class Context { * * @param name Name of the directory to retrieve. This is a directory * that is created as part of your application data. - * @param mode Operating mode. Use 0 or {@link #MODE_PRIVATE} for the - * default operation. + * @param mode Operating mode. * * @return A {@link File} object for the requested directory. The directory * will have been created if it does not already exist. * * @see #openFileOutput(String, int) */ - public abstract File getDir(String name, int mode); + public abstract File getDir(String name, @FileMode int mode); /** * Open a new private SQLiteDatabase associated with this Context's * application package. Create the database file if it doesn't exist. * * @param name The name (unique in the application package) of the database. - * @param mode Operating mode. Use 0 or {@link #MODE_PRIVATE} for the - * default operation. Use - * {@link #MODE_ENABLE_WRITE_AHEAD_LOGGING} to enable write-ahead - * logging by default. Use {@link #MODE_NO_LOCALIZED_COLLATORS} - * to disable localized collators. + * @param mode Operating mode. * @param factory An optional factory class that is called to instantiate a * cursor when query is called. * @return The contents of a newly created database with the given name. @@ -1444,7 +1466,7 @@ public abstract class Context { * @see #deleteDatabase */ public abstract SQLiteDatabase openOrCreateDatabase(String name, - int mode, CursorFactory factory); + @DatabaseMode int mode, CursorFactory factory); /** * Open a new private SQLiteDatabase associated with this Context's @@ -1455,11 +1477,7 @@ public abstract class Context { *

* * @param name The name (unique in the application package) of the database. - * @param mode Operating mode. Use 0 or {@link #MODE_PRIVATE} for the - * default operation. Use - * {@link #MODE_ENABLE_WRITE_AHEAD_LOGGING} to enable write-ahead - * logging by default. Use {@link #MODE_NO_LOCALIZED_COLLATORS} - * to disable localized collators. + * @param mode Operating mode. * @param factory An optional factory class that is called to instantiate a * cursor when query is called. * @param errorHandler the {@link DatabaseErrorHandler} to be used when @@ -1475,7 +1493,7 @@ public abstract class Context { * @see #deleteDatabase */ public abstract SQLiteDatabase openOrCreateDatabase(String name, - int mode, CursorFactory factory, + @DatabaseMode int mode, CursorFactory factory, @Nullable DatabaseErrorHandler errorHandler); /** @@ -1777,9 +1795,9 @@ public abstract class Context { * @see #startActivity(Intent) * @see #startIntentSender(IntentSender, Intent, int, int, int, Bundle) */ - public abstract void startIntentSender(IntentSender intent, - Intent fillInIntent, int flagsMask, int flagsValues, int extraFlags) - throws IntentSender.SendIntentException; + public abstract void startIntentSender(IntentSender intent, @Nullable Intent fillInIntent, + @Intent.MutableFlags int flagsMask, @Intent.MutableFlags int flagsValues, + int extraFlags) throws IntentSender.SendIntentException; /** * Like {@link #startActivity(Intent, Bundle)}, but taking a IntentSender @@ -1806,9 +1824,9 @@ public abstract class Context { * @see #startActivity(Intent, Bundle) * @see #startIntentSender(IntentSender, Intent, int, int, int) */ - public abstract void startIntentSender(IntentSender intent, - @Nullable Intent fillInIntent, int flagsMask, int flagsValues, int extraFlags, - Bundle options) throws IntentSender.SendIntentException; + public abstract void startIntentSender(IntentSender intent, @Nullable Intent fillInIntent, + @Intent.MutableFlags int flagsMask, @Intent.MutableFlags int flagsValues, + int extraFlags, @Nullable Bundle options) throws IntentSender.SendIntentException; /** * Broadcast the given intent to all interested BroadcastReceivers. This @@ -2192,10 +2210,6 @@ public abstract class Context { * all other ways, this behaves the same as * {@link #sendBroadcast(Intent)}. * - *

You must hold the {@link android.Manifest.permission#BROADCAST_STICKY} - * permission in order to use this API. If you do not hold that - * permission, {@link SecurityException} will be thrown. - * * @deprecated Sticky broadcasts should not be used. They provide no security (anyone * can access them), no protection (anyone can modify them), and many other problems. * The recommended pattern is to use a non-sticky broadcast to report that something @@ -2210,6 +2224,7 @@ public abstract class Context { * @see #sendStickyOrderedBroadcast(Intent, BroadcastReceiver, Handler, int, String, Bundle) */ @Deprecated + @RequiresPermission(android.Manifest.permission.BROADCAST_STICKY) public abstract void sendStickyBroadcast(@RequiresPermission Intent intent); /** @@ -2259,6 +2274,7 @@ public abstract class Context { * @see android.app.Activity#RESULT_OK */ @Deprecated + @RequiresPermission(android.Manifest.permission.BROADCAST_STICKY) public abstract void sendStickyOrderedBroadcast(@RequiresPermission Intent intent, BroadcastReceiver resultReceiver, @Nullable Handler scheduler, int initialCode, @Nullable String initialData, @@ -2268,10 +2284,6 @@ public abstract class Context { *

Remove the data previously sent with {@link #sendStickyBroadcast}, * so that it is as if the sticky broadcast had never happened. * - *

You must hold the {@link android.Manifest.permission#BROADCAST_STICKY} - * permission in order to use this API. If you do not hold that - * permission, {@link SecurityException} will be thrown. - * * @deprecated Sticky broadcasts should not be used. They provide no security (anyone * can access them), no protection (anyone can modify them), and many other problems. * The recommended pattern is to use a non-sticky broadcast to report that something @@ -2283,6 +2295,7 @@ public abstract class Context { * @see #sendStickyBroadcast */ @Deprecated + @RequiresPermission(android.Manifest.permission.BROADCAST_STICKY) public abstract void removeStickyBroadcast(@RequiresPermission Intent intent); /** @@ -3048,7 +3061,7 @@ public abstract class Context { * @see android.os.HardwarePropertiesManager * @see #HARDWARE_PROPERTIES_SERVICE */ - public abstract Object getSystemService(@ServiceName @NonNull String name); + public abstract @Nullable Object getSystemService(@ServiceName @NonNull String name); /** * Return the handle to a system-level service by class. @@ -3078,7 +3091,7 @@ public abstract class Context { * @return The service or null if the class is not a supported system service. */ @SuppressWarnings("unchecked") - public final T getSystemService(Class serviceClass) { + public final @Nullable T getSystemService(@NonNull Class serviceClass) { // Because subclasses may override getSystemService(String) we cannot // perform a lookup by class alone. We must first map the class to its // service name then invoke the string-based method. @@ -3092,7 +3105,7 @@ public abstract class Context { * @param serviceClass The class of the desired service. * @return The service name or null if the class is not a supported system service. */ - public abstract String getSystemServiceName(Class serviceClass); + public abstract @Nullable String getSystemServiceName(@NonNull Class serviceClass); /** * Use with {@link #getSystemService} to retrieve a @@ -4181,10 +4194,12 @@ public abstract class Context { * @see #checkCallingUriPermission */ @CheckResult(suggest="#enforceUriPermission(Uri,int,int,String)") + @PackageManager.PermissionResult public abstract int checkUriPermission(Uri uri, int pid, int uid, @Intent.AccessUriMode int modeFlags); /** @hide */ + @PackageManager.PermissionResult public abstract int checkUriPermission(Uri uri, int pid, int uid, @Intent.AccessUriMode int modeFlags, IBinder callerToken); @@ -4208,6 +4223,7 @@ public abstract class Context { * @see #checkUriPermission(Uri, int, int, int) */ @CheckResult(suggest="#enforceCallingUriPermission(Uri,int,String)") + @PackageManager.PermissionResult public abstract int checkCallingUriPermission(Uri uri, @Intent.AccessUriMode int modeFlags); /** @@ -4226,6 +4242,7 @@ public abstract class Context { * @see #checkCallingUriPermission */ @CheckResult(suggest="#enforceCallingOrSelfUriPermission(Uri,int,String)") + @PackageManager.PermissionResult public abstract int checkCallingOrSelfUriPermission(Uri uri, @Intent.AccessUriMode int modeFlags); @@ -4250,6 +4267,7 @@ public abstract class Context { * {@link PackageManager#PERMISSION_DENIED} if it is not. */ @CheckResult(suggest="#enforceUriPermission(Uri,String,String,int,int,int,String)") + @PackageManager.PermissionResult public abstract int checkUriPermission(@Nullable Uri uri, @Nullable String readPermission, @Nullable String writePermission, int pid, int uid, @Intent.AccessUriMode int modeFlags); @@ -4336,8 +4354,14 @@ public abstract class Context { @Nullable String message); /** @hide */ - @IntDef(flag = true, - value = {CONTEXT_INCLUDE_CODE, CONTEXT_IGNORE_SECURITY, CONTEXT_RESTRICTED}) + @IntDef(flag = true, prefix = { "CONTEXT_" }, value = { + CONTEXT_INCLUDE_CODE, + CONTEXT_IGNORE_SECURITY, + CONTEXT_RESTRICTED, + CONTEXT_DEVICE_PROTECTED_STORAGE, + CONTEXT_CREDENTIAL_PROTECTED_STORAGE, + CONTEXT_REGISTER_PACKAGE, + }) @Retention(RetentionPolicy.SOURCE) public @interface CreatePackageOptions {} @@ -4409,8 +4433,7 @@ public abstract class Context { * {@link #CONTEXT_INCLUDE_CODE} for more information}. * * @param packageName Name of the application's package. - * @param flags Option flags, one of {@link #CONTEXT_INCLUDE_CODE} - * or {@link #CONTEXT_IGNORE_SECURITY}. + * @param flags Option flags. * * @return A {@link Context} for the application. * @@ -4429,7 +4452,7 @@ public abstract class Context { * @hide */ public abstract Context createPackageContextAsUser( - String packageName, int flags, UserHandle user) + String packageName, @CreatePackageOptions int flags, UserHandle user) throws PackageManager.NameNotFoundException; /** @@ -4438,7 +4461,7 @@ public abstract class Context { * @hide */ public abstract Context createApplicationContext(ApplicationInfo application, - int flags) throws PackageManager.NameNotFoundException; + @CreatePackageOptions int flags) throws PackageManager.NameNotFoundException; /** * Return a new Context object for the given split name. The new Context has a ClassLoader and diff --git a/core/java/android/content/Intent.java b/core/java/android/content/Intent.java index b6f9ac97e7275..9c87ff27caafa 100644 --- a/core/java/android/content/Intent.java +++ b/core/java/android/content/Intent.java @@ -19,6 +19,8 @@ package android.content; import android.annotation.AnyRes; import android.annotation.BroadcastBehavior; import android.annotation.IntDef; +import android.annotation.NonNull; +import android.annotation.Nullable; import android.annotation.SdkConstant; import android.annotation.SdkConstant.SdkConstantType; import android.annotation.SystemApi; @@ -4903,6 +4905,96 @@ public class Intent implements Parcelable, Cloneable { | Intent.FLAG_GRANT_WRITE_URI_PERMISSION)) != 0; } + /** @hide */ + @IntDef(flag = true, prefix = { "FLAG_" }, value = { + FLAG_GRANT_READ_URI_PERMISSION, + FLAG_GRANT_WRITE_URI_PERMISSION, + FLAG_FROM_BACKGROUND, + FLAG_DEBUG_LOG_RESOLUTION, + FLAG_EXCLUDE_STOPPED_PACKAGES, + FLAG_INCLUDE_STOPPED_PACKAGES, + FLAG_GRANT_PERSISTABLE_URI_PERMISSION, + FLAG_GRANT_PREFIX_URI_PERMISSION, + FLAG_DEBUG_TRIAGED_MISSING, + FLAG_IGNORE_EPHEMERAL, + FLAG_ACTIVITY_NO_HISTORY, + FLAG_ACTIVITY_SINGLE_TOP, + FLAG_ACTIVITY_NEW_TASK, + FLAG_ACTIVITY_MULTIPLE_TASK, + FLAG_ACTIVITY_CLEAR_TOP, + FLAG_ACTIVITY_FORWARD_RESULT, + FLAG_ACTIVITY_PREVIOUS_IS_TOP, + FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS, + FLAG_ACTIVITY_BROUGHT_TO_FRONT, + FLAG_ACTIVITY_RESET_TASK_IF_NEEDED, + FLAG_ACTIVITY_LAUNCHED_FROM_HISTORY, + FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET, + FLAG_ACTIVITY_NEW_DOCUMENT, + FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET, + FLAG_ACTIVITY_NO_USER_ACTION, + FLAG_ACTIVITY_REORDER_TO_FRONT, + FLAG_ACTIVITY_NO_ANIMATION, + FLAG_ACTIVITY_CLEAR_TASK, + FLAG_ACTIVITY_TASK_ON_HOME, + FLAG_ACTIVITY_RETAIN_IN_RECENTS, + FLAG_ACTIVITY_LAUNCH_ADJACENT, + FLAG_RECEIVER_REGISTERED_ONLY, + FLAG_RECEIVER_REPLACE_PENDING, + FLAG_RECEIVER_FOREGROUND, + FLAG_RECEIVER_NO_ABORT, + FLAG_RECEIVER_REGISTERED_ONLY_BEFORE_BOOT, + FLAG_RECEIVER_BOOT_UPGRADE, + FLAG_RECEIVER_INCLUDE_BACKGROUND, + FLAG_RECEIVER_EXCLUDE_BACKGROUND, + FLAG_RECEIVER_FROM_SHELL, + FLAG_RECEIVER_VISIBLE_TO_INSTANT_APPS, + }) + @Retention(RetentionPolicy.SOURCE) + public @interface Flags {} + + /** @hide */ + @IntDef(flag = true, prefix = { "FLAG_" }, value = { + FLAG_FROM_BACKGROUND, + FLAG_DEBUG_LOG_RESOLUTION, + FLAG_EXCLUDE_STOPPED_PACKAGES, + FLAG_INCLUDE_STOPPED_PACKAGES, + FLAG_DEBUG_TRIAGED_MISSING, + FLAG_IGNORE_EPHEMERAL, + FLAG_ACTIVITY_NO_HISTORY, + FLAG_ACTIVITY_SINGLE_TOP, + FLAG_ACTIVITY_NEW_TASK, + FLAG_ACTIVITY_MULTIPLE_TASK, + FLAG_ACTIVITY_CLEAR_TOP, + FLAG_ACTIVITY_FORWARD_RESULT, + FLAG_ACTIVITY_PREVIOUS_IS_TOP, + FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS, + FLAG_ACTIVITY_BROUGHT_TO_FRONT, + FLAG_ACTIVITY_RESET_TASK_IF_NEEDED, + FLAG_ACTIVITY_LAUNCHED_FROM_HISTORY, + FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET, + FLAG_ACTIVITY_NEW_DOCUMENT, + FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET, + FLAG_ACTIVITY_NO_USER_ACTION, + FLAG_ACTIVITY_REORDER_TO_FRONT, + FLAG_ACTIVITY_NO_ANIMATION, + FLAG_ACTIVITY_CLEAR_TASK, + FLAG_ACTIVITY_TASK_ON_HOME, + FLAG_ACTIVITY_RETAIN_IN_RECENTS, + FLAG_ACTIVITY_LAUNCH_ADJACENT, + FLAG_RECEIVER_REGISTERED_ONLY, + FLAG_RECEIVER_REPLACE_PENDING, + FLAG_RECEIVER_FOREGROUND, + FLAG_RECEIVER_NO_ABORT, + FLAG_RECEIVER_REGISTERED_ONLY_BEFORE_BOOT, + FLAG_RECEIVER_BOOT_UPGRADE, + FLAG_RECEIVER_INCLUDE_BACKGROUND, + FLAG_RECEIVER_EXCLUDE_BACKGROUND, + FLAG_RECEIVER_FROM_SHELL, + FLAG_RECEIVER_VISIBLE_TO_INSTANT_APPS, + }) + @Retention(RetentionPolicy.SOURCE) + public @interface MutableFlags {} + /** * If set, the recipient of this Intent will be granted permission to * perform read operations on the URI in the Intent's data and any URIs @@ -5369,6 +5461,15 @@ public class Intent implements Parcelable, Cloneable { // --------------------------------------------------------------------- // toUri() and parseUri() options. + /** @hide */ + @IntDef(flag = true, prefix = { "URI_" }, value = { + URI_ALLOW_UNSAFE, + URI_ANDROID_APP_SCHEME, + URI_INTENT_SCHEME, + }) + @Retention(RetentionPolicy.SOURCE) + public @interface UriFlags {} + /** * Flag for use with {@link #toUri} and {@link #parseUri}: the URI string * always has the "intent:" scheme. This syntax can be used when you want @@ -5538,7 +5639,7 @@ public class Intent implements Parcelable, Cloneable { * Make a clone of only the parts of the Intent that are relevant for * filter matching: the action, data, type, component, and categories. */ - public Intent cloneFilter() { + public @NonNull Intent cloneFilter() { return new Intent(this, false); } @@ -5727,8 +5828,7 @@ public class Intent implements Parcelable, Cloneable { * the scheme and full path. * * @param uri The URI to turn into an Intent. - * @param flags Additional processing flags. Either 0, - * {@link #URI_INTENT_SCHEME}, or {@link #URI_ANDROID_APP_SCHEME}. + * @param flags Additional processing flags. * * @return Intent The newly created Intent object. * @@ -5738,7 +5838,7 @@ public class Intent implements Parcelable, Cloneable { * * @see #toUri */ - public static Intent parseUri(String uri, int flags) throws URISyntaxException { + public static Intent parseUri(String uri, @UriFlags int flags) throws URISyntaxException { int i = 0; try { final boolean androidApp = uri.startsWith("android-app:"); @@ -6568,7 +6668,7 @@ public class Intent implements Parcelable, Cloneable { * * @see #setAction */ - public String getAction() { + public @Nullable String getAction() { return mAction; } @@ -6583,7 +6683,7 @@ public class Intent implements Parcelable, Cloneable { * @see #getScheme * @see #setData */ - public Uri getData() { + public @Nullable Uri getData() { return mData; } @@ -6591,7 +6691,7 @@ public class Intent implements Parcelable, Cloneable { * The same as {@link #getData()}, but returns the URI as an encoded * String. */ - public String getDataString() { + public @Nullable String getDataString() { return mData != null ? mData.toString() : null; } @@ -6607,7 +6707,7 @@ public class Intent implements Parcelable, Cloneable { * * @see #getData */ - public String getScheme() { + public @Nullable String getScheme() { return mData != null ? mData.getScheme() : null; } @@ -6621,7 +6721,7 @@ public class Intent implements Parcelable, Cloneable { * @see #resolveType(ContentResolver) * @see #setType */ - public String getType() { + public @Nullable String getType() { return mType; } @@ -6636,7 +6736,7 @@ public class Intent implements Parcelable, Cloneable { * @see #getType * @see #resolveType(ContentResolver) */ - public String resolveType(Context context) { + public @Nullable String resolveType(@NonNull Context context) { return resolveType(context.getContentResolver()); } @@ -6654,7 +6754,7 @@ public class Intent implements Parcelable, Cloneable { * @see #getType * @see #resolveType(Context) */ - public String resolveType(ContentResolver resolver) { + public @Nullable String resolveType(@NonNull ContentResolver resolver) { if (mType != null) { return mType; } @@ -6678,7 +6778,7 @@ public class Intent implements Parcelable, Cloneable { * @return The MIME type of this intent, or null if it is unknown or not * needed. */ - public String resolveTypeIfNeeded(ContentResolver resolver) { + public @Nullable String resolveTypeIfNeeded(@NonNull ContentResolver resolver) { if (mComponent != null) { return mType; } @@ -6718,7 +6818,7 @@ public class Intent implements Parcelable, Cloneable { * * @see #setSelector */ - public Intent getSelector() { + public @Nullable Intent getSelector() { return mSelector; } @@ -6728,7 +6828,7 @@ public class Intent implements Parcelable, Cloneable { * * @see #setClipData */ - public ClipData getClipData() { + public @Nullable ClipData getClipData() { return mClipData; } @@ -6754,7 +6854,7 @@ public class Intent implements Parcelable, Cloneable { * @param loader a ClassLoader, or null to use the default loader * at the time of unmarshalling. */ - public void setExtrasClassLoader(ClassLoader loader) { + public void setExtrasClassLoader(@Nullable ClassLoader loader) { if (mExtras != null) { mExtras.setClassLoader(loader); } @@ -7275,7 +7375,7 @@ public class Intent implements Parcelable, Cloneable { * @return the map of all extras previously added with putExtra(), * or null if none have been added. */ - public Bundle getExtras() { + public @Nullable Bundle getExtras() { return (mExtras != null) ? new Bundle(mExtras) : null; @@ -7296,11 +7396,12 @@ public class Intent implements Parcelable, Cloneable { * normally just set them with {@link #setFlags} and let the system * take the appropriate action with them. * - * @return int The currently set flags. - * + * @return The currently set flags. * @see #setFlags + * @see #addFlags + * @see #removeFlags */ - public int getFlags() { + public @Flags int getFlags() { return mFlags; } @@ -7320,7 +7421,7 @@ public class Intent implements Parcelable, Cloneable { * @see #resolveActivity * @see #setPackage */ - public String getPackage() { + public @Nullable String getPackage() { return mPackage; } @@ -7335,7 +7436,7 @@ public class Intent implements Parcelable, Cloneable { * @see #resolveActivity * @see #setComponent */ - public ComponentName getComponent() { + public @Nullable ComponentName getComponent() { return mComponent; } @@ -7344,7 +7445,7 @@ public class Intent implements Parcelable, Cloneable { * used as a hint to the receiver for animations and the like. Null means that there * is no source bounds. */ - public Rect getSourceBounds() { + public @Nullable Rect getSourceBounds() { return mSourceBounds; } @@ -7395,7 +7496,7 @@ public class Intent implements Parcelable, Cloneable { * @see #getComponent * @see #resolveActivityInfo */ - public ComponentName resolveActivity(PackageManager pm) { + public ComponentName resolveActivity(@NonNull PackageManager pm) { if (mComponent != null) { return mComponent; } @@ -7427,7 +7528,8 @@ public class Intent implements Parcelable, Cloneable { * * @see #resolveActivity */ - public ActivityInfo resolveActivityInfo(PackageManager pm, int flags) { + public ActivityInfo resolveActivityInfo(@NonNull PackageManager pm, + @PackageManager.ComponentInfoFlags int flags) { ActivityInfo ai = null; if (mComponent != null) { try { @@ -7453,7 +7555,8 @@ public class Intent implements Parcelable, Cloneable { * there are no matches. * @hide */ - public ComponentName resolveSystemService(PackageManager pm, int flags) { + public @Nullable ComponentName resolveSystemService(@NonNull PackageManager pm, + @PackageManager.ComponentInfoFlags int flags) { if (mComponent != null) { return mComponent; } @@ -7490,7 +7593,7 @@ public class Intent implements Parcelable, Cloneable { * * @see #getAction */ - public Intent setAction(String action) { + public @NonNull Intent setAction(@Nullable String action) { mAction = action != null ? action.intern() : null; return this; } @@ -7516,7 +7619,7 @@ public class Intent implements Parcelable, Cloneable { * @see #setDataAndNormalize * @see android.net.Uri#normalizeScheme() */ - public Intent setData(Uri data) { + public @NonNull Intent setData(@Nullable Uri data) { mData = data; mType = null; return this; @@ -7544,7 +7647,7 @@ public class Intent implements Parcelable, Cloneable { * @see #setType * @see android.net.Uri#normalizeScheme */ - public Intent setDataAndNormalize(Uri data) { + public @NonNull Intent setDataAndNormalize(@NonNull Uri data) { return setData(data.normalizeScheme()); } @@ -7573,7 +7676,7 @@ public class Intent implements Parcelable, Cloneable { * @see #setDataAndType * @see #normalizeMimeType */ - public Intent setType(String type) { + public @NonNull Intent setType(@Nullable String type) { mData = null; mType = type; return this; @@ -7604,7 +7707,7 @@ public class Intent implements Parcelable, Cloneable { * @see #setData * @see #normalizeMimeType */ - public Intent setTypeAndNormalize(String type) { + public @NonNull Intent setTypeAndNormalize(@Nullable String type) { return setType(normalizeMimeType(type)); } @@ -7633,7 +7736,7 @@ public class Intent implements Parcelable, Cloneable { * @see android.net.Uri#normalizeScheme * @see #setDataAndTypeAndNormalize */ - public Intent setDataAndType(Uri data, String type) { + public @NonNull Intent setDataAndType(@Nullable Uri data, @Nullable String type) { mData = data; mType = type; return this; @@ -7664,7 +7767,7 @@ public class Intent implements Parcelable, Cloneable { * @see #normalizeMimeType * @see android.net.Uri#normalizeScheme */ - public Intent setDataAndTypeAndNormalize(Uri data, String type) { + public @NonNull Intent setDataAndTypeAndNormalize(@NonNull Uri data, @Nullable String type) { return setDataAndType(data.normalizeScheme(), normalizeMimeType(type)); } @@ -7684,7 +7787,7 @@ public class Intent implements Parcelable, Cloneable { * @see #hasCategory * @see #removeCategory */ - public Intent addCategory(String category) { + public @NonNull Intent addCategory(String category) { if (mCategories == null) { mCategories = new ArraySet(); } @@ -7739,7 +7842,7 @@ public class Intent implements Parcelable, Cloneable { * @param selector The desired selector Intent; set to null to not use * a special selector. */ - public void setSelector(Intent selector) { + public void setSelector(@Nullable Intent selector) { if (selector == this) { throw new IllegalArgumentException( "Intent being set as a selector of itself"); @@ -7778,7 +7881,7 @@ public class Intent implements Parcelable, Cloneable { * * @param clip The new clip to set. May be null to clear the current clip. */ - public void setClipData(ClipData clip) { + public void setClipData(@Nullable ClipData clip) { mClipData = clip; } @@ -7811,7 +7914,7 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getBooleanExtra(String, boolean) */ - public Intent putExtra(String name, boolean value) { + public @NonNull Intent putExtra(String name, boolean value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -7834,7 +7937,7 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getByteExtra(String, byte) */ - public Intent putExtra(String name, byte value) { + public @NonNull Intent putExtra(String name, byte value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -7857,7 +7960,7 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getCharExtra(String, char) */ - public Intent putExtra(String name, char value) { + public @NonNull Intent putExtra(String name, char value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -7880,7 +7983,7 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getShortExtra(String, short) */ - public Intent putExtra(String name, short value) { + public @NonNull Intent putExtra(String name, short value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -7903,7 +8006,7 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getIntExtra(String, int) */ - public Intent putExtra(String name, int value) { + public @NonNull Intent putExtra(String name, int value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -7926,7 +8029,7 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getLongExtra(String, long) */ - public Intent putExtra(String name, long value) { + public @NonNull Intent putExtra(String name, long value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -7949,7 +8052,7 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getFloatExtra(String, float) */ - public Intent putExtra(String name, float value) { + public @NonNull Intent putExtra(String name, float value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -7972,7 +8075,7 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getDoubleExtra(String, double) */ - public Intent putExtra(String name, double value) { + public @NonNull Intent putExtra(String name, double value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -7995,7 +8098,7 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getStringExtra(String) */ - public Intent putExtra(String name, String value) { + public @NonNull Intent putExtra(String name, String value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -8018,7 +8121,7 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getCharSequenceExtra(String) */ - public Intent putExtra(String name, CharSequence value) { + public @NonNull Intent putExtra(String name, CharSequence value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -8041,7 +8144,7 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getParcelableExtra(String) */ - public Intent putExtra(String name, Parcelable value) { + public @NonNull Intent putExtra(String name, Parcelable value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -8064,7 +8167,7 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getParcelableArrayExtra(String) */ - public Intent putExtra(String name, Parcelable[] value) { + public @NonNull Intent putExtra(String name, Parcelable[] value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -8087,7 +8190,8 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getParcelableArrayListExtra(String) */ - public Intent putParcelableArrayListExtra(String name, ArrayList value) { + public @NonNull Intent putParcelableArrayListExtra(String name, + ArrayList value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -8110,7 +8214,7 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getIntegerArrayListExtra(String) */ - public Intent putIntegerArrayListExtra(String name, ArrayList value) { + public @NonNull Intent putIntegerArrayListExtra(String name, ArrayList value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -8133,7 +8237,7 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getStringArrayListExtra(String) */ - public Intent putStringArrayListExtra(String name, ArrayList value) { + public @NonNull Intent putStringArrayListExtra(String name, ArrayList value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -8156,7 +8260,8 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getCharSequenceArrayListExtra(String) */ - public Intent putCharSequenceArrayListExtra(String name, ArrayList value) { + public @NonNull Intent putCharSequenceArrayListExtra(String name, + ArrayList value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -8179,7 +8284,7 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getSerializableExtra(String) */ - public Intent putExtra(String name, Serializable value) { + public @NonNull Intent putExtra(String name, Serializable value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -8202,7 +8307,7 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getBooleanArrayExtra(String) */ - public Intent putExtra(String name, boolean[] value) { + public @NonNull Intent putExtra(String name, boolean[] value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -8225,7 +8330,7 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getByteArrayExtra(String) */ - public Intent putExtra(String name, byte[] value) { + public @NonNull Intent putExtra(String name, byte[] value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -8248,7 +8353,7 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getShortArrayExtra(String) */ - public Intent putExtra(String name, short[] value) { + public @NonNull Intent putExtra(String name, short[] value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -8271,7 +8376,7 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getCharArrayExtra(String) */ - public Intent putExtra(String name, char[] value) { + public @NonNull Intent putExtra(String name, char[] value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -8294,7 +8399,7 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getIntArrayExtra(String) */ - public Intent putExtra(String name, int[] value) { + public @NonNull Intent putExtra(String name, int[] value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -8317,7 +8422,7 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getLongArrayExtra(String) */ - public Intent putExtra(String name, long[] value) { + public @NonNull Intent putExtra(String name, long[] value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -8340,7 +8445,7 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getFloatArrayExtra(String) */ - public Intent putExtra(String name, float[] value) { + public @NonNull Intent putExtra(String name, float[] value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -8363,7 +8468,7 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getDoubleArrayExtra(String) */ - public Intent putExtra(String name, double[] value) { + public @NonNull Intent putExtra(String name, double[] value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -8386,7 +8491,7 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getStringArrayExtra(String) */ - public Intent putExtra(String name, String[] value) { + public @NonNull Intent putExtra(String name, String[] value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -8409,7 +8514,7 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getCharSequenceArrayExtra(String) */ - public Intent putExtra(String name, CharSequence[] value) { + public @NonNull Intent putExtra(String name, CharSequence[] value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -8432,7 +8537,7 @@ public class Intent implements Parcelable, Cloneable { * @see #removeExtra * @see #getBundleExtra(String) */ - public Intent putExtra(String name, Bundle value) { + public @NonNull Intent putExtra(String name, Bundle value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -8459,7 +8564,7 @@ public class Intent implements Parcelable, Cloneable { * @hide */ @Deprecated - public Intent putExtra(String name, IBinder value) { + public @NonNull Intent putExtra(String name, IBinder value) { if (mExtras == null) { mExtras = new Bundle(); } @@ -8474,7 +8579,7 @@ public class Intent implements Parcelable, Cloneable { * * @see #putExtra */ - public Intent putExtras(Intent src) { + public @NonNull Intent putExtras(@NonNull Intent src) { if (src.mExtras != null) { if (mExtras == null) { mExtras = new Bundle(src.mExtras); @@ -8495,7 +8600,7 @@ public class Intent implements Parcelable, Cloneable { * @see #putExtra * @see #removeExtra */ - public Intent putExtras(Bundle extras) { + public @NonNull Intent putExtras(@NonNull Bundle extras) { if (mExtras == null) { mExtras = new Bundle(); } @@ -8510,7 +8615,7 @@ public class Intent implements Parcelable, Cloneable { * @param src The exact extras contained in this Intent are copied * into the target intent, replacing any that were previously there. */ - public Intent replaceExtras(Intent src) { + public @NonNull Intent replaceExtras(@NonNull Intent src) { mExtras = src.mExtras != null ? new Bundle(src.mExtras) : null; return this; } @@ -8522,7 +8627,7 @@ public class Intent implements Parcelable, Cloneable { * @param extras The new set of extras in the Intent, or null to erase * all extras. */ - public Intent replaceExtras(Bundle extras) { + public @NonNull Intent replaceExtras(@NonNull Bundle extras) { mExtras = extras != null ? new Bundle(extras) : null; return this; } @@ -8555,41 +8660,13 @@ public class Intent implements Parcelable, Cloneable { * the behavior of your application. * * @param flags The desired flags. - * * @return Returns the same Intent object, for chaining multiple calls * into a single statement. - * * @see #getFlags * @see #addFlags * @see #removeFlags - * - * @see #FLAG_GRANT_READ_URI_PERMISSION - * @see #FLAG_GRANT_WRITE_URI_PERMISSION - * @see #FLAG_GRANT_PERSISTABLE_URI_PERMISSION - * @see #FLAG_GRANT_PREFIX_URI_PERMISSION - * @see #FLAG_DEBUG_LOG_RESOLUTION - * @see #FLAG_FROM_BACKGROUND - * @see #FLAG_ACTIVITY_BROUGHT_TO_FRONT - * @see #FLAG_ACTIVITY_CLEAR_TASK - * @see #FLAG_ACTIVITY_CLEAR_TOP - * @see #FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET - * @see #FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS - * @see #FLAG_ACTIVITY_FORWARD_RESULT - * @see #FLAG_ACTIVITY_LAUNCHED_FROM_HISTORY - * @see #FLAG_ACTIVITY_MULTIPLE_TASK - * @see #FLAG_ACTIVITY_NEW_DOCUMENT - * @see #FLAG_ACTIVITY_NEW_TASK - * @see #FLAG_ACTIVITY_NO_ANIMATION - * @see #FLAG_ACTIVITY_NO_HISTORY - * @see #FLAG_ACTIVITY_NO_USER_ACTION - * @see #FLAG_ACTIVITY_PREVIOUS_IS_TOP - * @see #FLAG_ACTIVITY_RESET_TASK_IF_NEEDED - * @see #FLAG_ACTIVITY_REORDER_TO_FRONT - * @see #FLAG_ACTIVITY_SINGLE_TOP - * @see #FLAG_ACTIVITY_TASK_ON_HOME - * @see #FLAG_RECEIVER_REGISTERED_ONLY */ - public Intent setFlags(int flags) { + public @NonNull Intent setFlags(@Flags int flags) { mFlags = flags; return this; } @@ -8600,36 +8677,11 @@ public class Intent implements Parcelable, Cloneable { * @param flags The new flags to set. * @return Returns the same Intent object, for chaining multiple calls into * a single statement. - * @see #setFlags(int) - * @see #removeFlags(int) - * - * @see #FLAG_GRANT_READ_URI_PERMISSION - * @see #FLAG_GRANT_WRITE_URI_PERMISSION - * @see #FLAG_GRANT_PERSISTABLE_URI_PERMISSION - * @see #FLAG_GRANT_PREFIX_URI_PERMISSION - * @see #FLAG_DEBUG_LOG_RESOLUTION - * @see #FLAG_FROM_BACKGROUND - * @see #FLAG_ACTIVITY_BROUGHT_TO_FRONT - * @see #FLAG_ACTIVITY_CLEAR_TASK - * @see #FLAG_ACTIVITY_CLEAR_TOP - * @see #FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET - * @see #FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS - * @see #FLAG_ACTIVITY_FORWARD_RESULT - * @see #FLAG_ACTIVITY_LAUNCHED_FROM_HISTORY - * @see #FLAG_ACTIVITY_MULTIPLE_TASK - * @see #FLAG_ACTIVITY_NEW_DOCUMENT - * @see #FLAG_ACTIVITY_NEW_TASK - * @see #FLAG_ACTIVITY_NO_ANIMATION - * @see #FLAG_ACTIVITY_NO_HISTORY - * @see #FLAG_ACTIVITY_NO_USER_ACTION - * @see #FLAG_ACTIVITY_PREVIOUS_IS_TOP - * @see #FLAG_ACTIVITY_RESET_TASK_IF_NEEDED - * @see #FLAG_ACTIVITY_REORDER_TO_FRONT - * @see #FLAG_ACTIVITY_SINGLE_TOP - * @see #FLAG_ACTIVITY_TASK_ON_HOME - * @see #FLAG_RECEIVER_REGISTERED_ONLY + * @see #setFlags + * @see #getFlags + * @see #removeFlags */ - public Intent addFlags(int flags) { + public @NonNull Intent addFlags(@Flags int flags) { mFlags |= flags; return this; } @@ -8638,36 +8690,11 @@ public class Intent implements Parcelable, Cloneable { * Remove these flags from the intent. * * @param flags The flags to remove. - * @see #setFlags(int) - * @see #addFlags(int) - * - * @see #FLAG_GRANT_READ_URI_PERMISSION - * @see #FLAG_GRANT_WRITE_URI_PERMISSION - * @see #FLAG_GRANT_PERSISTABLE_URI_PERMISSION - * @see #FLAG_GRANT_PREFIX_URI_PERMISSION - * @see #FLAG_DEBUG_LOG_RESOLUTION - * @see #FLAG_FROM_BACKGROUND - * @see #FLAG_ACTIVITY_BROUGHT_TO_FRONT - * @see #FLAG_ACTIVITY_CLEAR_TASK - * @see #FLAG_ACTIVITY_CLEAR_TOP - * @see #FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET - * @see #FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS - * @see #FLAG_ACTIVITY_FORWARD_RESULT - * @see #FLAG_ACTIVITY_LAUNCHED_FROM_HISTORY - * @see #FLAG_ACTIVITY_MULTIPLE_TASK - * @see #FLAG_ACTIVITY_NEW_DOCUMENT - * @see #FLAG_ACTIVITY_NEW_TASK - * @see #FLAG_ACTIVITY_NO_ANIMATION - * @see #FLAG_ACTIVITY_NO_HISTORY - * @see #FLAG_ACTIVITY_NO_USER_ACTION - * @see #FLAG_ACTIVITY_PREVIOUS_IS_TOP - * @see #FLAG_ACTIVITY_RESET_TASK_IF_NEEDED - * @see #FLAG_ACTIVITY_REORDER_TO_FRONT - * @see #FLAG_ACTIVITY_SINGLE_TOP - * @see #FLAG_ACTIVITY_TASK_ON_HOME - * @see #FLAG_RECEIVER_REGISTERED_ONLY + * @see #setFlags + * @see #getFlags + * @see #addFlags */ - public void removeFlags(int flags) { + public void removeFlags(@Flags int flags) { mFlags &= ~flags; } @@ -8687,7 +8714,7 @@ public class Intent implements Parcelable, Cloneable { * @see #getPackage * @see #resolveActivity */ - public Intent setPackage(String packageName) { + public @NonNull Intent setPackage(@Nullable String packageName) { if (packageName != null && mSelector != null) { throw new IllegalArgumentException( "Can't set package name when selector is already set"); @@ -8719,7 +8746,7 @@ public class Intent implements Parcelable, Cloneable { * @see #getComponent * @see #resolveActivity */ - public Intent setComponent(ComponentName component) { + public @NonNull Intent setComponent(@Nullable ComponentName component) { mComponent = component; return this; } @@ -8739,7 +8766,8 @@ public class Intent implements Parcelable, Cloneable { * @see #setComponent * @see #setClass */ - public Intent setClassName(Context packageContext, String className) { + public @NonNull Intent setClassName(@NonNull Context packageContext, + @NonNull String className) { mComponent = new ComponentName(packageContext, className); return this; } @@ -8759,7 +8787,7 @@ public class Intent implements Parcelable, Cloneable { * @see #setComponent * @see #setClass */ - public Intent setClassName(String packageName, String className) { + public @NonNull Intent setClassName(@NonNull String packageName, @NonNull String className) { mComponent = new ComponentName(packageName, className); return this; } @@ -8778,7 +8806,7 @@ public class Intent implements Parcelable, Cloneable { * * @see #setComponent */ - public Intent setClass(Context packageContext, Class cls) { + public @NonNull Intent setClass(@NonNull Context packageContext, @NonNull Class cls) { mComponent = new ComponentName(packageContext, cls); return this; } @@ -8788,7 +8816,7 @@ public class Intent implements Parcelable, Cloneable { * used as a hint to the receiver for animations and the like. Null means that there * is no source bounds. */ - public void setSourceBounds(Rect r) { + public void setSourceBounds(@Nullable Rect r) { if (r != null) { mSourceBounds = new Rect(r); } else { @@ -8909,7 +8937,7 @@ public class Intent implements Parcelable, Cloneable { * changed. */ @FillInFlags - public int fillIn(Intent other, @FillInFlags int flags) { + public int fillIn(@NonNull Intent other, @FillInFlags int flags) { int changes = 0; boolean mayHaveCopiedUris = false; if (other.mAction != null @@ -9257,13 +9285,12 @@ public class Intent implements Parcelable, Cloneable { *

You can convert the returned string back to an Intent with * {@link #getIntent}. * - * @param flags Additional operating flags. Either 0, - * {@link #URI_INTENT_SCHEME}, or {@link #URI_ANDROID_APP_SCHEME}. + * @param flags Additional operating flags. * * @return Returns a URI encoding URI string describing the entire contents * of the Intent. */ - public String toUri(int flags) { + public String toUri(@UriFlags int flags) { StringBuilder uri = new StringBuilder(128); if ((flags&URI_ANDROID_APP_SCHEME) != 0) { if (mPackage == null) { @@ -9530,7 +9557,8 @@ public class Intent implements Parcelable, Cloneable { * @throws XmlPullParserException If there was an XML parsing error. * @throws IOException If there was an I/O error. */ - public static Intent parseIntent(Resources resources, XmlPullParser parser, AttributeSet attrs) + public static @NonNull Intent parseIntent(@NonNull Resources resources, + @NonNull XmlPullParser parser, AttributeSet attrs) throws XmlPullParserException, IOException { Intent intent = new Intent(); @@ -9677,7 +9705,7 @@ public class Intent implements Parcelable, Cloneable { * @see #setType * @see #setTypeAndNormalize */ - public static String normalizeMimeType(String type) { + public static @Nullable String normalizeMimeType(@Nullable String type) { if (type == null) { return null; } diff --git a/core/java/android/content/pm/PackageManager.java b/core/java/android/content/pm/PackageManager.java index 47d79cfba40ca..ecaf7ebe07d28 100644 --- a/core/java/android/content/pm/PackageManager.java +++ b/core/java/android/content/pm/PackageManager.java @@ -522,6 +522,18 @@ public abstract class PackageManager { */ public static final int PERMISSION_DENIED = -1; + /** @hide */ + @IntDef(prefix = { "SIGNATURE_" }, value = { + SIGNATURE_MATCH, + SIGNATURE_NEITHER_SIGNED, + SIGNATURE_FIRST_NOT_SIGNED, + SIGNATURE_SECOND_NOT_SIGNED, + SIGNATURE_NO_MATCH, + SIGNATURE_UNKNOWN_PACKAGE, + }) + @Retention(RetentionPolicy.SOURCE) + public @interface SignatureResult {} + /** * Signature check result: this is returned by {@link #checkSignatures} * if all signatures on the two packages match. @@ -558,11 +570,25 @@ public abstract class PackageManager { */ public static final int SIGNATURE_UNKNOWN_PACKAGE = -4; + /** @hide */ + @IntDef(prefix = { "COMPONENT_ENABLED_STATE_" }, value = { + COMPONENT_ENABLED_STATE_DEFAULT, + COMPONENT_ENABLED_STATE_ENABLED, + COMPONENT_ENABLED_STATE_DISABLED, + COMPONENT_ENABLED_STATE_DISABLED_USER, + COMPONENT_ENABLED_STATE_DISABLED_UNTIL_USED, + }) + @Retention(RetentionPolicy.SOURCE) + public @interface EnabledState {} + /** - * Flag for {@link #setApplicationEnabledSetting(String, int, int)} - * and {@link #setComponentEnabledSetting(ComponentName, int, int)}: This - * component or application is in its default enabled state (as specified - * in its manifest). + * Flag for {@link #setApplicationEnabledSetting(String, int, int)} and + * {@link #setComponentEnabledSetting(ComponentName, int, int)}: This + * component or application is in its default enabled state (as specified in + * its manifest). + *

+ * Explicitly setting the component state to this value restores it's + * enabled state to whatever is set in the manifest. */ public static final int COMPONENT_ENABLED_STATE_DEFAULT = 0; @@ -764,6 +790,13 @@ public abstract class PackageManager { */ public static final int INSTALL_ALLOCATE_AGGRESSIVE = 0x00008000; + /** @hide */ + @IntDef(flag = true, prefix = { "DONT_KILL_APP" }, value = { + DONT_KILL_APP + }) + @Retention(RetentionPolicy.SOURCE) + public @interface EnabledFlags {} + /** * Flag parameter for * {@link #setComponentEnabledSetting(android.content.ComponentName, int, int)} to indicate @@ -2871,7 +2904,7 @@ public abstract class PackageManager { * does not contain such an activity, or if packageName is not * recognized. */ - public abstract Intent getLaunchIntentForPackage(String packageName); + public abstract @Nullable Intent getLaunchIntentForPackage(@NonNull String packageName); /** * Return a "good" intent to launch a front-door Leanback activity in a @@ -2885,7 +2918,7 @@ public abstract class PackageManager { * the main Leanback activity in the package, or null if the package * does not contain such an activity. */ - public abstract Intent getLeanbackLaunchIntentForPackage(String packageName); + public abstract @Nullable Intent getLeanbackLaunchIntentForPackage(@NonNull String packageName); /** * Return an array of all of the POSIX secondary group IDs that have been @@ -2901,7 +2934,7 @@ public abstract class PackageManager { * @throws NameNotFoundException if a package with the given name cannot be * found on the system. */ - public abstract int[] getPackageGids(String packageName) + public abstract int[] getPackageGids(@NonNull String packageName) throws NameNotFoundException; /** @@ -3189,7 +3222,7 @@ public abstract class PackageManager { * @see #PERMISSION_DENIED */ @CheckResult - public abstract int checkPermission(String permName, String pkgName); + public abstract @PermissionResult int checkPermission(String permName, String pkgName); /** * Checks whether a particular permissions has been revoked for a @@ -3419,12 +3452,9 @@ public abstract class PackageManager { * #SIGNATURE_NO_MATCH} or {@link #SIGNATURE_UNKNOWN_PACKAGE}). * * @see #checkSignatures(int, int) - * @see #SIGNATURE_MATCH - * @see #SIGNATURE_NO_MATCH - * @see #SIGNATURE_UNKNOWN_PACKAGE */ @CheckResult - public abstract int checkSignatures(String pkg1, String pkg2); + public abstract @SignatureResult int checkSignatures(String pkg1, String pkg2); /** * Like {@link #checkSignatures(String, String)}, but takes UIDs of @@ -3442,12 +3472,9 @@ public abstract class PackageManager { * #SIGNATURE_NO_MATCH} or {@link #SIGNATURE_UNKNOWN_PACKAGE}). * * @see #checkSignatures(String, String) - * @see #SIGNATURE_MATCH - * @see #SIGNATURE_NO_MATCH - * @see #SIGNATURE_UNKNOWN_PACKAGE */ @CheckResult - public abstract int checkSignatures(int uid1, int uid2); + public abstract @SignatureResult int checkSignatures(int uid1, int uid2); /** * Retrieve the names of all packages that are associated with a particular @@ -3881,8 +3908,8 @@ public abstract class PackageManager { * included by one of the specifics intents. If there are * no matching activities, an empty list is returned. */ - public abstract List queryIntentActivityOptions( - ComponentName caller, Intent[] specifics, Intent intent, @ResolveInfoFlags int flags); + public abstract List queryIntentActivityOptions(@Nullable ComponentName caller, + @Nullable Intent[] specifics, Intent intent, @ResolveInfoFlags int flags); /** * Retrieve all receivers that can handle a broadcast of the given intent. @@ -5136,18 +5163,11 @@ public abstract class PackageManager { * manifest. * * @param componentName The component to enable - * @param newState The new enabled state for the component. The legal values for this state - * are: - * {@link #COMPONENT_ENABLED_STATE_ENABLED}, - * {@link #COMPONENT_ENABLED_STATE_DISABLED} - * and - * {@link #COMPONENT_ENABLED_STATE_DEFAULT} - * The last one removes the setting, thereby restoring the component's state to - * whatever was set in it's manifest (or enabled, by default). - * @param flags Optional behavior flags: {@link #DONT_KILL_APP} or 0. + * @param newState The new enabled state for the component. + * @param flags Optional behavior flags. */ public abstract void setComponentEnabledSetting(ComponentName componentName, - int newState, int flags); + @EnabledState int newState, @EnabledFlags int flags); /** * Return the enabled setting for a package component (activity, @@ -5157,14 +5177,10 @@ public abstract class PackageManager { * the value originally specified in the manifest has not been modified. * * @param componentName The component to retrieve. - * @return Returns the current enabled state for the component. May - * be one of {@link #COMPONENT_ENABLED_STATE_ENABLED}, - * {@link #COMPONENT_ENABLED_STATE_DISABLED}, or - * {@link #COMPONENT_ENABLED_STATE_DEFAULT}. The last one means the - * component's enabled state is based on the original information in - * the manifest as found in {@link ComponentInfo}. + * @return Returns the current enabled state for the component. */ - public abstract int getComponentEnabledSetting(ComponentName componentName); + public abstract @EnabledState int getComponentEnabledSetting( + ComponentName componentName); /** * Set the enabled setting for an application @@ -5174,18 +5190,11 @@ public abstract class PackageManager { * {@link #setComponentEnabledSetting} for any of the application's components. * * @param packageName The package name of the application to enable - * @param newState The new enabled state for the component. The legal values for this state - * are: - * {@link #COMPONENT_ENABLED_STATE_ENABLED}, - * {@link #COMPONENT_ENABLED_STATE_DISABLED} - * and - * {@link #COMPONENT_ENABLED_STATE_DEFAULT} - * The last one removes the setting, thereby restoring the applications's state to - * whatever was set in its manifest (or enabled, by default). - * @param flags Optional behavior flags: {@link #DONT_KILL_APP} or 0. + * @param newState The new enabled state for the application. + * @param flags Optional behavior flags. */ public abstract void setApplicationEnabledSetting(String packageName, - int newState, int flags); + @EnabledState int newState, @EnabledFlags int flags); /** * Return the enabled setting for an application. This returns @@ -5195,15 +5204,10 @@ public abstract class PackageManager { * the value originally specified in the manifest has not been modified. * * @param packageName The package name of the application to retrieve. - * @return Returns the current enabled state for the application. May - * be one of {@link #COMPONENT_ENABLED_STATE_ENABLED}, - * {@link #COMPONENT_ENABLED_STATE_DISABLED}, or - * {@link #COMPONENT_ENABLED_STATE_DEFAULT}. The last one means the - * application's enabled state is based on the original information in - * the manifest as found in {@link ApplicationInfo}. + * @return Returns the current enabled state for the application. * @throws IllegalArgumentException if the named package does not exist. */ - public abstract int getApplicationEnabledSetting(String packageName); + public abstract @EnabledState int getApplicationEnabledSetting(String packageName); /** * Flush the package restrictions for a given user to disk. This forces the package restrictions diff --git a/core/java/android/net/ConnectivityManager.java b/core/java/android/net/ConnectivityManager.java index 768beea94e188..b854cbf2d0f8a 100644 --- a/core/java/android/net/ConnectivityManager.java +++ b/core/java/android/net/ConnectivityManager.java @@ -19,6 +19,7 @@ import static com.android.internal.util.Preconditions.checkNotNull; import android.annotation.IntDef; import android.annotation.Nullable; +import android.annotation.RequiresPermission; import android.annotation.SdkConstant; import android.annotation.SdkConstant.SdkConstantType; import android.annotation.SystemApi; @@ -742,8 +743,6 @@ public class ConnectivityManager { /** * Retrieves the current preferred network type. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * * @return an integer representing the preferred network type * @@ -753,6 +752,7 @@ public class ConnectivityManager { * the networks to describe their precedence. */ @Deprecated + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public int getNetworkPreference() { return TYPE_NONE; } @@ -763,12 +763,11 @@ public class ConnectivityManager { * You should always check {@link NetworkInfo#isConnected()} before initiating * network traffic. This may return {@code null} when there is no default * network. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * * @return a {@link NetworkInfo} object for the current default network * or {@code null} if no default network is currently active */ + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public NetworkInfo getActiveNetworkInfo() { try { return mService.getActiveNetworkInfo(); @@ -783,12 +782,11 @@ public class ConnectivityManager { * network disconnects, the returned {@code Network} object will no longer * be usable. This will return {@code null} when there is no default * network. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * * @return a {@link Network} object for the current default network or * {@code null} if no default network is currently active */ + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public Network getActiveNetwork() { try { return mService.getActiveNetwork(); @@ -803,14 +801,13 @@ public class ConnectivityManager { * network disconnects, the returned {@code Network} object will no longer * be usable. This will return {@code null} when there is no default * network for the UID. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#CONNECTIVITY_INTERNAL}. * * @return a {@link Network} object for the current default network for the * given UID or {@code null} if no default network is currently active * * @hide */ + @RequiresPermission(android.Manifest.permission.CONNECTIVITY_INTERNAL) public Network getActiveNetworkForUid(int uid) { return getActiveNetworkForUid(uid, false); } @@ -871,8 +868,6 @@ public class ConnectivityManager { * Returns details about the currently active default data network * for a given uid. This is for internal use only to avoid spying * other apps. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#CONNECTIVITY_INTERNAL} * * @return a {@link NetworkInfo} object for the current default network * for the given uid or {@code null} if no default network is @@ -880,6 +875,7 @@ public class ConnectivityManager { * * {@hide} */ + @RequiresPermission(android.Manifest.permission.CONNECTIVITY_INTERNAL) public NetworkInfo getActiveNetworkInfoForUid(int uid) { return getActiveNetworkInfoForUid(uid, false); } @@ -896,8 +892,6 @@ public class ConnectivityManager { /** * Returns connection status information about a particular * network type. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * * @param networkType integer specifying which networkType in * which you're interested. @@ -910,6 +904,7 @@ public class ConnectivityManager { * {@link #getNetworkInfo(android.net.Network)} instead. */ @Deprecated + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public NetworkInfo getNetworkInfo(int networkType) { try { return mService.getNetworkInfo(networkType); @@ -921,8 +916,6 @@ public class ConnectivityManager { /** * Returns connection status information about a particular * Network. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * * @param network {@link Network} specifying which network * in which you're interested. @@ -930,6 +923,7 @@ public class ConnectivityManager { * network or {@code null} if the {@code Network} * is not valid. */ + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public NetworkInfo getNetworkInfo(Network network) { return getNetworkInfoForUid(network, Process.myUid(), false); } @@ -946,8 +940,6 @@ public class ConnectivityManager { /** * Returns connection status information about all network * types supported by the device. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * * @return an array of {@link NetworkInfo} objects. Check each * {@link NetworkInfo#getType} for which type each applies. @@ -957,6 +949,7 @@ public class ConnectivityManager { * {@link #getNetworkInfo(android.net.Network)} instead. */ @Deprecated + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public NetworkInfo[] getAllNetworkInfo() { try { return mService.getAllNetworkInfo(); @@ -969,15 +962,13 @@ public class ConnectivityManager { * Returns the {@link Network} object currently serving a given type, or * null if the given type is not connected. * - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. - * * @hide * @deprecated This method does not support multiple connected networks * of the same type. Use {@link #getAllNetworks} and * {@link #getNetworkInfo(android.net.Network)} instead. */ @Deprecated + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public Network getNetworkForType(int networkType) { try { return mService.getNetworkForType(networkType); @@ -989,11 +980,10 @@ public class ConnectivityManager { /** * Returns an array of all {@link Network} currently tracked by the * framework. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * * @return an array of {@link Network} objects. */ + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public Network[] getAllNetworks() { try { return mService.getAllNetworks(); @@ -1017,8 +1007,6 @@ public class ConnectivityManager { /** * Returns the IP information for the current default network. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * * @return a {@link LinkProperties} object describing the IP info * for the current default network, or {@code null} if there @@ -1026,6 +1014,7 @@ public class ConnectivityManager { * * {@hide} */ + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public LinkProperties getActiveLinkProperties() { try { return mService.getActiveLinkProperties(); @@ -1036,8 +1025,6 @@ public class ConnectivityManager { /** * Returns the IP information for a given network type. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * * @param networkType the network type of interest. * @return a {@link LinkProperties} object describing the IP info @@ -1051,6 +1038,7 @@ public class ConnectivityManager { * {@link #getLinkProperties(android.net.Network)} instead. */ @Deprecated + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public LinkProperties getLinkProperties(int networkType) { try { return mService.getLinkPropertiesForType(networkType); @@ -1062,12 +1050,11 @@ public class ConnectivityManager { /** * Get the {@link LinkProperties} for the given {@link Network}. This * will return {@code null} if the network is unknown. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * * @param network The {@link Network} object identifying the network in question. * @return The {@link LinkProperties} for the network, or {@code null}. */ + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public LinkProperties getLinkProperties(Network network) { try { return mService.getLinkProperties(network); @@ -1079,12 +1066,11 @@ public class ConnectivityManager { /** * Get the {@link android.net.NetworkCapabilities} for the given {@link Network}. This * will return {@code null} if the network is unknown. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * * @param network The {@link Network} object identifying the network in question. * @return The {@link android.net.NetworkCapabilities} for the network, or {@code null}. */ + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public NetworkCapabilities getNetworkCapabilities(Network network) { try { return mService.getNetworkCapabilities(network); @@ -1727,11 +1713,9 @@ public class ConnectivityManager { * network is active. Quota status can change rapidly, so these values * shouldn't be cached. * - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. - * * @hide */ + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public NetworkQuotaInfo getActiveNetworkQuotaInfo() { try { return mService.getActiveNetworkQuotaInfo(); @@ -1929,13 +1913,12 @@ public class ConnectivityManager { /** * Get the set of tetherable, available interfaces. This list is limited by * device configuration and current interface existence. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * * @return an array of 0 or more Strings of tetherable interface names. * * {@hide} */ + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public String[] getTetherableIfaces() { try { return mService.getTetherableIfaces(); @@ -1946,13 +1929,12 @@ public class ConnectivityManager { /** * Get the set of tethered interfaces. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * * @return an array of 0 or more String of currently tethered interface names. * * {@hide} */ + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public String[] getTetheredIfaces() { try { return mService.getTetheredIfaces(); @@ -1968,14 +1950,13 @@ public class ConnectivityManager { * may cause them to reset to the available state. * {@link ConnectivityManager#getLastTetherError} can be used to get more * information on the cause of the errors. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * * @return an array of 0 or more String indicating the interface names * which failed to tether. * * {@hide} */ + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public String[] getTetheringErroredIfaces() { try { return mService.getTetheringErroredIfaces(); @@ -2060,14 +2041,13 @@ public class ConnectivityManager { * Check if the device allows for tethering. It may be disabled via * {@code ro.tether.denied} system property, Settings.TETHER_SUPPORTED or * due to device configuration. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * * @return a boolean - {@code true} indicating Tethering is supported. * * {@hide} */ @SystemApi + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public boolean isTetheringSupported() { try { return mService.isTetheringSupported(); @@ -2171,14 +2151,13 @@ public class ConnectivityManager { * Get the list of regular expressions that define any tetherable * USB network interfaces. If USB tethering is not supported by the * device, this list should be empty. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * * @return an array of 0 or more regular expression Strings defining * what interfaces are considered tetherable usb interfaces. * * {@hide} */ + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public String[] getTetherableUsbRegexs() { try { return mService.getTetherableUsbRegexs(); @@ -2191,14 +2170,13 @@ public class ConnectivityManager { * Get the list of regular expressions that define any tetherable * Wifi network interfaces. If Wifi tethering is not supported by the * device, this list should be empty. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * * @return an array of 0 or more regular expression Strings defining * what interfaces are considered tetherable wifi interfaces. * * {@hide} */ + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public String[] getTetherableWifiRegexs() { try { return mService.getTetherableWifiRegexs(); @@ -2211,14 +2189,13 @@ public class ConnectivityManager { * Get the list of regular expressions that define any tetherable * Bluetooth network interfaces. If Bluetooth tethering is not supported by the * device, this list should be empty. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * * @return an array of 0 or more regular expression Strings defining * what interfaces are considered tetherable bluetooth interfaces. * * {@hide} */ + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public String[] getTetherableBluetoothRegexs() { try { return mService.getTetherableBluetoothRegexs(); @@ -2280,8 +2257,6 @@ public class ConnectivityManager { /** * Get a more detailed error code after a Tethering or Untethering * request asynchronously failed. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * * @param iface The name of the interface of interest * @return error The error code of the last error tethering or untethering the named @@ -2289,6 +2264,7 @@ public class ConnectivityManager { * * {@hide} */ + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public int getLastTetherError(String iface) { try { return mService.getLastTetherError(iface); @@ -2362,13 +2338,12 @@ public class ConnectivityManager { * for typical HTTP proxies - they are general network dependent. However if you're * doing something unusual like general internal filtering this may be useful. On * a private network where the proxy is not accessible, you may break HTTP using this. - *

This method requires the caller to hold the permission - * android.Manifest.permission#CONNECTIVITY_INTERNAL. * * @param p A {@link ProxyInfo} object defining the new global * HTTP proxy. A {@code null} value will clear the global HTTP proxy. * @hide */ + @RequiresPermission(android.Manifest.permission.CONNECTIVITY_INTERNAL) public void setGlobalProxy(ProxyInfo p) { try { mService.setGlobalProxy(p); @@ -2434,14 +2409,13 @@ public class ConnectivityManager { * hardware supports it. For example a GSM phone without a SIM * should still return {@code true} for mobile data, but a wifi only * tablet would return {@code false}. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * * @param networkType The network type we'd like to check * @return {@code true} if supported, else {@code false} * * @hide */ + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public boolean isNetworkSupported(int networkType) { try { return mService.isNetworkSupported(networkType); @@ -2457,12 +2431,11 @@ public class ConnectivityManager { * battery/performance issues. You should check this before doing large * data transfers, and warn the user or delay the operation until another * network is available. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * * @return {@code true} if large transfers should be avoided, otherwise * {@code false}. */ + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public boolean isActiveNetworkMetered() { try { return mService.isActiveNetworkMetered(); @@ -2541,13 +2514,12 @@ public class ConnectivityManager { /** * Set the value for enabling/disabling airplane mode - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#CONNECTIVITY_INTERNAL}. * * @param enable whether to enable airplane mode or not * * @hide */ + @RequiresPermission(android.Manifest.permission.CONNECTIVITY_INTERNAL) public void setAirplaneMode(boolean enable) { try { mService.setAirplaneMode(enable); @@ -3225,14 +3197,13 @@ public class ConnectivityManager { * Registers to receive notifications about all networks which satisfy the given * {@link NetworkRequest}. The callbacks will continue to be called until * either the application exits or link #unregisterNetworkCallback(NetworkCallback)} is called. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * * @param request {@link NetworkRequest} describing this request. * @param networkCallback The {@link NetworkCallback} that the system will call as suitable * networks change state. * The callback is invoked on the default internal Handler. */ + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public void registerNetworkCallback(NetworkRequest request, NetworkCallback networkCallback) { registerNetworkCallback(request, networkCallback, getDefaultHandler()); } @@ -3241,14 +3212,13 @@ public class ConnectivityManager { * Registers to receive notifications about all networks which satisfy the given * {@link NetworkRequest}. The callbacks will continue to be called until * either the application exits or link #unregisterNetworkCallback(NetworkCallback)} is called. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * * @param request {@link NetworkRequest} describing this request. * @param networkCallback The {@link NetworkCallback} that the system will call as suitable * networks change state. * @param handler {@link Handler} to specify the thread upon which the callback will be invoked. */ + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public void registerNetworkCallback( NetworkRequest request, NetworkCallback networkCallback, Handler handler) { CallbackHandler cbHandler = new CallbackHandler(handler); @@ -3280,13 +3250,12 @@ public class ConnectivityManager { *

* The request may be released normally by calling * {@link #unregisterNetworkCallback(android.app.PendingIntent)}. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * @param request {@link NetworkRequest} describing this request. * @param operation Action to perform when the network is available (corresponds * to the {@link NetworkCallback#onAvailable} call. Typically * comes from {@link PendingIntent#getBroadcast}. Cannot be null. */ + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public void registerNetworkCallback(NetworkRequest request, PendingIntent operation) { checkPendingIntent(operation); try { @@ -3300,13 +3269,12 @@ public class ConnectivityManager { * Registers to receive notifications about changes in the system default network. The callbacks * will continue to be called until either the application exits or * {@link #unregisterNetworkCallback(NetworkCallback)} is called. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * * @param networkCallback The {@link NetworkCallback} that the system will call as the * system default network changes. * The callback is invoked on the default internal Handler. */ + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public void registerDefaultNetworkCallback(NetworkCallback networkCallback) { registerDefaultNetworkCallback(networkCallback, getDefaultHandler()); } @@ -3315,13 +3283,12 @@ public class ConnectivityManager { * Registers to receive notifications about changes in the system default network. The callbacks * will continue to be called until either the application exits or * {@link #unregisterNetworkCallback(NetworkCallback)} is called. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * * @param networkCallback The {@link NetworkCallback} that the system will call as the * system default network changes. * @param handler {@link Handler} to specify the thread upon which the callback will be invoked. */ + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public void registerDefaultNetworkCallback(NetworkCallback networkCallback, Handler handler) { // This works because if the NetworkCapabilities are null, // ConnectivityService takes them from the default request. @@ -3398,15 +3365,13 @@ public class ConnectivityManager { * {@code always} is true, then the choice is remembered, so that the next time the user * connects to this network, the system will switch to it. * - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#CONNECTIVITY_INTERNAL} - * * @param network The network to accept. * @param accept Whether to accept the network even if unvalidated. * @param always Whether to remember this choice in the future. * * @hide */ + @RequiresPermission(android.Manifest.permission.CONNECTIVITY_INTERNAL) public void setAcceptUnvalidated(Network network, boolean accept, boolean always) { try { mService.setAcceptUnvalidated(network, accept, always); @@ -3421,13 +3386,11 @@ public class ConnectivityManager { * {@code config_networkAvoidBadWifi} configuration variable is set to 0 and the {@code * NETWORK_AVOID_BAD_WIFI setting is unset}. * - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#CONNECTIVITY_INTERNAL} - * * @param network The network to accept. * * @hide */ + @RequiresPermission(android.Manifest.permission.CONNECTIVITY_INTERNAL) public void setAvoidUnvalidated(Network network) { try { mService.setAvoidUnvalidated(network); @@ -3488,15 +3451,13 @@ public class ConnectivityManager { * for multipath data transfer on this network when it is not the system default network. * Applications desiring to use multipath network protocols should call this method before * each such operation. - *

- * This method requires the caller to hold the permission - * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. * * @param network The network on which the application desires to use multipath data. * If {@code null}, this method will return the a preference that will generally * apply to metered networks. * @return a bitwise OR of zero or more of the {@code MULTIPATH_PREFERENCE_*} constants. */ + @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) public @MultipathPreference int getMultipathPreference(Network network) { try { return mService.getMultipathPreference(network); diff --git a/core/java/android/os/Parcelable.java b/core/java/android/os/Parcelable.java index c10abec7a80a8..6632ca51e74c5 100644 --- a/core/java/android/os/Parcelable.java +++ b/core/java/android/os/Parcelable.java @@ -16,6 +16,11 @@ package android.os; +import android.annotation.IntDef; + +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; + /** * Interface for classes whose instances can be written to * and restored from a {@link Parcel}. Classes implementing the Parcelable @@ -53,6 +58,14 @@ package android.os; * } */ public interface Parcelable { + /** @hide */ + @IntDef(flag = true, prefix = { "PARCELABLE_" }, value = { + PARCELABLE_WRITE_RETURN_VALUE, + PARCELABLE_ELIDE_DUPLICATES, + }) + @Retention(RetentionPolicy.SOURCE) + public @interface WriteFlags {} + /** * Flag for use with {@link #writeToParcel}: the object being written * is a return value, that is the result of a function such as @@ -79,6 +92,13 @@ public interface Parcelable { * marshalled. */ + /** @hide */ + @IntDef(flag = true, prefix = { "CONTENTS_" }, value = { + CONTENTS_FILE_DESCRIPTOR, + }) + @Retention(RetentionPolicy.SOURCE) + public @interface ContentsFlags {} + /** * Descriptor bit used with {@link #describeContents()}: indicates that * the Parcelable object's flattened representation includes a file descriptor. @@ -96,10 +116,8 @@ public interface Parcelable { * * @return a bitmask indicating the set of special object types marshaled * by this Parcelable object instance. - * - * @see #CONTENTS_FILE_DESCRIPTOR */ - public int describeContents(); + public @ContentsFlags int describeContents(); /** * Flatten this object in to a Parcel. @@ -108,7 +126,7 @@ public interface Parcelable { * @param flags Additional flags about how the object should be written. * May be 0 or {@link #PARCELABLE_WRITE_RETURN_VALUE}. */ - public void writeToParcel(Parcel dest, int flags); + public void writeToParcel(Parcel dest, @WriteFlags int flags); /** * Interface that must be implemented and provided as a public CREATOR diff --git a/core/java/android/os/Vibrator.java b/core/java/android/os/Vibrator.java index c6bbf484e7024..1e55c78845d1a 100644 --- a/core/java/android/os/Vibrator.java +++ b/core/java/android/os/Vibrator.java @@ -16,6 +16,7 @@ package android.os; +import android.annotation.RequiresPermission; import android.app.ActivityThread; import android.content.Context; import android.media.AudioAttributes; @@ -65,22 +66,19 @@ public abstract class Vibrator { /** * Vibrate constantly for the specified period of time. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#VIBRATE}. * * @param milliseconds The number of milliseconds to vibrate. * * @deprecated Use {@link #vibrate(VibrationEffect)} instead. */ @Deprecated + @RequiresPermission(android.Manifest.permission.VIBRATE) public void vibrate(long milliseconds) { vibrate(milliseconds, null); } /** * Vibrate constantly for the specified period of time. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#VIBRATE}. * * @param milliseconds The number of milliseconds to vibrate. * @param attributes {@link AudioAttributes} corresponding to the vibration. For example, @@ -91,6 +89,7 @@ public abstract class Vibrator { * @deprecated Use {@link #vibrate(VibrationEffect, AudioAttributes)} instead. */ @Deprecated + @RequiresPermission(android.Manifest.permission.VIBRATE) public void vibrate(long milliseconds, AudioAttributes attributes) { try { // This ignores all exceptions to stay compatible with pre-O implementations. @@ -115,8 +114,6 @@ public abstract class Vibrator { * To cause the pattern to repeat, pass the index into the pattern array at which * to start the repeat, or -1 to disable repeating. *

- *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#VIBRATE}. * * @param pattern an array of longs of times for which to turn the vibrator on or off. * @param repeat the index into pattern at which to repeat, or -1 if @@ -125,6 +122,7 @@ public abstract class Vibrator { * @deprecated Use {@link #vibrate(VibrationEffect)} instead. */ @Deprecated + @RequiresPermission(android.Manifest.permission.VIBRATE) public void vibrate(long[] pattern, int repeat) { vibrate(pattern, repeat, null); } @@ -142,8 +140,6 @@ public abstract class Vibrator { * To cause the pattern to repeat, pass the index into the pattern array at which * to start the repeat, or -1 to disable repeating. *

- *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#VIBRATE}. * * @param pattern an array of longs of times for which to turn the vibrator on or off. * @param repeat the index into pattern at which to repeat, or -1 if @@ -156,6 +152,7 @@ public abstract class Vibrator { * @deprecated Use {@link #vibrate(VibrationEffect, AudioAttributes)} instead. */ @Deprecated + @RequiresPermission(android.Manifest.permission.VIBRATE) public void vibrate(long[] pattern, int repeat, AudioAttributes attributes) { // This call needs to continue throwing ArrayIndexOutOfBoundsException but ignore all other // exceptions for compatibility purposes @@ -170,10 +167,12 @@ public abstract class Vibrator { } } + @RequiresPermission(android.Manifest.permission.VIBRATE) public void vibrate(VibrationEffect vibe) { vibrate(vibe, null); } + @RequiresPermission(android.Manifest.permission.VIBRATE) public void vibrate(VibrationEffect vibe, AudioAttributes attributes) { vibrate(Process.myUid(), mPackageName, vibe, attributes); } @@ -183,13 +182,13 @@ public abstract class Vibrator { * that the vibration is owned by someone else. * @hide */ + @RequiresPermission(android.Manifest.permission.VIBRATE) public abstract void vibrate(int uid, String opPkg, VibrationEffect vibe, AudioAttributes attributes); /** * Turn the vibrator off. - *

This method requires the caller to hold the permission - * {@link android.Manifest.permission#VIBRATE}. */ + @RequiresPermission(android.Manifest.permission.VIBRATE) public abstract void cancel(); }