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 Usb audio device. 147 * 148 * @since 16 149 */ 150 AUDIO_DEVICE_TYPE_USB_DEVICE = 25, 151 152 /** 153 * @brief Accessory device. 154 */ 155 AUDIO_DEVICE_TYPE_ACCESSORY = 26, 156 157 /** 158 * @brief HDMI device, such as a device connected through an HDMI, ARC, or eARC interface. 159 * @since 19 160 */ 161 AUDIO_DEVICE_TYPE_HDMI = 27, 162 163 /** 164 * @brief Line-connected, digital audio output device, such as an S/PDIF device. 165 * @since 19 166 */ 167 AUDIO_DEVICE_TYPE_LINE_DIGITAL = 28, 168 169 /** 170 * @brief Distributed virtualization audio device. 171 * 172 * @since 18 173 */ 174 AUDIO_DEVICE_TYPE_REMOTE_DAUDIO = 29, 175 176 /** 177 * @brief Hearing aid audio device. 178 * 179 * @since 20 180 */ 181 AUDIO_DEVICE_TYPE_HEARING_AID = 30, 182 183 /** 184 * @brief Nearlink audio device. 185 * 186 * @since 20 187 */ 188 AUDIO_DEVICE_TYPE_NEARLINK = 31, 189 190 /** 191 * @brief Default device type. 192 */ 193 AUDIO_DEVICE_TYPE_DEFAULT = 1000, 194 } OH_AudioDevice_Type; 195 196 /** 197 * @brief Defines the audio device flag. 198 * 199 * @since 12 200 */ 201 typedef enum { 202 /** 203 * @brief None device. 204 */ 205 AUDIO_DEVICE_FLAG_NONE = 0, 206 207 /** 208 * @brief Output device. 209 */ 210 AUDIO_DEVICE_FLAG_OUTPUT = 1, 211 212 /** 213 * @brief Input device. 214 */ 215 AUDIO_DEVICE_FLAG_INPUT = 2, 216 217 /** 218 * @brief All device. 219 */ 220 AUDIO_DEVICE_FLAG_ALL = 3, 221 } OH_AudioDevice_Flag; 222 223 /** 224 * @brief Defines the audio device usage. 225 * 226 * @since 12 227 */ 228 typedef enum { 229 /** 230 * @brief Device used for media ouput. 231 * 232 * @since 12 233 */ 234 AUDIO_DEVICE_USAGE_MEDIA_OUTPUT = 1, 235 236 /** 237 * @brief Device used for media input. 238 * 239 * @since 12 240 */ 241 AUDIO_DEVICE_USAGE_MEDIA_INPUT = 2, 242 243 /** 244 * @brief Device used for media, including input and output. 245 * 246 * @since 12 247 */ 248 AUDIO_DEVICE_USAGE_MEDIA_ALL = 3, 249 250 /** 251 * @brief Device used for call output. 252 * 253 * @since 12 254 */ 255 AUDIO_DEVICE_USAGE_CALL_OUTPUT = 4, 256 257 /** 258 * @brief Device used for call input. 259 * 260 * @since 12 261 */ 262 AUDIO_DEVICE_USAGE_CALL_INPUT = 8, 263 264 /** 265 * @brief Device used for call, including input and output. 266 * 267 * @since 12 268 */ 269 AUDIO_DEVICE_USAGE_CALL_ALL = 12, 270 } OH_AudioDevice_Usage; 271 272 /** 273 * @brief Declaring the audio device descriptor. 274 * The instance is used to get more audio device detail attributes. 275 * 276 * @since 12 277 */ 278 typedef struct OH_AudioDeviceDescriptor OH_AudioDeviceDescriptor; 279 280 /** 281 * @brief Declaring the audio device descriptor array. 282 * 283 * @since 12 284 */ 285 typedef struct OH_AudioDeviceDescriptorArray { 286 /** 287 * @brief Audio device descriptor array size. 288 */ 289 uint32_t size; 290 291 /** 292 * @brief Audio device descriptor array. 293 */ 294 OH_AudioDeviceDescriptor **descriptors; 295 } OH_AudioDeviceDescriptorArray; 296 297 /** 298 * @brief Declaring the audio device blocked status. By default, the audio device is considered as unbloked. 299 * 300 * @since 13 301 */ 302 typedef enum { 303 /** 304 * @brief Audio device is unblocked. 305 * 306 * @since 13 307 */ 308 AUDIO_DEVICE_UNBLOCKED = 0, 309 310 /** 311 * @brief Audio Device is blocked. 312 * 313 * @since 13 314 */ 315 AUDIO_DEVICE_BLOCKED = 1, 316 } OH_AudioDevice_BlockStatus; 317 318 /** 319 * @brief Query the device role of the target audio device descriptor. 320 * 321 * @param audioDeviceDescriptor reference returned by {@link OH_AudioRoutingManager_GetDevices} or 322 * {@link OH_AudioRouterManager_OnDeviceChangedCallback}. 323 * @param deviceRole the pointer {@link OH_AudioDevice_DeviceRole} variable that will be set the device role value. 324 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}. 325 * @since 12 326 */ 327 OH_AudioCommon_Result OH_AudioDeviceDescriptor_GetDeviceRole(OH_AudioDeviceDescriptor *audioDeviceDescriptor, 328 OH_AudioDevice_Role *deviceRole); 329 330 /** 331 * @brief Query the device type of the target audio device descriptor. 332 * 333 * @param audioDeviceDescriptor reference returned by {@link OH_AudioRoutingManager_GetDevices} or 334 * {@link OH_AudioRouterManager_OnDeviceChangedCallback}. 335 * @param deviceType the pointer {@link OH_AudioDevice_DeviceType} 336 * pointer variable that will be set the device type value. 337 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}. 338 * @since 12 339 */ 340 OH_AudioCommon_Result OH_AudioDeviceDescriptor_GetDeviceType(OH_AudioDeviceDescriptor *audioDeviceDescriptor, 341 OH_AudioDevice_Type *deviceType); 342 343 /** 344 * @brief Query the device id of the target audio device descriptor. 345 * 346 * @param audioDeviceDescriptor reference returned by {@link OH_AudioRoutingManager_GetDevices} or 347 * {@link OH_AudioRouterManager_OnDeviceChangedCallback}. 348 * @param id pointer variable that will be set the device id value. 349 * @return {@link #AUDIODEVICE_SUCCESS} or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}. 350 * @since 12 351 */ 352 OH_AudioCommon_Result OH_AudioDeviceDescriptor_GetDeviceId(OH_AudioDeviceDescriptor *audioDeviceDescriptor, 353 uint32_t *id); 354 355 /** 356 * @brief Query the device name of the target audio device descriptor. 357 * 358 * @param audioDeviceDescriptor reference returned by {@link OH_AudioRoutingManager_GetDevices} or 359 * {@link OH_AudioRouterManager_OnDeviceChangedCallback}. 360 * @param name pointer variable that will be set the device name value. 361 * Do not release the name pointer separately 362 * instead call {@link OH_AudioRoutingManager_ReleaseDevices} to relase all the DeviceDescriptor array 363 * when it is no use anymore. 364 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}. 365 * @since 12 366 */ 367 OH_AudioCommon_Result OH_AudioDeviceDescriptor_GetDeviceName(OH_AudioDeviceDescriptor *audioDeviceDescriptor, 368 char **name); 369 370 /** 371 * @brief Query the device address of the target audio device descriptor. 372 * 373 * @param audioDeviceDescriptor reference returned by {@link OH_AudioRoutingManager_GetDevices} or 374 * {@link OH_AudioRouterManager_OnDeviceChangedCallback}. 375 * @param address pointer variable that will be set the device address value. 376 * Do not release the address pointer separately 377 * instead call {@link OH_AudioRoutingManager_ReleaseDevices} to relase all the DeviceDescriptor array 378 * when it is no use anymore. 379 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}. 380 * @since 12 381 */ 382 OH_AudioCommon_Result OH_AudioDeviceDescriptor_GetDeviceAddress(OH_AudioDeviceDescriptor *audioDeviceDescriptor, 383 char **address); 384 385 /** 386 * @brief Query the sample rate array of the target audio device descriptor. 387 * 388 * @param audioDeviceDescriptor reference returned by {@link OH_AudioRoutingManager_GetDevices} or 389 * {@link OH_AudioRouterManager_OnDeviceChangedCallback}. 390 * @param sampleRates array pointer variable that will be set the sample rate array value. 391 * Do not release the sampleRates pointer separately 392 * instead call {@link OH_AudioRoutingManager_ReleaseDevices} to relase all the DeviceDescriptor array 393 * when it is no use anymore. 394 * @param size pointer variable that will be set the sample rate size value. 395 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}. 396 * @since 12 397 */ 398 OH_AudioCommon_Result OH_AudioDeviceDescriptor_GetDeviceSampleRates(OH_AudioDeviceDescriptor *audioDeviceDescriptor, 399 uint32_t **sampleRates, uint32_t *size); 400 401 /** 402 * @brief Query the device channel count array of the target audio device descriptor. 403 * 404 * @param audioDeviceDescriptor reference returned by {@link OH_AudioRoutingManager_GetDevices} or 405 * {@link OH_AudioRouterManager_OnDeviceChangedCallback}. 406 * @param channelCounts array pointer variable that will be set the channel count array value. 407 * Do not release the channelCounts pointer separately 408 * instead call {@link OH_AudioRoutingManager_ReleaseDevices} to relase all the DeviceDescriptor array 409 * when it is no use anymore. 410 * @param size pointer variable that will be set the channel count size value. 411 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}. 412 * @since 12 413 */ 414 OH_AudioCommon_Result OH_AudioDeviceDescriptor_GetDeviceChannelCounts(OH_AudioDeviceDescriptor *audioDeviceDescriptor, 415 uint32_t **channelCounts, uint32_t *size); 416 417 /** 418 * @brief Query the display name of the target audio device descriptor. 419 * 420 * @param audioDeviceDescriptor reference returned by {@link OH_AudioRoutingManager_GetDevices} or 421 * {@link OH_AudioRouterManager_OnDeviceChangedCallback}. 422 * @param displayName pointer variable that will be set the display name value. 423 * Do not release the displayName pointer separately 424 * instead call {@link OH_AudioRoutingManager_ReleaseDevices} to relase all the DeviceDescriptor array 425 * when it is no use anymore. 426 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}. 427 * @since 12 428 */ 429 OH_AudioCommon_Result OH_AudioDeviceDescriptor_GetDeviceDisplayName(OH_AudioDeviceDescriptor *audioDeviceDescriptor, 430 char **displayName); 431 432 /** 433 * @brief Query the encoding type array of the target audio device descriptor. 434 * 435 * @param audioDeviceDescriptor reference returned by {@link OH_AudioRoutingManager_GetDevices} or 436 * {@link OH_AudioRouterManager_OnDeviceChangedCallback}. 437 * @param encodingTypes the {@link OH_AudioStream_EncodingType} 438 * Do not release the encodingTypes pointer separately 439 * instead call {@link OH_AudioRoutingManager_ReleaseDevices} to relase all the DeviceDescriptor array 440 * when it is no use anymore. 441 * @param size pointer variable that will be set the encoding type size value. 442 * @return {@link #AUDIOCOMMON_RESULT_SUCCESS} or {@link #AUDIOCOMMON_RESULT_ERROR_INVALID_PARAM}. 443 * @since 12 444 */ 445 OH_AudioCommon_Result OH_AudioDeviceDescriptor_GetDeviceEncodingTypes(OH_AudioDeviceDescriptor *audioDeviceDescriptor, 446 OH_AudioStream_EncodingType **encodingTypes, uint32_t *size); 447 #ifdef __cplusplus 448 } 449 #endif 450 /** @} */ 451 #endif // NATIVE_AUDIO_DEVICE_BASE_H