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