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