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