1/*
2 * Copyright (c) 2022-2023 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.0
27 * @version 1.0
28 */
29
30package ohos.hdi.audio.v1_0;
31
32import ohos.hdi.audio.v1_0.AudioTypes;
33import ohos.hdi.audio.v1_0.IAudioRender;
34import ohos.hdi.audio.v1_0.IAudioCapture;
35import ohos.hdi.audio.v1_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.0
44 * @version 1.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    InitAllPorts();
58
59    /**
60     * @brief Creates an <b>IAudioRender</b> object.
61     *
62     * @param adapter Indicates the pointer to the audio adapter to operate.
63     * @param desc Indicates the pointer to the descriptor of the audio adapter to start.
64     * @param attrs Indicates the pointer to the audio sampling attributes to open.
65     * @param render Indicates the double pointer to the <b>IAudioRender</b> object.
66     * @return Returns <b>0</b> if the <b>IAudioRender</b> object is created successfully;
67     * returns a negative value otherwise.
68     * @see GetPortCapability
69     * @see DestroyRender
70     */
71    CreateRender([in] struct AudioDeviceDescriptor desc, [in] struct AudioSampleAttributes attrs,
72                [out] IAudioRender render, [out] unsigned int renderId);
73
74    /**
75     * @brief Destroys an <b>IAudioRender</b> object.
76     *
77     * @attention Do not destroy the object during audio rendering.
78     *
79     * @param adapter Indicates the pointer to the audio adapter to operate.
80     * @param render Indicates the pointer to the <b>IAudioRender</b> object to operate.
81     * @return Returns <b>0</b> if the <b>IAudioRender</b> object is destroyed; returns a negative value otherwise.
82     * @see CreateRender
83     */
84    DestroyRender([in] unsigned int renderId);
85
86    /**
87     * @brief Creates an <b>IAudioCapture</b> object.
88     *
89     * @param adapter Indicates the pointer to the audio adapter to operate.
90     * @param desc Indicates the pointer to the descriptor of the audio adapter to start.
91     * @param attrs Indicates the pointer to the audio sampling attributes to open.
92     * @param capture Indicates the double pointer to the <b>IAudioCapture</b> object.
93     * @return Returns <b>0</b> if the <b>IAudioCapture</b> object is created successfully;
94     * returns a negative value otherwise.
95     * @see GetPortCapability
96     * @see DestroyCapture
97     */
98    CreateCapture([in] struct AudioDeviceDescriptor desc, [in] struct AudioSampleAttributes attrs,
99                  [out] IAudioCapture capture, [out] unsigned int captureId);
100
101    /**
102     * @brief Destroys an <b>IAudioCapture</b> object.
103     *
104     * @attention Do not destroy the object during audio capturing.
105     *
106     * @param adapter Indicates the pointer to the audio adapter to operate.
107     * @param capture Indicates the pointer to the <b>IAudioCapture</b> object to operate.
108     * @return Returns <b>0</b> if the <b>IAudioCapture</b> object is destroyed; returns a negative value otherwise.
109     * @see CreateCapture
110     */
111    DestroyCapture([in] unsigned int captureId);
112
113    /**
114     * @brief Obtains the capability set of the port driver for the audio adapter.
115     *
116     * @param adapter Indicates the pointer to the audio adapter to operate.
117     * @param port Indicates the pointer to the port.
118     * @param capability Indicates the pointer to the capability set to obtain.
119     * @return Returns <b>0</b> if the capability set is successfully obtained; returns a negative value otherwise.
120     */
121    GetPortCapability([in] struct AudioPort port, [out] struct AudioPortCapability capability);
122
123    /**
124     * @brief Sets the passthrough data transmission mode of the audio port driver.
125     *
126     * @param adapter Indicates the pointer to the audio adapter to operate.
127     * @param port Indicates the pointer to the port.
128     * @param mode Indicates the passthrough transmission mode to set.
129     * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise.
130     * @see GetPassthroughMode
131     */
132    SetPassthroughMode([in] struct AudioPort port, [in] enum AudioPortPassthroughMode mode);
133
134    /**
135     * @brief Obtains the passthrough data transmission mode of the audio port driver.
136     *
137     * @param adapter Indicates the pointer to the audio adapter to operate.
138     * @param port Indicates the pointer to the port.
139     * @param mode Indicates the pointer to the passthrough transmission mode to obtain.
140     * @return Returns <b>0</b> if the mode is successfully obtained; returns a negative value otherwise.
141     * @see SetPassthroughMode
142     */
143    GetPassthroughMode([in] struct AudioPort port, [out] enum AudioPortPassthroughMode mode);
144
145    /**
146     * @brief Get the device status of an adapter.
147     *
148     * @param adapter Indicates the audio adapter.
149     * @param status Indicates the status of device .
150     * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
151     */
152    GetDeviceStatus([out] struct AudioDeviceStatus status);
153
154    /**
155     * @brief Update audio route on several source and sink ports.
156     *
157     * @param adapter Indicates the pointer to the audio adapter to operate.
158     * @param route Indicates route information.
159     * @param routeHandle Indicates route handle.
160     * @return Returns <b>0</b> if the mode is successfully obtained; returns a negative value otherwise.
161     * @see SetPassthroughMode
162     */
163    UpdateAudioRoute([in] struct AudioRoute route, [out] int routeHandle);
164
165    /**
166     * @brief Release an audio route.
167     *
168     * @param adapter Indicates the pointer to the audio adapter to operate.
169     * @param routeHandle Indicates route handle.
170     * @return Returns <b>0</b> if the mode is successfully obtained; returns a negative value otherwise.
171     * @see SetPassthroughMode
172     */
173    ReleaseAudioRoute([in] int routeHandle);
174
175    /**
176     * @brief Sets the mute operation for the audio.
177     *
178     * @param adapter Indicates the pointer to the audio adapter to operate.
179     * @param mute Specifies whether to mute the audio. Value <b>true</b> means to mute the audio,
180     * and <b>false</b> means the opposite.
181     * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise.
182     * @see GetMute
183     */
184    SetMicMute([in] boolean mute);
185
186    /**
187     * @brief Obtains the mute operation set for the audio.
188     *
189     * @param adapter Indicates the pointer to the audio adapter to operate.
190     * @param mute Indicates the pointer to the mute operation set for the audio. Value <b>true</b> means that
191     * the audio is muted, and <b>false</b> means the opposite.
192     * @return Returns <b>0</b> if the mute operation is obtained; returns a negative value otherwise.
193     * @see SetMute
194     */
195    GetMicMute([out] boolean mute);
196
197    /**
198     * @brief Sets the audio volume for voice call.
199     *
200     * The volume ranges from 0.0 to 1.0. If the volume level in an audio service ranges from 0 to 15,
201     * <b>0.0</b> indicates that the audio is muted, and <b>1.0</b> indicates the maximum volume level (15).
202     *
203     * @param adapter Indicates the pointer to the audio adapter to operate.
204     * @param volume Indicates the volume to set. The value ranges from 0.0 to 1.0.
205     * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise.
206     * @see GetVolume
207     */
208    SetVoiceVolume([in] float volume);
209
210    /**
211     * @brief Sets extra audio parameters.
212     *
213     * @param adapter Indicates the audio adapter.
214     * @param key Indicates what kind of parameter type will be set.
215     * @param condition Indicates the specific extend parameter condition of AudioExtParamKey.
216     * @param value Indicates the value of the specified condition.
217     *
218     * The format of condition is <i>key=value</i>. Separate multiple key-value pairs by semicolons (;).
219     * When key equals to AudioExtParamKey::AUDIO_EXT_PARAM_KEY_VOLUME, the format of condition must be like this:
220     * <i>"EVENT_TYPE=xxx;VOLUME_GROUP_ID=xxx;AUDIO_VOLUME_TYPE=xxx;"</i>
221     * EVENT_TYPE indicates sub volume event type: SetVolume = 1; SetMute = 4;
222     * VOLUME_GROUP_ID indicates which volume group will be set;
223     * AUDIO_VOLUME_TYPE indicates which volume type will be set;
224     *
225     * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
226     */
227    SetExtraParams([in] enum AudioExtParamKey key, [in] String condition, [in] String value);
228
229    /**
230     * @brief Get extra audio parameters.
231     *
232     * @param adapter Indicates the audio adapter.
233     * @param key Indicates what kind of parameter type will be get.
234     * @param condition Indicates the specific extend parameter condition of AudioExtParamKey.
235     * @param value Indicates the value of the specified condition.
236     * @param lenth Indicates the length of the value pointer.
237     *
238     * The format of condition is <i>key=value</i>. Separate multiple key-value pairs by semicolons (;).
239     * When key equals to AudioExtParamKey::AUDIO_EXT_PARAM_KEY_VOLUME, the format of condition must be like this:
240     * <i>"EVENT_TYPE=xxx;VOLUME_GROUP_ID=xxx;AUDIO_VOLUME_TYPE=xxx;"</i>
241     * EVENT_TYPE indicates sub volume event type: GetVolume = 1; GetMinVolume = 2; GetMaxVolume = 3; IsStreamMute = 4;
242     * VOLUME_GROUP_ID indicates which volume group want get;
243     * AUDIO_VOLUME_TYPE indicates which volume type want get;
244     *
245     * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
246     */
247    GetExtraParams([in] enum AudioExtParamKey key, [in] String condition, [out] String value);
248
249    /**
250     * @brief Register extra audio parameters observer.
251     *
252     * @param adapter Indicates the audio adapter.
253     * @param callback Indicates param observer.
254     * @param cookie Indicates the pointer to the callback parameters;
255     * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
256     */
257    RegExtraParamObserver([in] IAudioCallback audioCallback, [in] byte cookie);
258}
259/** @} */