include/audio_io.h

   1 /*
   2 * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
   3 *
   4 * Licensed under the Apache License, Version 2.0 (the "License");
   5 * you may not use this file except in compliance with the License.
   6 * You may obtain a copy of the License at
   7 *
   8 * http://www.apache.org/licenses/LICENSE-2.0
   9 *
  10 * Unless required by applicable law or agreed to in writing, software
  11 * distributed under the License is distributed on an "AS IS" BASIS,
  12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 * See the License for the specific language governing permissions and
  14 * limitations under the License.
  15 */
  16
  17 #ifndef __TIZEN_MEDIA_AUDIO_IO_H__
  18 #define __TIZEN_MEDIA_AUDIO_IO_H__
  19
  20 #include <tizen.h>
  21 #include <sound_manager.h>
  22
  23 #ifdef __cplusplus
  24 extern "C"
  25 {
  26 #endif
  27
  28 #define AUDIO_IO_ERROR_CLASS          TIZEN_ERROR_MULTIMEDIA_CLASS | 0x40
  29
  30 /**
  31  * @file audio_io.h
  32  * @brief This file contains the Audio Input and Output API.
  33  */
  34
  35 /**
  36  * @addtogroup CAPI_MEDIA_AUDIO_IN_MODULE
  37  * @{
  38 */
  39
  40 /**
  41  * @brief Audio input handle type.
  42  */
  43 typedef struct audio_in_s *audio_in_h;
  44
  45 /**
  46  * @}
  47 */
  48
  49 /**
  50  * @addtogroup CAPI_MEDIA_AUDIO_OUT_MODULE
  51  * @{
  52  */
  53
  54 /**
  55  * @brief Audio output handle type.
  56  */
  57 typedef struct audio_out_s *audio_out_h;
  58
  59  /**
  60  * @}
  61  */
  62
  63 /**
  64  * @addtogroup CAPI_MEDIA_AUDIO_IO_MODULE
  65  * @{
  66  */
  67
  68 /**
  69  * @brief Enumerations of audio sample type with bit depth
  70  */
  71 typedef enum
  72 {
  73     AUDIO_SAMPLE_TYPE_U8 = 0x70,   /**< Unsigned 8-bit audio samples */
  74     AUDIO_SAMPLE_TYPE_S16_LE,   /**< Signed 16-bit audio samples */
  75 } audio_sample_type_e;
  76
  77 /**
  78  * @brief Enumerations of audio channel
  79  */
  80 typedef enum {
  81     AUDIO_CHANNEL_MONO = 0x80,    /**< 1 channel, mono */
  82     AUDIO_CHANNEL_STEREO,      /**< 2 channel, stereo */
  83 } audio_channel_e;
  84
  85 /**
  86  * @brief Enumerations of audio input and output error code
  87  */
  88 typedef enum{
  89     AUDIO_IO_ERROR_NONE                = TIZEN_ERROR_NONE,                /**<Successful */
  90     AUDIO_IO_ERROR_OUT_OF_MEMORY       = TIZEN_ERROR_OUT_OF_MEMORY,     /**< Out of memory */
  91     AUDIO_IO_ERROR_INVALID_PARAMETER   = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
  92     AUDIO_IO_ERROR_INVALID_OPERATION   = TIZEN_ERROR_INVALID_OPERATION, /**< Invalid operation */
  93         AUDIO_IO_ERROR_PERMISSION_DENIED   = TIZEN_ERROR_PERMISSION_DENIED, /**< Device open error by security */
  94     AUDIO_IO_ERROR_DEVICE_NOT_OPENED   = AUDIO_IO_ERROR_CLASS | 0x01, /**< Device open error */
  95     AUDIO_IO_ERROR_DEVICE_NOT_CLOSED   = AUDIO_IO_ERROR_CLASS | 0x02, /**< Device close error */
  96     AUDIO_IO_ERROR_INVALID_BUFFER      = AUDIO_IO_ERROR_CLASS | 0x03, /**< Invalid buffer pointer */
  97     AUDIO_IO_ERROR_SOUND_POLICY        = AUDIO_IO_ERROR_CLASS | 0x04, /**< Sound policy error */
  98 } audio_io_error_e;
  99
 100 /**
 101  * @brief Enumerations of audio io interrupted type
 102  */
 103 typedef enum
 104 {
 105     AUDIO_IO_INTERRUPTED_COMPLETED = 0,         /**< Interrupt completed */
 106     AUDIO_IO_INTERRUPTED_BY_MEDIA,              /**< Interrupted by a media application */
 107     AUDIO_IO_INTERRUPTED_BY_CALL,               /**< Interrupted by an incoming call */
 108     AUDIO_IO_INTERRUPTED_BY_EARJACK_UNPLUG,     /**< Interrupted by unplugging headphones */
 109     AUDIO_IO_INTERRUPTED_BY_RESOURCE_CONFLICT,  /**< Interrupted by a resource conflict */
 110     AUDIO_IO_INTERRUPTED_BY_ALARM,              /**< Interrupted by an alarm */
 111     AUDIO_IO_INTERRUPTED_BY_EMERGENCY,          /**< Interrupted by an emergency */
 112     AUDIO_IO_INTERRUPTED_BY_NOTIFICATION,       /**< Interrupted by a notification */
 113 } audio_io_interrupted_code_e;
 114
 115 /**
 116  * @brief  Called when the audio input or output is interrupted.
 117  * @param[in]   error_code      The interrupted error code
 118  * @param[in]   user_data       The user data passed from the callback registration function
 119  * @see audio_in_set_interrupted_cb()
 120  * @see audio_out_set_interrupted_cb()
 121  * @see audio_in_unset_interrupted_cb()
 122  * @see audio_out_unset_interrupted_cb()
 123  */
 124 typedef void (*audio_io_interrupted_cb)(audio_io_interrupted_code_e code, void *user_data);
 125
 126 /**
 127  * @}
 128 */
 129
 130 /**
 131  * @addtogroup CAPI_MEDIA_AUDIO_IN_MODULE
 132  * @{
 133 */
 134
 135
 136 //
 137 //AUDIO INPUT
 138 //
 139
 140 /**
 141  * @brief Called when audio input data is available in asynchronous(event) mode.
 142  *
 143  *
 144  * @remarks @a use audio_in_peek() to get audio in data inside callback, use audio_in_drop() after use of peeked data.
 145  *
 146  * @param[in] handle The handle to the audio input
 147  * @param[in] nbytes The amount of available audio in data which can be peeked.
 148  * @param[in] userdata The user data passed from the callback registration function
 149  *
 150  * @see audio_in_set_stream_cb()
 151  */
 152 typedef void (*audio_in_stream_cb)(audio_in_h handle, size_t nbytes, void *userdata);
 153
 154 /**
 155  * @brief    Creates an audio device instance and returns an input handle to record PCM (pulse-code modulation) data
 156  * @details  This function is used for audio input initialization.
 157  *
 158  * @remarks @a input must be release audio_in_destroy() by you.
 159  *
 160  * @param[in]  sample_rate      The audio sample rate in 8000[Hz] ~ 48000[Hz]
 161  * @param[in]  channel  The audio channel type, mono, or stereo
 162  * @param[in]  type     The type of audio sample (8- or 16-bit)
 163  * @param[out] input    An audio input handle will be created, if successful
 164  *
 165  * @return 0 on success, otherwise a negative error value.
 166  * @retval #AUDIO_IO_ERROR_NONE Successful
 167  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 168  * @retval #AUDIO_IO_ERROR_PERMISSION_DENIED Permission denied
 169  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 170  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
 171  * @retval #AUDIO_IO_ERROR_SOUND_POLICY    Sound policy error
 172  * @see audio_in_destroy()
 173  */
 174 int audio_in_create(int sample_rate, audio_channel_e channel, audio_sample_type_e type , audio_in_h *input);
 175
 176 /**
 177  * @brief Creates an audio loopback device instance and returns an input handle to record PCM (pulse-code modulation) data.
 178  *
 179  *
 180  * @details This function is used for audio loopback input initialization.
 181  *
 182  * @remarks @a input must be released using audio_in_destroy().
 183  *
 184  * @param[in] sample_rate       The audio sample rate in 8000[Hz] ~ 48000[Hz]
 185  * @param[in] channel   The audio channel type, mono, or stereo
 186  * @param[in] type      The type of audio sample (8- or 16-bit)
 187  * @param[out] input    An audio input handle will be created, if successful
 188  * @return @c 0 on success,
 189  *         otherwise a negative error value
 190  * @retval #AUDIO_IO_ERROR_NONE Successful
 191  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 192  * @retval #AUDIO_IO_ERROR_PERMISSION_DENIED Permission denied
 193  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 194  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
 195  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 196  * @see audio_in_destroy()
 197  */
 198 int audio_in_create_loopback(int sample_rate, audio_channel_e channel, audio_sample_type_e type , audio_in_h* input);
 199
 200 /**
 201  * @brief    Releases the audio input handle and all its resources associated with an audio stream
 202  *
 203  * @param[in]   input   The handle to the audio input to destroy
 204  *
 205  * @return 0 on success, otherwise a negative error value.
 206  * @retval #AUDIO_IO_ERROR_NONE Successful
 207  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 208  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
 209  * @see audio_in_create()
 210  */
 211 int audio_in_destroy(audio_in_h input);
 212
 213
 214
 215 /**
 216  * @brief   Prepare reading audio in by starting buffering the audio data from the device
 217  * @param[in]   input   The handle to the audio input
 218  * @return 0 on success, otherwise a negative error value.
 219  * @retval #AUDIO_IO_ERROR_NONE Successful
 220  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 221  * @see audio_in_unprepare()
 222  */
 223 int audio_in_prepare(audio_in_h input);
 224
 225
 226
 227 /**
 228  * @brief    Unprepare reading audio in by stopping buffering the audio data from the device
 229  * @param[in]   input   The handle to the audio input
 230  * @return 0 on success, otherwise a negative error value.
 231  * @retval #AUDIO_IO_ERROR_NONE Successful
 232  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 233  * @see audio_in_prepare()
 234  */
 235 int audio_in_unprepare(audio_in_h input);
 236
 237
 238
 239 /**
 240  * @brief   Reads audio data from the audio input buffer
 241  *
 242  * @param[in]   input   The handle to the audio input
 243  * @param[out]  buffer  The PCM buffer address
 244  * @param[in]   length  The length of PCM data buffer (in bytes)
 245  *
 246  * @return  Number of read bytes on success, otherwise a negative error value.
 247  * @retval  #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 248  * @retval  #AUDIO_IO_ERROR_INVALID_BUFFER  Invalid buffer pointer
 249  * @retval  #AUDIO_IO_ERROR_SOUND_POLICY    Sound policy error
 250  * @retval  #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 251  * @pre audio_in_start_recording()
 252 */
 253 int audio_in_read(audio_in_h input, void *buffer, unsigned int length);
 254
 255
 256
 257 /**
 258  * @brief    Gets the size to be allocated for audio input buffer
 259  * @param[in]   input   The handle to the audio input
 260  * @param[out]  size    The buffer size (in bytes). \n The maximum size is 1 MB.
 261  *
 262  * @return  0 on success, otherwise a negative error value.
 263  * @retval  #AUDIO_IO_ERROR_NONE Successful
 264  * @retval  #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 265  * @see audio_in_read()
 266 */
 267 int audio_in_get_buffer_size(audio_in_h input, int *size);
 268
 269
 270
 271 /**
 272  * @brief    Gets the sample rate of the audio input data stream
 273  *
 274  * @param[in]   input   The handle to the audio input
 275  * @param[out]  sample_rate  The audio sample rate in Hertz (8000 ~ 48000)
 276  *
 277  * @return  0 on success, otherwise a negative error value.
 278  * @retval  #AUDIO_IO_ERROR_NONE Successful
 279  * @retval  #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 280 */
 281 int audio_in_get_sample_rate(audio_in_h input, int *sample_rate);
 282
 283
 284
 285 /**
 286  * @brief    Gets the channel type of audio input data stream
 287  *
 288  * @details  The audio channel type defines whether the audio is mono or stereo.
 289  *
 290  * @param[in]   input   The handle to the audio input
 291  * @param[out]  channel The audio channel type
 292  *
 293  * @return 0 on success, otherwise a negative error value.
 294  * @retval #AUDIO_IO_ERROR_NONE Successful
 295  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 296 */
 297 int audio_in_get_channel(audio_in_h input, audio_channel_e *channel);
 298
 299
 300
 301 /**
 302  * @brief    Gets the sample audio format (8-bit or 16-bit) of audio input data stream
 303  *
 304  * @param[in]  input    The handle to the audio input
 305  * @param[out] type     The audio sample type
 306  *
 307  * @return 0 on success, otherwise a negative error value.
 308  * @retval #AUDIO_IO_ERROR_NONE Successful
 309  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 310 */
 311 int audio_in_get_sample_type(audio_in_h input, audio_sample_type_e *type);
 312
 313
 314 /**
 315  * @brief Registers a callback function to be invoked when the audio input handle is interrupted or interrupt completed.
 316  * @param[in] input    The handle to the audio input
 317  * @param[in] callback  The callback function to register
 318  * @param[in] user_data The user data to be passed to the callback function
 319  * @return 0 on success, otherwise a negative error value.
 320  * @retval #AUDIO_IO_ERROR_NONE Successful
 321  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 322  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 323  * @post  audio_io_interrupted_cb() will be invoked
 324  * @see audio_in_unset_interrupted_cb()
 325  * @see audio_io_interrupted_cb()
 326  */
 327 int audio_in_set_interrupted_cb(audio_in_h input, audio_io_interrupted_cb callback, void *user_data);
 328
 329 /**
 330  * @brief Unregisters the callback function.
 331  * @param[in]  input   The handle to the audio input
 332  * @return 0 on success, otherwise a negative error value.
 333  * @retval #AUDIO_IO_ERROR_NONE Successful
 334  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 335  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 336  * @see audio_in_set_interrupted_cb()
 337  */
 338 int audio_in_unset_interrupted_cb(audio_in_h input);
 339
 340 /**
 341  * @brief Ignore session for input
 342  * @param[in]  input   The handle to the audio input
 343  * @return 0 on success, otherwise a negative error value.
 344  * @retval #AUDIO_IO_ERROR_NONE Successful
 345  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 346  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 347  * @see
 348  */
 349 int audio_in_ignore_session(audio_in_h input);
 350
 351 /**
 352  * @brief Sets an asynchronous(event) callback function to handle recording PCM (pulse-code modulation) data.
 353  *
 354  *
 355  * @details @a callback will be called when you can read a PCM data.
 356  * It might cause dead lock if change the state of audio handle in callback.
 357  * (ex: audio_in_destroy, audio_in_prepare, audio_in_unprepare)
 358  * Recommend to use as a VOIP only.
 359  * Recommend not to hold callback too long.(it affects latency)
 360  *
 361  * @remarks @a input must be created using audio_in_create().
 362  *
 363  * @param[in] input    An audio input handle
 364  * @param[in] callback notify stream callback when user can read data (#audio_in_stream_cb)
 365  * @param[in] userdata user data to be retrieved when callback is called
 366  * @return @c 0 on success,
 367  *         otherwise a negative error value
 368  * @retval #AUDIO_IO_ERROR_NONE Successful
 369  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 370  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 371  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
 372  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 373  *
 374  * @see audio_out_set_stream_cb()
 375  */
 376 int audio_in_set_stream_cb(audio_in_h input, audio_in_stream_cb callback, void* userdata);
 377
 378 /**
 379  * @brief Unregisters the callback function.
 380  *
 381  *
 382  * @param[in] input The handle to the audio input
 383  * @return @c 0 on success,
 384  *         otherwise a negative error value
 385  * @retval #AUDIO_IO_ERROR_NONE Successful
 386  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 387  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 388  *
 389  * @see audio_in_set_interrupted_cb()
 390  */
 391 int audio_in_unset_stream_cb(audio_in_h input);
 392
 393 /**
 394  * @brief peek from audio in buffer
 395  *
 396  *
 397  * @details This function works correctly only with read, write callback. Otherwise it won't operate as intended.
 398  *
 399  * @remarks @a Works only in asynchronous(event) mode. This will just retrieve buffer pointer from audio in buffer. Drop after use.
 400  *
 401  * @param[in] input The handle to the audio input
 402  * @param[out] buffer start buffer pointer of peeked audio in data
 403  * @param[in,out] length amount of audio in data to be peeked
 404  * @return @c 0 on success,
 405  *         otherwise a negative error value
 406  * @retval #AUDIO_IO_ERROR_NONE Successful
 407  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 408  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 409  *
 410  * @see audio_in_drop()
 411  */
 412 int audio_in_peek(audio_in_h input, const void **buffer, unsigned int *length);
 413
 414 /**
 415  * @brief drop peeked audio buffer.
 416  *
 417  * @details This function works correctly only with read, write callback. Otherwise it won't operate as intended.
 418  *
 419  *
 420  * @remarks @a Works only in asynchronous(event) mode. This will remove audio in data from actual stream buffer. Use this if peeked data is not needed anymore.
 421  *
 422  * @param[in] input The handle to the audio input
 423  * @return 0 on success, otherwise a negative error value
 424  * @retval #AUDIO_IO_ERROR_NONE Successful
 425  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 426  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 427  *
 428  * @see audio_in_peek()
 429  */
 430 int audio_in_drop(audio_in_h input);
 431
 432
 433
 434 //
 435 //  AUDIO OUTPUT
 436 //
 437
 438 /**
 439  * @}
 440 */
 441
 442 /**
 443  * @addtogroup CAPI_MEDIA_AUDIO_OUT_MODULE
 444  * @{
 445  */
 446
 447 /**
 448  * @brief Called when audio out data can be written in asynchronous(event) mode.
 449  *
 450  *
 451  * @remarks @a use audio_out_write() to write pcm data inside this callback.
 452  * @param[in] handle The handle to the audio output
 453  * @param[in] nbytes The amount of audio in data which can be written.
 454  * @param[in] userdata The user data passed from the callback registration function
 455  *
 456  * @see audio_out_set_stream_cb()
 457  */
 458 typedef void (*audio_out_stream_cb)(audio_out_h handle, size_t nbytes, void *userdata);
 459
 460 /**
 461  * @brief Creates an audio device instance and returns an output handle to play PCM (pulse-code modulation) data.
 462
 463  *
 464  * @details This function is used for audio output initialization.
 465  *
 466  * @remarks @a output must be released by audio_out_destroy().
 467  *
 468  * @param[in]  sample_rate  The audio sample rate in 8000[Hz] ~ 48000[Hz]
 469  * @param[in]  channel      The audio channel type, mono, or stereo
 470  * @param[in]  type         The type of audio sample (8- or 16-bit)
 471  * @param[in]  sound_type   The type of sound (#sound_type_e)
 472  * @param[out] output       An audio output handle will be created, if successful
 473  *
 474  * @return 0 on success, otherwise a negative error value.
 475  * @retval #AUDIO_IO_ERROR_NONE Successful
 476  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 477  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 478  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
 479  * @retval #AUDIO_IO_ERROR_SOUND_POLICY    Sound policy error
 480  *
 481  * @see audio_out_destroy()
 482 */
 483 int audio_out_create(int sample_rate, audio_channel_e channel, audio_sample_type_e type, sound_type_e sound_type,  audio_out_h *output);
 484
 485
 486
 487 /**
 488  * @brief    Releases the audio output handle, along with all its resources
 489  *
 490  * @param[in]   output The handle to the audio output to destroy
 491  *
 492  * @return  0 on success, otherwise a negative error value.
 493  * @retval  #AUDIO_IO_ERROR_NONE Successful
 494  * @retval  #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 495  * @retval  #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 496  * @retval  #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
 497  *
 498  * @see audio_out_create()
 499 */
 500 int audio_out_destroy(audio_out_h output);
 501
 502 /**
 503  * @brief   Prepare playing audio out, this must be called before audio_out_write()
 504  * @param[in]   output  The handle to the audio output
 505  * @return 0 on success, otherwise a negative error value.
 506  * @retval #AUDIO_IO_ERROR_NONE Successful
 507  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 508  * @see audio_out_unprepare()
 509  */
 510 int audio_out_prepare(audio_out_h output);
 511
 512
 513
 514 /**
 515  * @brief    Unprepare playing audio out.
 516  * @param[in]   output  The handle to the audio output
 517  * @return 0 on success, otherwise a negative error value.
 518  * @retval #AUDIO_IO_ERROR_NONE Successful
 519  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 520  * @see audio_out_prepare()
 521  */
 522 int audio_out_unprepare(audio_out_h output);
 523
 524
 525
 526
 527 /**
 528  * @brief    Starts writing the audio data to the device
 529  *
 530  * @param[in]       output  The handle to the audio output
 531  * @param[in,out]   buffer  The PCM buffer address
 532  * @param[in]       length  The length of PCM buffer (in bytes)
 533  *
 534  * @return  Written data size on success, otherwise a negative error value.
 535  * @retval  #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 536  * @retval  #AUDIO_IO_ERROR_INVALID_BUFFER  Invalid buffer pointer
 537  * @retval  #AUDIO_IO_ERROR_SOUND_POLICY    Sound policy error
 538 */
 539 int audio_out_write(audio_out_h output, void *buffer, unsigned int length);
 540
 541
 542
 543 /**
 544  * @brief    Gets the size to be allocated for audio output buffer
 545  * @param[in]     output  The handle to the audio output
 546  * @param[out]    size    The suggested buffer size (in bytes). \n The maximum size is 1 MB.
 547  *
 548  * @return  0 on success, otherwise a negative error value.
 549  * @retval  #AUDIO_IO_ERROR_NONE Successful
 550  * @retval  #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 551  * @see audio_out_write()
 552  *
 553 */
 554 int audio_out_get_buffer_size(audio_out_h output, int *size);
 555
 556
 557
 558 /**
 559  * @brief    Gets the sample rate of audio output data stream
 560  *
 561  * @param[in]   output       The handle to the audio output
 562  * @param[out]  sample_rate  The audio sample rate in Hertz (8000 ~ 48000)
 563  *
 564  * @return  0 on success, otherwise a negative error value.
 565  * @retval  #AUDIO_IO_ERROR_NONE Successful
 566  * @retval  #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 567 */
 568 int audio_out_get_sample_rate(audio_out_h output, int *sample_rate);
 569
 570
 571
 572 /**
 573  * @brief    Gets the channel type of audio output data stream
 574  *
 575  * @details  The audio channel type defines whether the audio is mono or stereo.
 576  *
 577  * @param[in]   output  The handle to the audio output
 578  * @param[out]  channel The audio channel type
 579  *
 580  * @return 0 on success, otherwise a negative error value.
 581  * @retval #AUDIO_IO_ERROR_NONE Successful
 582  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 583 */
 584 int audio_out_get_channel(audio_out_h output, audio_channel_e *channel);
 585
 586
 587
 588 /**
 589  * @brief    Gets the sample audio format (8-bit or 16-bit) of audio output data stream
 590  *
 591  * @param[in]   output  The handle to the audio output
 592  * @param[out]  type    The audio sample type
 593  * @return 0 on success, otherwise a negative error value.
 594  * @retval #AUDIO_IO_ERROR_NONE Successful
 595  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 596 */
 597 int audio_out_get_sample_type(audio_out_h output, audio_sample_type_e *type);
 598
 599
 600
 601 /**
 602  * @brief    Gets the sound type supported by the audio output device
 603  * @param[in]  output   The handle to the audio output
 604  * @param[out] type     The sound type
 605  *
 606  * @return 0 on success, otherwise a negative error value.
 607  * @retval #AUDIO_IO_ERROR_NONE Successful
 608  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 609 */
 610 int audio_out_get_sound_type(audio_out_h output, sound_type_e *type);
 611
 612
 613 /**
 614  * @brief Registers a callback function to be invoked when the audio out handle is interrupted or interrupt completed.
 615  * @param[in] output   The handle to the audio output
 616  * @param[in] callback  The callback function to register
 617  * @param[in] user_data The user data to be passed to the callback function
 618  * @return 0 on success, otherwise a negative error value.
 619  * @retval #AUDIO_IO_ERROR_NONE Successful
 620  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 621  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 622  * @post  audio_io_interrupted_cb() will be invoked
 623  * @see audio_out_unset_interrupted_cb()
 624  * @see audio_io_interrupted_cb()
 625  */
 626 int audio_out_set_interrupted_cb(audio_out_h output, audio_io_interrupted_cb callback, void *user_data);
 627
 628 /**
 629  * @brief Unregisters the callback function.
 630  * @param[in]  output   The handle to the audio output
 631  * @return 0 on success, otherwise a negative error value.
 632  * @retval #AUDIO_IO_ERROR_NONE Successful
 633  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 634  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 635  * @see audio_out_set_interrupted_cb()
 636  */
 637 int audio_out_unset_interrupted_cb(audio_out_h output);
 638
 639 /**
 640  * @brief Ignore session for output
 641  * @param[in]  output   The handle to the audio output
 642  * @return 0 on success, otherwise a negative error value.
 643  * @retval #AUDIO_IO_ERROR_NONE Successful
 644  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 645  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 646  * @see
 647  */
 648 int audio_out_ignore_session(audio_out_h output);
 649
 650 /**
 651  * @brief Sets an asynchronous(event) callback function to handle playing PCM (pulse-code modulation) data.
 652  *
 653  *
 654  * @details @a callback will be called when you can write a PCM data.
 655  * It might cause dead lock if change the state of audio handle in callback.
 656  * (ex: audio_in_destroy, audio_in_prepare, audio_in_unprepare)
 657  * Recommend to use as a VOIP only.
 658  * Recommend not to hold callback too long.(it affects latency)
 659  *
 660  * @remarks @a output must be created using audio_out_create().
 661  *
 662  * @param[in] output   An audio output handle
 663  * @param[in] callback notify stream callback when user can write data (#audio_out_stream_cb)
 664  * @param[in] userdata user data to be retrieved when callback is called
 665  * @return 0 on success, otherwise a negative error value
 666  * @retval #AUDIO_IO_ERROR_NONE Successful
 667  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 668  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 669  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
 670  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 671  *
 672  * @see audio_in_set_stream_cb()
 673  */
 674 int audio_out_set_stream_cb(audio_out_h output, audio_out_stream_cb callback, void* userdata);
 675
 676 /**
 677  * @brief Unregisters the callback function.
 678  *
 679  *
 680  * @param[in] output The handle to the audio output
 681  * @return 0 on success, otherwise a negative error value
 682  * @retval #AUDIO_IO_ERROR_NONE Successful
 683  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 684  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 685  *
 686  * @see audio_out_set_stream_cb()
 687  */
 688 int audio_out_unset_stream_cb(audio_out_h output);
 689 /**
 690  * @}
 691 */
 692
 693 #ifdef __cplusplus
 694 }
 695 #endif
 696
 697 #endif /* __TIZEN_MEDIA_AUDIO_IO_H__ */