API for audio session ID generation

Expose the value used by the framework to generate an audio
 session ID when a value isn't known.
Rename allocateAudioSessionId() to generateAudioSessionId()
 as this operation doesn't "allocate" anything, and there is
 no allocated resource to free after this operation.

Bug 16401631

Change-Id: I7a7bc05b39ea0b024ff225254eb755a9c85a2ad9

5 files changed, 22 insertions, 9 deletions

diff --git a/api/current.txt b/api/current.txt
index 011fa53..7bac44f 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -14105,8 +14105,8 @@ package android.media {
     method public void adjustStreamVolume(int, int, int);
     method public void adjustSuggestedStreamVolume(int, int, int);
     method public void adjustVolume(int, int);
-    method public int allocateAudioSessionId();
     method public void dispatchMediaKeyEvent(android.view.KeyEvent);
+    method public int generateAudioSessionId();
     method public int getMode();
     method public java.lang.String getParameters(java.lang.String);
     method public java.lang.String getProperty(java.lang.String);
@@ -14167,6 +14167,7 @@ package android.media {
     field public static final int AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK = -3; // 0xfffffffd
     field public static final int AUDIOFOCUS_REQUEST_FAILED = 0; // 0x0
     field public static final int AUDIOFOCUS_REQUEST_GRANTED = 1; // 0x1
+    field public static final int AUDIO_SESSION_ID_GENERATE = 0; // 0x0
     field public static final int ERROR = -1; // 0xffffffff
     field public static final int ERROR_DEAD_OBJECT = -6; // 0xfffffffa
     field public static final java.lang.String EXTRA_RINGER_MODE = "android.media.EXTRA_RINGER_MODE";
diff --git a/core/java/android/speech/tts/TextToSpeech.java b/core/java/android/speech/tts/TextToSpeech.java
index d8b9b5f..0075d0b 100644
--- a/core/java/android/speech/tts/TextToSpeech.java
+++ b/core/java/android/speech/tts/TextToSpeech.java
@@ -604,7 +604,7 @@ public class TextToSpeech {
 
         /**
          * Parameter key to specify an audio session identifier (obtained from
-         * {@link AudioManager#allocateAudioSessionId()}) that will be used by the request audio
+         * {@link AudioManager#generateAudioSessionId()}) that will be used by the request audio
          * output. It can be used to associate one of the {@link android.media.audiofx.AudioEffect}
          * objects with the synthesis (or earcon) output.
          *
diff --git a/media/java/android/media/AudioManager.java b/media/java/android/media/AudioManager.java
index 5dc59f9..52608a9 100644
--- a/media/java/android/media/AudioManager.java
+++ b/media/java/android/media/AudioManager.java
@@ -1697,20 +1697,29 @@ public class AudioManager {
     /**
      * Return a new audio session identifier not associated with any player or effect.
      * It can for instance be used to create one of the {@link android.media.audiofx.AudioEffect}
-     * objects.
+     * objects or specify a session for speech synthesis in
+     * {@link android.speech.tts.TextToSpeech.Engine}.
      * @return a new unclaimed and unused audio session identifier, or {@link #ERROR} when the
-     *   system failed to allocate a new session.
+     *   system failed to generate a new session.
      */
-    public int allocateAudioSessionId() {
+    public int generateAudioSessionId() {
         int session = AudioSystem.newAudioSessionId();
         if (session > 0) {
             return session;
         } else {
-            Log.e(TAG, "Failure to allocate a new audio session ID");
+            Log.e(TAG, "Failure to generate a new audio session ID");
             return ERROR;
         }
     }
 
+    /**
+     * A special audio session ID to indicate that the audio session ID isn't known and the
+     * framework should generate a new value. This can be used when building a new
+     * {@link AudioTrack} instance with
+     * {@link AudioTrack#AudioTrack(AudioAttributes, AudioFormat, int, int, int)}.
+     */
+    public static final int AUDIO_SESSION_ID_GENERATE = AudioSystem.AUDIO_SESSION_ALLOCATE;
+
 
     /*
      * Sets a generic audio configuration parameter. The use of these parameters
diff --git a/media/java/android/media/AudioTrack.java b/media/java/android/media/AudioTrack.java
index a8a4710..f3c8ac6 100644
--- a/media/java/android/media/AudioTrack.java
+++ b/media/java/android/media/AudioTrack.java
@@ -379,7 +379,10 @@ public class AudioTrack
      *   for the successful creation of an AudioTrack instance in streaming mode. Using values
      *   smaller than getMinBufferSize() will result in an initialization failure.
      * @param mode streaming or static buffer. See {@link #MODE_STATIC} and {@link #MODE_STREAM}.
-     * @param sessionId ID of audio session the AudioTrack must be attached to.
+     * @param sessionId ID of audio session the AudioTrack must be attached to, or
+     *   {@link AudioManager#AUDIO_SESSION_ID_GENERATE} if the session isn't known at construction
+     *   time. See also {@link AudioManager#generateAudioSessionId()} to obtain a session ID before
+     *   construction.
      * @throws IllegalArgumentException
      */
     public AudioTrack(AudioAttributes attributes, AudioFormat format, int bufferSizeInBytes,
diff --git a/media/java/android/media/MediaPlayer.java b/media/java/android/media/MediaPlayer.java
index b15bd69..a29b0bc 100644
--- a/media/java/android/media/MediaPlayer.java
+++ b/media/java/android/media/MediaPlayer.java
@@ -836,7 +836,7 @@ public class MediaPlayer implements SubtitleController.Listener
      * @param holder the SurfaceHolder to use for displaying the video, may be null.
      * @param audioAttributes the {@link AudioAttributes} to be used by the media player.
      * @param audioSessionId the audio session ID to be used by the media player,
-     *     see {@link AudioManager#allocateAudioSessionId()} to obtain a new session.
+     *     see {@link AudioManager#generateAudioSessionId()} to obtain a new session.
      * @return a MediaPlayer object, or null if creation failed
      */
     public static MediaPlayer create(Context context, Uri uri, SurfaceHolder holder,
@@ -899,7 +899,7 @@ public class MediaPlayer implements SubtitleController.Listener
      *              the resource to use as the datasource
      * @param audioAttributes the {@link AudioAttributes} to be used by the media player.
      * @param audioSessionId the audio session ID to be used by the media player,
-     *     see {@link AudioManager#allocateAudioSessionId()} to obtain a new session.
+     *     see {@link AudioManager#generateAudioSessionId()} to obtain a new session.
      * @return a MediaPlayer object, or null if creation failed
      */
     public static MediaPlayer create(Context context, int resid,