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

Commit 50750ff1 authored by Jean-Michel Trivi's avatar Jean-Michel Trivi
Browse files

Audio focus: SDK/System API updates 

Addressed API council notes: document some missing default values
  of AudioFocusRequest builder, remove getters on lister and
  handler.
Fix missing support of custom Handler for focus listener.
Integrate focus lock feature from AudioManager SystemAPI into
  new AudioFocusRequest class and builder. Deprecate system
  methods for focus requests that don't use AudioFocusRequest
Switch to a ConcurrentHashMap in AudioManager instead of a
  lock and HashMap to maintain the list of focus listeners
  for each AudioManager instance.
Clean up: all local IAudioService references can be made final.
  Add missing @Override for the Stub implementations.

Test: cts-tradefed run cts -m CtsMediaTestCases -t android.media.cts.AudioFocusTest
Bug: 30258418

Change-Id: I9e903379a607c723a2620821200547de679231d1
parent 0a637ecd

api/current.txt

+0 −2
Original line number Diff line number Diff line
@@ -20950,8 +20950,6 @@ package android.media { 
    method public boolean acceptsDelayedFocusGain();

    method public android.media.AudioAttributes getAudioAttributes();

    method public int getFocusGain();

    method public android.media.AudioManager.OnAudioFocusChangeListener getOnAudioFocusChangeListener();

    method public android.os.Handler getOnAudioFocusChangeListenerHandler();

    method public boolean willPauseWhenDucked();

  }

























api/system-current.txt



+5
−4




























Original line number
Diff line number
Diff line








@@ -22713,8 +22713,7 @@ package android.media {













    method public boolean acceptsDelayedFocusGain();















    method public android.media.AudioAttributes getAudioAttributes();















    method public int getFocusGain();













    method public android.media.AudioManager.OnAudioFocusChangeListener getOnAudioFocusChangeListener();













    method public android.os.Handler getOnAudioFocusChangeListenerHandler();













    method public boolean locksFocus();















    method public boolean willPauseWhenDucked();















  }























@@ -22725,6 +22724,7 @@ package android.media {













    method public android.media.AudioFocusRequest.Builder setAcceptsDelayedFocusGain(boolean);















    method public android.media.AudioFocusRequest.Builder setAudioAttributes(android.media.AudioAttributes);















    method public android.media.AudioFocusRequest.Builder setFocusGain(int);













    method public android.media.AudioFocusRequest.Builder setLocksFocus(boolean);















    method public android.media.AudioFocusRequest.Builder setOnAudioFocusChangeListener(android.media.AudioManager.OnAudioFocusChangeListener, android.os.Handler);















    method public android.media.AudioFocusRequest.Builder setWillPauseWhenDucked(boolean);















  }










@@ -22805,7 +22805,7 @@ package android.media {



























  public class AudioManager {















    method public deprecated int abandonAudioFocus(android.media.AudioManager.OnAudioFocusChangeListener);













    method public int abandonAudioFocus(android.media.AudioManager.OnAudioFocusChangeListener, android.media.AudioAttributes);













    method public deprecated int abandonAudioFocus(android.media.AudioManager.OnAudioFocusChangeListener, android.media.AudioAttributes);















    method public int abandonAudioFocusRequest(android.media.AudioFocusRequest);















    method public void adjustStreamVolume(int, int, int);















    method public void adjustSuggestedStreamVolume(int, int, int);










@@ -22847,7 +22847,8 @@ package android.media {













    method public deprecated int requestAudioFocus(android.media.AudioManager.OnAudioFocusChangeListener, int, int);















    method public int requestAudioFocus(android.media.AudioFocusRequest);















    method public int requestAudioFocus(android.media.AudioManager.OnAudioFocusChangeListener, android.media.AudioAttributes, int, int) throws java.lang.IllegalArgumentException;













    method public int requestAudioFocus(android.media.AudioManager.OnAudioFocusChangeListener, android.media.AudioAttributes, int, int, android.media.audiopolicy.AudioPolicy) throws java.lang.IllegalArgumentException;













    method public deprecated int requestAudioFocus(android.media.AudioManager.OnAudioFocusChangeListener, android.media.AudioAttributes, int, int, android.media.audiopolicy.AudioPolicy) throws java.lang.IllegalArgumentException;













    method public int requestAudioFocus(android.media.AudioFocusRequest, android.media.audiopolicy.AudioPolicy);















    method public deprecated void setBluetoothA2dpOn(boolean);















    method public void setBluetoothScoOn(boolean);















    method public void setMicrophoneMute(boolean);

























api/test-current.txt



+0
−2




























Original line number
Diff line number
Diff line








@@ -21051,8 +21051,6 @@ package android.media {













    method public boolean acceptsDelayedFocusGain();















    method public android.media.AudioAttributes getAudioAttributes();















    method public int getFocusGain();













    method public android.media.AudioManager.OnAudioFocusChangeListener getOnAudioFocusChangeListener();













    method public android.os.Handler getOnAudioFocusChangeListenerHandler();















    method public boolean willPauseWhenDucked();















  }







































media/java/android/media/AudioFocusRequest.java



+48
−8




























Original line number
Diff line number
Diff line








@@ -18,6 +18,7 @@ package android.media;





























import android.annotation.NonNull;















import android.annotation.Nullable;













import android.annotation.SystemApi;















import android.media.AudioManager.OnAudioFocusChangeListener;















import android.os.Handler;















import android.os.Looper;










@@ -48,7 +49,6 @@ public final class AudioFocusRequest {













    private final int mFocusGain;















    private final int mFlags;





























    //TODO implement use of optional handler















    private AudioFocusRequest(OnAudioFocusChangeListener listener, Handler handler,















            AudioAttributes attr, int focusGain, int flags) {















        mFocusListener = listener;










@@ -77,6 +77,7 @@ public final class AudioFocusRequest {













    }































    /**













     * @hide















     * Returns the focus change listener set for this {@code AudioFocusRequest}.















     * @return null if no {@link AudioManager.OnAudioFocusChangeListener} was set.















     */









@@ -85,6 +86,7 @@ public final class AudioFocusRequest {













    }































    /**













     * @hide















     * Returns the {@link Handler} to be used for the focus change listener.















     * @return the same {@code Handler} set in.















     *   {@link Builder#setOnAudioFocusChangeListener(OnAudioFocusChangeListener, Handler)}, or null










@@ -134,6 +136,18 @@ public final class AudioFocusRequest {













                == AudioManager.AUDIOFOCUS_FLAG_DELAY_OK;















    }





























    /**













     * @hide













     * Returns whether audio focus will be locked (i.e. focus cannot change) as a result of this













     * focus request being successful.













     * @return whether this request will lock focus.













     */













    @SystemApi













    public boolean locksFocus() {













        return (mFlags & AudioManager.AUDIOFOCUS_FLAG_LOCK)













                == AudioManager.AUDIOFOCUS_FLAG_LOCK;













    }





























    int getFlags() {















        return mFlags;















    }









@@ -158,9 +172,16 @@ public final class AudioFocusRequest {













     *  ...















     * mMediaPlayer.setAudioAttributes(mPlaybackAttributes);















     *  ...













     * mAudioManager.requestAudioFocus(mFocusRequest);













     *  ...













     * mAudioManager.abandonAudioFocusRequest(mFocusRequest);













     * boolean mPlaybackAuthorized = true;;













     * int res = mAudioManager.requestAudioFocus(mFocusRequest);













     * if (res == AUDIOFOCUS_REQUEST_FAILED) {













     *     mPlaybackAuthorized = false;













     *     cancelPlayback();













     * } else if (res == AUDIOFOCUS_REQUEST_DELAYED) {













     *     playbackDelayed();













     * } else { // res == AUDIOFOCUS_REQUEST_GRANTED













     *     playbackNow();













     * }















     * </pre>















     *















     */









@@ -171,6 +192,7 @@ public final class AudioFocusRequest {













        private int mFocusGain;















        private boolean mPausesOnDuck = false;















        private boolean mDelayedFocus = false;













        private boolean mFocusLocked = false;































        /**















         * Constructs a new {@code Builder}, and specifies how audio focus









@@ -178,7 +200,8 @@ public final class AudioFocusRequest {













         * {@link AudioManager#AUDIOFOCUS_GAIN}, {@link AudioManager#AUDIOFOCUS_GAIN_TRANSIENT},















         * {@link AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK}, and















         * {@link AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE}.













         * <p>By default there is no focus change listener, and the <code>AudioAttributes</code>













         * <p>By default there is no focus change listener, delayed focus is not supported, ducking













         * is suitable for the application, and the <code>AudioAttributes</code>















         * have a usage of {@link AudioAttributes#USAGE_MEDIA}.















         * @param focusGain the type of audio focus gain that will be requested















         * @throws IllegalArgumentException thrown when an invalid focus gain type is used










@@ -258,11 +281,11 @@ public final class AudioFocusRequest {













         * in {@code AudioTrack}.















         * @param attributes the {@link AudioAttributes} for the focus request.















         * @return this {@code Builder} instance.













         * @throws IllegalArgumentException thrown when using null for the attributes.













         * @throws NullPointerException thrown when using null for the attributes.















         */















        public @NonNull Builder setAudioAttributes(@NonNull AudioAttributes attributes) {















            if (attributes == null) {













                throw new IllegalArgumentException("Illegal null AudioAttributes");













                throw new NullPointerException("Illegal null AudioAttributes");















            }















            mAttr = attributes;















            return this;










@@ -298,6 +321,22 @@ public final class AudioFocusRequest {













            return this;















        }





























        /**













         * @hide













         * Marks this focus request as locking audio focus so granting is temporarily disabled.













         * This feature can only be used by owners of a registered













         * {@link android.media.audiopolicy.AudioPolicy} in













         * {@link AudioManager#requestAudioFocus(AudioFocusRequest, android.media.audiopolicy.AudioPolicy)}.













         * Setting to false is the same as the default behavior.













         * @param focusLocked true when locking focus













         * @return this {@code Builder} instance













         */













        @SystemApi













        public @NonNull Builder setLocksFocus(boolean focusLocked) {













            mFocusLocked = focusLocked;













            return this;













        }





























        /**















         * Builds a new {@code AudioFocusRequest} instance combining all the information gathered















         * by this {@code Builder}'s configuration methods.









@@ -313,7 +352,8 @@ public final class AudioFocusRequest {













            }















            final int flags = 0















                    | (mDelayedFocus ? AudioManager.AUDIOFOCUS_FLAG_DELAY_OK : 0)













                    | (mPausesOnDuck ? AudioManager.AUDIOFOCUS_FLAG_PAUSES_ON_DUCKABLE_LOSS : 0);













                    | (mPausesOnDuck ? AudioManager.AUDIOFOCUS_FLAG_PAUSES_ON_DUCKABLE_LOSS : 0)













                    | (mFocusLocked  ? AudioManager.AUDIOFOCUS_FLAG_LOCK : 0);















            return new AudioFocusRequest(mFocusListener, mListenerHandler,















                    mAttr, mFocusGain, flags);















        }

































media/java/android/media/AudioManager.java



+153
−99


























File changed.
Preview size limit exceeded, changes collapsed.