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
17package android.hardware.audio@2.0;
18
19import android.hardware.audio.common@2.0;
20import IStreamIn;
21import IStreamOut;
22
23interface IDevice {
24    typedef android.hardware.audio@2.0::Result Result;
25
26    /**
27     * Returns whether the audio hardware interface has been initialized.
28     *
29     * @return retval OK on success, NOT_INITIALIZED on failure.
30     */
31    initCheck() generates (Result retval);
32
33    /**
34     * Sets the audio volume for all audio activities other than voice call. If
35     * NOT_SUPPORTED is returned, the software mixer will emulate this
36     * capability.
37     *
38     * @param volume 1.0f means unity, 0.0f is zero.
39     * @return retval operation completion status.
40     */
41    setMasterVolume(float volume) generates (Result retval);
42
43    /**
44     * Get the current master volume value for the HAL, if the HAL supports
45     * master volume control. For example, AudioFlinger will query this value
46     * from the primary audio HAL when the service starts and use the value for
47     * setting the initial master volume across all HALs. HALs which do not
48     * support this method must return NOT_SUPPORTED in 'retval'.
49     *
50     * @return retval operation completion status.
51     * @return volume 1.0f means unity, 0.0f is zero.
52     */
53    getMasterVolume() generates (Result retval, float volume);
54
55    /**
56     * Sets microphone muting state.
57     *
58     * @param mute whether microphone is muted.
59     * @return retval operation completion status.
60     */
61    setMicMute(bool mute) generates (Result retval);
62
63    /**
64     * Gets whether microphone is muted.
65     *
66     * @return retval operation completion status.
67     * @return mute whether microphone is muted.
68     */
69    getMicMute() generates (Result retval, bool mute);
70
71    /**
72     * Set the audio mute status for all audio activities. If the return value
73     * is NOT_SUPPORTED, the software mixer will emulate this capability.
74     *
75     * @param mute whether audio is muted.
76     * @return retval operation completion status.
77     */
78    setMasterMute(bool mute) generates (Result retval);
79
80    /**
81     * Get the current master mute status for the HAL, if the HAL supports
82     * master mute control. AudioFlinger will query this value from the primary
83     * audio HAL when the service starts and use the value for setting the
84     * initial master mute across all HALs. HAL must indicate that the feature
85     * is not supported by returning NOT_SUPPORTED status.
86     *
87     * @return retval operation completion status.
88     * @return mute whether audio is muted.
89     */
90    getMasterMute() generates (Result retval, bool mute);
91
92    /**
93     * Returns audio input buffer size according to parameters passed or
94     * INVALID_ARGUMENTS if one of the parameters is not supported.
95     *
96     * @param config audio configuration.
97     * @return retval operation completion status.
98     * @return bufferSize input buffer size in bytes.
99     */
100    getInputBufferSize(AudioConfig config)
101            generates (Result retval, uint64_t bufferSize);
102
103    /**
104     * This method creates and opens the audio hardware output stream.
105     * If the stream can not be opened with the proposed audio config,
106     * HAL must provide suggested values for the audio config.
107     *
108     * @param ioHandle handle assigned by AudioFlinger.
109     * @param device device type and (if needed) address.
110     * @param config stream configuration.
111     * @param flags additional flags.
112     * @return retval operation completion status.
113     * @return outStream created output stream.
114     * @return suggestedConfig in case of invalid parameters, suggested config.
115     */
116    openOutputStream(
117            AudioIoHandle ioHandle,
118            DeviceAddress device,
119            AudioConfig config,
120            AudioOutputFlag flags) generates (
121                    Result retval,
122                    IStreamOut outStream,
123                    AudioConfig suggestedConfig);
124
125    /**
126     * This method creates and opens the audio hardware input stream.
127     * If the stream can not be opened with the proposed audio config,
128     * HAL must provide suggested values for the audio config.
129     *
130     * @param ioHandle handle assigned by AudioFlinger.
131     * @param device device type and (if needed) address.
132     * @param config stream configuration.
133     * @param flags additional flags.
134     * @param source source specification.
135     * @return retval operation completion status.
136     * @return inStream in case of success, created input stream.
137     * @return suggestedConfig in case of invalid parameters, suggested config.
138     */
139    openInputStream(
140            AudioIoHandle ioHandle,
141            DeviceAddress device,
142            AudioConfig config,
143            AudioInputFlag flags,
144            AudioSource source) generates (
145                    Result retval,
146                    IStreamIn inStream,
147                    AudioConfig suggestedConfig);
148
149    /**
150     * Returns whether HAL supports audio patches.
151     *
152     * @return supports true if audio patches are supported.
153     */
154    supportsAudioPatches() generates (bool supports);
155
156    /**
157     * Creates an audio patch between several source and sink ports.  The handle
158     * is allocated by the HAL and must be unique for this audio HAL module.
159     *
160     * @param sources patch sources.
161     * @param sinks patch sinks.
162     * @return retval operation completion status.
163     * @return patch created patch handle.
164     */
165    createAudioPatch(vec<AudioPortConfig> sources, vec<AudioPortConfig> sinks)
166            generates (Result retval, AudioPatchHandle patch);
167
168    /**
169     * Release an audio patch.
170     *
171     * @param patch patch handle.
172     * @return retval operation completion status.
173     */
174    releaseAudioPatch(AudioPatchHandle patch) generates (Result retval);
175
176    /**
177     * Returns the list of supported attributes for a given audio port.
178     *
179     * As input, 'port' contains the information (type, role, address etc...)
180     * needed by the HAL to identify the port.
181     *
182     * As output, 'resultPort' contains possible attributes (sampling rates,
183     * formats, channel masks, gain controllers...) for this port.
184     *
185     * @param port port identifier.
186     * @return retval operation completion status.
187     * @return resultPort port descriptor with all parameters filled up.
188     */
189    getAudioPort(AudioPort port)
190            generates (Result retval, AudioPort resultPort);
191
192    /**
193     * Set audio port configuration.
194     *
195     * @param config audio port configuration.
196     * @return retval operation completion status.
197     */
198    setAudioPortConfig(AudioPortConfig config) generates (Result retval);
199
200    /**
201     * Gets the HW synchronization source of the device. Calling this method is
202     * equivalent to getting AUDIO_PARAMETER_HW_AV_SYNC on the legacy HAL.
203     *
204     * @return hwAvSync HW synchronization source
205     */
206    getHwAvSync() generates (AudioHwSync hwAvSync);
207
208    /**
209     * Sets whether the screen is on. Calling this method is equivalent to
210     * setting AUDIO_PARAMETER_KEY_SCREEN_STATE on the legacy HAL.
211     *
212     * @param turnedOn whether the screen is turned on.
213     * @return retval operation completion status.
214     */
215    setScreenState(bool turnedOn) generates (Result retval);
216
217    /**
218     * Generic method for retrieving vendor-specific parameter values.
219     * The framework does not interpret the parameters, they are passed
220     * in an opaque manner between a vendor application and HAL.
221     *
222     * @param keys parameter keys.
223     * @return retval operation completion status.
224     * @return parameters parameter key value pairs.
225     */
226    getParameters(vec<string> keys)
227            generates (Result retval, vec<ParameterValue> parameters);
228
229    /**
230     * Generic method for setting vendor-specific parameter values.
231     * The framework does not interpret the parameters, they are passed
232     * in an opaque manner between a vendor application and HAL.
233     *
234     * @param parameters parameter key value pairs.
235     * @return retval operation completion status.
236     */
237    setParameters(vec<ParameterValue> parameters) generates (Result retval);
238
239    /**
240     * Dumps information about the stream into the provided file descriptor.
241     * This is used for the dumpsys facility.
242     *
243     * @param fd dump file descriptor.
244     */
245    debugDump(handle fd);
246};
247