1 /* 2 * Copyright (c) 2025 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 OHAudio 18 * @{ 19 * 20 * @brief Provide the definition of the C interface for the audio module. 21 * 22 * @syscap SystemCapability.Multimedia.Audio.Core 23 * 24 * @since 20 25 */ 26 27 /** 28 * @file native_audio_volume_manager.h 29 * 30 * @brief Declare audio volume manager related interfaces. 31 * 32 * This file interfaces are used for the creation of AudioVolumeManager. 33 * 34 * @library libohaudio.so 35 * @syscap SystemCapability.Multimedia.Audio.Core 36 * @kit AudioKit 37 * @since 20 38 */ 39 40 #ifndef NATIVE_AUDIO_VOLUME_MANAGER_H 41 #define NATIVE_AUDIO_VOLUME_MANAGER_H 42 43 #include "native_audio_common.h" 44 #include "native_audiostream_base.h" 45 46 #ifdef __cplusplus 47 extern "C" { 48 #endif 49 50 /** 51 * @brief Declare the audio volume manager. 52 * Audio volume manager provides many functions for developer to get the information about system volume. 53 * 54 * @since 20 55 */ 56 typedef struct OH_AudioVolumeManager OH_AudioVolumeManager; 57 58 /** 59 * @brief Prototype for the volume change function that is passed to 60 * {@link OH_AudioVolumeManager_RegisterStreamVolumeChangeCallback}. 61 * 62 * @param userData userdata which is passed by register. 63 * @param usage the stream usage type for which volume changed. 64 * @param volumeLevel the latest volume level. 65 * @param updateUi whether to show the volume change in UI. 66 * 67 * @since 20 68 */ 69 typedef void (*OH_AudioVolumeManager_OnStreamVolumeChangeCallback)( 70 void *userData, 71 OH_AudioStream_Usage usage, 72 int32_t volumeLevel, 73 bool updateUi 74 ); 75 76 /** 77 * @brief Prototype for the volume change function that is passed to 78 * {@link OH_AudioVolumeManager_RegisterStreamVolumeChangeCallback}. 79 * 80 * @param userData userdata which is passed by register. 81 * @param ringerMode the latest ringer mode. 82 * 83 * @since 20 84 */ 85 typedef void (*OH_AudioVolumeManager_OnRingerModeChangeCallback)( 86 void *userData, 87 OH_AudioRingerMode ringerMode 88 ); 89 90 /** 91 * @brief Fetch the audio volume manager handle, which is a singleton. 92 * 93 * @param volumeManager output parameter to get {@link OH_AudioVolumeManager} instance. 94 * @return 95 * {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 96 * {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if input param is nullptr 97 * 98 * @since 20 99 */ 100 OH_AudioCommon_Result OH_AudioManager_GetAudioVolumeManager( 101 OH_AudioVolumeManager **volumeManager); 102 103 /** 104 * @brief Obtains the maximum volume level for a specific stream usage type. 105 * 106 * @param volumeManager {@link OH_AudioVolumeManager} handle 107 * provided by {@link OH_AudioManager_GetAudioVolumeManager}. 108 * @param usage the stream usage type used to map a specific volume type. 109 * @param maxVolumeLevel output parameter to get maximum volume level. 110 * @return 111 * {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 112 * {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if input param is nullptr or invalid 113 * {@link #AUDIOCOMMON_RESULT_ERROR_SYSTEM} system process error occurs 114 * 115 * @since 20 116 */ 117 OH_AudioCommon_Result OH_AudioVolumeManager_GetMaxVolumeByUsage(OH_AudioVolumeManager *volumeManager, 118 OH_AudioStream_Usage usage, int32_t *maxVolumeLevel); 119 120 /** 121 * @brief Obtains the minimum volume level for a specific stream usage type. 122 * 123 * @param volumeManager {@link OH_AudioVolumeManager} handle 124 * provided by {@link OH_AudioManager_GetAudioVolumeManager}. 125 * @param usage the stream usage type used to map a specific volume type. 126 * @param minVolumeLevel output parameter to get minimum volume level. 127 * @return 128 * {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 129 * {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if input param is nullptr or invalid 130 * {@link #AUDIOCOMMON_RESULT_ERROR_SYSTEM} system process error occurs 131 * 132 * @since 20 133 */ 134 OH_AudioCommon_Result OH_AudioVolumeManager_GetMinVolumeByUsage(OH_AudioVolumeManager *volumeManager, 135 OH_AudioStream_Usage usage, int32_t *minVolumeLevel); 136 137 /** 138 * @brief Obtains the system volume level for a specific stream usage type. 139 * 140 * @param volumeManager {@link OH_AudioVolumeManager} handle 141 * provided by {@link OH_AudioManager_GetAudioVolumeManager}. 142 * @param usage the stream usage type used to map a specific volume type. 143 * @param volumeLevel output parameter to get system volume level. 144 * @return 145 * {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 146 * {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if input param is nullptr or invalid 147 * {@link #AUDIOCOMMON_RESULT_ERROR_SYSTEM} system process error occurs 148 * 149 * @since 20 150 */ 151 OH_AudioCommon_Result OH_AudioVolumeManager_GetVolumeByUsage(OH_AudioVolumeManager *volumeManager, 152 OH_AudioStream_Usage usage, int32_t *volumeLevel); 153 154 /** 155 * @brief Checks whether a stream is muted for a specific stream usage type. 156 * 157 * @param volumeManager {@link OH_AudioVolumeManager} handle 158 * provided by {@link OH_AudioManager_GetAudioVolumeManager}. 159 * @param usage the stream usage type used to map a specific volume type. 160 * @param muted output parameter to get whether the stream of this usage is muted. 161 * @return 162 * {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 163 * {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if input param is nullptr or invalid 164 * {@link #AUDIOCOMMON_RESULT_ERROR_SYSTEM} system process error occurs 165 * 166 * @since 20 167 */ 168 OH_AudioCommon_Result OH_AudioVolumeManager_IsMuteByUsage(OH_AudioVolumeManager *volumeManager, 169 OH_AudioStream_Usage usage, bool *muted); 170 171 /** 172 * @brief Register callback to receive stream volume changed events. 173 * 174 * @param volumeManager {@link OH_AudioVolumeManager} handle 175 * provided by {@link OH_AudioManager_GetAudioVolumeManager}. 176 * @param usage the stream usage type used to map a specific volume type which caller want to listen. 177 * @param callback callback function which will be called when stream volume changed. 178 * @param userData pointer to a data structure that will be passed to the callback functions. 179 * @return 180 * {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 181 * {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if input param is nullptr or invalid 182 * {@link #AUDIOCOMMON_RESULT_ERROR_SYSTEM} system process error occurs 183 * 184 * @since 20 185 */ 186 OH_AudioCommon_Result OH_AudioVolumeManager_RegisterStreamVolumeChangeCallback( 187 OH_AudioVolumeManager *volumeManager, OH_AudioStream_Usage usage, 188 OH_AudioVolumeManager_OnStreamVolumeChangeCallback callback, void *userData); 189 190 /** 191 * @brief Unregister stream volume change callback. 192 * 193 * @param volumeManager {@link OH_AudioVolumeManager} handle 194 * provided by {@link OH_AudioManager_GetAudioVolumeManager}. 195 * @param callback callback function which registered in 196 * {@link OH_AudioVolumeManager_RegisterStreamVolumeChangeCallback}. 197 * @return 198 * {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 199 * {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if input param is nullptr 200 * {@link #AUDIOCOMMON_RESULT_ERROR_SYSTEM} system process error occurs 201 * 202 * @since 20 203 */ 204 OH_AudioCommon_Result OH_AudioVolumeManager_UnregisterStreamVolumeChangeCallback( 205 OH_AudioVolumeManager *volumeManager, 206 OH_AudioVolumeManager_OnStreamVolumeChangeCallback callback); 207 208 /** 209 * @brief Get current ringer mode. 210 * 211 * @param volumeManager {@link OH_AudioVolumeManager} handle 212 * provided by {@link OH_AudioManager_GetAudioVolumeManager}. 213 * @param ringerMode output parameter to get the ringer mode. 214 * @return 215 * {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 216 * {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if input param is nullptr 217 * {@link #AUDIOCOMMON_RESULT_ERROR_SYSTEM} system process error occurs 218 * 219 * @since 20 220 */ 221 OH_AudioCommon_Result OH_AudioVolumeManager_GetRingerMode(OH_AudioVolumeManager *volumeManager, 222 OH_AudioRingerMode *ringerMode); 223 224 /** 225 * @brief Register callback to receive ringer mode changed events. 226 * 227 * @param volumeManager {@link OH_AudioVolumeManager} handle 228 * provided by {@link OH_AudioManager_GetAudioVolumeManager}. 229 * @param callback callback function which will be called when ringer mode changed. 230 * @param userData pointer to a data structure that will be passed to the callback functions. 231 * @return 232 * {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 233 * {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if input param is nullptr 234 * {@link #AUDIOCOMMON_RESULT_ERROR_SYSTEM} system process error occurs 235 * 236 * @since 20 237 */ 238 OH_AudioCommon_Result OH_AudioVolumeManager_RegisterRingerModeChangeCallback( 239 OH_AudioVolumeManager *volumeManager, 240 OH_AudioVolumeManager_OnRingerModeChangeCallback callback, void *userData); 241 242 /** 243 * @brief Unregister ringer mode change callback. 244 * 245 * @param volumeManager {@link OH_AudioVolumeManager} handle 246 * provided by {@link OH_AudioManager_GetAudioVolumeManager}. 247 * @param callback callback function which registered in 248 * {@link OH_AudioVolumeManager_RegisterRingerModeChangeCallback}. 249 * @return 250 * {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 251 * {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if input param is nullptr 252 * {@link #AUDIOCOMMON_RESULT_ERROR_SYSTEM} system process error occurs 253 * 254 * @since 20 255 */ 256 OH_AudioCommon_Result OH_AudioVolumeManager_UnregisterRingerModeChangeCallback( 257 OH_AudioVolumeManager *volumeManager, 258 OH_AudioVolumeManager_OnRingerModeChangeCallback callback); 259 260 #ifdef __cplusplus 261 } 262 #endif 263 264 #endif // NATIVE_AUDIO_ROUTING_MANAGER_H 265 /** @} */