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_device_base.h 30 * 31 * @brief Declare audio device related interfaces for audio device descriptor. 32 * 33 * Defines the types of audio device parameters and the interfaces for obtaining the parameters of each device. 34 * 35 * @library libohaudio.so 36 * @syscap SystemCapability.Multimedia.Audio.Core 37 * @since 12 38 * @version 1.0 39 */ 40 41 #ifndef NATIVE_AUDIO_DEVICE_BASE_H 42 #define NATIVE_AUDIO_DEVICE_BASE_H 43 44 #include "native_audiostream_base.h" 45 #include "native_audio_common.h" 46 #ifdef __cplusplus 47 extern "C" { 48 #endif 49 50 /** 51 * @brief Defines the audio device change type. 52 * 53 * @since 12 54 */ 55 typedef enum { 56 /** 57 * @brief Device connection. 58 */ 59 AUDIO_DEVICE_CHANGE_TYPE_CONNECT = 0, 60 61 /** 62 * @brief Device disconnection. 63 */ 64 AUDIO_DEVICE_CHANGE_TYPE_DISCONNECT = 1, 65 } OH_AudioDevice_ChangeType; 66 67 /** 68 * @brief Defines the audio device device role. 69 * 70 * @since 12 71 */ 72 typedef enum { 73 /** 74 * @brief Input role. 75 */ 76 AUDIO_DEVICE_ROLE_INPUT = 1, 77 78 /** 79 * @brief Output role. 80 */ 81 AUDIO_DEVICE_ROLE_OUTPUT = 2, 82 } OH_AudioDevice_Role; 83 84 /** 85 * @brief Defines the audio device device type. 86 * 87 * @since 12 88 */ 89 typedef enum { 90 /** 91 * @brief Invalid device. 92 */ 93 AUDIO_DEVICE_TYPE_INVALID = 0, 94 95 /** 96 * @brief Built-in earpiece. 97 */ 98 AUDIO_DEVICE_TYPE_EARPIECE = 1, 99 100 /** 101 * @brief Built-in speaker. 102 */ 103 AUDIO_DEVICE_TYPE_SPEAKER = 2, 104 105 /** 106 * @brief Wired headset, which is a combination of a pair of earpieces and a microphone. 107 */ 108 AUDIO_DEVICE_TYPE_WIRED_HEADSET = 3, 109 110 /** 111 * @brief A pair of wired headphones. 112 */ 113 AUDIO_DEVICE_TYPE_WIRED_HEADPHONES = 4, 114 115 /** 116 * @brief Bluetooth device using the synchronous connection oriented link (SCO). 117 */ 118 AUDIO_DEVICE_TYPE_BLUETOOTH_SCO = 7, 119 120 /** 121 * @brief Bluetooth device using advanced audio distibution profile (A2DP). 122 */ 123 AUDIO_DEVICE_TYPE_BLUETOOTH_A2DP = 8, 124 125 /** 126 * @brief Built-in microphone. 127 */ 128 AUDIO_DEVICE_TYPE_MIC = 15, 129 130 /** 131 * @brief USB audio headset. 132 */ 133 AUDIO_DEVICE_TYPE_USB_HEADSET = 22, 134 135 /** 136 * @brief Display port device. 137 */ 138 AUDIO_DEVICE_TYPE_DISPLAY_PORT = 23, 139 140 /** 141 * @brief A device type for rerouting audio to other remote devices by system application. 142 */ 143 AUDIO_DEVICE_TYPE_REMOTE_CAST = 24, 144 145 /** 146 * @brief Default device type. 147 */ 148 AUDIO_DEVICE_TYPE_DEFAULT = 1000, 149 } OH_AudioDevice_Type; 150 151 /** 152 * @brief Defines the audio device flag. 153 * 154 * @since 12 155 */ 156 typedef enum { 157 /** 158 * @brief None device. 159 */ 160 AUDIO_DEVICE_FLAG_NONE = 0, 161 162 /** 163 * @brief Output device. 164 */ 165 AUDIO_DEVICE_FLAG_OUTPUT = 1, 166 167 /** 168 * @brief Input device. 169 */ 170 AUDIO_DEVICE_FLAG_INPUT = 2, 171 172 /** 173 * @brief All device. 174 */ 175 AUDIO_DEVICE_FLAG_ALL = 3, 176 } OH_AudioDevice_Flag; 177 178 /** 179 * @brief Defines the audio device usage. 180 * 181 * @since 12 182 */ 183 typedef enum { 184 /** 185 * @brief Device used for media ouput. 186 * 187 * @since 12 188 */ 189 AUDIO_DEVICE_USAGE_MEDIA_OUTPUT = 1, 190 191 /** 192 * @brief Device used for media input. 193 * 194 * @since 12 195 */ 196 AUDIO_DEVICE_USAGE_MEDIA_INPUT = 2, 197 198 /** 199 * @brief Device used for media, including input and output. 200 * 201 * @since 12 202 */ 203 AUDIO_DEVICE_USAGE_MEDIA_ALL = 3, 204 205 /** 206 * @brief Device used for call output. 207 * 208 * @since 12 209 */ 210 AUDIO_DEVICE_USAGE_CALL_OUTPUT = 4, 211 212 /** 213 * @brief Device used for call input. 214 * 215 * @since 12 216 */ 217 AUDIO_DEVICE_USAGE_CALL_INPUT = 8, 218 219 /** 220 * @brief Device used for call, including input and output. 221 * 222 * @since 12 223 */ 224 AUDIO_DEVICE_USAGE_CALL_ALL = 12, 225 } OH_AudioDevice_Usage; 226 227 /** 228 * @brief Declaring the audio device descriptor. 229 * The instance is used to get more audio device detail attributes. 230 * 231 * @since 12 232 */ 233 typedef struct OH_AudioDeviceDescriptor OH_AudioDeviceDescriptor; 234 235 /** 236 * @brief Declaring the audio device descriptor array. 237 * 238 * @since 12 239 */ 240 typedef struct OH_AudioDeviceDescriptorArray { 241 /** 242 * @brief Audio device descriptor array size. 243 */ 244 uint32_t size; 245 246 /** 247 * @brief Audio device descriptor array. 248 */ 249 OH_AudioDeviceDescriptor **descriptors; 250 } OH_AudioDeviceDescriptorArray; 251 252 /** 253 * @brief Declaring the audio device blocked status. By default, the audio device is considered as unbloked. 254 * 255 * @since 13 256 */ 257 typedef enum { 258 /** 259 * @brief Audio device is unblocked. 260 * 261 * @since 13 262 */ 263 AUDIO_DEVICE_UNBLOCKED = 0, 264 265 /** 266 * @brief Audio Device is blocked. 267 * 268 * @since 13 269 */ 270 AUDIO_DEVICE_BLOCKED = 1, 271 } OH_AudioDevice_BlockStatus; 272 273 /** 274 * @brief Query the device role of the target audio device descriptor. 275 * 276 * @param audioDeviceDescriptor reference returned by {@link OH_AudioRoutingManager_GetDevices} or 277 * {@link OH_AudioRouterManager_OnDeviceChangedCallback}. 278 * @param deviceRole the pointer {@link OH_AudioDevice_DeviceRole} variable that will be set the device role value. 279 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}. 280 * @since 12 281 */ 282 OH_AudioCommon_Result OH_AudioDeviceDescriptor_GetDeviceRole(OH_AudioDeviceDescriptor *audioDeviceDescriptor, 283 OH_AudioDevice_Role *deviceRole); 284 285 /** 286 * @brief Query the device type of the target audio device descriptor. 287 * 288 * @param audioDeviceDescriptor reference returned by {@link OH_AudioRoutingManager_GetDevices} or 289 * {@link OH_AudioRouterManager_OnDeviceChangedCallback}. 290 * @param deviceType the pointer {@link OH_AudioDevice_DeviceType} 291 * pointer variable that will be set the device type value. 292 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}. 293 * @since 12 294 */ 295 OH_AudioCommon_Result OH_AudioDeviceDescriptor_GetDeviceType(OH_AudioDeviceDescriptor *audioDeviceDescriptor, 296 OH_AudioDevice_Type *deviceType); 297 298 /** 299 * @brief Query the device id of the target audio device descriptor. 300 * 301 * @param audioDeviceDescriptor reference returned by {@link OH_AudioRoutingManager_GetDevices} or 302 * {@link OH_AudioRouterManager_OnDeviceChangedCallback}. 303 * @param id pointer variable that will be set the device id value. 304 * @return {@link #AUDIODEVICE_SUCCESS} or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}. 305 * @since 12 306 */ 307 OH_AudioCommon_Result OH_AudioDeviceDescriptor_GetDeviceId(OH_AudioDeviceDescriptor *audioDeviceDescriptor, 308 uint32_t *id); 309 310 /** 311 * @brief Query the device name of the target audio device descriptor. 312 * 313 * @param audioDeviceDescriptor reference returned by {@link OH_AudioRoutingManager_GetDevices} or 314 * {@link OH_AudioRouterManager_OnDeviceChangedCallback}. 315 * @param name pointer variable that will be set the device name value. 316 * Do not release the name pointer separately 317 * instead call {@link OH_AudioRoutingManager_ReleaseDevices} to relase all the DeviceDescriptor array 318 * when it is no use anymore. 319 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}. 320 * @since 12 321 */ 322 OH_AudioCommon_Result OH_AudioDeviceDescriptor_GetDeviceName(OH_AudioDeviceDescriptor *audioDeviceDescriptor, 323 char **name); 324 325 /** 326 * @brief Query the device address of the target audio device descriptor. 327 * 328 * @param audioDeviceDescriptor reference returned by {@link OH_AudioRoutingManager_GetDevices} or 329 * {@link OH_AudioRouterManager_OnDeviceChangedCallback}. 330 * @param address pointer variable that will be set the device address value. 331 * Do not release the address pointer separately 332 * instead call {@link OH_AudioRoutingManager_ReleaseDevices} to relase all the DeviceDescriptor array 333 * when it is no use anymore. 334 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}. 335 * @since 12 336 */ 337 OH_AudioCommon_Result OH_AudioDeviceDescriptor_GetDeviceAddress(OH_AudioDeviceDescriptor *audioDeviceDescriptor, 338 char **address); 339 340 /** 341 * @brief Query the sample rate array of the target audio device descriptor. 342 * 343 * @param audioDeviceDescriptor reference returned by {@link OH_AudioRoutingManager_GetDevices} or 344 * {@link OH_AudioRouterManager_OnDeviceChangedCallback}. 345 * @param sampleRates array pointer variable that will be set the sample rate array value. 346 * Do not release the sampleRates pointer separately 347 * instead call {@link OH_AudioRoutingManager_ReleaseDevices} to relase all the DeviceDescriptor array 348 * when it is no use anymore. 349 * @param size pointer variable that will be set the sample rate size value. 350 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}. 351 * @since 12 352 */ 353 OH_AudioCommon_Result OH_AudioDeviceDescriptor_GetDeviceSampleRates(OH_AudioDeviceDescriptor *audioDeviceDescriptor, 354 uint32_t **sampleRates, uint32_t *size); 355 356 /** 357 * @brief Query the device channel count array of the target audio device descriptor. 358 * 359 * @param audioDeviceDescriptor reference returned by {@link OH_AudioRoutingManager_GetDevices} or 360 * {@link OH_AudioRouterManager_OnDeviceChangedCallback}. 361 * @param channelCounts array pointer variable that will be set the channel count array value. 362 * Do not release the channelCounts pointer separately 363 * instead call {@link OH_AudioRoutingManager_ReleaseDevices} to relase all the DeviceDescriptor array 364 * when it is no use anymore. 365 * @param size pointer variable that will be set the channel count size value. 366 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}. 367 * @since 12 368 */ 369 OH_AudioCommon_Result OH_AudioDeviceDescriptor_GetDeviceChannelCounts(OH_AudioDeviceDescriptor *audioDeviceDescriptor, 370 uint32_t **channelCounts, uint32_t *size); 371 372 /** 373 * @brief Query the display name of the target audio device descriptor. 374 * 375 * @param audioDeviceDescriptor reference returned by {@link OH_AudioRoutingManager_GetDevices} or 376 * {@link OH_AudioRouterManager_OnDeviceChangedCallback}. 377 * @param displayName pointer variable that will be set the display name value. 378 * Do not release the displayName pointer separately 379 * instead call {@link OH_AudioRoutingManager_ReleaseDevices} to relase all the DeviceDescriptor array 380 * when it is no use anymore. 381 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}. 382 * @since 12 383 */ 384 OH_AudioCommon_Result OH_AudioDeviceDescriptor_GetDeviceDisplayName(OH_AudioDeviceDescriptor *audioDeviceDescriptor, 385 char **displayName); 386 387 /** 388 * @brief Query the encoding type array of the target audio device descriptor. 389 * 390 * @param audioDeviceDescriptor reference returned by {@link OH_AudioRoutingManager_GetDevices} or 391 * {@link OH_AudioRouterManager_OnDeviceChangedCallback}. 392 * @param encodingTypes the {@link OH_AudioStream_EncodingType} 393 * Do not release the encodingTypes pointer separately 394 * instead call {@link OH_AudioRoutingManager_ReleaseDevices} to relase all the DeviceDescriptor array 395 * when it is no use anymore. 396 * @param size pointer variable that will be set the encoding type size value. 397 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}. 398 * @since 12 399 */ 400 OH_AudioCommon_Result OH_AudioDeviceDescriptor_GetDeviceEncodingTypes(OH_AudioDeviceDescriptor *audioDeviceDescriptor, 401 OH_AudioStream_EncodingType **encodingTypes, uint32_t *size); 402 #ifdef __cplusplus 403 } 404 #endif 405 /** @} */ 406 #endif // NATIVE_AUDIO_DEVICE_BASE_H