Merge "Cleanup AudioManager volume flags" into udc-dev

media/java/android/media/AudioManager.java

@@ -661,7 +661,10 @@ public class AudioManager {
      */
     public static final int ENCODED_SURROUND_OUTPUT_MANUAL = 3;
 
-    /** @hide */
+    /**
+     * @hide
+     * This list contains all the flags that can be used in internal APIs for volume
+     * related operations */
     @IntDef(flag = true, prefix = "FLAG", value = {
             FLAG_SHOW_UI,
             FLAG_ALLOW_RINGER_MODES,
@@ -681,16 +684,64 @@ public class AudioManager {
     @Retention(RetentionPolicy.SOURCE)
     public @interface Flags {}
 
-    /** @hide */
+    /**
+     * @hide
+     * This list contains all the flags that can be used in SDK-visible methods for volume
+     * related operations.
+     * See for instance {@link #adjustVolume(int, int)},
+     * {@link #adjustStreamVolume(int, int, int)},
+     * {@link #adjustSuggestedStreamVolume(int, int, int)},
+     * {@link #adjustVolumeGroupVolume(int, int, int)},
+     * {@link #setStreamVolume(int, int, int)}
+     * The list contains all volume flags, but the values commented out of the list are there for
+     * maintenance reasons (for when adding flags or changing their visibility),
+     * and to document why some are not in the list (hidden or SystemApi). */
     @IntDef(flag = true, prefix = "FLAG", value = {
             FLAG_SHOW_UI,
             FLAG_ALLOW_RINGER_MODES,
             FLAG_PLAY_SOUND,
             FLAG_REMOVE_SOUND_AND_VIBRATE,
             FLAG_VIBRATE,
+            //FLAG_FIXED_VOLUME,             removed due to @hide
+            //FLAG_BLUETOOTH_ABS_VOLUME,     removed due to @SystemApi
+            //FLAG_SHOW_SILENT_HINT,         removed due to @hide
+            //FLAG_HDMI_SYSTEM_AUDIO_VOLUME, removed due to @hide
+            //FLAG_ACTIVE_MEDIA_ONLY,        removed due to @hide
+            //FLAG_SHOW_UI_WARNINGS,         removed due to @hide
+            //FLAG_SHOW_VIBRATE_HINT,        removed due to @hide
+            //FLAG_FROM_KEY,                 removed due to @SystemApi
+            //FLAG_ABSOLUTE_VOLUME,          removed due to @hide
+    })
+    @Retention(RetentionPolicy.SOURCE)
+    public @interface PublicVolumeFlags {}
+
+    /**
+     * @hide
+     * Like PublicVolumeFlags, but for all the flags that can be used in @SystemApi methods for
+     * volume related operations.
+     * See for instance {@link #setVolumeIndexForAttributes(AudioAttributes, int, int)},
+     * {@link #setVolumeGroupVolumeIndex(int, int, int)},
+     * {@link #setStreamVolumeForUid(int, int, int, String, int, int, int)},
+     * {@link #adjustStreamVolumeForUid(int, int, int, String, int, int, int)},
+     * {@link #adjustSuggestedStreamVolumeForUid(int, int, int, String, int, int, int)}
+     * The list contains all volume flags, but the values commented out of the list are there for
+     * maintenance reasons (for when adding flags or changing their visibility),
+     * and to document which hidden values are not in the list. */
+    @IntDef(flag = true, prefix = "FLAG", value = {
+            FLAG_SHOW_UI,
+            FLAG_ALLOW_RINGER_MODES,
+            FLAG_PLAY_SOUND,
+            FLAG_REMOVE_SOUND_AND_VIBRATE,
+            FLAG_VIBRATE,
+            //FLAG_FIXED_VOLUME,             removed due to @hide
             FLAG_BLUETOOTH_ABS_VOLUME,
-            FLAG_HDMI_SYSTEM_AUDIO_VOLUME,
+            //FLAG_SHOW_SILENT_HINT,         removed due to @hide
+            //FLAG_HDMI_SYSTEM_AUDIO_VOLUME, removed due to @hide
+            //FLAG_ACTIVE_MEDIA_ONLY,        removed due to @hide
+            //FLAG_SHOW_UI_WARNINGS,         removed due to @hide
+            //FLAG_SHOW_VIBRATE_HINT,        removed due to @hide
             FLAG_FROM_KEY,
+            //FLAG_ABSOLUTE_VOLUME,          removed due to @hide
     })
     @Retention(RetentionPolicy.SOURCE)
     public @interface SystemVolumeFlags {}
@@ -981,13 +1032,13 @@ public class AudioManager {
      * @param direction The direction to adjust the volume. One of
      *            {@link #ADJUST_LOWER}, {@link #ADJUST_RAISE}, or
      *            {@link #ADJUST_SAME}.
-     * @param flags One or more flags.
+     * @param flags
      * @see #adjustVolume(int, int)
      * @see #setStreamVolume(int, int, int)
      * @throws SecurityException if the adjustment triggers a Do Not Disturb change
      *   and the caller is not granted notification policy access.
      */
-    public void adjustStreamVolume(int streamType, int direction, int flags) {
+    public void adjustStreamVolume(int streamType, int direction, @PublicVolumeFlags int flags) {
         final IAudioService service = getService();
         try {
             service.adjustStreamVolumeWithAttribution(streamType, direction, flags,
@@ -1014,13 +1065,13 @@ public class AudioManager {
      *            {@link #ADJUST_LOWER}, {@link #ADJUST_RAISE},
      *            {@link #ADJUST_SAME}, {@link #ADJUST_MUTE},
      *            {@link #ADJUST_UNMUTE}, or {@link #ADJUST_TOGGLE_MUTE}.
-     * @param flags One or more flags.
+     * @param flags
      * @see #adjustSuggestedStreamVolume(int, int, int)
      * @see #adjustStreamVolume(int, int, int)
      * @see #setStreamVolume(int, int, int)
      * @see #isVolumeFixed()
      */
-    public void adjustVolume(int direction, int flags) {
+    public void adjustVolume(int direction, @PublicVolumeFlags int flags) {
         MediaSessionLegacyHelper helper = MediaSessionLegacyHelper.getHelper(getContext());
         helper.sendAdjustVolumeBy(USE_DEFAULT_STREAM_TYPE, direction, flags);
     }
@@ -1043,13 +1094,14 @@ public class AudioManager {
      * @param suggestedStreamType The stream type that will be used if there
      *            isn't a relevant stream. {@link #USE_DEFAULT_STREAM_TYPE} is
      *            valid here.
-     * @param flags One or more flags.
+     * @param flags
      * @see #adjustVolume(int, int)
      * @see #adjustStreamVolume(int, int, int)
      * @see #setStreamVolume(int, int, int)
      * @see #isVolumeFixed()
      */
-    public void adjustSuggestedStreamVolume(int direction, int suggestedStreamType, int flags) {
+    public void adjustSuggestedStreamVolume(int direction, int suggestedStreamType,
+            @PublicVolumeFlags int flags) {
         MediaSessionLegacyHelper helper = MediaSessionLegacyHelper.getHelper(getContext());
         helper.sendAdjustVolumeBy(suggestedStreamType, direction, flags);
     }
@@ -1334,14 +1386,14 @@ public class AudioManager {
      * @param streamType The stream whose volume index should be set.
      * @param index The volume index to set. See
      *            {@link #getStreamMaxVolume(int)} for the largest valid value.
-     * @param flags One or more flags.
+     * @param flags
      * @see #getStreamMaxVolume(int)
      * @see #getStreamVolume(int)
      * @see #isVolumeFixed()
      * @throws SecurityException if the volume change triggers a Do Not Disturb change
      *   and the caller is not granted notification policy access.
      */
-    public void setStreamVolume(int streamType, int index, int flags) {
+    public void setStreamVolume(int streamType, int index, @PublicVolumeFlags int flags) {
         final IAudioService service = getService();
         try {
             service.setStreamVolumeWithAttribution(streamType, index, flags,
@@ -1357,7 +1409,7 @@ public class AudioManager {
      * @param index The volume index to set. See
      *          {@link #getMaxVolumeIndexForAttributes(AudioAttributes)} for the largest valid value
      *          {@link #getMinVolumeIndexForAttributes(AudioAttributes)} for the lowest valid value.
-     * @param flags One or more flags.
+     * @param flags
      * @see #getMaxVolumeIndexForAttributes(AudioAttributes)
      * @see #getMinVolumeIndexForAttributes(AudioAttributes)
      * @see #isVolumeFixed()
@@ -1365,7 +1417,8 @@ public class AudioManager {
      */
     @SystemApi
     @RequiresPermission(Manifest.permission.MODIFY_AUDIO_ROUTING)
-    public void setVolumeIndexForAttributes(@NonNull AudioAttributes attr, int index, int flags) {
+    public void setVolumeIndexForAttributes(@NonNull AudioAttributes attr, int index,
+            @SystemVolumeFlags int flags) {
         Preconditions.checkNotNull(attr, "attr must not be null");
         final IAudioService service = getService();
         int groupId = getVolumeGroupIdForAttributes(attr);
@@ -1451,7 +1504,7 @@ public class AudioManager {
      * @param index The volume index to set. See
      *          {@link #getVolumeGroupMaxVolumeIndex(id)} for the largest valid value
      *          {@link #getVolumeGroupMinVolumeIndex(id)} for the lowest valid value.
-     * @param flags One or more flags.
+     * @param flags
      * @hide
      */
     @SystemApi
@@ -1552,11 +1605,11 @@ public class AudioManager {
      * @param direction The direction to adjust the volume. One of
      *            {@link #ADJUST_LOWER}, {@link #ADJUST_RAISE}, or
      *            {@link #ADJUST_SAME}.
-     * @param flags One or more flags.
+     * @param flags
      * @throws SecurityException if the adjustment triggers a Do Not Disturb change and the caller
      * is not granted notification policy access.
      */
-    public void adjustVolumeGroupVolume(int groupId, int direction, @SystemVolumeFlags int flags) {
+    public void adjustVolumeGroupVolume(int groupId, int direction, @PublicVolumeFlags int flags) {
         IAudioService service = getService();
         try {
             service.adjustVolumeGroupVolume(groupId, direction, flags,
@@ -8234,7 +8287,7 @@ public class AudioManager {
      *         {@link #ADJUST_LOWER}, {@link #ADJUST_RAISE},
      *         {@link #ADJUST_SAME}, {@link #ADJUST_MUTE},
      *         {@link #ADJUST_UNMUTE}, or {@link #ADJUST_TOGGLE_MUTE}.
-     * @param flags One or more flags.
+     * @param flags
      * @param packageName the package name of client application
      * @param uid the uid of client application
      * @param pid the pid of client application
@@ -8247,7 +8300,8 @@ public class AudioManager {
      * @hide
      */
     @SystemApi(client = SystemApi.Client.MODULE_LIBRARIES)
-    public void adjustSuggestedStreamVolumeForUid(int suggestedStreamType, int direction, int flags,
+    public void adjustSuggestedStreamVolumeForUid(int suggestedStreamType, int direction,
+            @SystemVolumeFlags int flags,
             @NonNull String packageName, int uid, int pid, int targetSdkVersion) {
         try {
             getService().adjustSuggestedStreamVolumeForUid(suggestedStreamType, direction, flags,
@@ -8277,7 +8331,7 @@ public class AudioManager {
      * @param direction The direction to adjust the volume. One of
      *         {@link #ADJUST_LOWER}, {@link #ADJUST_RAISE}, or
      *         {@link #ADJUST_SAME}.
-     * @param flags One or more flags.
+     * @param flags
      * @param packageName the package name of client application
      * @param uid the uid of client application
      * @param pid the pid of client application
@@ -8290,7 +8344,8 @@ public class AudioManager {
      * @hide
      */
     @SystemApi(client = SystemApi.Client.MODULE_LIBRARIES)
-    public void adjustStreamVolumeForUid(int streamType, int direction, int flags,
+    public void adjustStreamVolumeForUid(int streamType, int direction,
+            @SystemVolumeFlags int flags,
             @NonNull String packageName, int uid, int pid, int targetSdkVersion) {
         try {
             getService().adjustStreamVolumeForUid(streamType, direction, flags, packageName, uid,
@@ -8314,7 +8369,7 @@ public class AudioManager {
      * @param streamType The stream whose volume index should be set.
      * @param index The volume index to set. See
      *         {@link #getStreamMaxVolume(int)} for the largest valid value.
-     * @param flags One or more flags.
+     * @param flags
      * @param packageName the package name of client application
      * @param uid the uid of client application
      * @param pid the pid of client application
@@ -8328,7 +8383,8 @@ public class AudioManager {
      * @hide
      */
     @SystemApi(client = SystemApi.Client.MODULE_LIBRARIES)
-    public void setStreamVolumeForUid(int streamType, int index, int flags,
+    public void setStreamVolumeForUid(int streamType, int index,
+            @SystemVolumeFlags int flags,
             @NonNull String packageName, int uid, int pid, int targetSdkVersion) {
         try {
             getService().setStreamVolumeForUid(streamType, index, flags, packageName, uid, pid,

media/java/android/media/session/MediaSessionManager.java

@@ -1169,7 +1169,7 @@ public final class MediaSessionManager {
          * @param flags flags containing extra action or information regarding the volume change
          */
         void onVolumeChanged(@NonNull MediaSession.Token sessionToken,
-                @AudioManager.Flags int flags);
+                @AudioManager.SystemVolumeFlags int flags);
 
         /**
          * Called when the default remote session is changed where the default remote session