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