tizen-audio.h

   1 /*
   2  * audio-hal
   3  *
   4  * Copyright (c) 2015 - 2016 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  * http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  */
  19
  20 #ifndef footizenaudiofoo
  21 #define footizenaudiofoo
  22
  23 #include <stdint.h>
  24 #include <hal/hal-audio-interface.h>
  25
  26 /**
  27  * @file tizen-audio.h
  28  * @brief This file contains the Audio Hardware Abstraction Layer Interfaces.
  29  */
  30
  31 /**
  32  * @addtogroup TIZEN_AUDIO_HAL_MODULE
  33  * @{
  34  */
  35
  36 /**
  37  * @brief Initializes audio hal.
  38  * @since_tizen 3.0
  39  * @param[out] audio_handle The audio hal handle
  40  *
  41  * @return @c 0 on success,
  42  *         otherwise a negative error value
  43  * @retval #AUDIO_RET_OK Success
  44  * @see audio_deinit()
  45  */
  46 audio_return_e audio_init(void **audio_handle);
  47
  48 /**
  49  * @brief De-initializes audio hal.
  50  * @since_tizen 3.0
  51  * @param[in] audio_handle The audio hal handle
  52  *
  53  * @return @c 0 on success,
  54  *         otherwise a negative error value
  55  * @retval #AUDIO_RET_OK Success
  56  * @see audio_init()
  57  */
  58 audio_return_e audio_deinit(void *audio_handle);
  59
  60 /**
  61  * @brief Gets the maximum volume level supported for a particular volume information.
  62  * @since_tizen 3.0
  63  * @param[in] audio_handle The audio hal handle
  64  * @param[in] info The audio volume information
  65  * @param[out] level The maximum volume level
  66  *
  67  * @return @c 0 on success,
  68  *         otherwise a negative error value
  69  * @retval #AUDIO_RET_OK Success
  70  * @see audio_set_volume_level()
  71  * @see audio_get_volume_level()
  72  * @see audio_get_volume_value()
  73  */
  74 audio_return_e audio_get_volume_level_max(void *audio_handle, audio_volume_info_s *info, uint32_t *level);
  75
  76 /**
  77  * @brief Gets the volume level specified for a particular volume information.
  78  * @since_tizen 3.0
  79  * @param[in] audio_handle The audio hal handle
  80  * @param[in] info The audio volume information
  81  * @param[out] level The current volume level
  82  *
  83  * @return @c 0 on success,
  84  *         otherwise a negative error value
  85  * @retval #AUDIO_RET_OK Success
  86  * @see audio_set_volume_level()
  87  * @see audio_get_volume_level_max()
  88  * @see audio_get_volume_value()
  89  */
  90 audio_return_e audio_get_volume_level(void *audio_handle, audio_volume_info_s *info, uint32_t *level);
  91
  92 /**
  93  * @brief Sets the volume level specified for a particular volume information.
  94  * @since_tizen 3.0
  95  * @param[in] audio_handle The audio hal handle
  96  * @param[in] info The audio volume information
  97  * @param[in] level The volume level to be set
  98  *
  99  * @return @c 0 on success,
 100  *         otherwise a negative error value
 101  * @retval #AUDIO_RET_OK Success
 102  * @see audio_get_volume_level()
 103  * @see audio_get_volume_level_max()
 104  * @see audio_get_volume_value()
 105  */
 106 audio_return_e audio_set_volume_level(void *audio_handle, audio_volume_info_s *info, uint32_t level);
 107
 108 /**
 109  * @brief Gets the volume value specified for a particular volume information and level.
 110  * @since_tizen 3.0
 111  * @param[in] audio_handle The audio hal handle
 112  * @param[in] info The audio volume information
 113  * @param[in] level The volume level
 114  * @param[out] value The volume value (range is from 0.0 to 1.0 inclusive, 1.0 = 100%)
 115  *
 116  * @return @c 0 on success,
 117  *         otherwise a negative error value
 118  * @retval #AUDIO_RET_OK Success
 119  * @see audio_set_volume_level()
 120  * @see audio_get_volume_level()
 121  * @see audio_get_volume_level_max()
 122  */
 123 audio_return_e audio_get_volume_value(void *audio_handle, audio_volume_info_s *info, uint32_t level, double *value);
 124
 125 /**
 126  * @brief Gets the volume mute specified for a particular volume information.
 127  * @since_tizen 3.0
 128  * @param[in] audio_handle The audio hal handle
 129  * @param[in] info The audio volume information
 130  * @param[out] mute The volume mute state : (@c 0 = unmute, @c 1 = mute)
 131  *
 132  * @return @c 0 on success,
 133  *         otherwise a negative error value
 134  * @retval #AUDIO_RET_OK Success
 135  * @see audio_set_volume_mute()
 136  */
 137 audio_return_e audio_get_volume_mute(void *audio_handle, audio_volume_info_s *info, uint32_t *mute);
 138
 139 /**
 140  * @brief Sets the volume mute specified for a particular volume information.
 141  * @since_tizen 3.0
 142  * @param[in] audio_handle The audio hal handle
 143  * @param[in] info The audio volume information
 144  * @param[in] mute The volume mute state to be set : (@c 0 = unmute, @c 1 = mute)
 145  *
 146  * @return @c 0 on success,
 147  *         otherwise a negative error value
 148  * @retval #AUDIO_RET_OK Success
 149  * @see audio_get_volume_mute()
 150  */
 151 audio_return_e audio_set_volume_mute(void *audio_handle, audio_volume_info_s *info, uint32_t mute);
 152
 153 /**
 154  * @brief Sets the volume ratio specified for a particular volume information. (optional)
 155  * @since_tizen 5.5
 156  * @param[in] audio_handle The audio hal handle
 157  * @param[in] info The audio volume information
 158  * @param[in] ratio The volume ratio to be set (Min.:0.0 ~ Max.:1.0, default:1.0)
 159  *
 160  * @return @c 0 on success,
 161  *         otherwise a negative error value
 162  * @retval #AUDIO_RET_OK Success
 163  */
 164 audio_return_e audio_set_volume_ratio(void *audio_handle, audio_stream_info_s *info, double ratio);
 165
 166 /**
 167  * @brief Gets notified when a ducking is activated and deactivated.
 168  * @since_tizen 5.5
 169  * @param[in] audio_handle The audio hal handle
 170  * @param[in] info The ducking information including target role, duration and ratio
 171  * @param[in] is_activated The activation state (@c true = activated, @c false = deactivated)
 172  *
 173  * @remarks This information can be used for volume controls.
 174  *
 175  * @return @c 0 on success,
 176  *         otherwise a negative error value
 177  * @retval #AUDIO_RET_OK Success
 178  */
 179 audio_return_e audio_notify_ducking_activation_changed(void *audio_handle, audio_ducking_info_s *info, uint32_t is_activated);
 180
 181 /**
 182  * @brief Updates the audio routing according to audio route information.
 183  * @since_tizen 3.0
 184  * @param[in] audio_handle The audio hal handle
 185  * @param[in] info The audio route information including role and devices
 186  *
 187  * @return @c 0 on success,
 188  *         otherwise a negative error value
 189  * @retval #AUDIO_RET_OK Success
 190  * @see audio_update_route_option()
 191  */
 192 audio_return_e audio_update_route(void *audio_handle, audio_route_info_s *info);
 193
 194 /**
 195  * @brief Updates audio routing option according to audio route option.
 196  * @since_tizen 3.0
 197  * @param[in] audio_handle The audio hal handle
 198  * @param[in] option The option that can be used for audio routing including role, name and value
 199  *
 200  * @remarks This option can be used for audio routing.\n
 201  * It is recommended to apply this option for routing per each role.
 202  *
 203  * @return @c 0 on success,
 204  *         otherwise a negative error value
 205  * @retval #AUDIO_RET_OK Success
 206  * @see audio_update_route()
 207  */
 208 audio_return_e audio_update_route_option(void *audio_handle, audio_route_option_s *option);
 209
 210 /**
 211  * @brief Gets notified when a stream is connected and disconnected.
 212  * @since_tizen 3.0
 213  * @param[in] audio_handle The audio hal handle
 214  * @param[in] info The stream information including role, direction, index
 215  * @param[in] is_connected The connection state of this stream (@c true = connected, @c false = disconnected)
 216  *
 217  * @remarks This information can be used for audio routing, volume controls and so on.
 218  *
 219  * @return @c 0 on success,
 220  *         otherwise a negative error value
 221  * @retval #AUDIO_RET_OK Success
 222  */
 223 audio_return_e audio_notify_stream_connection_changed(void *audio_handle, audio_stream_info_s *info, uint32_t is_connected);
 224
 225 /**
 226  * @brief Opens a PCM device.
 227  * @since_tizen 3.0
 228  * @param[in] audio_handle The audio hal handle
 229  * @param[in] card The card of PCM
 230  * @param[in] device The device of PCM
 231  * @param[in] direction The direction of PCM
 232  * @param[in] sample_spec The sample specification
 233  * @param[in] period_size The period size
 234  * @param[in] periods The periods
 235  * @param[out] pcm_handle The PCM handle
 236  *
 237  * @return @c 0 on success,
 238  *         otherwise a negative error value
 239  * @retval #AUDIO_RET_OK Success
 240  * @see audio_pcm_close()
 241  */
 242 audio_return_e audio_pcm_open(void *audio_handle, const char *card, const char *device, uint32_t direction, void *sample_spec, uint32_t period_size, uint32_t periods, void **pcm_handle);
 243
 244 /**
 245  * @brief Starts a PCM device.
 246  * @since_tizen 3.0
 247  * @param[in] audio_handle The audio hal handle
 248  * @param[in] pcm_handle The PCM handle to be started
 249  *
 250  * @return @c 0 on success,
 251  *         otherwise a negative error value
 252  * @retval #AUDIO_RET_OK Success
 253  * @see audio_pcm_avail()
 254  * @see audio_pcm_write()
 255  * @see audio_pcm_read()
 256  * @see audio_pcm_stop()
 257  * @see audio_pcm_recover()
 258  */
 259 audio_return_e audio_pcm_start(void *audio_handle, void *pcm_handle);
 260
 261 /**
 262  * @brief Stops a PCM device.
 263  * @since_tizen 3.0
 264  * @param[in] audio_handle The audio hal handle
 265  * @param[in] pcm_handle The PCM handle to be stopped
 266  *
 267  * @return @c 0 on success,
 268  *         otherwise a negative error value
 269  * @retval #AUDIO_RET_OK Success
 270  * @see audio_pcm_start()
 271  */
 272 audio_return_e audio_pcm_stop(void *audio_handle, void *pcm_handle);
 273
 274 /**
 275  * @brief Closes a PCM device.
 276  * @since_tizen 3.0
 277  * @param[in] audio_handle The audio hal handle
 278  * @param[in] pcm_handle The PCM handle to be closed
 279  *
 280  * @return @c 0 on success,
 281  *         otherwise a negative error value
 282  * @retval #AUDIO_RET_OK Success
 283  * @see audio_pcm_open()
 284  */
 285 audio_return_e audio_pcm_close(void *audio_handle, void *pcm_handle);
 286
 287 /**
 288  * @brief Gets available number of frames.
 289  * @since_tizen 3.0
 290  * @param[in] audio_handle The audio hal handle
 291  * @param[in] pcm_handle The PCM handle
 292  * @param[out] avail The available number of frames
 293  *
 294  * @return @c 0 on success,
 295  *         otherwise a negative error value
 296  * @retval #AUDIO_RET_OK Success
 297  * @see audio_pcm_write()
 298  * @see audio_pcm_read()
 299  */
 300 audio_return_e audio_pcm_avail(void *audio_handle, void *pcm_handle, uint32_t *avail);
 301
 302 /**
 303  * @brief Writes frames to a PCM device.
 304  * @since_tizen 3.0
 305  * @param[in] audio_handle The audio hal handle
 306  * @param[in] pcm_handle The PCM handle
 307  * @param[in] buffer The buffer containing frames
 308  * @param[in] frames The number of frames to be written
 309  *
 310  * @return @c 0 on success,
 311  *         otherwise a negative error value
 312  * @retval #AUDIO_RET_OK Success
 313  * @see audio_pcm_avail()
 314  * @see audio_pcm_recover()
 315  */
 316 audio_return_e audio_pcm_write(void *audio_handle, void *pcm_handle, const void *buffer, uint32_t frames);
 317
 318 /**
 319  * @brief Reads frames from a PCM device.
 320  * @since_tizen 3.0
 321  * @param[in] audio_handle The audio hal handle
 322  * @param[in] pcm_handle The PCM handle
 323  * @param[out] buffer The buffer containing frames
 324  * @param[in] frames The number of frames to be read
 325  *
 326  * @return @c 0 on success,
 327  *         otherwise a negative error value
 328  * @retval #AUDIO_RET_OK Success
 329  * @see audio_pcm_avail()
 330  * @see audio_pcm_recover()
 331  */
 332 audio_return_e audio_pcm_read(void *audio_handle, void *pcm_handle, void *buffer, uint32_t frames);
 333
 334 /**
 335  * @brief Gets poll descriptor for a PCM handle.
 336  * @since_tizen 3.0
 337  * @param[in] audio_handle The audio hal handle
 338  * @param[in] pcm_handle The PCM handle
 339  * @param[out] fd The poll descriptor
 340  *
 341  * @return @c 0 on success,
 342  *         otherwise a negative error value
 343  * @retval #AUDIO_RET_OK Success
 344  * @see audio_pcm_open()
 345  * @see audio_pcm_recover()
 346  */
 347 audio_return_e audio_pcm_get_fd(void *audio_handle, void *pcm_handle, int *fd);
 348
 349 /**
 350  * @brief Recovers the PCM state.
 351  * @since_tizen 3.0
 352  * @param[in] audio_handle The audio hal handle
 353  * @param[in] pcm_handle The PCM handle
 354  * @param[in] revents The returned event from pollfd
 355  *
 356  * @return @c 0 on success,
 357  *         otherwise a negative error value
 358  * @retval #AUDIO_RET_OK Success
 359  * @see audio_pcm_start()
 360  * @see audio_pcm_write()
 361  * @see audio_pcm_read()
 362  * @see audio_pcm_get_fd()
 363  */
 364 audio_return_e audio_pcm_recover(void *audio_handle, void *pcm_handle, int revents);
 365
 366 /**
 367  * @brief Gets parameters of a PCM device.
 368  * @since_tizen 3.0
 369  * @param[in] audio_handle The audio hal handle
 370  * @param[in] pcm_handle The PCM handle
 371  * @param[in] direction The direction of PCM
 372  * @param[out] sample_spec The sample specification
 373  * @param[out] period_size The period size
 374  * @param[out] periods The periods
 375  *
 376  * @return @c 0 on success,
 377  *         otherwise a negative error value
 378  * @retval #AUDIO_RET_OK Success
 379  * @see audio_pcm_set_params()
 380  */
 381 audio_return_e audio_pcm_get_params(void *audio_handle, void *pcm_handle, uint32_t direction, void *sample_spec, uint32_t *period_size, uint32_t *periods);
 382
 383 /**
 384  * @brief Sets hardware and software parameters of a PCM device.
 385  * @since_tizen 3.0
 386  * @param[in] audio_handle The audio hal handle
 387  * @param[in] pcm_handle The PCM handle
 388  * @param[in] direction The direction of PCM
 389  * @param[in] sample_spec The sample specification
 390  * @param[in] period_size The period size
 391  * @param[in] periods The periods
 392  *
 393  * @return @c 0 on success,
 394  *         otherwise a negative error value
 395  * @retval #AUDIO_RET_OK Success
 396  * @see audio_pcm_set_params()
 397  */
 398 audio_return_e audio_pcm_set_params(void *audio_handle, void *pcm_handle, uint32_t direction, void *sample_spec, uint32_t period_size, uint32_t periods);
 399
 400 /**
 401  * @brief Adds the message callback function.
 402  * @since_tizen 3.0
 403  * @param[in] audio_handle The audio hal handle
 404  * @param[in] message_cb The message callback function
 405  * @param[in] user_data The user data passed to the callback function
 406  *
 407  * @see message_cb()
 408  * @see audio_remove_message_cb()
 409  */
 410 audio_return_e audio_add_message_cb(void *audio_handle, message_cb callback, void *user_data);
 411
 412 /**
 413  * @brief Removes the message callback function.
 414  * @since_tizen 3.0
 415  * @param[in] audio_handle The audio hal handle
 416  * @param[in] message_cb The message callback function to be removed
 417  *
 418  * @see message_cb()
 419  * @see audio_add_message_cb()
 420  */
 421 audio_return_e audio_remove_message_cb(void *audio_handle, message_cb callback);
 422
 423 /**
 424 * @}
 425 */
 426
 427 /**
 428 * @}
 429 */
 430
 431 #endif