1/*
2 * Copyright (c) 2020-2021 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 Audio
18 * @{
19 *
20 * @brief Defines audio-related APIs, including custom data types and functions for loading drivers,
21 * accessing a driver adapter, and rendering and capturing audios.
22 *
23 * @since 1.0
24 * @version 1.0
25 */
26
27/**
28 * @file audio_volume.h
29 *
30 * @brief Declares APIs for audio volume.
31 *
32 * @since 1.0
33 * @version 1.0
34 */
35
36#ifndef AUDIO_VOLUME_H
37#define AUDIO_VOLUME_H
38
39#include "audio_types.h"
40namespace OHOS::HDI::Audio_Bluetooth {
41/**
42 * @brief Provides volume-related APIs for audio rendering or capturing, including functions to
43 * set the mute operation, volume, and gain.
44 *
45 * @since 1.0
46 * @version 1.0
47 */
48struct AudioVolume {
49    /**
50     * @brief Sets the mute operation for the audio.
51     *
52     * @param handle Indicates the audio handle.
53     * @param mute Specifies whether to mute the audio. Value <b>true</b> means to mute the audio,
54     * and <b>false</b> means the opposite.
55     * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise.
56     * @see GetMute
57     */
58    int32_t (*SetMute)(AudioHandle handle, bool mute);
59
60    /**
61     * @brief Obtains the mute operation set for the audio.
62     *
63     * @param handle Indicates the audio handle.
64     * @param mute Indicates the pointer to the mute operation set for the audio. Value <b>true</b> means that
65     * the audio is muted, and <b>false</b> means the opposite.
66     * @return Returns <b>0</b> if the mute operation is obtained; returns a negative value otherwise.
67     * @see SetMute
68     */
69    int32_t (*GetMute)(AudioHandle handle, bool *mute);
70
71    /**
72     * @brief Sets the audio volume.
73     *
74     * The volume ranges from 0.0 to 1.0. If the volume level in an audio service ranges from 0 to 15,
75     * <b>0.0</b> indicates that the audio is muted, and <b>1.0</b> indicates the maximum volume level (15).
76     *
77     * @param handle Indicates the audio handle.
78     * @param volume Indicates the volume to set. The value ranges from 0.0 to 1.0.
79     * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise.
80     * @see GetVolume
81     */
82    int32_t (*SetVolume)(AudioHandle handle, float volume);
83
84    /**
85     * @brief Obtains the audio volume.
86     *
87     * @param handle Indicates the audio handle.
88     * @param volume Indicates the pointer to the volume to obtain. The value ranges from 0.0 to 1.0.
89     * @return Returns <b>0</b> if the volume is obtained; returns a negative value otherwise.
90     * @see SetVolume
91     */
92    int32_t (*GetVolume)(AudioHandle handle, float *volume);
93
94    /**
95     * @brief Obtains the range of the audio gain.
96     *
97     * The audio gain can be expressed in one of the following two ways (depending on the chip platform),
98     * corresponding to two types of value ranges:
99     * <ul>
100     *   <li>Actual audio gain values, for example, ranging from -50 to 6 dB</li>
101     *   <li>Float numbers ranging from 0.0 to 1.0, where <b>0.0</b> means to mute the audio,
102     *     and <b>1.0</b> means the maximum gain value, for example, 6 dB</li>
103     * </ul>
104     * @param handle Indicates the audio handle.
105     * @param min Indicates the pointer to the minimum value of the range.
106     * @param max Indicates the pointer to the maximum value of the range.
107     * @return Returns <b>0</b> if the range is obtained; returns a negative value otherwise.
108     * @see GetGain
109     * @see SetGain
110     */
111    int32_t (*GetGainThreshold)(AudioHandle handle, float *min, float *max);
112
113    /**
114     * @brief Obtains the audio gain.
115     *
116     * @param handle Indicates the audio handle.
117     * @param gain Indicates the pointer to the audio gain.
118     * @return Returns <b>0</b> if the audio gain is obtained; returns a negative value otherwise.
119     * @see GetGainThreshold
120     * @see SetGain
121     */
122    int32_t (*GetGain)(AudioHandle handle, float *gain);
123
124    /**
125     * @brief Sets the audio gain.
126     *
127     * @param handle Indicates the audio handle.
128     * @param gain Indicates the audio gain to set.
129     * @return Returns <b>0</b> if the setting is successful; returns a negative value otherwise.
130     * @see GetGainThreshold
131     * @see GetGain
132     */
133    int32_t (*SetGain)(AudioHandle handle, float gain);
134};
135}
136#endif /* AUDIO_VOLUME_H */
137/** @} */
138