1 /* 2 * Copyright (c) 2022 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" 40 namespace OHOS { 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 */ 48 struct 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 } /* end of OHOS */ 136 #endif /* AUDIO_VOLUME_H */ 137 /** @} */ 138