1/*
2 * Copyright (c) 2024 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16/**
17 * @addtogroup HdiAudio
18 *
19 * @brief Provides unified APIs for audio services to access audio drivers.
20 *
21 * An audio service can obtain an audio driver object or agent and then call APIs provided by this object or agent to
22 * access different types of audio devices based on the audio IDs, thereby obtaining audio information,
23 * subscribing to or unsubscribing from audio data, enabling or disabling an audio,
24 * setting the audio data reporting mode, and setting audio options such as the accuracy and measurement range.
25 *
26 * @since 4.1
27 * @version 3.0
28 */
29
30package ohos.hdi.audio.v3_0;
31
32import ohos.hdi.audio.v3_0.AudioTypes;
33import ohos.hdi.audio.v3_0.IAudioRender;
34import ohos.hdi.audio.v3_0.IAudioCapture;
35import ohos.hdi.audio.v3_0.IAudioCallback;
36
37/**
38 * @brief Provides audio adapter capabilities, including initializing ports, creating rendering and capturing tasks,
39 * and obtaining the port capability set.
40 *
41 * @see IAudioRender
42 * @see IAudioCapture
43 * @since 4.1
44 * @version 2.0
45 */
46interface IAudioAdapter {
47    /**
48     * @brief Initializes all ports of an audio adapter.
49     *
50     * Call this function before calling other driver functions to check whether the initialization is complete.
51     * If the initialization is not complete, wait for a while (for example, 100 ms) and perform the check again
52     * until the port initialization is complete.
53     *
54     * @param adapter Indicates the pointer to the audio adapter to operate.
55     * @return Returns <b>0</b> if the initialization is successful; returns a negative value otherwise.
56     *
57     * @since 4.1
58     * @version 2.0
59     */
60    InitAllPorts();
61
62    /**
63     * @brief Creates an <b>IAudioRender</b> object.
64     *
65     * @param adapter Indicates the pointer to the audio adapter to operate.
66     * @param desc Indicates the pointer to the descriptor of the audio adapter to start.
67     * @param attrs Indicates the pointer to the audio sampling attributes to open.
68     * @param render Indicates the double pointer to the <b>IAudioRender</b> object.
69     * @return Returns <b>0</b> if the <b>IAudioRender</b> object is created successfully;
70     * returns a negative value otherwise.
71     * @see GetPortCapability
72     * @see DestroyRender
73     *
74     * @since 4.1
75     * @version 2.0
76     */
77    CreateRender([in] struct AudioDeviceDescriptor desc, [in] struct AudioSampleAttributes attrs,
78                [out] IAudioRender render, [out] unsigned int renderId);
79
80    /**
81     * @brief Destroys an <b>IAudioRender</b> object.
82     *
83     * @attention Do not destroy the object during audio rendering.
84     *
85     * @param adapter Indicates the pointer to the audio adapter to operate.
86     * @param render Indicates the pointer to the <b>IAudioRender</b> object to operate.
87     * @return Returns <b>0</b> if the <b>IAudioRender</b> object is destroyed; returns a negative value otherwise.
88     * @see CreateRender
89     *
90     * @since 4.1
91     * @version 2.0
92     */
93    DestroyRender([in] unsigned int renderId);
94
95    /**
96     * @brief Creates an <b>IAudioCapture</b> object.
97     *
98     * @param adapter Indicates the pointer to the audio adapter to operate.
99     * @param desc Indicates the pointer to the descriptor of the audio adapter to start.
100     * @param attrs Indicates the pointer to the audio sampling attributes to open.
101     * @param capture Indicates the double pointer to the <b>IAudioCapture</b> object.
102     * @return Returns <b>0</b> if the <b>IAudioCapture</b> object is created successfully;
103     * returns a negative value otherwise.
104     * @see GetPortCapability
105     * @see DestroyCapture
106     *
107     * @since 4.1
108     * @version 2.0
109     */
110    CreateCapture([in] struct AudioDeviceDescriptor desc, [in] struct AudioSampleAttributes attrs,
111                  [out] IAudioCapture capture, [out] unsigned int captureId);
112
113    /**
114     * @brief Destroys an <b>IAudioCapture</b> object.
115     *
116     * @attention Do not destroy the object during audio capturing.
117     *
118     * @param adapter Indicates the pointer to the audio adapter to operate.
119     * @param capture Indicates the pointer to the <b>IAudioCapture</b> object to operate.
120     * @return Returns <b>0</b> if the <b>IAudioCapture</b> object is destroyed; returns a negative value otherwise.
121     * @see CreateCapture
122     *
123     * @since 4.1
124     * @version 2.0
125     */
126    DestroyCapture([in] unsigned int captureId);
127
128    /**
129     * @brief Obtains the capability set of the port driver for the audio adapter.
130     *
131     * @param adapter Indicates the pointer to the audio adapter to operate.
132     * @param port Indicates the pointer to the port.
133     * @param capability Indicates the pointer to the capability set to obtain.
134     * @return Returns <b>0</b> if the capability set is successfully obtained; returns a negative value otherwise.
135     *
136     * @since 4.1
137     * @version 2.0
138     */
139    GetPortCapability([in] struct AudioPort port, [out] struct AudioPortCapability capability);
140
141    /**
142     * @brief Sets the passthrough data transmission mode of the audio port driver.
143     *
144     * @param adapter Indicates the pointer to the audio adapter to operate.
145     * @param port Indicates the pointer to the port.
146     * @param mode Indicates the passthrough transmission mode to set.
147     * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise.
148     * @see GetPassthroughMode
149     *
150     * @since 4.1
151     * @version 2.0
152     */
153    SetPassthroughMode([in] struct AudioPort port, [in] enum AudioPortPassthroughMode mode);
154
155    /**
156     * @brief Obtains the passthrough data transmission mode of the audio port driver.
157     *
158     * @param adapter Indicates the pointer to the audio adapter to operate.
159     * @param port Indicates the pointer to the port.
160     * @param mode Indicates the pointer to the passthrough transmission mode to obtain.
161     * @return Returns <b>0</b> if the mode is successfully obtained; returns a negative value otherwise.
162     * @see SetPassthroughMode
163     *
164     * @since 4.1
165     * @version 2.0
166     */
167    GetPassthroughMode([in] struct AudioPort port, [out] enum AudioPortPassthroughMode mode);
168
169    /**
170     * @brief Get the device status of an adapter.
171     *
172     * @param adapter Indicates the audio adapter.
173     * @param status Indicates the status of device .
174     * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
175     *
176     * @since 4.1
177     * @version 2.0
178     */
179    GetDeviceStatus([out] struct AudioDeviceStatus status);
180
181    /**
182     * @brief Update audio route on several source and sink ports.
183     *
184     * @param adapter Indicates the pointer to the audio adapter to operate.
185     * @param route Indicates route information.
186     * @param routeHandle Indicates route handle.
187     * @return Returns <b>0</b> if the mode is successfully obtained; returns a negative value otherwise.
188     * @see SetPassthroughMode
189     *
190     * @since 4.1
191     * @version 2.0
192     */
193    UpdateAudioRoute([in] struct AudioRoute route, [out] int routeHandle);
194
195    /**
196     * @brief Release an audio route.
197     *
198     * @param adapter Indicates the pointer to the audio adapter to operate.
199     * @param routeHandle Indicates route handle.
200     * @return Returns <b>0</b> if the mode is successfully obtained; returns a negative value otherwise.
201     * @see SetPassthroughMode
202     *
203     * @since 4.1
204     * @version 2.0
205     */
206    ReleaseAudioRoute([in] int routeHandle);
207
208    /**
209     * @brief Sets the mute operation for the audio.
210     *
211     * @param adapter Indicates the pointer to the audio adapter to operate.
212     * @param mute Specifies whether to mute the audio. Value <b>true</b> means to mute the audio,
213     * and <b>false</b> means the opposite.
214     * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise.
215     * @see GetMute
216     *
217     * @since 4.1
218     * @version 2.0
219     */
220    SetMicMute([in] boolean mute);
221
222    /**
223     * @brief Obtains the mute operation set for the audio.
224     *
225     * @param adapter Indicates the pointer to the audio adapter to operate.
226     * @param mute Indicates the pointer to the mute operation set for the audio. Value <b>true</b> means that
227     * the audio is muted, and <b>false</b> means the opposite.
228     * @return Returns <b>0</b> if the mute operation is obtained; returns a negative value otherwise.
229     * @see SetMute
230     *
231     * @since 4.1
232     * @version 2.0
233     */
234    GetMicMute([out] boolean mute);
235
236    /**
237     * @brief Sets the audio volume for voice call.
238     *
239     * The volume ranges from 0.0 to 1.0. If the volume level in an audio service ranges from 0 to 15,
240     * <b>0.0</b> indicates that the audio is muted, and <b>1.0</b> indicates the maximum volume level (15).
241     *
242     * @param adapter Indicates the pointer to the audio adapter to operate.
243     * @param volume Indicates the volume to set. The value ranges from 0.0 to 1.0.
244     * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise.
245     * @see GetVolume
246     *
247     * @since 4.1
248     * @version 2.0
249     */
250    SetVoiceVolume([in] float volume);
251
252    /**
253     * @brief Sets extra audio parameters.
254     *
255     * @param adapter Indicates the audio adapter.
256     * @param key Indicates what kind of parameter type will be set.
257     * @param condition Indicates the specific extend parameter condition of AudioExtParamKey.
258     * @param value Indicates the value of the specified condition.
259     *
260     * The format of condition is <i>key=value</i>. Separate multiple key-value pairs by semicolons (;).
261     * When key equals to AudioExtParamKey::AUDIO_EXT_PARAM_KEY_VOLUME, the format of condition must be like this:
262     * <i>"EVENT_TYPE=xxx;VOLUME_GROUP_ID=xxx;AUDIO_VOLUME_TYPE=xxx;"</i>
263     * EVENT_TYPE indicates sub volume event type: SetVolume = 1; SetMute = 4;
264     * VOLUME_GROUP_ID indicates which volume group will be set;
265     * AUDIO_VOLUME_TYPE indicates which volume type will be set;
266     *
267     * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
268     *
269     * @since 4.1
270     * @version 2.0
271     */
272    SetExtraParams([in] enum AudioExtParamKey key, [in] String condition, [in] String value);
273
274    /**
275     * @brief Get extra audio parameters.
276     *
277     * @param adapter Indicates the audio adapter.
278     * @param key Indicates what kind of parameter type will be get.
279     * @param condition Indicates the specific extend parameter condition of AudioExtParamKey.
280     * @param value Indicates the value of the specified condition.
281     * @param lenth Indicates the length of the value pointer.
282     *
283     * The format of condition is <i>key=value</i>. Separate multiple key-value pairs by semicolons (;).
284     * When key equals to AudioExtParamKey::AUDIO_EXT_PARAM_KEY_VOLUME, the format of condition must be like this:
285     * <i>"EVENT_TYPE=xxx;VOLUME_GROUP_ID=xxx;AUDIO_VOLUME_TYPE=xxx;"</i>
286     * EVENT_TYPE indicates sub volume event type: GetVolume = 1; GetMinVolume = 2; GetMaxVolume = 3; IsStreamMute = 4;
287     * VOLUME_GROUP_ID indicates which volume group want get;
288     * AUDIO_VOLUME_TYPE indicates which volume type want get;
289     *
290     * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
291     *
292     * @since 4.1
293     * @version 2.0
294     */
295    GetExtraParams([in] enum AudioExtParamKey key, [in] String condition, [out] String value);
296
297    /**
298     * @brief Register extra audio parameters observer.
299     *
300     * @param adapter Indicates the audio adapter.
301     * @param callback Indicates param observer.
302     * @param cookie Indicates the pointer to the callback parameters;
303     * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
304     *
305     * @since 4.1
306     * @version 2.0
307     */
308    RegExtraParamObserver([in] IAudioCallback audioCallback, [in] byte cookie);
309}
310/** @} */