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
  25 /**
  26  * @file tizen-audio.h
  27  * @brief This file contains the Audio Hardware Abstraction Layer Interfaces.
  28  */
  29
  30 /**
  31  * @addtogroup TIZEN_AUDIO_HAL_MODULE
  32  * @{
  33  */
  34
  35 /**
  36  * @brief Enumeration for return codes.
  37  * @since_tizen 3.0
  38  */
  39 typedef enum audio_return {
  40     AUDIO_RET_OK                        = 0,
  41     AUDIO_ERR_UNDEFINED                 = (int32_t)0x80001000,
  42     AUDIO_ERR_RESOURCE                  = (int32_t)0x80001001,
  43     AUDIO_ERR_PARAMETER                 = (int32_t)0x80001002,
  44     AUDIO_ERR_IOCTL                     = (int32_t)0x80001003,
  45     AUDIO_ERR_INVALID_STATE             = (int32_t)0x80001004,
  46     AUDIO_ERR_INTERNAL                  = (int32_t)0x80001005,
  47     /* add new enemerator here */
  48     AUDIO_ERR_NOT_IMPLEMENTED           = (int32_t)0x80001100,
  49 } audio_return_t ;
  50
  51 /**
  52  * @brief Enumeration for audio direction.
  53  * @since_tizen 3.0
  54  */
  55 typedef enum audio_direction {
  56     AUDIO_DIRECTION_IN,                 /**< Capture */
  57     AUDIO_DIRECTION_OUT,                /**< Playback */
  58 } audio_direction_t;
  59
  60 /**
  61  * @brief Device information including type, direction and id.
  62  * @since_tizen 3.0
  63  */
  64 typedef struct device_info {
  65     const char *type;
  66     uint32_t direction;
  67     uint32_t id;
  68 } device_info_t;
  69
  70 /**
  71  * @brief Volume information including type, gain and direction.
  72  * @since_tizen 3.0
  73  */
  74 typedef struct audio_volume_info {
  75     const char *type;
  76     const char *gain;
  77     uint32_t direction;
  78 } audio_volume_info_t ;
  79
  80 /**
  81  * @brief Route information including role and device.
  82  * @since_tizen 3.0
  83  */
  84 typedef struct audio_route_info {
  85     const char *role;
  86     device_info_t *device_infos;
  87     uint32_t num_of_devices;
  88 } audio_route_info_t;
  89
  90 /**
  91  * @brief Route option including role, name and value.
  92  * @since_tizen 3.0
  93  */
  94 typedef struct audio_route_option {
  95     const char *role;
  96     const char *name;
  97     int32_t value;
  98 } audio_route_option_t;
  99
 100 /**
 101  * @brief Stream information including role, direction and index.
 102  * @since_tizen 3.0
 103  */
 104 typedef struct audio_stream_info {
 105     const char *role;
 106     uint32_t direction;
 107     uint32_t idx;
 108 } audio_stream_info_t ;
 109
 110 /**
 111  * @brief Called when audio hal implementation needs to send a message.
 112  * @since_tizen 3.0
 113  * @param[in] name The message name
 114  * @param[in] value The message value
 115  * @param[in] user_data The user data passed from the callback registration function
 116  *
 117  * @see audio_add_message_cb()
 118  * @see audio_remove_message_cb()
 119  */
 120 typedef void (*message_cb)(const char *name, int value, void *user_data);
 121
 122 /* Overall */
 123 typedef struct audio_interface {
 124     /* Initialization & de-initialization */
 125     audio_return_t (*init)(void **audio_handle);
 126     audio_return_t (*deinit)(void *audio_handle);
 127     /* Volume */
 128     audio_return_t (*get_volume_level_max)(void *audio_handle, audio_volume_info_t *info, uint32_t *level);
 129     audio_return_t (*get_volume_level)(void *audio_handle, audio_volume_info_t *info, uint32_t *level);
 130     audio_return_t (*set_volume_level)(void *audio_handle, audio_volume_info_t *info, uint32_t level);
 131     audio_return_t (*get_volume_value)(void *audio_handle, audio_volume_info_t *info, uint32_t level, double *value);
 132     audio_return_t (*get_volume_mute)(void *audio_handle, audio_volume_info_t *info, uint32_t *mute);
 133     audio_return_t (*set_volume_mute)(void *audio_handle, audio_volume_info_t *info, uint32_t mute);
 134     audio_return_t (*set_volume_ratio)(void *audio_handle, audio_stream_info_t *info, double ratio);
 135     /* Routing */
 136     audio_return_t (*update_route)(void *audio_handle, audio_route_info_t *info);
 137     audio_return_t (*update_route_option)(void *audio_handle, audio_route_option_t *option);
 138     /* Stream */
 139     audio_return_t (*notify_stream_connection_changed)(void *audio_handle, audio_stream_info_t *info, uint32_t is_connected);
 140     /* PCM */
 141     audio_return_t (*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);
 142     audio_return_t (*pcm_start)(void *audio_handle, void *pcm_handle);
 143     audio_return_t (*pcm_stop)(void *audio_handle, void *pcm_handle);
 144     audio_return_t (*pcm_close)(void *audio_handle, void *pcm_handle);
 145     audio_return_t (*pcm_avail)(void *audio_handle, void *pcm_handle, uint32_t *avail);
 146     audio_return_t (*pcm_write)(void *audio_handle, void *pcm_handle, const void *buffer, uint32_t frames);
 147     audio_return_t (*pcm_read)(void *audio_handle, void *pcm_handle, void *buffer, uint32_t frames);
 148     audio_return_t (*pcm_get_fd)(void *audio_handle, void *pcm_handle, int *fd);
 149     audio_return_t (*pcm_recover)(void *audio_handle, void *pcm_handle, int revents);
 150     audio_return_t (*pcm_get_params)(void *audio_handle, void *pcm_handle, uint32_t direction, void **sample_spec, uint32_t *period_size, uint32_t *periods);
 151     audio_return_t (*pcm_set_params)(void *audio_handle, void *pcm_handle, uint32_t direction, void *sample_spec, uint32_t period_size, uint32_t periods);
 152     /* Message callback */
 153     audio_return_t (*add_message_cb)(void *audio_handle, message_cb callback, void *user_data);
 154     audio_return_t (*remove_message_cb)(void *audio_handle, message_cb callback);
 155 } audio_interface_t;
 156
 157 /**
 158  * @brief Initializes audio hal.
 159  * @since_tizen 3.0
 160  * @param[out] audio_handle The audio hal handle
 161  *
 162  * @return @c 0 on success,
 163  *         otherwise a negative error value
 164  * @retval #AUDIO_RET_OK Success
 165  * @see audio_deinit()
 166  */
 167 audio_return_t audio_init(void **audio_handle);
 168
 169 /**
 170  * @brief De-initializes audio hal.
 171  * @since_tizen 3.0
 172  * @param[in] audio_handle The audio hal handle
 173  *
 174  * @return @c 0 on success,
 175  *         otherwise a negative error value
 176  * @retval #AUDIO_RET_OK Success
 177  * @see audio_init()
 178  */
 179 audio_return_t audio_deinit(void *audio_handle);
 180
 181 /**
 182  * @brief Gets the maximum volume level supported for a particular volume information.
 183  * @since_tizen 3.0
 184  * @param[in] audio_handle The audio hal handle
 185  * @param[in] info The audio volume information
 186  * @param[out] level The maximum volume level
 187  *
 188  * @return @c 0 on success,
 189  *         otherwise a negative error value
 190  * @retval #AUDIO_RET_OK Success
 191  * @see audio_set_volume_level()
 192  * @see audio_get_volume_level()
 193  * @see audio_get_volume_value()
 194  */
 195 audio_return_t audio_get_volume_level_max(void *audio_handle, audio_volume_info_t *info, uint32_t *level);
 196
 197 /**
 198  * @brief Gets the volume level specified for a particular volume information.
 199  * @since_tizen 3.0
 200  * @param[in] audio_handle The audio hal handle
 201  * @param[in] info The audio volume information
 202  * @param[out] level The current volume level
 203  *
 204  * @return @c 0 on success,
 205  *         otherwise a negative error value
 206  * @retval #AUDIO_RET_OK Success
 207  * @see audio_set_volume_level()
 208  * @see audio_get_volume_level_max()
 209  * @see audio_get_volume_value()
 210  */
 211 audio_return_t audio_get_volume_level(void *audio_handle, audio_volume_info_t *info, uint32_t *level);
 212
 213 /**
 214  * @brief Sets the volume level specified for a particular volume information.
 215  * @since_tizen 3.0
 216  * @param[in] audio_handle The audio hal handle
 217  * @param[in] info The audio volume information
 218  * @param[in] level The volume level to be set
 219  *
 220  * @return @c 0 on success,
 221  *         otherwise a negative error value
 222  * @retval #AUDIO_RET_OK Success
 223  * @see audio_get_volume_level()
 224  * @see audio_get_volume_level_max()
 225  * @see audio_get_volume_value()
 226  */
 227 audio_return_t audio_set_volume_level(void *audio_handle, audio_volume_info_t *info, uint32_t level);
 228
 229 /**
 230  * @brief Gets the volume value specified for a particular volume information and level.
 231  * @since_tizen 3.0
 232  * @param[in] audio_handle The audio hal handle
 233  * @param[in] info The audio volume information
 234  * @param[in] level The volume level
 235  * @param[out] value The volume value (range is from 0.0 to 1.0 inclusive, 1.0 = 100%)
 236  *
 237  * @return @c 0 on success,
 238  *         otherwise a negative error value
 239  * @retval #AUDIO_RET_OK Success
 240  * @see audio_set_volume_level()
 241  * @see audio_get_volume_level()
 242  * @see audio_get_volume_level_max()
 243  */
 244 audio_return_t audio_get_volume_value(void *audio_handle, audio_volume_info_t *info, uint32_t level, double *value);
 245
 246 /**
 247  * @brief Gets the volume mute specified for a particular volume information.
 248  * @since_tizen 3.0
 249  * @param[in] audio_handle The audio hal handle
 250  * @param[in] info The audio volume information
 251  * @param[out] mute The volume mute state : (@c 0 = unmute, @c 1 = mute)
 252  *
 253  * @return @c 0 on success,
 254  *         otherwise a negative error value
 255  * @retval #AUDIO_RET_OK Success
 256  * @see audio_set_volume_mute()
 257  */
 258 audio_return_t audio_get_volume_mute(void *audio_handle, audio_volume_info_t *info, uint32_t *mute);
 259
 260 /**
 261  * @brief Sets the volume mute specified for a particular volume information.
 262  * @since_tizen 3.0
 263  * @param[in] audio_handle The audio hal handle
 264  * @param[in] info The audio volume information
 265  * @param[in] mute The volume mute state to be set : (@c 0 = unmute, @c 1 = mute)
 266  *
 267  * @return @c 0 on success,
 268  *         otherwise a negative error value
 269  * @retval #AUDIO_RET_OK Success
 270  * @see audio_get_volume_mute()
 271  */
 272 audio_return_t audio_set_volume_mute(void *audio_handle, audio_volume_info_t *info, uint32_t mute);
 273
 274 /**
 275  * @brief Updates the audio routing according to audio route information.
 276  * @since_tizen 3.0
 277  * @param[in] audio_handle The audio hal handle
 278  * @param[in] info The audio route information including role and devices
 279  *
 280  * @return @c 0 on success,
 281  *         otherwise a negative error value
 282  * @retval #AUDIO_RET_OK Success
 283  * @see audio_update_route_option()
 284  */
 285 audio_return_t audio_update_route(void *audio_handle, audio_route_info_t *info);
 286
 287 /**
 288  * @brief Updates audio routing option according to audio route option.
 289  * @since_tizen 3.0
 290  * @param[in] audio_handle The audio hal handle
 291  * @param[in] option The option that can be used for audio routing including role, name and value
 292  *
 293  * @remarks This option can be used for audio routing.\n
 294  * It is recommended to apply this option for routing per each role.
 295  *
 296  * @return @c 0 on success,
 297  *         otherwise a negative error value
 298  * @retval #AUDIO_RET_OK Success
 299  * @see audio_update_route()
 300  */
 301 audio_return_t audio_update_route_option(void *audio_handle, audio_route_option_t *option);
 302
 303 /**
 304  * @brief Gets notified when a stream is connected and disconnected.
 305  * @since_tizen 3.0
 306  * @param[in] audio_handle The audio hal handle
 307  * @param[in] info The stream information including role, direction, index
 308  * @param[in] is_connected The connection state of this stream (@c true = connected, @c false = disconnected)
 309  *
 310  * @remarks This information can be used for audio routing, volume controls and so on.
 311  *
 312  * @return @c 0 on success,
 313  *         otherwise a negative error value
 314  * @retval #AUDIO_RET_OK Success
 315  */
 316 audio_return_t audio_notify_stream_connection_changed(void *audio_handle, audio_stream_info_t *info, uint32_t is_connected);
 317
 318 /**
 319  * @brief Opens a PCM device.
 320  * @since_tizen 3.0
 321  * @param[in] audio_handle The audio hal handle
 322  * @param[in] card The card of PCM
 323  * @param[in] device The device of PCM
 324  * @param[in] direction The direction of PCM
 325  * @param[in] sample_spec The sample specification
 326  * @param[in] period_size The period size
 327  * @param[in] periods The periods
 328  * @param[out] pcm_handle The PCM handle
 329  *
 330  * @return @c 0 on success,
 331  *         otherwise a negative error value
 332  * @retval #AUDIO_RET_OK Success
 333  * @see audio_pcm_close()
 334  */
 335 audio_return_t 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);
 336
 337 /**
 338  * @brief Starts a PCM device.
 339  * @since_tizen 3.0
 340  * @param[in] audio_handle The audio hal handle
 341  * @param[in] pcm_handle The PCM handle to be started
 342  *
 343  * @return @c 0 on success,
 344  *         otherwise a negative error value
 345  * @retval #AUDIO_RET_OK Success
 346  * @see audio_pcm_avail()
 347  * @see audio_pcm_write()
 348  * @see audio_pcm_read()
 349  * @see audio_pcm_stop()
 350  * @see audio_pcm_recover()
 351  */
 352 audio_return_t audio_pcm_start(void *audio_handle, void *pcm_handle);
 353
 354 /**
 355  * @brief Stops a PCM device.
 356  * @since_tizen 3.0
 357  * @param[in] audio_handle The audio hal handle
 358  * @param[in] pcm_handle The PCM handle to be stopped
 359  *
 360  * @return @c 0 on success,
 361  *         otherwise a negative error value
 362  * @retval #AUDIO_RET_OK Success
 363  * @see audio_pcm_start()
 364  */
 365 audio_return_t audio_pcm_stop(void *audio_handle, void *pcm_handle);
 366
 367 /**
 368  * @brief Closes a PCM device.
 369  * @since_tizen 3.0
 370  * @param[in] audio_handle The audio hal handle
 371  * @param[in] pcm_handle The PCM handle to be closed
 372  *
 373  * @return @c 0 on success,
 374  *         otherwise a negative error value
 375  * @retval #AUDIO_RET_OK Success
 376  * @see audio_pcm_open()
 377  */
 378 audio_return_t audio_pcm_close(void *audio_handle, void *pcm_handle);
 379
 380 /**
 381  * @brief Gets available number of frames.
 382  * @since_tizen 3.0
 383  * @param[in] audio_handle The audio hal handle
 384  * @param[in] pcm_handle The PCM handle
 385  * @param[out] avail The available number of frames
 386  *
 387  * @return @c 0 on success,
 388  *         otherwise a negative error value
 389  * @retval #AUDIO_RET_OK Success
 390  * @see audio_pcm_write()
 391  * @see audio_pcm_read()
 392  */
 393 audio_return_t audio_pcm_avail(void *audio_handle, void *pcm_handle, uint32_t *avail);
 394
 395 /**
 396  * @brief Writes frames to a PCM device.
 397  * @since_tizen 3.0
 398  * @param[in] audio_handle The audio hal handle
 399  * @param[in] pcm_handle The PCM handle
 400  * @param[in] buffer The buffer containing frames
 401  * @param[in] frames The number of frames to be written
 402  *
 403  * @return @c 0 on success,
 404  *         otherwise a negative error value
 405  * @retval #AUDIO_RET_OK Success
 406  * @see audio_pcm_avail()
 407  * @see audio_pcm_recover()
 408  */
 409 audio_return_t audio_pcm_write(void *audio_handle, void *pcm_handle, const void *buffer, uint32_t frames);
 410
 411 /**
 412  * @brief Reads frames from a PCM device.
 413  * @since_tizen 3.0
 414  * @param[in] audio_handle The audio hal handle
 415  * @param[in] pcm_handle The PCM handle
 416  * @param[out] buffer The buffer containing frames
 417  * @param[in] frames The number of frames to be read
 418  *
 419  * @return @c 0 on success,
 420  *         otherwise a negative error value
 421  * @retval #AUDIO_RET_OK Success
 422  * @see audio_pcm_avail()
 423  * @see audio_pcm_recover()
 424  */
 425 audio_return_t audio_pcm_read(void *audio_handle, void *pcm_handle, void *buffer, uint32_t frames);
 426
 427 /**
 428  * @brief Gets poll descriptor for a PCM handle.
 429  * @since_tizen 3.0
 430  * @param[in] audio_handle The audio hal handle
 431  * @param[in] pcm_handle The PCM handle
 432  * @param[out] fd The poll descriptor
 433  *
 434  * @return @c 0 on success,
 435  *         otherwise a negative error value
 436  * @retval #AUDIO_RET_OK Success
 437  * @see audio_pcm_open()
 438  * @see audio_pcm_recover()
 439  */
 440 audio_return_t audio_pcm_get_fd(void *audio_handle, void *pcm_handle, int *fd);
 441
 442 /**
 443  * @brief Recovers the PCM state.
 444  * @since_tizen 3.0
 445  * @param[in] audio_handle The audio hal handle
 446  * @param[in] pcm_handle The PCM handle
 447  * @param[in] revents The returned event from pollfd
 448  *
 449  * @return @c 0 on success,
 450  *         otherwise a negative error value
 451  * @retval #AUDIO_RET_OK Success
 452  * @see audio_pcm_start()
 453  * @see audio_pcm_write()
 454  * @see audio_pcm_read()
 455  * @see audio_pcm_get_fd()
 456  */
 457 audio_return_t audio_pcm_recover(void *audio_handle, void *pcm_handle, int revents);
 458
 459 /**
 460  * @brief Gets parameters of a PCM device.
 461  * @since_tizen 3.0
 462  * @param[in] audio_handle The audio hal handle
 463  * @param[in] pcm_handle The PCM handle
 464  * @param[in] direction The direction of PCM
 465  * @param[out] sample_spec The sample specification
 466  * @param[out] period_size The period size
 467  * @param[out] periods The periods
 468  *
 469  * @return @c 0 on success,
 470  *         otherwise a negative error value
 471  * @retval #AUDIO_RET_OK Success
 472  * @see audio_pcm_set_params()
 473  */
 474 audio_return_t audio_pcm_get_params(void *audio_handle, void *pcm_handle, uint32_t direction, void **sample_spec, uint32_t *period_size, uint32_t *periods);
 475
 476 /**
 477  * @brief Sets hardware and software parameters of a PCM device.
 478  * @since_tizen 3.0
 479  * @param[in] audio_handle The audio hal handle
 480  * @param[in] pcm_handle The PCM handle
 481  * @param[in] direction The direction of PCM
 482  * @param[in] sample_spec The sample specification
 483  * @param[in] period_size The period size
 484  * @param[in] periods The periods
 485  *
 486  * @return @c 0 on success,
 487  *         otherwise a negative error value
 488  * @retval #AUDIO_RET_OK Success
 489  * @see audio_pcm_set_params()
 490  */
 491 audio_return_t audio_pcm_set_params(void *audio_handle, void *pcm_handle, uint32_t direction, void *sample_spec, uint32_t period_size, uint32_t periods);
 492
 493 /**
 494  * @brief Adds the message callback function.
 495  * @since_tizen 3.0
 496  * @param[in] audio_handle The audio hal handle
 497  * @param[in] message_cb The message callback function
 498  * @param[in] user_data The user data passed to the callback function
 499  *
 500  * @see message_cb()
 501  * @see audio_remove_message_cb()
 502  */
 503 audio_return_t audio_add_message_cb(void *audio_handle, message_cb callback, void *user_data);
 504
 505 /**
 506  * @brief Removes the message callback function.
 507  * @since_tizen 3.0
 508  * @param[in] audio_handle The audio hal handle
 509  * @param[in] message_cb The message callback function to be removed
 510  *
 511  * @see message_cb()
 512  * @see audio_add_message_cb()
 513  */
 514 audio_return_t audio_remove_message_cb(void *audio_handle, message_cb callback);
 515
 516 /**
 517 * @}
 518 */
 519
 520 /**
 521 * @}
 522 */
 523
 524 #endif