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

3 files changed, 19 insertions, 7 deletions

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,