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_routing_manager.h 30 * 31 * @brief Declare audio routing manager related interfaces. 32 * 33 * This file interface is used for the creation of audioRoutingManager 34 * as well as the registration and deregistration functions when the device connection status changes 35 * as well as the release of pointer arrays storing device information. 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_ROUTING_MANAGER_H 45 #define NATIVE_AUDIO_ROUTING_MANAGER_H 46 47 #include "native_audio_device_base.h" 48 #ifdef __cplusplus 49 extern "C" { 50 #endif 51 52 /** 53 * @brief Declaring the audio routing manager. 54 * The handle of audio routing manager used for routing and device related functions. 55 * 56 * @since 12 57 */ 58 typedef struct OH_AudioRoutingManager OH_AudioRoutingManager; 59 60 /** 61 * @brief This function pointer will point to the callback function that 62 * is used to return the changing audio device descriptors. 63 * There may be more than one audio device descriptor returned. 64 * 65 * @param type the {@link OH_AudioDevice_ChangeType} is connect or disconnect. 66 * @param audioDeviceDescriptorArray the {@link OH_AudioDeviceDescriptorArray} 67 * pointer variable which will be set the audio device descriptors value. 68 * Do not release the audioDeviceDescriptorArray pointer separately 69 * instead call {@link OH_AudioRoutingManager_ReleaseDevices} to release the DeviceDescriptor array 70 * when it is no use anymore. 71 * @since 12 72 */ 73 typedef int32_t (*OH_AudioRoutingManager_OnDeviceChangedCallback) ( 74 OH_AudioDevice_ChangeType type, 75 OH_AudioDeviceDescriptorArray *audioDeviceDescriptorArray 76 ); 77 78 /** 79 * @brief This type defines the callback function that is used to receive the audio devices' block status. 80 * 81 * @param audioDeviceDescriptorArray The {@link OH_AudioDeviceDescriptorArray} 82 * pointer variable which will be set the audio device descriptors value. 83 * Do not release the audioDeviceDescriptorArray pointer separately instead of calling 84 * {@link OH_AudioRoutingManager_ReleaseDevices} to release the DeviceDescriptor array when it is no use anymore. 85 * @param status The {@link OH_AudioDevice_BlockStatus} is the block status. 86 * @param userData User data which is passed by user. 87 * @since 13 88 */ 89 typedef void (*OH_AudioRoutingManager_OnDeviceBlockStatusCallback)( 90 OH_AudioDeviceDescriptorArray *audioDeviceDescriptorArray, 91 OH_AudioDevice_BlockStatus status, 92 void *userData); 93 94 /** 95 * @brief Query whether microphone block detection is supported on current device. 96 * 97 * @param audioRoutingManager the {@link OH_AudioRoutingManager} handle returned by 98 * {@link OH_AudioManager_GetAudioRoutingManager}. 99 * @param supported query result. 100 * @return Function result code: 101 * {@link AUDIOCOMMON_RESULT_SUCCESS} If the execution is successful. 102 * {@link AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}: 103 * 1.The param of audioRoutingManager is nullptr; 104 * 2.The param of supported is nullptr. 105 * @since 13 106 */ 107 OH_AudioCommon_Result OH_AudioRoutingManager_IsMicBlockDetectionSupported( 108 OH_AudioRoutingManager *audioRoutingManager, 109 bool *supported); 110 111 /** 112 * @brief Query the audio routing manager handle. 113 * which should be set as the first parameter in routing releated functions. 114 * 115 * @param audioRoutingManager the {@link OH_AudioRoutingManager} 116 * handle returned by {@link OH_AudioManager_GetAudioRoutingManager}. 117 * @return Function result code: 118 * {@link AUDIOCOMMON_RESULT_SUCCESS} If the execution is successful. 119 * @since 12 120 */ 121 OH_AudioCommon_Result OH_AudioManager_GetAudioRoutingManager(OH_AudioRoutingManager **audioRoutingManager); 122 123 /** 124 * @brief Query the available devices according to the input deviceFlag. 125 * 126 * @param audioRoutingManager the {@link OH_AudioRoutingManager} 127 * handle returned by {@link OH_AudioManager_GetAudioRoutingManager}. 128 * @param deviceFlag the {@link OH_AudioDevice_DeviceFlag} which is used as 129 * the filter parameter for selecting the target devices. 130 * @param audioDeviceDescriptorArray the {@link OH_AudioDeviceDescriptorArray} 131 * pointer variable which will be set the audio device descriptors value 132 * Do not release the audioDeviceDescriptorArray pointer separately 133 * instead call {@link OH_AudioRoutingManager_ReleaseDevices} to release the DeviceDescriptor array 134 * when it is no use anymore. 135 * @return Function result code: 136 * {@link AUDIOCOMMON_RESULT_SUCCESS} If the execution is successful. 137 * {@link AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}: 138 * 1.The param of audioRoutingManager is nullptr; 139 * 2.The param of deviceFlag invalid; 140 * 3.The param of audioDeviceDescriptorArray is nullptr. 141 * {@link AUDIOCOMMON_RESULT_ERROR_NO_MEMORY} The param of audioDeviceDescriptorArray is nullptr. 142 * @since 12 143 */ 144 OH_AudioCommon_Result OH_AudioRoutingManager_GetDevices( 145 OH_AudioRoutingManager *audioRoutingManager, 146 OH_AudioDevice_Flag deviceFlag, 147 OH_AudioDeviceDescriptorArray **audioDeviceDescriptorArray); 148 149 /** 150 * @brief Get available devices by device usage. 151 * 152 * @param audioRoutingManager the {@link OH_AudioRoutingManager} handle returned 153 * by {@link OH_AudioManager_GetAudioRoutingManager}. 154 * @param deviceUsage the device usage. 155 * @param audioDeviceDescriptorArray the {@link OH_AudioDeviceDescriptorArray} 156 * pointer variable which will be set the audio device descriptors value 157 * Do not release the audioDeviceDescriptorArray pointer separately 158 * instead call {@link OH_AudioRoutingManager_ReleaseDevices} to release the DeviceDescriptor array 159 * when it is no use anymore. 160 * @return Function result code: 161 * {@link AUDIOCOMMON_RESULT_SUCCESS} If the execution is successful. 162 * {@link AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}: 163 * 1.The param of audioRoutingManager is nullptr; 164 * 2.The param of deviceUsage invalid; 165 * 3.The param of audioDeviceDescriptorArray is nullptr. 166 * {@link AUDIOCOMMON_RESULT_ERROR_NO_MEMORY} No memory error. 167 * @since 12 168 */ 169 OH_AudioCommon_Result OH_AudioRoutingManager_GetAvailableDevices( 170 OH_AudioRoutingManager *audioRoutingManager, 171 OH_AudioDevice_Usage deviceUsage, OH_AudioDeviceDescriptorArray **audioDeviceDescriptorArray); 172 173 /** 174 * @brief Get preferred ouput devices by audio usage. 175 * 176 * @param audioRoutingManager the {@link OH_AudioRoutingManager} handle returned 177 * by {@link OH_AudioManager_GetAudioRoutingManager}. 178 * @param streamUsage the audio stream usage. 179 * @param audioDeviceDescriptorArray the {@link OH_AudioDeviceDescriptorArray} 180 * pointer variable which will be set the audio device descriptors value 181 * Do not release the audioDeviceDescriptorArray pointer separately 182 * instead call {@link OH_AudioRoutingManager_ReleaseDevices} to release the DeviceDescriptor array 183 * when it is no use anymore. 184 * @return Function result code: 185 * {@link AUDIOCOMMON_RESULT_SUCCESS} If the execution is successful. 186 * {@link AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}: 187 * 1.The param of audioRoutingManager is nullptr; 188 * 2.The param of streamUsage invalid; 189 * 3.The param of audioDeviceDescriptorArray is nullptr. 190 * {@link AUDIOCOMMON_RESULT_ERROR_NO_MEMORY} No memory error. 191 * @since 12 192 */ 193 OH_AudioCommon_Result OH_AudioRoutingManager_GetPreferredOutputDevice( 194 OH_AudioRoutingManager *audioRoutingManager, 195 OH_AudioStream_Usage streamUsage, OH_AudioDeviceDescriptorArray **audioDeviceDescriptorArray); 196 197 /** 198 * @brief Get preferred input devices by audio source type. 199 * @param audioRoutingManager the {@link OH_AudioRoutingManager} handle returned 200 * by {@link OH_AudioManager_GetAudioRoutingManager}. 201 * @param sourceType the audio source type. 202 * @param audioDeviceDescriptorArray the {@link OH_AudioDeviceDescriptorArray} 203 * pointer variable which will be set the audio device descriptors value 204 * Do not release the audioDeviceDescriptorArray pointer separately 205 * instead call {@link OH_AudioRoutingManager_ReleaseDevices} to release the DeviceDescriptor array 206 * when it is no use anymore. 207 * @return Function result code: 208 * {@link AUDIOCOMMON_RESULT_SUCCESS} If the execution is successful. 209 * {@link AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}: 210 * 1.The param of audioRoutingManager is nullptr; 211 * 2.The param of sourceType invalid; 212 * 3.The param of audioDeviceDescriptorArray is nullptr. 213 * {@link AUDIOCOMMON_RESULT_ERROR_NO_MEMORY} No memory error. 214 * @since 12 215 */ 216 OH_AudioCommon_Result OH_AudioRoutingManager_GetPreferredInputDevice(OH_AudioRoutingManager *audioRoutingManager, 217 OH_AudioStream_SourceType sourceType, OH_AudioDeviceDescriptorArray **audioDeviceDescriptorArray); 218 /** 219 * @brief Register the device change callback of the audio routing manager. 220 * 221 * @param audioRoutingManager the {@link OH_AudioRoutingManager} 222 * handle returned by {@link OH_AudioManager_GetAudioRoutingManager}. 223 * @param deviceFlag the {@link OH_AudioDevice_DeviceFlag} which is used to register callback. 224 * @param callback the {@link OH_AudioRoutingManager_OnDeviceChangedCallback} 225 * Callback function which will be called when devices changed. 226 * @return Function result code: 227 * {@link AUDIOCOMMON_RESULT_SUCCESS} If the execution is successful. 228 * {@link AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}: 229 * 1.The param of audioRoutingManager is nullptr; 230 * 2.The param of deviceFlag invalid; 231 * 3.The param of callback is nullptr. 232 * @since 12 233 */ 234 OH_AudioCommon_Result OH_AudioRoutingManager_RegisterDeviceChangeCallback( 235 OH_AudioRoutingManager *audioRoutingManager, OH_AudioDevice_Flag deviceFlag, 236 OH_AudioRoutingManager_OnDeviceChangedCallback callback); 237 238 /** 239 * @brief Unregister the device change callback of the audio routing manager. 240 * 241 * @param audioRoutingManager the {@link OH_AudioRoutingManager} 242 * handle returned by {@link OH_AudioManager_GetAudioRoutingManager}. 243 * @param callback the {@link OH_AudioRoutingManager_OnDeviceChangedCallback} 244 * Callback function which will be called when devices changed. 245 * @return Function result code: 246 * {@link AUDIOCOMMON_RESULT_SUCCESS} If the execution is successful. 247 * {@link AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}: 248 * 1.The param of audioRoutingManager is nullptr; 249 * 2.The param of callback is nullptr. 250 * @since 12 251 */ 252 OH_AudioCommon_Result OH_AudioRoutingManager_UnregisterDeviceChangeCallback( 253 OH_AudioRoutingManager *audioRoutingManager, 254 OH_AudioRoutingManager_OnDeviceChangedCallback callback); 255 256 /** 257 * @brief Set the microphone block status callback. The caller will receive the callback only when it is recording 258 * and the used microphones' block status have changed. Currently, block detecting is only support for microphones 259 * located on the local device. 260 * 261 * @param audioRoutingManager The {@link OH_AudioRoutingManager} handle returned by 262 * {@link OH_AudioManager_GetAudioRoutingManager}. 263 * @param callback The function pointer will point to the callback function that is used to receive the block status. 264 * @param userData User data which is passed by user. 265 * @return Function result code: 266 * {@link AUDIOCOMMON_RESULT_SUCCESS} If the execution is successful. 267 * {@link AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}: 268 * 1.The param of audioRoutingManager is nullptr; 269 * 2.The param of callback is nullptr. 270 * @since 13 271 */ 272 OH_AudioCommon_Result OH_AudioRoutingManager_SetMicBlockStatusCallback( 273 OH_AudioRoutingManager *audioRoutingManager, 274 OH_AudioRoutingManager_OnDeviceBlockStatusCallback callback, 275 void *userData); 276 277 /** 278 * @brief Release the audio device descriptor array object. 279 * 280 * @param audioRoutingManager the {@link OH_AudioRoutingManager} 281 * handle returned by {@link OH_AudioManager_GetAudioRoutingManager}. 282 * @param audioDeviceDescriptorArray Audio device descriptors should be released. 283 * and get from {@link OH_AudioRoutingManager_GetDevices} 284 * @return Function result code: 285 * {@link AUDIOCOMMON_RESULT_SUCCESS} If the execution is successful. 286 * {@link AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}: 287 * 1.The param of audioRoutingManager is nullptr; 288 * 2.The param of audioDeviceDescriptorArray is nullptr. 289 * @since 12 290 */ 291 OH_AudioCommon_Result OH_AudioRoutingManager_ReleaseDevices( 292 OH_AudioRoutingManager *audioRoutingManager, 293 OH_AudioDeviceDescriptorArray *audioDeviceDescriptorArray); 294 #ifdef __cplusplus 295 } 296 #endif 297 /** @} */ 298 #endif // NATIVE_AUDIO_ROUTING_MANAGER_H 299