1 /*
2  * Copyright (C) 2016 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.media;
18 
19 import android.os.Handler;
20 import android.os.Looper;
21 
22 /**
23  * AudioRouting defines an interface for controlling routing and routing notifications in
24  * AudioTrack and AudioRecord objects.
25  */
26 public interface AudioRouting {
27     /**
28      * Specifies an audio device (via an {@link AudioDeviceInfo} object) to route
29      * the output/input to/from.
30      * @param deviceInfo The {@link AudioDeviceInfo} specifying the audio sink or source.
31      *  If deviceInfo is null, default routing is restored.
32      * @return true if succesful, false if the specified {@link AudioDeviceInfo} is non-null and
33      * does not correspond to a valid audio device.
34      */
setPreferredDevice(AudioDeviceInfo deviceInfo)35     public boolean setPreferredDevice(AudioDeviceInfo deviceInfo);
36 
37     /**
38      * Returns the selected output/input specified by {@link #setPreferredDevice}. Note that this
39      * is not guaranteed to correspond to the actual device being used for playback/recording.
40      */
getPreferredDevice()41     public AudioDeviceInfo getPreferredDevice();
42 
43     /**
44      * Returns an {@link AudioDeviceInfo} identifying the current routing of this
45      * AudioTrack/AudioRecord.
46      * Note: The query is only valid if the AudioTrack/AudioRecord is currently playing.
47      * If it is not, <code>getRoutedDevice()</code> will return null.
48      */
getRoutedDevice()49     public AudioDeviceInfo getRoutedDevice();
50 
51     /**
52      * Adds an {@link AudioRouting.OnRoutingChangedListener} to receive notifications of routing
53      * changes on this AudioTrack/AudioRecord.
54      * @param listener The {@link AudioRouting.OnRoutingChangedListener} interface to receive
55      * notifications of rerouting events.
56      * @param handler  Specifies the {@link Handler} object for the thread on which to execute
57      * the callback. If <code>null</code>, the {@link Handler} associated with the main
58      * {@link Looper} will be used.
59      */
addOnRoutingChangedListener(OnRoutingChangedListener listener, Handler handler)60     public void addOnRoutingChangedListener(OnRoutingChangedListener listener,
61             Handler handler);
62 
63     /**
64      * Removes an {@link AudioRouting.OnRoutingChangedListener} which has been previously added
65      * to receive rerouting notifications.
66      * @param listener The previously added {@link AudioRouting.OnRoutingChangedListener} interface
67      * to remove.
68      */
removeOnRoutingChangedListener(OnRoutingChangedListener listener)69     public void removeOnRoutingChangedListener(OnRoutingChangedListener listener);
70 
71     /**
72      * Defines the interface by which applications can receive notifications of routing
73      * changes for the associated {@link AudioRouting}.
74      */
75     public interface OnRoutingChangedListener {
onRoutingChanged(AudioRouting router)76         public void onRoutingChanged(AudioRouting router);
77     }
78 }
79