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
17package 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 */
38public 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
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
93    AudioHandle handle() {
94        return mHandle;
95    }
96
97    /**
98     * Get the system unique device ID.
99     */
100    public int id() {
101        return mHandle.id();
102    }
103
104
105    /**
106     * Get the audio port role
107     */
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     */
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     */
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     */
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     */
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     */
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     */
159    public AudioGain[] gains() {
160        return mGains;
161    }
162
163    /**
164     * Get the gain descriptor at a given index
165     */
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     */
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     */
190    public AudioPortConfig activeConfig() {
191        return mActiveConfig;
192    }
193
194    @Override
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
204    public int hashCode() {
205        return mHandle.hashCode();
206    }
207
208    @Override
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