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 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 12 25 * @version 1.0 26 */ 27 28 /** 29 * @file native_audio_session_manager.h 30 * 31 * @brief Declare audio session manager related interfaces. 32 * 33 * This file interfaces are used for the creation of audioSessionManager 34 * as well as activating/deactivating the audio session 35 * as well as checking and listening the audio session decativated events. 36 * 37 * @library libohaudio.so 38 * @syscap SystemCapability.Multimedia.Audio.Core 39 * @since 12 40 * @version 1.0 41 */ 42 43 #ifndef NATIVE_AUDIO_SESSION_MANAGER_H 44 #define NATIVE_AUDIO_SESSION_MANAGER_H 45 46 #include "native_audio_common.h" 47 #include "native_audiostream_base.h" 48 #include "native_audio_device_base.h" 49 #ifdef __cplusplus 50 extern "C" { 51 #endif 52 53 /** 54 * @brief Declare the audio session manager. 55 * The handle of audio session manager is used for audio session related functions. 56 * 57 * @since 12 58 */ 59 typedef struct OH_AudioSessionManager OH_AudioSessionManager; 60 61 /** 62 * @brief Declare the audio concurrency modes. 63 * 64 * @since 12 65 */ 66 typedef enum { 67 /** 68 * @brief default mode 69 */ 70 CONCURRENCY_DEFAULT = 0, 71 72 /** 73 * @brief mix with others mode 74 */ 75 CONCURRENCY_MIX_WITH_OTHERS = 1, 76 77 /** 78 * @brief duck others mode 79 */ 80 CONCURRENCY_DUCK_OTHERS = 2, 81 82 /** 83 * @brief pause others mode 84 */ 85 CONCURRENCY_PAUSE_OTHERS = 3, 86 } OH_AudioSession_ConcurrencyMode; 87 88 /** 89 * @brief Declare the audio session scene. 90 * 91 * @since 20 92 */ 93 typedef enum { 94 /** 95 * @brief scene for media 96 */ 97 AUDIO_SESSION_SCENE_MEDIA = 0, 98 99 /** 100 * @brief scene for game 101 */ 102 AUDIO_SESSION_SCENE_GAME = 1, 103 104 /** 105 * @brief scene for voice communication 106 */ 107 AUDIO_SESSION_SCENE_VOICE_COMMUNICATION = 2, 108 } OH_AudioSession_Scene; 109 110 /** 111 * @brief Declare the audio session state change hints. 112 * 113 * @since 20 114 */ 115 typedef enum { 116 /** 117 * @brief Resume the playback 118 */ 119 AUDIO_SESSION_STATE_CHANGE_HINT_RESUME = 0, 120 121 /** 122 * @brief paused/pause the playback 123 */ 124 AUDIO_SESSION_STATE_CHANGE_HINT_PAUSE = 1, 125 126 /** 127 * @brief stopped/stop the playback. 128 */ 129 AUDIO_SESSION_STATE_CHANGE_HINT_STOP = 2, 130 131 /** 132 * @brief stopped/stop the playback due to no audio stream for a long time. 133 */ 134 AUDIO_SESSION_STATE_CHANGE_HINT_TIME_OUT_STOP = 3, 135 136 /** 137 * @brief Ducked the playback. (In ducking, the audio volume is reduced, but not silenced.) 138 */ 139 AUDIO_SESSION_STATE_CHANGE_HINT_DUCK = 4, 140 141 /** 142 * @brief Unducked the playback. 143 */ 144 AUDIO_SESSION_STATE_CHANGE_HINT_UNDUCK = 5, 145 } OH_AudioSession_StateChangeHint; 146 147 /** 148 * @brief Declare the recommend action when device change. 149 * 150 * @since 20 151 */ 152 typedef enum { 153 /** 154 * @brief Recommend to continue the playback. 155 */ 156 DEVICE_CHANGE_RECOMMEND_TO_CONTINUE = 0, 157 158 /** 159 * @brief recommend to stop the playback. 160 */ 161 DEVICE_CHANGE_RECOMMEND_TO_STOP = 1, 162 } OH_AudioSession_OutputDeviceChangeRecommendedAction; 163 164 /** 165 * @brief Declare the audio deactivated reasons. 166 * 167 * @since 12 168 */ 169 typedef enum { 170 /** 171 * @brief deactivated because of lower priority 172 */ 173 DEACTIVATED_LOWER_PRIORITY = 0, 174 175 /** 176 * @brief deactivated because of timing out 177 */ 178 DEACTIVATED_TIMEOUT = 1, 179 } OH_AudioSession_DeactivatedReason; 180 181 /** 182 * @brief declare the audio session strategy 183 * 184 * @since 12 185 */ 186 typedef struct OH_AudioSession_Strategy { 187 /** 188 * @brief audio session concurrency mode 189 */ 190 OH_AudioSession_ConcurrencyMode concurrencyMode; 191 } OH_AudioSession_Strategy; 192 193 /** 194 * @brief declare the audio session deactivated event 195 * 196 * @since 12 197 */ 198 typedef struct OH_AudioSession_DeactivatedEvent { 199 /** 200 * @brief audio session deactivated reason 201 */ 202 OH_AudioSession_DeactivatedReason reason; 203 } OH_AudioSession_DeactivatedEvent; 204 205 /** 206 * @brief declare the audio session state change event 207 * 208 * @since 20 209 */ 210 typedef struct OH_AudioSession_StateChangedEvent { 211 /** 212 * @brief audio session state change hints. 213 */ 214 OH_AudioSession_StateChangeHint stateChangeHint; 215 } OH_AudioSession_StateChangedEvent; 216 217 /** 218 * @brief This function pointer will point to the callback function that 219 * is used to return the audio session state change event. 220 * 221 * @param event the {@link #OH_AudioSession_StateChangedEvent} state change triggering event. 222 * @since 20 223 */ 224 typedef void (*OH_AudioSession_StateChangedCallback) ( 225 OH_AudioSession_StateChangedEvent event); 226 227 /** 228 * @brief This function pointer will point to the callback function that 229 * is used to return the audio session device change event. 230 * 231 * @param audioDeviceDescriptorArray the {@link OH_AudioDeviceDescriptorArray} 232 * pointer variable which will be set the audio device descriptors value. 233 * Do not release the audioDeviceDescriptorArray pointer separately 234 * instead call {@link OH_AudioSessionManager_ReleaseDevices} 235 * to release the DeviceDescriptor array when it is no use anymore. 236 * @param changeReason the {@link #OH_AudioStream_DeviceChangeReason} indicates that why does the device changes. 237 * @param recommendedAction the {@link #OH_AudioSession_OutputDeviceChangeRecommendedAction} 238 * recommend action when device change. 239 * @since 20 240 */ 241 typedef void (*OH_AudioSession_CurrentOutputDeviceChangedCallback) ( 242 OH_AudioDeviceDescriptorArray *devices, 243 OH_AudioStream_DeviceChangeReason changeReason, 244 OH_AudioSession_OutputDeviceChangeRecommendedAction recommendedAction); 245 246 /** 247 * @brief This function pointer will point to the callback function that 248 * is used to return the audio session deactivated event. 249 * 250 * @param event the {@link #OH_AudioSession_DeactivatedEvent} deactivated triggering event. 251 * @since 12 252 */ 253 typedef int32_t (*OH_AudioSession_DeactivatedCallback) ( 254 OH_AudioSession_DeactivatedEvent event); 255 256 /** 257 * @brief Fetch the audio session manager handle. 258 * The audio session manager handle should be the first parameter in audio session related functions 259 * 260 * @param audioSessionManager the {@link #OH_AudioSessionManager} 261 * which will be returned as the output parameter 262 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 263 * or {@link #AUDIOCOMMON_RESULT_ERROR_SYSTEM} if system state error 264 * @since 12 265 */ 266 OH_AudioCommon_Result OH_AudioManager_GetAudioSessionManager( 267 OH_AudioSessionManager **audioSessionManager); 268 269 /** 270 * @brief Activate the audio session for the current pid application. 271 * If {@link #OH_AudioSessionManager_SetScene} is called, it will take focus when calling this method. 272 * 273 * @param audioSessionManager the {@link #OH_AudioSessionManager} 274 * returned by the {@link #OH_AudioManager_GetAudioSessionManager} 275 * @param strategy pointer of {@link #OH_AudioSession_Strategy} 276 * which is used for setting audio session strategy 277 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 278 * or {@link #AUDIOCOMMON_REULT_INVALID_PARAM} if parameter validation fails 279 * or {@link #AUDIOCOMMON_RESULT_ERROR_ILLEGAL_STATE} if system illegal state 280 * @since 12 281 */ 282 OH_AudioCommon_Result OH_AudioSessionManager_ActivateAudioSession( 283 OH_AudioSessionManager *audioSessionManager, const OH_AudioSession_Strategy *strategy); 284 285 /** 286 * @brief Deactivate the audio session for the current pid application. 287 * 288 * @param audioSessionManager the {@link #OH_AudioSessionManager} 289 * returned by the {@link #OH_AudioManager_GetAudioSessionManager} 290 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 291 * or {@link #AUDIOCOMMON_REULT_INVALID_PARAM} if parameter validation fails 292 * or {@link #AUDIOCOMMON_RESULT_ERROR_ILLEGAL_STATE} if system illegal state 293 * @since 12 294 */ 295 OH_AudioCommon_Result OH_AudioSessionManager_DeactivateAudioSession( 296 OH_AudioSessionManager *audioSessionManager); 297 298 /** 299 * @brief Querying whether the current pid application has an activated audio session. 300 * 301 * @param audioSessionManager the {@link #OH_AudioSessionManager} 302 * returned by the {@link #OH_AudioManager_GetAudioSessionManager} 303 * @return True when the current pid application has an activated audio session 304 * False when it does not 305 * @since 12 306 */ 307 bool OH_AudioSessionManager_IsAudioSessionActivated( 308 OH_AudioSessionManager *audioSessionManager); 309 310 /** 311 * @brief Register the audio session deactivated event callback. 312 * 313 * @param audioSessionManager the {@link #OH_AudioSessionManager} 314 * returned by the {@link #OH_AudioManager_GetAudioSessionManager} 315 * @param callback the {@link #OH_AudioSession_DeactivatedCallback} which is used 316 * to receive the deactivated event 317 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 318 * or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if parameter validation fails 319 * @since 12 320 */ 321 OH_AudioCommon_Result OH_AudioSessionManager_RegisterSessionDeactivatedCallback( 322 OH_AudioSessionManager *audioSessionManager, OH_AudioSession_DeactivatedCallback callback); 323 324 /** 325 * @brief Unregister the audio session deactivated event callback. 326 * 327 * @param audioSessionManager the {@link #OH_AudioSessionManager} 328 * returned by the {@link #OH_AudioManager_GetAudioSessionManager} 329 * @param callback the {@link #OH_AudioSession_DeactivatedCallback} which is used 330 * to receive the deactivated event 331 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 332 * or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if parameter validation fails 333 * @since 12 334 */ 335 OH_AudioCommon_Result OH_AudioSessionManager_UnregisterSessionDeactivatedCallback( 336 OH_AudioSessionManager *audioSessionManager, OH_AudioSession_DeactivatedCallback callback); 337 338 /** 339 * @brief Set scene for audio session. 340 * 341 * @param audioSessionManager the {@link #OH_AudioSessionManager} 342 * returned by the {@link #OH_AudioManager_GetAudioSessionManager} 343 * @param scene the {@link #OH_AudioSession_Scene} 344 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 345 * or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if parameter validation fails 346 * or {@link #AUDIOCOMMON_RESULT_ERROR_ILLEGAL_STATE} if system illegal state 347 * or {@link #AUDIOCOMMON_RESULT_ERROR_SYSTEM} if system state error 348 * @since 20 349 */ 350 OH_AudioCommon_Result OH_AudioSessionManager_SetScene( 351 OH_AudioSessionManager *audioSessionManager, OH_AudioSession_Scene scene); 352 353 /** 354 * @brief Register the audio session state change event callback. 355 * 356 * @param audioSessionManager the {@link #OH_AudioSessionManager} 357 * returned by the {@link #OH_AudioManager_GetAudioSessionManager} 358 * @param callback the {@link #OH_AudioSession_StateChangedCallback} which is used 359 * to receive the state change event 360 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 361 * or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if parameter validation fails 362 * or {@link AUDIOCOMMON_RESULT_ERROR_NO_MEMORY} No memory error 363 * or {@link #AUDIOCOMMON_RESULT_ERROR_SYSTEM} if system state error 364 * @since 20 365 */ 366 OH_AudioCommon_Result OH_AudioSessionManager_RegisterStateChangeCallback( 367 OH_AudioSessionManager *audioSessionManager, OH_AudioSession_StateChangedCallback callback); 368 369 /** 370 * @brief Unregister the audio session state change event callback. 371 * 372 * @param audioSessionManager the {@link #OH_AudioSessionManager} 373 * returned by the {@link #OH_AudioManager_GetAudioSessionManager} 374 * @param callback the {@link #OH_AudioSession_StateChangedCallback} which is used 375 * to receive the state change event 376 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 377 * or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if parameter validation fails 378 * or {@link #AUDIOCOMMON_RESULT_ERROR_SYSTEM} if system state error 379 * @since 20 380 */ 381 OH_AudioCommon_Result OH_AudioSessionManager_UnregisterStateChangeCallback( 382 OH_AudioSessionManager *audioSessionManager, OH_AudioSession_StateChangedCallback callback); 383 384 /** 385 * @brief Sets the default output device. 386 * This function applys on audiorenderers whose StreamUsage are 387 * STREAM_USAGE_VOICE_COMMUNICATION/STREAM_USAGE_VIDEO_COMMUNICATION/STREAM_USAGE_VOICE_MESSAGE. 388 * Setting the device will only takes effect if no other accessory such as headphones are in use 389 * @param audioSessionManager the {@link #OH_AudioSessionManager} 390 * returned by the {@link #OH_AudioManager_GetAudioSessionManager} 391 * @param deviceType The target device. The available deviceTypes are: 392 * EARPIECE: Built-in earpiece 393 * SPEAKER: Built-in speaker 394 * DEFAULT: System default output device 395 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 396 * or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if parameter validation fails 397 * or {@link #AUDIOCOMMON_RESULT_ERROR_SYSTEM} if system state error 398 * @since 20 399 */ 400 OH_AudioCommon_Result OH_AudioSessionManager_SetDefaultOutputDevice( 401 OH_AudioSessionManager *audioSessionManager, OH_AudioDevice_Type deviceType); 402 403 /** 404 * @brief Gets the default output device. 405 * 406 * @param audioSessionManager the {@link #OH_AudioSessionManager} 407 * returned by the {@link #OH_AudioManager_GetAudioSessionManager} 408 * @param deviceType The target device.The available deviceTypes are: 409 * EARPIECE: Built-in earpiece 410 * SPEAKER: Built-in speaker 411 * DEFAULT: System default output device 412 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 413 * or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if parameter validation fails 414 * or {@link #AUDIOCOMMON_RESULT_ERROR_ILLEGAL_STATE} if system illegal state 415 * @since 20 416 */ 417 OH_AudioCommon_Result OH_AudioSessionManager_GetDefaultOutputDevice( 418 OH_AudioSessionManager *audioSessionManager, OH_AudioDevice_Type *deviceType); 419 420 /** 421 * @brief Release the audio device descriptor array object. 422 * 423 * @param audioSessionManager the {@link OH_AudioSessionManager} 424 * returned by the {@link #OH_AudioManager_GetAudioSessionManager} 425 * @param audioDeviceDescriptorArray Audio device descriptors should be released. 426 * @return {@link AUDIOCOMMON_RESULT_SUCCESS} If the execution is successful. 427 * or {@link AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if parameter validation fails 428 * 1.The param of audioSessionManager is nullptr; 429 * 2.The param of audioDeviceDescriptorArray is nullptr. 430 * @since 20 431 */ 432 OH_AudioCommon_Result OH_AudioSessionManager_ReleaseDevices( 433 OH_AudioSessionManager *audioSessionManager, 434 OH_AudioDeviceDescriptorArray *audioDeviceDescriptorArray); 435 436 /** 437 * @brief Register the audio session device change event callback. 438 * 439 * @param audioSessionManager the {@link #OH_AudioSessionManager} 440 * returned by the {@link #OH_AudioManager_GetAudioSessionManager} 441 * @param callback the {@link #OH_AudioSession_CurrentOutputDeviceChangedCallback} which is used 442 * to receive the device change event 443 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 444 * or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if parameter validation fails 445 * or {@link AUDIOCOMMON_RESULT_ERROR_NO_MEMORY} No memory error 446 * or {@link #AUDIOCOMMON_RESULT_ERROR_SYSTEM} if system state error 447 * @since 20 448 */ 449 OH_AudioCommon_Result OH_AudioSessionManager_RegisterCurrentOutputDeviceChangeCallback( 450 OH_AudioSessionManager *audioSessionManager, 451 OH_AudioSession_CurrentOutputDeviceChangedCallback callback); 452 453 /** 454 * @brief Unregister the audio session device change event callback. 455 * 456 * @param audioSessionManager the {@link #OH_AudioSessionManager} 457 * returned by the {@link #OH_AudioManager_GetAudioSessionManager} 458 * @param callback the {@link #OH_AudioSession_CurrentOutputDeviceChangedCallback} which is used 459 * to receive the device change event 460 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 461 * or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if parameter validation fails 462 * or {@link #AUDIOCOMMON_RESULT_ERROR_SYSTEM} if system state error 463 * @since 20 464 */ 465 OH_AudioCommon_Result OH_AudioSessionManager_UnregisterCurrentOutputDeviceChangeCallback( 466 OH_AudioSessionManager *audioSessionManager, 467 OH_AudioSession_CurrentOutputDeviceChangedCallback callback); 468 469 #ifdef __cplusplus 470 } 471 #endif 472 /** @} */ 473 #endif // NATIVE_AUDIO_ROUTING_MANAGER_H