Merge "AudioDeviceVolumeManager and VolumeInfo in SystemApi"

core/api/system-current.txt

@@ -6134,6 +6134,11 @@ package android.media {
     field public static final int ROLE_OUTPUT = 2; // 0x2
   }
 
+  public class AudioDeviceVolumeManager {
+    ctor public AudioDeviceVolumeManager(@NonNull android.content.Context);
+    method @RequiresPermission(android.Manifest.permission.MODIFY_AUDIO_ROUTING) public void setDeviceVolume(@NonNull android.media.VolumeInfo, @NonNull android.media.AudioDeviceAttributes);
+  }
+
   public final class AudioFocusInfo implements android.os.Parcelable {
     method public int describeContents();
     method @NonNull public android.media.AudioAttributes getAttributes();
@@ -6453,6 +6458,33 @@ package android.media {
     method public void onSpatializerOutputChanged(@NonNull android.media.Spatializer, @IntRange(from=0) int);
   }
 
+  public final class VolumeInfo implements android.os.Parcelable {
+    method public int describeContents();
+    method @NonNull public static android.media.VolumeInfo getDefaultVolumeInfo();
+    method public int getMaxVolumeIndex();
+    method public int getMinVolumeIndex();
+    method public int getStreamType();
+    method @Nullable public android.media.audiopolicy.AudioVolumeGroup getVolumeGroup();
+    method public int getVolumeIndex();
+    method public boolean hasStreamType();
+    method public boolean hasVolumeGroup();
+    method public boolean isMuted();
+    method public void writeToParcel(@NonNull android.os.Parcel, int);
+    field @NonNull public static final android.os.Parcelable.Creator<android.media.VolumeInfo> CREATOR;
+    field public static final int INDEX_NOT_SET = -100; // 0xffffff9c
+  }
+
+  public static final class VolumeInfo.Builder {
+    ctor public VolumeInfo.Builder(int);
+    ctor public VolumeInfo.Builder(@NonNull android.media.audiopolicy.AudioVolumeGroup);
+    ctor public VolumeInfo.Builder(@NonNull android.media.VolumeInfo);
+    method @NonNull public android.media.VolumeInfo build();
+    method @NonNull public android.media.VolumeInfo.Builder setMaxVolumeIndex(int);
+    method @NonNull public android.media.VolumeInfo.Builder setMinVolumeIndex(int);
+    method @NonNull public android.media.VolumeInfo.Builder setMuted(boolean);
+    method @NonNull public android.media.VolumeInfo.Builder setVolumeIndex(int);
+  }
+
 }
 
 package android.media.audiofx {

media/java/android/media/AudioDeviceVolumeManager.java

@@ -21,6 +21,8 @@ import android.annotation.IntDef;
 import android.annotation.NonNull;
 import android.annotation.Nullable;
 import android.annotation.RequiresPermission;
+import android.annotation.SuppressLint;
+import android.annotation.SystemApi;
 import android.content.Context;
 import android.os.IBinder;
 import android.os.RemoteException;
@@ -39,23 +41,29 @@ import java.util.concurrent.Executor;
  * @hide
  * AudioDeviceVolumeManager provides access to audio device volume control.
  */
+@SystemApi
 public class AudioDeviceVolumeManager {
 
     // define when using Log.*
     //private static final String TAG = "AudioDeviceVolumeManager";
 
-    /** Indicates no special treatment in the handling of the volume adjustment */
+    /** @hide
+     * Indicates no special treatment in the handling of the volume adjustment */
     public static final int ADJUST_MODE_NORMAL = 0;
-    /** Indicates the start of a volume adjustment */
+    /** @hide
+     * Indicates the start of a volume adjustment */
     public static final int ADJUST_MODE_START = 1;
-    /** Indicates the end of a volume adjustment */
+    /** @hide
+     * Indicates the end of a volume adjustment */
     public static final int ADJUST_MODE_END = 2;
 
+    /** @hide */
     @IntDef(flag = false, prefix = "ADJUST_MODE", value = {
             ADJUST_MODE_NORMAL,
             ADJUST_MODE_START,
             ADJUST_MODE_END}
     )
+    /** @hide */
     @Retention(RetentionPolicy.SOURCE)
     public @interface VolumeAdjustmentMode {}
 
@@ -64,7 +72,16 @@ public class AudioDeviceVolumeManager {
     private final @NonNull String mPackageName;
     private final @Nullable String mAttributionTag;
 
-    public AudioDeviceVolumeManager(Context context) {
+    /**
+     * Constructor
+     * @param context the Context for the device volume operations
+     */
+    @SuppressLint("ManagerConstructor")
+    // reason for suppression: even though the functionality handled by this class is implemented in
+    // AudioService, we want to avoid bloating android.media.AudioManager
+    // with @SystemApi functionality
+    public AudioDeviceVolumeManager(@NonNull Context context) {
+        Objects.requireNonNull(context);
         mPackageName = context.getApplicationContext().getOpPackageName();
         mAttributionTag = context.getApplicationContext().getAttributionTag();
     }
@@ -101,6 +118,7 @@ public class AudioDeviceVolumeManager {
                 @VolumeAdjustmentMode int mode);
     }
 
+    /** @hide */
     static class ListenerInfo {
         final @NonNull OnAudioDeviceVolumeChangedListener mListener;
         final @NonNull Executor mExecutor;
@@ -127,6 +145,7 @@ public class AudioDeviceVolumeManager {
     @GuardedBy("mDeviceVolumeListenerLock")
     private DeviceVolumeDispatcherStub mDeviceVolumeDispatcherStub;
 
+    /** @hide */
     final class DeviceVolumeDispatcherStub extends IAudioDeviceVolumeDispatcher.Stub {
         /**
          * Register / unregister the stub
@@ -305,6 +324,7 @@ public class AudioDeviceVolumeManager {
      * @param vi the volume information, only stream-based volumes are supported
      * @param ada the device for which volume is to be modified
      */
+    @SystemApi
     @RequiresPermission(android.Manifest.permission.MODIFY_AUDIO_ROUTING)
     public void setDeviceVolume(@NonNull VolumeInfo vi, @NonNull AudioDeviceAttributes ada) {
         try {
@@ -315,6 +335,7 @@ public class AudioDeviceVolumeManager {
     }
 
     /**
+     * @hide
      * Return human-readable name for volume behavior
      * @param behavior one of the volume behaviors defined in AudioManager
      * @return a string for the given behavior

media/java/android/media/VolumeInfo.java

@@ -18,6 +18,7 @@ package android.media;
 
 import android.annotation.NonNull;
 import android.annotation.Nullable;
+import android.annotation.SystemApi;
 import android.content.Context;
 import android.media.audiopolicy.AudioVolumeGroup;
 import android.os.IBinder;
@@ -32,16 +33,13 @@ import java.util.Objects;
 
 /**
  * @hide
- * A class to represent type of volume information.
+ * A class to represent volume information.
  * Can be used to represent volume associated with a stream type or {@link AudioVolumeGroup}.
  * Volume index is optional when used to represent a category of volume.
  * Index ranges are supported too, making the representation of volume changes agnostic to the
  * range (e.g. can be used to map BT A2DP absolute volume range to internal range).
- *
- * Note: this class is not yet part of the SystemApi but is intended to be gradually introduced
- *       particularly in parts of the audio framework that suffer from code ambiguity when
- *       dealing with different volume ranges / units.
  */
+@SystemApi
 public final class VolumeInfo implements Parcelable {
     private static final String TAG = "VolumeInfo";