Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 47556d88 authored by Yan Han's avatar Yan Han
Browse files

Update volume behavior documentation. 

setDeviceVolumeBehavior doesn't work for any of the absolute volume
behaviors, as they cause AudioService to throw an exception in
setDeviceVolumeBehaviorInternal.

The documentation and runtime checks in AudioManager should be
consistent with this behavior.

Also document compatibility behavior for
DEVICE_VOLUME_BEHAVIOR_ADJUST_ONLY in its definition.

Test: make
Bug: 240663268
Change-Id: I60b7aac0c329dae0e1301362d9803d7586e62602
parent 1480f63c

media/java/android/media/AudioManager.java

+23 −14
Original line number Original line Diff line number Diff line
@@ -6251,7 +6251,6 @@ public class AudioManager { 
     * Volume behavior for an audio device where no software attenuation is applied, and

     * Volume behavior for an audio device where no software attenuation is applied, and

     *     the volume is kept synchronized between the host and the device itself through a

     *     the volume is kept synchronized between the host and the device itself through a

     *     device-specific protocol such as BT AVRCP.

     *     device-specific protocol such as BT AVRCP.

     * @see #setDeviceVolumeBehavior(AudioDeviceAttributes, int)

     */

     */

    @SystemApi

    @SystemApi

    public static final int DEVICE_VOLUME_BEHAVIOR_ABSOLUTE = 3;

    public static final int DEVICE_VOLUME_BEHAVIOR_ABSOLUTE = 3;
@@ -6262,7 +6261,6 @@ public class AudioManager { 
     *     device-specific protocol (such as for hearing aids), based on the audio mode (e.g.

     *     device-specific protocol (such as for hearing aids), based on the audio mode (e.g.

     *     normal vs in phone call).

     *     normal vs in phone call).

     * @see #setMode(int)

     * @see #setMode(int)

     * @see #setDeviceVolumeBehavior(AudioDeviceAttributes, int)

     */

     */

    @SystemApi

    @SystemApi

    public static final int DEVICE_VOLUME_BEHAVIOR_ABSOLUTE_MULTI_MODE = 4;

    public static final int DEVICE_VOLUME_BEHAVIOR_ABSOLUTE_MULTI_MODE = 4;
@@ -6272,6 +6270,11 @@ public class AudioManager { 
     * A variant of {@link #DEVICE_VOLUME_BEHAVIOR_ABSOLUTE} where the host cannot reliably set

     * A variant of {@link #DEVICE_VOLUME_BEHAVIOR_ABSOLUTE} where the host cannot reliably set

     * the volume percentage of the audio device. Specifically, {@link #setStreamVolume} will have

     * the volume percentage of the audio device. Specifically, {@link #setStreamVolume} will have

     * no effect, or an unreliable effect.

     * no effect, or an unreliable effect.

     *

     * {@link #DEVICE_VOLUME_BEHAVIOR_FULL} will be returned instead by

     * {@link #getDeviceVolumeBehavior} for target SDK versions before U.

     *

     * @see #RETURN_DEVICE_VOLUME_BEHAVIOR_ABSOLUTE_ADJUST_ONLY

     */

     */

    @SystemApi

    @SystemApi

    public static final int DEVICE_VOLUME_BEHAVIOR_ABSOLUTE_ADJUST_ONLY = 5;

    public static final int DEVICE_VOLUME_BEHAVIOR_ABSOLUTE_ADJUST_ONLY = 5;
@@ -6313,18 +6316,27 @@ public class AudioManager { 
    public @interface AbsoluteDeviceVolumeBehavior {}

    public @interface AbsoluteDeviceVolumeBehavior {}





    /**

    /**

     * Volume behaviors that can be set with {@link #setDeviceVolumeBehavior}.

     * @hide

     * @hide

     * Throws IAE on an invalid volume behavior value

     */

    @IntDef({

        DEVICE_VOLUME_BEHAVIOR_VARIABLE,

        DEVICE_VOLUME_BEHAVIOR_FULL,

        DEVICE_VOLUME_BEHAVIOR_FIXED,

    })

    @Retention(RetentionPolicy.SOURCE)

    public @interface SettableDeviceVolumeBehavior {}



    /**

     * @hide

     * Throws IAE on a non-settable volume behavior value

     * @param volumeBehavior behavior value to check

     * @param volumeBehavior behavior value to check

     */

     */

    public static void enforceValidVolumeBehavior(int volumeBehavior) {

    public static void enforceSettableVolumeBehavior(int volumeBehavior) {

        switch (volumeBehavior) {

        switch (volumeBehavior) {

            case DEVICE_VOLUME_BEHAVIOR_VARIABLE:

            case DEVICE_VOLUME_BEHAVIOR_VARIABLE:

            case DEVICE_VOLUME_BEHAVIOR_FULL:

            case DEVICE_VOLUME_BEHAVIOR_FULL:

            case DEVICE_VOLUME_BEHAVIOR_FIXED:

            case DEVICE_VOLUME_BEHAVIOR_FIXED:

            case DEVICE_VOLUME_BEHAVIOR_ABSOLUTE:

            case DEVICE_VOLUME_BEHAVIOR_ABSOLUTE_MULTI_MODE:

            case DEVICE_VOLUME_BEHAVIOR_ABSOLUTE_ADJUST_ONLY:

                return;

                return;

            default:

            default:

                throw new IllegalArgumentException("Illegal volume behavior " + volumeBehavior);

                throw new IllegalArgumentException("Illegal volume behavior " + volumeBehavior);
@@ -6334,11 +6346,8 @@ public class AudioManager { 
    /**

    /**

     * @hide

     * @hide

     * Sets the volume behavior for an audio output device.

     * Sets the volume behavior for an audio output device.

     * @see #DEVICE_VOLUME_BEHAVIOR_VARIABLE

     *

     * @see #DEVICE_VOLUME_BEHAVIOR_FULL

     * @see SettableDeviceVolumeBehavior

     * @see #DEVICE_VOLUME_BEHAVIOR_FIXED

     * @see #DEVICE_VOLUME_BEHAVIOR_ABSOLUTE

     * @see #DEVICE_VOLUME_BEHAVIOR_ABSOLUTE_MULTI_MODE

     * @param device the device to be affected

     * @param device the device to be affected

     * @param deviceVolumeBehavior one of the device behaviors

     * @param deviceVolumeBehavior one of the device behaviors

     */

     */
@@ -6348,10 +6357,10 @@ public class AudioManager { 
            Manifest.permission.MODIFY_AUDIO_SETTINGS_PRIVILEGED

            Manifest.permission.MODIFY_AUDIO_SETTINGS_PRIVILEGED

    })

    })

    public void setDeviceVolumeBehavior(@NonNull AudioDeviceAttributes device,

    public void setDeviceVolumeBehavior(@NonNull AudioDeviceAttributes device,

            @DeviceVolumeBehavior int deviceVolumeBehavior) {

            @SettableDeviceVolumeBehavior int deviceVolumeBehavior) {

        // verify arguments (validity of device type is enforced in server)

        // verify arguments (validity of device type is enforced in server)

        Objects.requireNonNull(device);

        Objects.requireNonNull(device);

        enforceValidVolumeBehavior(deviceVolumeBehavior);

        enforceSettableVolumeBehavior(deviceVolumeBehavior);

        // communicate with service

        // communicate with service

        final IAudioService service = getService();

        final IAudioService service = getService();

        try {

        try {

services/core/java/com/android/server/audio/AudioService.java

+1 −1
Original line number Original line Diff line number Diff line
@@ -7228,7 +7228,7 @@ public class AudioService extends IAudioService.Stub 
        super.setDeviceVolumeBehavior_enforcePermission();

        super.setDeviceVolumeBehavior_enforcePermission();

        // verify arguments

        // verify arguments

        Objects.requireNonNull(device);

        Objects.requireNonNull(device);

        AudioManager.enforceValidVolumeBehavior(deviceVolumeBehavior);

        AudioManager.enforceSettableVolumeBehavior(deviceVolumeBehavior);

















        sVolumeLogger.enqueue(new EventLogger.StringEvent("setDeviceVolumeBehavior: dev:"







        sVolumeLogger.enqueue(new EventLogger.StringEvent("setDeviceVolumeBehavior: dev:"











                + AudioSystem.getOutputDeviceName(device.getInternalType()) + " addr:"







                + AudioSystem.getOutputDeviceName(device.getInternalType()) + " addr:"