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;
33
34
35/**
36 * @brief Provides capabilities for audio capturing, including controlling the capturing, setting audio attributes,
37 * scenes, and volume, and capturing audio frames.
38 * @since 4.0
39 * @version 1.0
40 */
41interface IAudioCapture {
42    /**
43     * @brief Reads a frame of input data (uplink data) from the audio driver for capturing.
44     *
45     * @param capture Indicates the pointer to the <b>IAudioCapture</b> object to operate.
46     * @param frame Indicates the pointer to the input data to read.
47     * @param requestBytes Indicates the size of the input data, in bytes.
48     * @param replyBytes Indicates the pointer to the actual length (in bytes) of the audio data to read.
49     * @return Returns <b>0</b> if the input data is read successfully; returns a negative value otherwise.
50     */
51    CaptureFrame([out] byte[] frame, [out] unsigned long replyBytes);
52
53    /**
54     * @brief Obtains the last number of input audio frames.
55     *
56     * @param capture Indicates the pointer to the <b>IAudioCapture</b> object to operate.
57     * @param frames Indicates the pointer to the last number of input audio frames.
58     * @param time Indicates the pointer to the timestamp associated with the frame.
59     * @return Returns <b>0</b> if the last number is obtained; returns a negative value otherwise.
60     * @see CaptureFrame
61     */
62    GetCapturePosition([out] unsigned long frames, [out] struct AudioTimeStamp time);
63
64    /**
65     * @brief Checks whether the configuration of an audio scene is supported.
66     *
67     * @param handle Indicates the audio handle.
68     * @param scene Indicates the pointer to the descriptor of the audio scene.
69     * @param supported Indicates the pointer to the variable specifying whether the configuration is supported.
70     * Value <b>true</b> means that the configuration is supported, and <b>false</b> means the opposite.
71     * @return Returns <b>0</b> if the result is obtained; returns a negative value otherwise.
72     * @see SelectScene
73     */
74    CheckSceneCapability([in] struct AudioSceneDescriptor scene, [out] boolean supported);
75
76    /**
77     * @brief Selects an audio scene.
78     *
79     * <ul>
80     *   <li>To select a specific audio scene, you need to specify both the application scenario and output device.
81     *     For example, to select a scene using a smartphone speaker as the output device, set <b>scene</b> according
82     *     to the scenarios where the speaker is used. For example:</li>
83     *     <ul>
84     *       <li>For media playback, set the value to <b>media_speaker</b>.</li>
85     *       <li>For a voice call, set the value to <b>voice_speaker</b>.</li>
86     *     </ul>
87     *   <li>To select only the application scenario, such as media playback, movie, or gaming, you can set
88     *     <b>scene</b> to <b>media</b>, <b>movie</b>, or <b>game</b>, respectively.</li>
89     *   <li>To select only the output device, such as media receiver, speaker, or headset, you can set
90     *     <b>scene</b> to <b>receiver</b>, <b>speaker</b>, or <b>headset</b>, respectively.</li>
91     * </ul>
92     * @param handle Indicates the audio handle.
93     * @param scene Indicates the pointer to the descriptor of the audio scene to select.
94     * @return Returns <b>0</b> if the scene is selected successfully; returns a negative value otherwise.
95     * @see CheckSceneCapability
96     */
97    SelectScene([in] struct AudioSceneDescriptor scene);
98
99    /**
100     * @brief Sets the mute operation for the audio.
101     *
102     * @param handle Indicates the audio handle.
103     * @param mute Specifies whether to mute the audio. Value <b>true</b> means to mute the audio,
104     * and <b>false</b> means the opposite.
105     * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise.
106     * @see GetMute
107     */
108    SetMute([in] boolean mute);
109
110    /**
111     * @brief Obtains the mute operation set for the audio.
112     *
113     * @param handle Indicates the audio handle.
114     * @param mute Indicates the pointer to the mute operation set for the audio. Value <b>true</b> means that
115     * the audio is muted, and <b>false</b> means the opposite.
116     * @return Returns <b>0</b> if the mute operation is obtained; returns a negative value otherwise.
117     * @see SetMute
118     */
119    GetMute([out] boolean mute);
120
121    /**
122     * @brief Sets the audio volume.
123     *
124     * The volume ranges from 0.0 to 1.0. If the volume level in an audio service ranges from 0 to 15,
125     * <b>0.0</b> indicates that the audio is muted, and <b>1.0</b> indicates the maximum volume level (15).
126     *
127     * @param handle Indicates the audio handle.
128     * @param volume Indicates the volume to set. The value ranges from 0.0 to 1.0.
129     * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise.
130     * @see GetVolume
131     */
132    SetVolume([in] float volume);
133
134    /**
135     * @brief Obtains the audio volume.
136     *
137     * @param handle Indicates the audio handle.
138     * @param volume Indicates the pointer to the volume to obtain. The value ranges from 0.0 to 1.0.
139     * @return Returns <b>0</b> if the volume is obtained; returns a negative value otherwise.
140     * @see SetVolume
141     */
142    GetVolume([out] float volume);
143
144    /**
145     * @brief Obtains the range of the audio gain.
146     *
147     * The audio gain can be expressed in one of the following two ways (depending on the chip platform),
148     * corresponding to two types of value ranges:
149     * <ul>
150     *   <li>Actual audio gain values, for example, ranging from -50 to 6 dB</li>
151     *   <li>Float numbers ranging from 0.0 to 1.0, where <b>0.0</b> means to mute the audio,
152     *     and <b>1.0</b> means the maximum gain value, for example, 6 dB</li>
153     * </ul>
154     * @param handle Indicates the audio handle.
155     * @param min Indicates the pointer to the minimum value of the range.
156     * @param max Indicates the pointer to the maximum value of the range.
157     * @return Returns <b>0</b> if the range is obtained; returns a negative value otherwise.
158     * @see GetGain
159     * @see SetGain
160     */
161    GetGainThreshold([out] float min, [out] float max);
162
163    /**
164     * @brief Obtains the audio gain.
165     *
166     * @param handle Indicates the audio handle.
167     * @param gain Indicates the pointer to the audio gain.
168     * @return Returns <b>0</b> if the audio gain is obtained; returns a negative value otherwise.
169     * @see GetGainThreshold
170     * @see SetGain
171     */
172    GetGain([out] float gain);
173
174    /**
175     * @brief Sets the audio gain.
176     *
177     * @param handle Indicates the audio handle.
178     * @param gain Indicates the audio gain to set.
179     * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise.
180     * @see GetGainThreshold
181     * @see GetGain
182     */
183    SetGain([in] float gain);
184
185    /**
186     * @brief Obtains the audio frame size, that is, the length (in bytes) of a frame.
187     *
188     * @param handle Indicates the audio handle.
189     * @param size Indicates the pointer to the audio frame size (in bytes).
190     * @return Returns <b>0</b> if the audio frame size is obtained; returns a negative value otherwise.
191     */
192    GetFrameSize([out] unsigned long size);
193
194    /**
195     * @brief Obtains the number of audio frames in the audio buffer.
196     *
197     * @param handle Indicates the audio handle.
198     * @param count Indicates the pointer to the number of audio frames in the audio buffer.
199     * @return Returns <b>0</b> if the number of audio frames is obtained; returns a negative value otherwise.
200     */
201    GetFrameCount([out] unsigned long count);
202
203    /**
204     * @brief Sets audio sampling attributes.
205     *
206     * @param handle Indicates the audio handle.
207     * @param attrs Indicates the pointer to the audio sampling attributes to set, such as the sampling rate,
208     * sampling precision, and channel.
209     * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise.
210     * @see GetSampleAttributes
211     */
212    SetSampleAttributes([in] struct AudioSampleAttributes attrs);
213
214    /**
215     * @brief Obtains audio sampling attributes.
216     *
217     * @param handle Indicates the audio handle.
218     * @param attrs Indicates the pointer to the audio sampling attributes, such as the sampling rate,
219     * sampling precision, and channel.
220     * @return Returns <b>0</b> if audio sampling attributes are obtained; returns a negative value otherwise.
221     * @see SetSampleAttributes
222     */
223    GetSampleAttributes([out] struct AudioSampleAttributes attrs);
224
225    /**
226     * @brief Obtains the data channel ID of the audio.
227     *
228     * @param handle Indicates the audio handle.
229     * @param channelId Indicates the pointer to the data channel ID.
230     * @return Returns <b>0</b> if the data channel ID is obtained; returns a negative value otherwise.
231     */
232    GetCurrentChannelId([out] unsigned int channelId);
233
234    /**
235     * @brief Sets extra audio parameters.
236     *
237     * @param handle Indicates the audio handle.
238     * @param keyValueList Indicates the pointer to the key-value list of the extra audio parameters.
239     * The format is <i>key=value</i>. Separate multiple key-value pairs by semicolons (;).
240     * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
241     */
242    SetExtraParams([in] String keyValueList);
243
244    /**
245     * @brief Obtains extra audio parameters.
246     *
247     * @param handle Indicates the audio handle.
248     * @param keyValueList Indicates the pointer to the key-value list of the extra audio parameters.
249     * The format is <i>key=value</i>. Separate multiple key-value pairs by semicolons (;).
250     * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
251     */
252    GetExtraParams([out] String keyValueList);
253
254    /**
255     * @brief Requests a mmap buffer.
256     *
257     * @param handle Indicates the audio handle.
258     * @param reqSize Indicates the size of the request mmap buffer.
259     * @param desc Indicates the pointer to the mmap buffer descriptor.
260     * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
261     */
262    ReqMmapBuffer([in] int reqSize, [out] struct AudioMmapBufferDescriptor desc);
263
264    /**
265     * @brief Obtains the read/write position of the current mmap buffer.
266     *
267     * @param handle Indicates the audio handle.
268     * @param frames Indicates the pointer to the frame where the read/write starts.
269     * @param time Indicates the pointer to the timestamp associated with the frame where the read/write starts.
270     * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
271     */
272    GetMmapPosition([out] unsigned long frames, [out] struct AudioTimeStamp time);
273
274    /**
275     * @brief Add the audio effect which the effectid indicated.
276     *
277     * @param handle Indicates the audio handle.
278     * @param effectid Indicates the audio effect instance identifier which is going to be added.
279     * @return Returns <b>0</b> if the audio effect were added succesffully; returns a negative value otherwise.
280     */
281    AddAudioEffect([in] unsigned long effectid);
282
283    /**
284     * @brief Remove the audio effect which the effectid indicated.
285     *
286     * @param handle Indicates the audio handle.
287     * @param effectid Indicates the audio effect which is going to be removed.
288     * @return Returns <b>0</b> if the audio effect were removed succesffully; returns a negative value otherwise.
289     */
290    RemoveAudioEffect([in] unsigned long effectid);
291
292    /**
293     * @brief Get the buffer size of render or capturer
294     *
295     * @param handle Indicates the audio handle.
296     * @param bufferSize Indicates the buffer size (in bytes) queried from the vendor
297     * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
298     */
299    GetFrameBufferSize([out] unsigned long bufferSize);
300
301    /**
302     * @brief Starts audio rendering or capturing.
303     *
304     * @param handle Indicates the audio handle.
305     * @return Returns <b>0</b> if the rendering or capturing is successfully started;
306     * returns a negative value otherwise.
307     * @see Stop
308     */
309    Start();
310
311    /**
312     * @brief Stops audio rendering or capturing.
313     *
314     * @param handle Indicates the audio handle.
315     * @return Returns <b>0</b> if the rendering or capturing is successfully stopped;
316     * returns a negative value otherwise.
317     * @see Start
318     */
319    Stop();
320
321    /**
322     * @brief Pauses audio rendering or capturing.
323     *
324     * @param handle Indicates the audio handle.
325     * @return Returns <b>0</b> if the rendering or capturing is successfully paused;
326     * returns a negative value otherwise.
327     * @see Resume
328     */
329    Pause();
330
331    /**
332     * @brief Resumes audio rendering or capturing.
333     *
334     * @param handle Indicates the audio handle.
335     * @return Returns <b>0</b> if the rendering or capturing is successfully resumed;
336     * returns a negative value otherwise.
337     * @see Pause
338     */
339    Resume();
340
341    /**
342     * @brief Flushes data in the audio buffer.
343     *
344     * @param handle Indicates the audio handle.
345     * @return Returns <b>0</b> if the flush is successful; returns a negative value otherwise.
346     */
347    Flush();
348
349    /**
350     * @brief Sets or cancels the standby mode of the audio device.
351     *
352     * @param handle Indicates the audio handle.
353     * @return Returns <b>0</b> if the device is set to standby mode; returns a positive value if the standby mode is
354     * canceled; returns a negative value if the setting fails.
355     */
356    TurnStandbyMode();
357
358    /**
359     * @brief Dumps information about the audio device.
360     *
361     * @param handle Indicates the audio handle.
362     * @param range Indicates the range of the device information to dump, which can be brief or full information.
363     * @param fd Indicates the file to which the device information will be dumped.
364     * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
365     */
366    AudioDevDump([in] int range, [in] int fd);
367
368    /**
369     * @brief Query whether the vendor support pause and resume.
370     *
371     * @param handle Indicates the audio handle.
372     * @param supportPause Indicates the state whether the vendor supports pausing. Value <b>true</b> means that
373     * the vendor supports, and <b>false</b> means the opposite.
374     * @param supportResume Indicates the state whether the vendor supports resuming. Value <b>true</b> means that
375     * the vendor supports, and <b>false</b> means the opposite.
376     * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
377     * @see IsSupportsPauseAndResume
378     */
379    IsSupportsPauseAndResume([out] boolean supportPause, [out] boolean supportResume);
380}
381