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