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