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