1 /*
2  * Copyright (C) 2014 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 /**
20  * An audio port is a node of the audio framework or hardware that can be connected to or
21  * disconnect from another audio node to create a specific audio routing configuration.
22  * Examples of audio ports are an output device (speaker) or an output mix (see AudioMixPort).
23  * All attributes that are relevant for applications to make routing selection are decribed
24  * in an AudioPort,  in particular:
25  * - possible channel mask configurations.
26  * - audio format (PCM 16bit, PCM 24bit...)
27  * - gain: a port can be associated with one or more gain controllers (see AudioGain).
28  *
29  * This object is always created by the framework and read only by applications.
30  * A list of all audio port descriptors currently available for applications to control
31  * is obtained by AudioManager.listAudioPorts().
32  * An application can obtain an AudioPortConfig for a valid configuration of this port
33  * by calling AudioPort.buildConfig() and use this configuration
34  * to create a connection between audio sinks and sources with AudioManager.connectAudioPatch()
35  *
36  * @hide
37  */
38 public class AudioPort {
39     private static final String TAG = "AudioPort";
40 
41     /**
42      * For use by the audio framework.
43      */
44     public static final int ROLE_NONE = 0;
45     /**
46      * The audio port is a source (produces audio)
47      */
48     public static final int ROLE_SOURCE = 1;
49     /**
50      * The audio port is a sink (consumes audio)
51      */
52     public static final int ROLE_SINK = 2;
53 
54     /**
55      * audio port type for use by audio framework implementation
56      */
57     public static final int TYPE_NONE = 0;
58     /**
59      */
60     public static final int TYPE_DEVICE = 1;
61     /**
62      */
63     public static final int TYPE_SUBMIX = 2;
64     /**
65      */
66     public static final int TYPE_SESSION = 3;
67 
68 
69     AudioHandle mHandle;
70     protected final int mRole;
71     private final String mName;
72     private final int[] mSamplingRates;
73     private final int[] mChannelMasks;
74     private final int[] mChannelIndexMasks;
75     private final int[] mFormats;
76     private final AudioGain[] mGains;
77     private AudioPortConfig mActiveConfig;
78 
AudioPort(AudioHandle handle, int role, String name, int[] samplingRates, int[] channelMasks, int[] channelIndexMasks, int[] formats, AudioGain[] gains)79     AudioPort(AudioHandle handle, int role, String name,
80             int[] samplingRates, int[] channelMasks, int[] channelIndexMasks,
81             int[] formats, AudioGain[] gains) {
82 
83         mHandle = handle;
84         mRole = role;
85         mName = name;
86         mSamplingRates = samplingRates;
87         mChannelMasks = channelMasks;
88         mChannelIndexMasks = channelIndexMasks;
89         mFormats = formats;
90         mGains = gains;
91     }
92 
handle()93     AudioHandle handle() {
94         return mHandle;
95     }
96 
97     /**
98      * Get the system unique device ID.
99      */
id()100     public int id() {
101         return mHandle.id();
102     }
103 
104 
105     /**
106      * Get the audio port role
107      */
role()108     public int role() {
109         return mRole;
110     }
111 
112     /**
113      * Get the human-readable name of this port. Perhaps an internal
114      * designation or an physical device.
115      */
name()116     public String name() {
117         return mName;
118     }
119 
120     /**
121      * Get the list of supported sampling rates
122      * Empty array if sampling rate is not relevant for this audio port
123      */
samplingRates()124     public int[] samplingRates() {
125         return mSamplingRates;
126     }
127 
128     /**
129      * Get the list of supported channel mask configurations
130      * (e.g AudioFormat.CHANNEL_OUT_STEREO)
131      * Empty array if channel mask is not relevant for this audio port
132      */
channelMasks()133     public int[] channelMasks() {
134         return mChannelMasks;
135     }
136 
137     /**
138      * Get the list of supported channel index mask configurations
139      * (e.g 0x0003 means 2 channel, 0x000F means 4 channel....)
140      * Empty array if channel index mask is not relevant for this audio port
141      */
channelIndexMasks()142     public int[] channelIndexMasks() {
143         return mChannelIndexMasks;
144     }
145 
146     /**
147      * Get the list of supported audio format configurations
148      * (e.g AudioFormat.ENCODING_PCM_16BIT)
149      * Empty array if format is not relevant for this audio port
150      */
formats()151     public int[] formats() {
152         return mFormats;
153     }
154 
155     /**
156      * Get the list of gain descriptors
157      * Empty array if this port does not have gain control
158      */
gains()159     public AudioGain[] gains() {
160         return mGains;
161     }
162 
163     /**
164      * Get the gain descriptor at a given index
165      */
gain(int index)166     AudioGain gain(int index) {
167         if (index < 0 || index >= mGains.length) {
168             return null;
169         }
170         return mGains[index];
171     }
172 
173     /**
174      * Build a specific configuration of this audio port for use by methods
175      * like AudioManager.connectAudioPatch().
176      * @param channelMask The desired channel mask. AudioFormat.CHANNEL_OUT_DEFAULT if no change
177      * from active configuration requested.
178      * @param format The desired audio format. AudioFormat.ENCODING_DEFAULT if no change
179      * from active configuration requested.
180      * @param gain The desired gain. null if no gain changed requested.
181      */
buildConfig(int samplingRate, int channelMask, int format, AudioGainConfig gain)182     public AudioPortConfig buildConfig(int samplingRate, int channelMask, int format,
183                                         AudioGainConfig gain) {
184         return new AudioPortConfig(this, samplingRate, channelMask, format, gain);
185     }
186 
187     /**
188      * Get currently active configuration of this audio port.
189      */
activeConfig()190     public AudioPortConfig activeConfig() {
191         return mActiveConfig;
192     }
193 
194     @Override
equals(Object o)195     public boolean equals(Object o) {
196         if (o == null || !(o instanceof AudioPort)) {
197             return false;
198         }
199         AudioPort ap = (AudioPort)o;
200         return mHandle.equals(ap.handle());
201     }
202 
203     @Override
hashCode()204     public int hashCode() {
205         return mHandle.hashCode();
206     }
207 
208     @Override
toString()209     public String toString() {
210         String role = Integer.toString(mRole);
211         switch (mRole) {
212             case ROLE_NONE:
213                 role = "NONE";
214                 break;
215             case ROLE_SOURCE:
216                 role = "SOURCE";
217                 break;
218             case ROLE_SINK:
219                 role = "SINK";
220                 break;
221         }
222         return "{mHandle: " + mHandle
223                 + ", mRole: " + role
224                 + "}";
225     }
226 }
227