Merge "Updating (and completing) documentation post API-council changes." into mnc-dev
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 @@
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 @@
}
/**
- * 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 @@
}
}
- // Now load them up
+ // Now load them up...
AudioDeviceInfo[] deviceList = new AudioDeviceInfo[numRecs];
int slot = 0;
for (AudioDevicePort port : ports) {
@@ -3782,7 +3793,12 @@
}
/*
- * 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 @@
* 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 @@
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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
/**
* 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 @@
//--------------------------------------------------------------------------
// (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 @@
}
/**
- * 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 @@
/**
* 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 @@
/**
* 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 d21762b..7697e27 100644
--- a/media/java/android/media/AudioTrack.java
+++ b/media/java/android/media/AudioTrack.java
@@ -2153,16 +2153,23 @@
//--------------------------------------------------------------------------
// (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();
@@ -2180,8 +2187,9 @@
}
/**
- * 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 =
@@ -2190,6 +2198,11 @@
/**
* 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) {
@@ -2206,7 +2219,8 @@
/**
* 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) {