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 #ifdef __cplusplus 49 extern "C" { 50 #endif 51 52 /** 53 * @brief Declare the audio session manager. 54 * The handle of audio session manager is used for audio session related functions. 55 * 56 * @since 12 57 */ 58 typedef struct OH_AudioSessionManager OH_AudioSessionManager; 59 60 /** 61 * @brief Declare the audio concurrency modes. 62 * 63 * @since 12 64 */ 65 typedef enum { 66 /** 67 * @brief default mode 68 */ 69 CONCURRENCY_DEFAULT = 0, 70 71 /** 72 * @brief mix with others mode 73 */ 74 CONCURRENCY_MIX_WITH_OTHERS = 1, 75 76 /** 77 * @brief duck others mode 78 */ 79 CONCURRENCY_DUCK_OTHERS = 2, 80 81 /** 82 * @brief pause others mode 83 */ 84 CONCURRENCY_PAUSE_OTHERS = 3, 85 } OH_AudioSession_ConcurrencyMode; 86 87 /** 88 * @brief Declare the audio deactivated reasons. 89 * 90 * @since 12 91 */ 92 typedef enum { 93 /** 94 * @brief deactivated because of lower priority 95 */ 96 DEACTIVATED_LOWER_PRIORITY = 0, 97 98 /** 99 * @brief deactivated because of timing out 100 */ 101 DEACTIVATED_TIMEOUT = 1, 102 } OH_AudioSession_DeactivatedReason; 103 104 /** 105 * @brief declare the audio session strategy 106 * 107 * @since 12 108 */ 109 typedef struct OH_AudioSession_Strategy { 110 /** 111 * @brief audio session concurrency mode 112 */ 113 OH_AudioSession_ConcurrencyMode concurrencyMode; 114 } OH_AudioSession_Strategy; 115 116 /** 117 * @brief declare the audio session deactivated event 118 * 119 * @since 12 120 */ 121 typedef struct OH_AudioSession_DeactivatedEvent { 122 /** 123 * @brief audio session deactivated reason 124 */ 125 OH_AudioSession_DeactivatedReason reason; 126 } OH_AudioSession_DeactivatedEvent; 127 128 /** 129 * @brief This function pointer will point to the callback function that 130 * is used to return the audio session deactivated event. 131 * 132 * @param event the {@link #OH_AudioSession_DeactivatedEvent} deactivated triggering event. 133 * @since 12 134 */ 135 typedef int32_t (*OH_AudioSession_DeactivatedCallback) ( 136 OH_AudioSession_DeactivatedEvent event); 137 138 /** 139 * @brief Fetch the audio session manager handle. 140 * The audio session manager handle should be the first parameter in audio session related functions 141 * 142 * @param audioSessionManager the {@link #OH_AudioSessionManager} 143 * which will be returned as the output parameter 144 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 145 * or {@link #AUDIOCOMMON_RESULT_ERROR_SYSTEM} if system state error 146 * @since 12 147 */ 148 OH_AudioCommon_Result OH_AudioManager_GetAudioSessionManager( 149 OH_AudioSessionManager **audioSessionManager); 150 151 /** 152 * @brief Activate the audio session for the current pid application. 153 * 154 * @param audioSessionManager the {@link #OH_AudioSessionManager} 155 * returned by the {@link #OH_AudioManager_GetAudioSessionManager} 156 * @param strategy pointer of {@link #OH_AudioSession_Strategy} 157 * which is used for setting audio session strategy 158 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 159 * or {@link #AUDIOCOMMON_REULT_INVALID_PARAM} if parameter validation fails 160 * or {@link #AUDIOCOMMON_RESULT_ERROR_ILLEGAL_STATE} if system illegal state 161 * @since 12 162 */ 163 OH_AudioCommon_Result OH_AudioSessionManager_ActivateAudioSession( 164 OH_AudioSessionManager *audioSessionManager, const OH_AudioSession_Strategy *strategy); 165 166 /** 167 * @brief Deactivate the audio session for the current pid application. 168 * 169 * @param audioSessionManager the {@link #OH_AudioSessionManager} 170 * returned by the {@link #OH_AudioManager_GetAudioSessionManager} 171 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 172 * or {@link #AUDIOCOMMON_REULT_INVALID_PARAM} if parameter validation fails 173 * or {@link #AUDIOCOMMON_RESULT_ERROR_ILLEGAL_STATE} if system illegal state 174 * @since 12 175 */ 176 OH_AudioCommon_Result OH_AudioSessionManager_DeactivateAudioSession( 177 OH_AudioSessionManager *audioSessionManager); 178 179 /** 180 * @brief Querying whether the current pid application has an activated audio session. 181 * 182 * @param audioSessionManager the {@link #OH_AudioSessionManager} 183 * returned by the {@link #OH_AudioManager_GetAudioSessionManager} 184 * @return True when the current pid application has an activated audio session 185 * False when it does not 186 * @since 12 187 */ 188 bool OH_AudioSessionManager_IsAudioSessionActivated( 189 OH_AudioSessionManager *audioSessionManager); 190 191 /** 192 * @brief Register the audio session deactivated event callback. 193 * 194 * @param audioSessionManager the {@link #OH_AudioSessionManager} 195 * returned by the {@link #OH_AudioManager_GetAudioSessionManager} 196 * @param callback the {@link #OH_AudioSession_DeactivatedCallback} which is used 197 * to receive the deactivated event 198 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 199 * or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if parameter validation fails 200 * @since 12 201 */ 202 OH_AudioCommon_Result OH_AudioSessionManager_RegisterSessionDeactivatedCallback( 203 OH_AudioSessionManager *audioSessionManager, OH_AudioSession_DeactivatedCallback callback); 204 205 /** 206 * @brief Unregister the audio session deactivated event callback. 207 * 208 * @param audioSessionManager the {@link #OH_AudioSessionManager} 209 * returned by the {@link #OH_AudioManager_GetAudioSessionManager} 210 * @param callback the {@link #OH_AudioSession_DeactivatedCallback} which is used 211 * to receive the deactivated event 212 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} if execution succeeds 213 * or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM} if parameter validation fails 214 * @since 12 215 */ 216 OH_AudioCommon_Result OH_AudioSessionManager_UnregisterSessionDeactivatedCallback( 217 OH_AudioSessionManager *audioSessionManager, OH_AudioSession_DeactivatedCallback callback); 218 #ifdef __cplusplus 219 } 220 #endif 221 222 #endif // NATIVE_AUDIO_ROUTING_MANAGER_H 223 /** @} */