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 described
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 samplingRate
177     * @param channelMask The desired channel mask. AudioFormat.CHANNEL_OUT_DEFAULT if no change
178     * from active configuration requested.
179     * @param format The desired audio format. AudioFormat.ENCODING_DEFAULT if no change
180     * from active configuration requested.
181     * @param gain The desired gain. null if no gain changed requested.
182     */
183    public AudioPortConfig buildConfig(int samplingRate, int channelMask, int format,
184                                        AudioGainConfig gain) {
185        return new AudioPortConfig(this, samplingRate, channelMask, format, gain);
186    }
187
188    /**
189     * Get currently active configuration of this audio port.
190     */
191    public AudioPortConfig activeConfig() {
192        return mActiveConfig;
193    }
194
195    @Override
196    public boolean equals(Object o) {
197        if (o == null || !(o instanceof AudioPort)) {
198            return false;
199        }
200        AudioPort ap = (AudioPort)o;
201        return mHandle.equals(ap.handle());
202    }
203
204    @Override
205    public int hashCode() {
206        return mHandle.hashCode();
207    }
208
209    @Override
210    public String toString() {
211        String role = Integer.toString(mRole);
212        switch (mRole) {
213            case ROLE_NONE:
214                role = "NONE";
215                break;
216            case ROLE_SOURCE:
217                role = "SOURCE";
218                break;
219            case ROLE_SINK:
220                role = "SINK";
221                break;
222        }
223        return "{mHandle: " + mHandle
224                + ", mRole: " + role
225                + "}";
226    }
227}
228