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 *
20 * @brief Provides unified APIs for audio services to access audio drivers.
21 *
22 * An audio service can obtain an audio driver object or agent and then call APIs provided by this object or agent to
23 * access different types of audio devices based on the audio IDs, thereby obtaining audio information,
24 * subscribing to or unsubscribing from audio data, enabling or disabling an audio,
25 * setting the audio data reporting mode, and setting audio options such as the accuracy and measurement range.
26 *
27 * @since 4.0
28 * @version 1.0
29 */
30
31package ohos.hdi.audio.v1_0;
32
33import ohos.hdi.audio.v1_0.AudioTypes;
34import ohos.hdi.audio.v1_0.IAudioRender;
35import ohos.hdi.audio.v1_0.IAudioCapture;
36import ohos.hdi.audio.v1_0.IAudioCallback;
37
38/**
39 * @brief Provides audio adapter capabilities, including initializing ports, creating rendering and capturing tasks,
40 * and obtaining the port capability set.
41 *
42 * @see IAudioRender
43 * @see IAudioCapture
44 * @since 4.0
45 * @version 1.0
46 */
47interface IAudioAdapter {
48    /**
49     * @brief Initializes all ports of an audio adapter.
50     *
51     * Call this function before calling other driver functions to check whether the initialization is complete.
52     * If the initialization is not complete, wait for a while (for example, 100 ms) and perform the check again
53     * until the port initialization is complete.
54     *
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 renderId Indicates the pointer to the <b>IAudioRender</b> object to operate.
80     * @return Returns <b>0</b> if the <b>IAudioRender</b> object is destroyed; returns a negative value otherwise.
81     * @see CreateRender
82     */
83    DestroyRender([in] unsigned int renderId);
84
85    /**
86     * @brief Creates an <b>IAudioCapture</b> object.
87     *
88     * @param adapter Indicates the pointer to the audio adapter to operate.
89     * @param desc Indicates the pointer to the descriptor of the audio adapter to start.
90     * @param attrs Indicates the pointer to the audio sampling attributes to open.
91     * @param capture Indicates the double pointer to the <b>IAudioCapture</b> object.
92     * @return Returns <b>0</b> if the <b>IAudioCapture</b> object is created successfully;
93     * returns a negative value otherwise.
94     * @see GetPortCapability
95     * @see DestroyCapture
96     */
97    CreateCapture([in] struct AudioDeviceDescriptor desc, [in] struct AudioSampleAttributes attrs,
98                  [out] IAudioCapture capture, [out] unsigned int captureId);
99
100    /**
101     * @brief Destroys an <b>IAudioCapture</b> object.
102     *
103     * @attention Do not destroy the object during audio capturing.
104     *
105     * @param captureId Indicates the pointer to the <b>IAudioCapture</b> object to operate.
106     * @return Returns <b>0</b> if the <b>IAudioCapture</b> object is destroyed; returns a negative value otherwise.
107     * @see CreateCapture
108     */
109    DestroyCapture([in] unsigned int captureId);
110
111    /**
112     * @brief Obtains the capability set of the port driver for the audio adapter.
113     *
114     * @param port Indicates the pointer to the port.
115     * @param capability Indicates the pointer to the capability set to obtain.
116     * @return Returns <b>0</b> if the capability set is successfully obtained; returns a negative value otherwise.
117     */
118    GetPortCapability([in] struct AudioPort port, [out] struct AudioPortCapability capability);
119
120    /**
121     * @brief Sets the passthrough data transmission mode of the audio port driver.
122     *
123     * @param port Indicates the pointer to the port.
124     * @param mode Indicates the passthrough transmission mode to set.
125     * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise.
126     * @see GetPassthroughMode
127     */
128    SetPassthroughMode([in] struct AudioPort port, [in] enum AudioPortPassthroughMode mode);
129
130    /**
131     * @brief Obtains the passthrough data transmission mode of the audio port driver.
132     *
133     * @param port Indicates the pointer to the port.
134     * @param mode Indicates the pointer to the passthrough transmission mode to obtain.
135     * @return Returns <b>0</b> if the mode is successfully obtained; returns a negative value otherwise.
136     * @see SetPassthroughMode
137     */
138    GetPassthroughMode([in] struct AudioPort port, [out] enum AudioPortPassthroughMode mode);
139
140    /**
141     * @brief Get the device status of an adapter.
142     *
143     * @param status Indicates the status of device .
144     * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
145     */
146    GetDeviceStatus([out] struct AudioDeviceStatus status);
147
148    /**
149     * @brief Update audio route on several source and sink ports.
150     *
151     * @param route Indicates route information.
152     * @param routeHandle Indicates route handle.
153     * @return Returns <b>0</b> if the mode is successfully obtained; returns a negative value otherwise.
154     * @see SetPassthroughMode
155     */
156    UpdateAudioRoute([in] struct AudioRoute route, [out] int routeHandle);
157
158    /**
159     * @brief Release an audio route.
160     *
161     * @param routeHandle Indicates route handle.
162     * @return Returns <b>0</b> if the mode is successfully obtained; returns a negative value otherwise.
163     * @see SetPassthroughMode
164     */
165    ReleaseAudioRoute([in] int routeHandle);
166
167    /**
168     * @brief Sets the mute operation for the audio.
169     *
170     * @param mute Specifies whether to mute the audio. Value <b>true</b> means to mute the audio,
171     * and <b>false</b> means the opposite.
172     * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise.
173     * @see GetMute
174     */
175    SetMicMute([in] boolean mute);
176
177    /**
178     * @brief Obtains the mute operation set for the audio.
179     *
180     * @param mute Indicates the pointer to the mute operation set for the audio. Value <b>true</b> means that
181     * the audio is muted, and <b>false</b> means the opposite.
182     * @return Returns <b>0</b> if the mute operation is obtained; returns a negative value otherwise.
183     * @see SetMute
184     */
185    GetMicMute([out] boolean mute);
186
187    /**
188     * @brief Sets the audio volume for voice call.
189     *
190     * The volume ranges from 0.0 to 1.0. If the volume level in an audio service ranges from 0 to 15,
191     * <b>0.0</b> indicates that the audio is muted, and <b>1.0</b> indicates the maximum volume level (15).
192     *
193     * @param volume Indicates the volume to set. The value ranges from 0.0 to 1.0.
194     * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise.
195     * @see GetVolume
196     */
197    SetVoiceVolume([in] float volume);
198
199    /**
200     * @brief Sets extra audio parameters.
201     *
202     * @param key Indicates what kind of parameter type will be set.
203     * @param condition Indicates the specific extend parameter condition of AudioExtParamKey.
204     * @param value Indicates the value of the specified condition.
205     *
206     * The format of condition is <i>key=value</i>. Separate multiple key-value pairs by semicolons (;).
207     * When key equals to AudioExtParamKey::AUDIO_EXT_PARAM_KEY_VOLUME, the format of condition must be like this:
208     * <i>"EVENT_TYPE=xxx;VOLUME_GROUP_ID=xxx;AUDIO_VOLUME_TYPE=xxx;"</i>
209     * EVENT_TYPE indicates sub volume event type: SetVolume = 1; SetMute = 4;
210     * VOLUME_GROUP_ID indicates which volume group will be set;
211     * AUDIO_VOLUME_TYPE indicates which volume type will be set;
212     *
213     * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
214     */
215    SetExtraParams([in] enum AudioExtParamKey key, [in] String condition, [in] String value);
216
217    /**
218     * @brief Get extra audio parameters.
219     *
220     * @param key Indicates what kind of parameter type will be get.
221     * @param condition Indicates the specific extend parameter condition of AudioExtParamKey.
222     * @param value Indicates the value of the specified condition.
223     *
224     * The format of condition is <i>key=value</i>. Separate multiple key-value pairs by semicolons (;).
225     * When key equals to AudioExtParamKey::AUDIO_EXT_PARAM_KEY_VOLUME, the format of condition must be like this:
226     * <i>"EVENT_TYPE=xxx;VOLUME_GROUP_ID=xxx;AUDIO_VOLUME_TYPE=xxx;"</i>
227     * EVENT_TYPE indicates sub volume event type: GetVolume = 1; GetMinVolume = 2; GetMaxVolume = 3; IsStreamMute = 4;
228     * VOLUME_GROUP_ID indicates which volume group want get;
229     * AUDIO_VOLUME_TYPE indicates which volume type want get;
230     *
231     * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
232     */
233    GetExtraParams([in] enum AudioExtParamKey key, [in] String condition, [out] String value);
234
235    /**
236     * @brief Register extra audio parameters observer.
237     *
238     * @param audioCallback Indicates param observer.
239     * @param cookie Indicates the pointer to the callback parameters;
240     * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
241     */
242    RegExtraParamObserver([in] IAudioCallback audioCallback, [in] byte cookie);
243}
244/** @} */