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