Updating (and completing) documentation post API-council changes.

1. Enum/Select/Notify API
2. (re)routing API

bug: 21151568
Change-Id: Idce969c8b8955022b7810cf5dddb800e6aa01000

4 files changed, 88 insertions, 26 deletions

diff --git a/media/java/android/media/AudioDeviceCallback.java b/media/java/android/media/AudioDeviceCallback.java
index d7fa492..d9f0037 100644
--- a/media/java/android/media/AudioDeviceCallback.java
+++ b/media/java/android/media/AudioDeviceCallback.java
@@ -17,16 +17,24 @@
 package android.media;
 
 /**
- * OnAudioDeviceConnectionListener defines the interface for notification listeners in the
- * {@link AudioManager}
+ * AudioDeviceCallback defines the mechanism by which applications can receive notifications
+ * of audio device connection and disconnection events.
+ * @see AudioManager#registerAudioDeviceCallback.
  */
 public abstract class AudioDeviceCallback {
     /**
-     * Called by the {@link AudioManager} to indicate that an audio device has been
-     * connected or disconnected. A listener will probably call the
-     * {@link AudioManager#getDevices} method to retrieve the current list of audio
-     * devices.
+     * Called by the {@link AudioManager} to indicate that one or more audio devices have been
+     * connected.
+     * @param addedDevices  An array of {@link AudioDeviceInfo} objects corresponding to any
+     * newly added audio devices.
      */
     public void onAudioDevicesAdded(AudioDeviceInfo[] addedDevices) {}
+
+    /**
+     * Called by the {@link AudioManager} to indicate that one or more audio devices have been
+     * disconnected.
+     * @param removedDevices  An array of {@link AudioDeviceInfo} objects corresponding to any
+     * newly removed audio devices.
+     */
     public void onAudioDevicesRemoved(AudioDeviceInfo[] removedDevices) {}
 }
diff --git a/media/java/android/media/AudioManager.java b/media/java/android/media/AudioManager.java
index e7013a5..316ccf6 100644
--- a/media/java/android/media/AudioManager.java
+++ b/media/java/android/media/AudioManager.java
@@ -3713,11 +3713,18 @@ public class AudioManager {
     private final static int MSG_DEVICES_DEVICES_ADDED = 0;
     private final static int MSG_DEVICES_DEVICES_REMOVED = 1;
 
+    /**
+     * The list of {@link AudioDeviceCallback} objects to receive add/remove notifications.
+     */
     private ArrayMap<AudioDeviceCallback, NativeEventHandlerDelegate>
         mDeviceCallbacks =
             new ArrayMap<AudioDeviceCallback, NativeEventHandlerDelegate>();
 
     /**
+     * The following are flags to allow users of {@link AudioManager#getDevices(int)} to filter
+     * the results list to only those device types they are interested in.
+     */
+    /**
      * Specifies to the {@link AudioManager#getDevices(int)} method to include
      * source (i.e. input) audio devices.
      */
@@ -3747,21 +3754,25 @@ public class AudioManager {
     }
 
     /**
-     * Generates a list of AudioDeviceInfo objects corresponding to the audio devices currently
-     * connected to the system and meeting the criteria specified in the <code>flags</code>
-     * parameter.
+     * Returns an array of {@link AudioDeviceInfo} objects corresponding to the audio devices
+     * currently connected to the system and meeting the criteria specified in the
+     * <code>flags</code> parameter.
      * @param flags A set of bitflags specifying the criteria to test.
-     * @see {@link GET_DEVICES_OUTPUTS}, {@link GET_DEVICES_INPUTS} and {@lGET_DEVICES_CES_ALL}.
+     * @see {@link GET_DEVICES_OUTPUTS}, {@link GET_DEVICES_INPUTS} and {@link GET_DEVICES_ALL}.
      * @return A (possibly zero-length) array of AudioDeviceInfo objects.
      */
     public AudioDeviceInfo[] getDevices(int flags) {
         return getDevicesStatic(flags);
     }
 
+    /**
+     * Does the actual computation to generate an array of (externally-visible) AudioDeviceInfo
+     * objects from the current (internal) AudioDevicePort list.
+     */
     private static AudioDeviceInfo[]
         infoListFromPortList(ArrayList<AudioDevicePort> ports, int flags) {
 
-        // figure out how many AudioDeviceInfo we need space for
+        // figure out how many AudioDeviceInfo we need space for...
         int numRecs = 0;
         for (AudioDevicePort port : ports) {
             if (checkFlags(port, flags)) {
@@ -3769,7 +3780,7 @@ public class AudioManager {
             }
         }
 
-        // Now load them up
+        // Now load them up...
         AudioDeviceInfo[] deviceList = new AudioDeviceInfo[numRecs];
         int slot = 0;
         for (AudioDevicePort port : ports) {
@@ -3782,7 +3793,12 @@ public class AudioManager {
     }
 
     /*
-     * Calculate the list of ports that are in ports_B, but not in ports_A
+     * Calculate the list of ports that are in ports_B, but not in ports_A. This is used by
+     * the add/remove callback mechanism to provide a list of the newly added or removed devices
+     * rather than the whole list and make the app figure it out.
+     * Note that calling this method with:
+     *  ports_A == PREVIOUS_ports and ports_B == CURRENT_ports will calculated ADDED ports.
+     *  ports_A == CURRENT_ports and ports_B == PREVIOUS_ports will calculated REMOVED ports.
      */
     private static AudioDeviceInfo[] calcListDeltas(
             ArrayList<AudioDevicePort> ports_A, ArrayList<AudioDevicePort> ports_B, int flags) {
@@ -3811,6 +3827,7 @@ public class AudioManager {
      * Generates a list of AudioDeviceInfo objects corresponding to the audio devices currently
      * connected to the system and meeting the criteria specified in the <code>flags</code>
      * parameter.
+     * This is an internal function. The public API front is getDevices(int).
      * @param flags A set of bitflags specifying the criteria to test.
      * @see {@link GET_DEVICES_OUTPUTS}, {@link GET_DEVICES_INPUTS} and {@link GET_DEVICES_ALL}.
      * @return A (possibly zero-length) array of AudioDeviceInfo objects.
@@ -3821,15 +3838,20 @@ public class AudioManager {
         int status = AudioManager.listAudioDevicePorts(ports);
         if (status != AudioManager.SUCCESS) {
             // fail and bail!
-            return new AudioDeviceInfo[0];
+            return new AudioDeviceInfo[0];  // Always return an array.
         }
 
         return infoListFromPortList(ports, flags);
     }
 
     /**
-     * Adds an {@link AudioDeviceCallback} to receive notifications of changes
+     * Registers an {@link AudioDeviceCallback} object to receive notifications of changes
      * to the set of connected audio devices.
+     * @param callback The {@link AudioDeviceCallback} object to receive connect/disconnect
+     * notifications.
+     * @param handler Specifies the {@link Handler} object for the thread on which to execute
+     * the callback. If <code>null</code>, the {@link Handler} associated with the main
+     * {@link Looper} will be used.
      */
     public void registerAudioDeviceCallback(AudioDeviceCallback callback,
             android.os.Handler handler) {
@@ -3842,8 +3864,10 @@ public class AudioManager {
     }
 
     /**
-     * Removes an {@link AudioDeviceCallback} which has been previously registered
+     * Unregisters an {@link AudioDeviceCallback} object which has been previously registered
      * to receive notifications of changes to the set of connected audio devices.
+     * @param callback The {@link AudioDeviceCallback} object that was previously registered
+     * with {@link AudioManager#registerAudioDeviceCallback) to be unregistered.
      */
     public void unregisterAudioDeviceCallback(AudioDeviceCallback callback) {
         synchronized (mDeviceCallbacks) {
@@ -3854,7 +3878,8 @@ public class AudioManager {
     }
 
     /**
-     * Sends device list change notification to all listeners.
+     * Internal method to compute and generate add/remove messages and then send to any
+     * registered callbacks.
      */
     private void broadcastDeviceListChange() {
         int status;
@@ -3908,7 +3933,8 @@ public class AudioManager {
 
         /**
          * Callback method called upon audio patch list update.
-         * @param patchList the updated list of audio patches
+         * Note: We don't do anything with Patches at this time, so ignore this notification.
+         * @param patchList the updated list of audio patches.
          */
         public void onAudioPatchListUpdate(AudioPatch[] patchList) {}
 
diff --git a/media/java/android/media/AudioRecord.java b/media/java/android/media/AudioRecord.java
index c0bc6d6..798daed 100644
--- a/media/java/android/media/AudioRecord.java
+++ b/media/java/android/media/AudioRecord.java
@@ -1218,16 +1218,23 @@ public class AudioRecord
     //--------------------------------------------------------------------------
     // (Re)Routing Info
     //--------------------
+    /**
+     * Defines the interface by which applications can receive notifications of routing
+     * changes for the associated {@link AudioRecord}.
+     */
     public interface OnRoutingChangedListener {
         /**
          * Called when the routing of an AudioRecord changes from either and explicit or
-         * policy rerouting.
+         * policy rerouting. Use {@link #getRoutedDevice()} to retrieve the newly routed-from
+         * device.
          */
         public void onRoutingChanged(AudioRecord audioRecord);
     }
 
     /**
      * Returns an {@link AudioDeviceInfo} identifying the current routing of this AudioRecord.
+     * Note: The query is only valid if the AudioRecord is currently recording. If it is not,
+     * <code>getRoutedDevice()</code> will return null.
      */
     public AudioDeviceInfo getRoutedDevice() {
         int deviceId = native_getRoutedDeviceId();
@@ -1245,8 +1252,9 @@ public class AudioRecord
     }
 
     /**
-     * The message sent to apps when the routing of this AudioRecord changes if they provide
-     * a {#link Handler} object to addOnRoutingChangeListener().
+     * The list of AudioRecord.OnRoutingChangedListener interface added (with
+     * {@link AudioRecord#addOnRoutingChangedListener(OnRoutingChangedListener,android.os.Handler)}
+     * by an app to receive (re)routing notifications.
      */
     private ArrayMap<OnRoutingChangedListener, NativeRoutingEventHandlerDelegate>
         mRoutingChangeListeners =
@@ -1255,6 +1263,11 @@ public class AudioRecord
     /**
      * Adds an {@link OnRoutingChangedListener} to receive notifications of routing changes
      * on this AudioRecord.
+     * @param listener The {@link OnRoutingChangedListener} interface to receive notifications
+     * of rerouting events.
+     * @param handler  Specifies the {@link Handler} object for the thread on which to execute
+     * the callback. If <code>null</code>, the {@link Handler} associated with the main
+     * {@link Looper} will be used.
      */
     public void addOnRoutingChangedListener(OnRoutingChangedListener listener,
             android.os.Handler handler) {
@@ -1271,7 +1284,8 @@ public class AudioRecord
 
     /**
      * Removes an {@link OnRoutingChangedListener} which has been previously added
-     * to receive notifications of changes to the set of connected audio devices.
+     * to receive rerouting notifications.
+     * @param listener The previously added {@link OnRoutingChangedListener} interface to remove.
      */
     public void removeOnRoutingChangedListener(OnRoutingChangedListener listener) {
         synchronized (mRoutingChangeListeners) {
diff --git a/media/java/android/media/AudioTrack.java b/media/java/android/media/AudioTrack.java
index f893fdd..2702405 100644
--- a/media/java/android/media/AudioTrack.java
+++ b/media/java/android/media/AudioTrack.java
@@ -2074,16 +2074,23 @@ public class AudioTrack
     //--------------------------------------------------------------------------
     // (Re)Routing Info
     //--------------------
+    /**
+     * Defines the interface by which applications can receive notifications of routing
+     * changes for the associated {@link AudioTrack}.
+     */
     public interface OnRoutingChangedListener {
         /**
          * Called when the routing of an AudioTrack changes from either and explicit or
-         * policy rerouting.
+         * policy rerouting.  Use {@link #getRoutedDevice()} to retrieve the newly routed-to
+         * device.
          */
         public void onRoutingChanged(AudioTrack audioTrack);
     }
 
     /**
      * Returns an {@link AudioDeviceInfo} identifying the current routing of this AudioTrack.
+     * Note: The query is only valid if the AudioTrack is currently playing. If it is not,
+     * <code>getRoutedDevice()</code> will return null.
      */
     public AudioDeviceInfo getRoutedDevice() {
         int deviceId = native_getRoutedDeviceId();
@@ -2101,8 +2108,9 @@ public class AudioTrack
     }
 
     /**
-     * The message sent to apps when the routing of this AudioTrack changes if they provide
-     * a {#link Handler} object to addOnRoutingChangedListener().
+     * The list of AudioTrack.OnRoutingChangedListener interfaces added (with
+     * {@link AudioTrack#addOnRoutingChangedListener(OnRoutingChangedListener, android.os.Handler)}
+     * by an app to receive (re)routing notifications.
      */
     private ArrayMap<OnRoutingChangedListener, NativeRoutingEventHandlerDelegate>
         mRoutingChangeListeners =
@@ -2111,6 +2119,11 @@ public class AudioTrack
     /**
      * Adds an {@link OnRoutingChangedListener} to receive notifications of routing changes
      * on this AudioTrack.
+     * @param listener The {@link OnRoutingChangedListener} interface to receive notifications
+     * of rerouting events.
+     * @param handler  Specifies the {@link Handler} object for the thread on which to execute
+     * the callback. If <code>null</code>, the {@link Handler} associated with the main
+     * {@link Looper} will be used.
      */
     public void addOnRoutingChangedListener(OnRoutingChangedListener listener,
             android.os.Handler handler) {
@@ -2127,7 +2140,8 @@ public class AudioTrack
 
     /**
      * Removes an {@link OnRoutingChangedListener} which has been previously added
-     * to receive notifications of changes to the set of connected audio devices.
+     * to receive rerouting notifications.
+     * @param listener The previously added {@link OnRoutingChangedListener} interface to remove.
      */
     public void removeOnRoutingChangedListener(OnRoutingChangedListener listener) {
         synchronized (mRoutingChangeListeners) {