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