Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "Updating (and completing) documentation post API-council changes." into mnc-dev

Browse Source
This commit is contained in:
Paul McLean
2015-05-20 15:56:06 +00:00
committed by Android (Google) Code Review
parent e46a5b31d6 8e6c9f4617
commit aa1cd25db7
4 changed files with 88 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
media/java/android/media/AudioDeviceCallback.java
View File

@@ -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) {}
}

50
media/java/android/media/AudioManager.java
View File

@@ -3713,10 +3713,17 @@ 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) {}

22
media/java/android/media/AudioRecord.java
View File

@@ -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) {

22
media/java/android/media/AudioTrack.java
View File

@@ -2153,16 +2153,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();
@@ -2180,8 +2187,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 =
@@ -2190,6 +2198,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) {
@@ -2206,7 +2219,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) {