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 #include <sys/types.h>
  23
  24 #ifdef __cplusplus
  25 extern "C"
  26 {
  27 #endif
  28
  29 /**
  30  * @file audio_io.h
  31  * @brief This file contains the Audio Input and Audio Output API.
  32  */
  33
  34 /**
  35  * @addtogroup CAPI_MEDIA_AUDIO_IN_MODULE
  36  * @{
  37 */
  38
  39 /**
  40  * @brief The audio input handle.
  41  * @since_tizen 2.3
  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 The audio output handle.
  56  * @since_tizen 2.3
  57  */
  58 typedef struct audio_out_s *audio_out_h;
  59
  60  /**
  61  * @}
  62  */
  63
  64 /**
  65  * @addtogroup CAPI_MEDIA_AUDIO_IO_MODULE
  66  * @{
  67  */
  68
  69 /**
  70  * @brief Enumeration for audio sample type with bit depth.
  71  * @since_tizen 2.3
  72  */
  73 typedef enum
  74 {
  75     AUDIO_SAMPLE_TYPE_U8 = 0x70,    /**< Unsigned 8-bit audio samples */
  76     AUDIO_SAMPLE_TYPE_S16_LE,       /**< Signed 16-bit audio samples */
  77 } audio_sample_type_e;
  78
  79 /**
  80  * @brief Enumeration for audio channel.
  81  * @since_tizen 2.3
  82  */
  83 typedef enum {
  84     AUDIO_CHANNEL_MONO = 0x80,                  /**< 1 channel, mono */
  85     AUDIO_CHANNEL_STEREO,                       /**< 2 channel, stereo */
  86 } audio_channel_e;
  87
  88 /**
  89  * @brief Enumeration for audio input and output error.
  90  * @since_tizen 2.3
  91  */
  92 typedef enum{
  93     AUDIO_IO_ERROR_NONE                = TIZEN_ERROR_NONE,              /**< Successful */
  94     AUDIO_IO_ERROR_OUT_OF_MEMORY       = TIZEN_ERROR_OUT_OF_MEMORY,     /**< Out of memory */
  95     AUDIO_IO_ERROR_INVALID_PARAMETER   = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
  96     AUDIO_IO_ERROR_INVALID_OPERATION   = TIZEN_ERROR_INVALID_OPERATION, /**< Invalid operation */
  97     AUDIO_IO_ERROR_PERMISSION_DENIED   = TIZEN_ERROR_PERMISSION_DENIED, /**< Device open error by security */
  98     AUDIO_IO_ERROR_NOT_SUPPORTED       = TIZEN_ERROR_NOT_SUPPORTED,     /**< Not supported */
  99     AUDIO_IO_ERROR_DEVICE_NOT_OPENED   = TIZEN_ERROR_AUDIO_IO | 0x01,   /**< Device open error */
 100     AUDIO_IO_ERROR_DEVICE_NOT_CLOSED   = TIZEN_ERROR_AUDIO_IO | 0x02,   /**< Device close error */
 101     AUDIO_IO_ERROR_INVALID_BUFFER      = TIZEN_ERROR_AUDIO_IO | 0x03,   /**< Invalid buffer pointer */
 102     AUDIO_IO_ERROR_SOUND_POLICY        = TIZEN_ERROR_AUDIO_IO | 0x04,   /**< Sound policy error */
 103 } audio_io_error_e;
 104
 105 /**
 106  * @brief Enumeration for audio IO interrupted messages.
 107  * @since_tizen 2.3
 108  */
 109 typedef enum
 110 {
 111     AUDIO_IO_INTERRUPTED_COMPLETED = 0,         /**< Interrupt completed */
 112     AUDIO_IO_INTERRUPTED_BY_MEDIA,              /**< Interrupted by a media application */
 113     AUDIO_IO_INTERRUPTED_BY_CALL,               /**< Interrupted by an incoming call */
 114     AUDIO_IO_INTERRUPTED_BY_EARJACK_UNPLUG,     /**< Interrupted by unplugging headphones */
 115     AUDIO_IO_INTERRUPTED_BY_RESOURCE_CONFLICT,  /**< Interrupted by a resource conflict */
 116     AUDIO_IO_INTERRUPTED_BY_ALARM,              /**< Interrupted by an alarm */
 117     AUDIO_IO_INTERRUPTED_BY_EMERGENCY,          /**< Interrupted by an emergency */
 118     AUDIO_IO_INTERRUPTED_BY_NOTIFICATION,       /**< Interrupted by a notification */
 119 } audio_io_interrupted_code_e;
 120
 121 /**
 122  * @brief Called when audio input or output is interrupted.
 123  *
 124  * @since_tizen 2.3
 125  * @param[in] error_code The interrupted error code
 126  * @param[in] user_data The user data passed from the callback registration function
 127  *
 128  * @see audio_in_set_interrupted_cb()
 129  * @see audio_out_set_interrupted_cb()
 130  * @see audio_in_unset_interrupted_cb()
 131  * @see audio_out_unset_interrupted_cb()
 132  */
 133 typedef void (*audio_io_interrupted_cb)(audio_io_interrupted_code_e code, void *user_data);
 134
 135 /**
 136  * @}
 137 */
 138
 139 /**
 140  * @addtogroup CAPI_MEDIA_AUDIO_IN_MODULE
 141  * @{
 142 */
 143
 144 //
 145 //AUDIO INPUT
 146 //
 147
 148 /**
 149  * @brief Called when audio input data is available in asynchronous(event) mode.
 150  *
 151  * @since_tizen 2.3
 152  *
 153  * @remarks @a use audio_in_peek() to get audio in data inside callback, use audio_in_drop() after use of peeked data.
 154  *
 155  * @param[in] handle The handle to the audio input
 156  * @param[in] nbytes The amount of available audio in data which can be peeked.
 157  * @param[in] userdata The user data passed from the callback registration function
 158  *
 159  * @see audio_in_set_stream_cb()
 160  */
 161 typedef void (*audio_in_stream_cb)(audio_in_h handle, size_t nbytes, void *userdata);
 162
 163 /**
 164  * @brief Creates an audio device instance and returns an input handle to record PCM (pulse-code modulation) data.
 165  *
 166  * @since_tizen 2.3
 167  * @privlevel public
 168  * @privilege %http://tizen.org/privilege/recorder
 169  *
 170  * @details This function is used for audio input initialization.
 171  *
 172  * @remarks @a input must be released using audio_in_destroy().
 173  *
 174  * @param[in] sample_rate       The audio sample rate in 8000[Hz] ~ 48000[Hz]
 175  * @param[in] channel   The audio channel type (mono or stereo)
 176  * @param[in] type      The type of audio sample (8- or 16-bit)
 177  * @param[out] input    An audio input handle is created on success
 178  * @return @c 0 on success,
 179  *         otherwise a negative error value
 180  * @retval #AUDIO_IO_ERROR_NONE Successful
 181  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 182  * @retval #AUDIO_IO_ERROR_PERMISSION_DENIED Permission denied
 183  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 184  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
 185  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 186  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 187  * @see audio_in_destroy()
 188  */
 189 int audio_in_create(int sample_rate, audio_channel_e channel, audio_sample_type_e type, audio_in_h *input);
 190
 191 /**
 192  * @brief Creates an audio loopback device instance and returns an input handle to record PCM (pulse-code modulation) data.
 193  *
 194  * @since_tizen 2.3
 195  * @privlevel public
 196  * @privilege %http://tizen.org/privilege/recorder
 197  *
 198  * @details This function is used for audio loopback input initialization.
 199  *
 200  * @remarks @a input must be released using audio_in_destroy().
 201  *
 202  * @param[in] sample_rate       The audio sample rate in 8000[Hz] ~ 48000[Hz]
 203  * @param[in] channel   The audio channel type, mono, or stereo
 204  * @param[in] type      The type of audio sample (8- or 16-bit)
 205  * @param[out] input    An audio input handle will be created, if successful
 206  * @return @c 0 on success,
 207  *         otherwise a negative error value
 208  * @retval #AUDIO_IO_ERROR_NONE Successful
 209  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 210  * @retval #AUDIO_IO_ERROR_PERMISSION_DENIED Permission denied
 211  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 212  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
 213  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 214  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 215  * @see audio_in_destroy()
 216  */
 217 int audio_in_create_loopback(int sample_rate, audio_channel_e channel, audio_sample_type_e type , audio_in_h* input);
 218
 219 /**
 220  * @brief Releases the audio input handle and all its resources associated with an audio stream.
 221  *
 222  * @since_tizen 2.3
 223  *
 224  * @param[in] input The handle to the audio input to destroy
 225  * @return @c 0 on success,
 226  *         otherwise a negative error value
 227  * @retval #AUDIO_IO_ERROR_NONE Successful
 228  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 229  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
 230  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 231  * @see audio_in_create()
 232  */
 233 int audio_in_destroy(audio_in_h input);
 234
 235 /**
 236  * @brief Prepares reading audio input by starting buffering of audio data from the device.
 237  *
 238  * @since_tizen 2.3
 239  *
 240  * @param[in] input The handle to the audio input
 241  * @return @c 0 on success,
 242  *         otherwise a negative error value
 243  * @retval #AUDIO_IO_ERROR_NONE Successful
 244  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 245  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 246  *
 247  * @see audio_in_unprepare()
 248  */
 249 int audio_in_prepare(audio_in_h input);
 250
 251 /**
 252  * @brief Unprepares reading audio input by stopping buffering the audio data from the device.
 253  *
 254  * @since_tizen 2.3
 255  *
 256  * @param[in] input The handle to the audio input
 257  * @return @c 0 on success,
 258  *         otherwise a negative error value
 259  * @retval #AUDIO_IO_ERROR_NONE Successful
 260  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 261  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 262  * @see audio_in_prepare()
 263  */
 264 int audio_in_unprepare(audio_in_h input);
 265
 266 /**
 267  * @brief Flushes and discards buffered audio data from the input stream.
 268  *
 269  * @since_tizen 2.4
 270  *
 271  * @param[in] input The handle to the audio input
 272  * @return @c 0 on success,
 273  *         otherwise a negative error value
 274  * @retval #AUDIO_IO_ERROR_NONE Successful
 275  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 276  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 277  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 278  *
 279  * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
 280  */
 281 int audio_in_flush(audio_in_h input);
 282
 283 /**
 284  * @brief Reads audio data from the audio input buffer.
 285  *
 286  * @since_tizen 2.3
 287  *
 288  * @param[in] input The handle to the audio input
 289  * @param[out] buffer The PCM buffer address
 290  * @param[in] length The length of the PCM data buffer (in bytes)
 291  * @return The number of read bytes on success,
 292  *         otherwise a negative error value
 293  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 294  * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
 295  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 296  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 297  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 298  * @pre audio_in_start_recording().
 299 */
 300 int audio_in_read(audio_in_h input, void *buffer, unsigned int length);
 301
 302 /**
 303  * @brief Gets the size to be allocated for the audio input buffer.
 304  *
 305  * @since_tizen 2.3
 306  *
 307  * @param[in] input The handle to the audio input
 308  * @param[out] size The buffer size (in bytes, the maximum size is 1 MB)
 309  * @return @c 0 on success,
 310  *         otherwise a negative error value
 311  * @retval #AUDIO_IO_ERROR_NONE Successful
 312  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 313  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 314  * @see audio_in_read()
 315 */
 316 int audio_in_get_buffer_size(audio_in_h input, int *size);
 317
 318 /**
 319  * @brief Gets the sample rate of the audio input data stream.
 320  *
 321  * @since_tizen 2.3
 322  *
 323  * @param[in] input The handle to the audio input
 324  * @param[out] sample_rate The audio sample rate in Hertz (8000 ~ 48000)
 325  * @return @c 0 on success,
 326  *         otherwise a negative error value
 327  * @retval #AUDIO_IO_ERROR_NONE Successful
 328  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 329  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 330 */
 331 int audio_in_get_sample_rate(audio_in_h input, int *sample_rate);
 332
 333 /**
 334  * @brief Gets the channel type of the audio input data stream.
 335  *
 336  * @since_tizen 2.3
 337  *
 338  * @details The audio channel type defines whether the audio is mono or stereo.
 339  *
 340  * @param[in] input The handle to the audio input
 341  * @param[out] channel The audio channel type
 342  * @return @c 0 on success,
 343  *         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_NOT_SUPPORTED Not supported
 347 */
 348 int audio_in_get_channel(audio_in_h input, audio_channel_e *channel);
 349
 350 /**
 351  * @brief Gets the sample audio format (8-bit or 16-bit) of the audio input data stream.
 352  *
 353  * @since_tizen 2.3
 354  *
 355  * @param[in] input The handle to the audio input
 356  * @param[out] type The audio sample type
 357  * @return @c 0 on success,
 358  *         otherwise a negative error value
 359  * @retval #AUDIO_IO_ERROR_NONE Successful
 360  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 361  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 362 */
 363 int audio_in_get_sample_type(audio_in_h input, audio_sample_type_e *type);
 364
 365 /**
 366  * @brief Registers a callback function to be invoked when the audio input handle is interrupted or the interrupt is completed.
 367  *
 368  * @since_tizen 2.3
 369  *
 370  * @param[in] input The handle to the audio input
 371  * @param[in] callback The callback function to register
 372  * @param[in] user_data The user data to be passed to the callback function
 373  * @return @c 0 on success,
 374  *         otherwise a negative error value
 375  * @retval #AUDIO_IO_ERROR_NONE Successful
 376  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 377  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 378  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 379  * @post audio_io_interrupted_cb() will be invoked.
 380  *
 381  * @see audio_in_unset_interrupted_cb()
 382  * @see audio_io_interrupted_cb()
 383  */
 384 int audio_in_set_interrupted_cb(audio_in_h input, audio_io_interrupted_cb callback, void *user_data);
 385
 386 /**
 387  * @brief Unregisters the callback function.
 388  *
 389  * @since_tizen 2.3
 390  *
 391  * @param[in] input The handle to the audio input
 392  * @return @c 0 on success,
 393  *         otherwise a negative error value
 394  * @retval #AUDIO_IO_ERROR_NONE Successful
 395  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 396  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 397  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 398  *
 399  * @see audio_in_set_interrupted_cb()
 400  */
 401 int audio_in_unset_interrupted_cb(audio_in_h input);
 402
 403 /**
 404  * @brief Ignores session for input.
 405  *
 406  * @since_tizen 2.3
 407  *
 408  * @param[in] input The handle to the audio input
 409  * @return @c 0 on success,
 410  *         otherwise a negative error value
 411  * @retval #AUDIO_IO_ERROR_NONE Successful
 412  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 413  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 414  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 415  */
 416 int audio_in_ignore_session(audio_in_h input);
 417
 418 /**
 419  * @brief Sets an asynchronous(event) callback function to handle recording PCM (pulse-code modulation) data.
 420  *
 421  * @since_tizen 2.3
 422  *
 423  * @details @a callback will be called when you can read a PCM data.
 424  * It might cause dead lock if change the state of audio handle in callback.
 425  * (ex: audio_in_destroy, audio_in_prepare, audio_in_unprepare)
 426  * Recommend to use as a VOIP only.
 427  * Recommend not to hold callback too long.(it affects latency)
 428  *
 429  * @remarks @a input must be created using audio_in_create().
 430  *
 431  * @param[in] input    An audio input handle
 432  * @param[in] callback notify stream callback when user can read data (#audio_in_stream_cb)
 433  * @param[in] userdata user data to be retrieved when callback is called
 434  * @return @c 0 on success,
 435  *         otherwise a negative error value
 436  * @retval #AUDIO_IO_ERROR_NONE Successful
 437  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 438  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 439  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
 440  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 441  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 442  *
 443  * @see audio_out_set_stream_cb()
 444  */
 445 int audio_in_set_stream_cb(audio_in_h input, audio_in_stream_cb callback, void* userdata);
 446
 447 /**
 448  * @brief Unregisters the callback function.
 449  *
 450  * @since_tizen 2.3
 451  *
 452  * @param[in] input The handle to the audio input
 453  * @return @c 0 on success,
 454  *         otherwise a negative error value
 455  * @retval #AUDIO_IO_ERROR_NONE Successful
 456  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 457  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 458  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 459  *
 460  * @see audio_in_set_interrupted_cb()
 461  */
 462 int audio_in_unset_stream_cb(audio_in_h input);
 463
 464 /**
 465  * @brief peek from audio in buffer
 466  *
 467  * @since_tizen 2.3
 468  *
 469  * @details This function works correctly only with read, write callback. Otherwise it won't operate as intended.
 470  *
 471  * @remarks @a Works only in asynchronous(event) mode. This will just retrieve buffer pointer from audio in buffer. Drop after use.
 472  *
 473  * @param[in] input The handle to the audio input
 474  * @param[out] buffer start buffer pointer of peeked audio in data
 475  * @param[in,out] length amount of audio in data to be peeked
 476  * @return @c 0 on success,
 477  *         otherwise a negative error value
 478  * @retval #AUDIO_IO_ERROR_NONE Successful
 479  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 480  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 481  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 482  *
 483  * @see audio_in_drop()
 484  */
 485 int audio_in_peek(audio_in_h input, const void **buffer, unsigned int *length);
 486
 487 /**
 488  * @brief drop peeked audio buffer.
 489  *
 490  * @details This function works correctly only with read, write callback. Otherwise it won't operate as intended.
 491  *
 492  * @since_tizen 2.3
 493  *
 494  * @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.
 495  *
 496  * @param[in] input The handle to the audio input
 497  * @return 0 on success, otherwise a negative error value
 498  * @retval #AUDIO_IO_ERROR_NONE Successful
 499  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 500  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 501  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 502  *
 503  * @see audio_in_peek()
 504  */
 505 int audio_in_drop(audio_in_h input);
 506
 507
 508
 509 //
 510 // AUDIO OUTPUT
 511 //
 512
 513 /**
 514  * @}
 515 */
 516
 517 /**
 518  * @addtogroup CAPI_MEDIA_AUDIO_OUT_MODULE
 519  * @{
 520  */
 521
 522 /**
 523  * @brief Called when audio out data can be written in asynchronous(event) mode.
 524  *
 525  * @since_tizen 2.3
 526  *
 527  * @remarks @a use audio_out_write() to write pcm data inside this callback.
 528  * @param[in] handle The handle to the audio output
 529  * @param[in] nbytes The amount of audio in data which can be written.
 530  * @param[in] userdata The user data passed from the callback registration function
 531  *
 532  * @see audio_out_set_stream_cb()
 533  */
 534 typedef void (*audio_out_stream_cb)(audio_out_h handle, size_t nbytes, void *userdata);
 535
 536 /**
 537  * @brief Creates an audio device instance and returns an output handle to play PCM (pulse-code modulation) data.
 538
 539  * @since_tizen 2.3
 540  *
 541  * @details This function is used for audio output initialization.
 542  *
 543  * @remarks @a output must be released by audio_out_destroy().
 544  *
 545  * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
 546  * @param[in] channel The audio channel type (mono or stereo)
 547  * @param[in] type The type of audio sample (8- or 16-bit)
 548  * @param[in] sound_type The type of sound (#sound_type_e)
 549  * @param[out] output An audio output handle is created on success
 550  * @return @c 0 on success,
 551  *         otherwise a negative error value
 552  * @retval #AUDIO_IO_ERROR_NONE Successful
 553  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 554  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 555  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
 556  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 557  *
 558  * @see audio_out_destroy()
 559 */
 560 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);
 561
 562 /**
 563  * @brief Releases the audio output handle, along with all its resources.
 564  *
 565  * @since_tizen 2.3
 566  *
 567  * @param[in] output The handle to the audio output to destroy
 568  * @return @c 0 on success,
 569  *         otherwise a negative error value
 570  * @retval #AUDIO_IO_ERROR_NONE Successful
 571  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 572  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 573  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
 574  *
 575  * @see audio_out_create()
 576 */
 577 int audio_out_destroy(audio_out_h output);
 578
 579 /**
 580  * @brief Prepares playing audio output, this must be called before audio_out_write().
 581  *
 582  * @since_tizen 2.3
 583  *
 584  * @param[in] output The handle to the audio output
 585  * @return @c 0 on success,
 586  *         otherwise a negative error value
 587  * @retval #AUDIO_IO_ERROR_NONE Successful
 588  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 589  *
 590  * @see audio_out_unprepare()
 591  */
 592 int audio_out_prepare(audio_out_h output);
 593
 594 /**
 595  * @brief Unprepares playing audio output.
 596  *
 597  * @since_tizen 2.3
 598  *
 599  * @param[in] output The handle to the audio output
 600  * @return @c 0 on success,
 601  *         otherwise a negative error value
 602  * @retval #AUDIO_IO_ERROR_NONE Successful
 603  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 604  *
 605  * @see audio_out_prepare()
 606  */
 607 int audio_out_unprepare(audio_out_h output);
 608
 609 /**
 610  * @brief Drains buffered audio data from the output stream.
 611  *
 612  * @details This function waits until drains stream buffer completely. (e.g end of playback)
 613  *
 614  * @since_tizen 2.4
 615  *
 616  * @param[in] output The handle to the audio output
 617  * @return @c 0 on success,
 618  *         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_STATE Invalid state
 622  *
 623  * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
 624  * @see audio_out_flush()
 625  */
 626 int audio_out_drain(audio_out_h output);
 627
 628 /**
 629  * @brief Flushes and discards buffered audio data from the output stream.
 630  *
 631  * @since_tizen 2.4
 632  *
 633  * @param[in] output The handle to the audio output
 634  * @return @c 0 on success,
 635  *         otherwise a negative error value
 636  * @retval #AUDIO_IO_ERROR_NONE Successful
 637  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 638  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 639  *
 640  * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
 641  * @see audio_out_drain()
 642  */
 643 int audio_out_flush(audio_out_h output);
 644
 645 /**
 646  * @brief Starts writing the audio data to the device.
 647  *
 648  * @since_tizen 2.3
 649  *
 650  * @param[in] output The handle to the audio output
 651  * @param[in,out] buffer The PCM buffer address
 652  * @param[in] length The length of the PCM buffer (in bytes)
 653  * @return The written data size on success,
 654  *         otherwise a negative error value
 655  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 656  * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
 657  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 658 */
 659 int audio_out_write(audio_out_h output, void *buffer, unsigned int length);
 660
 661 /**
 662  * @brief Gets the size to be allocated for the audio output buffer.
 663  *
 664  * @since_tizen 2.3
 665  *
 666  * @param[in] output The handle to the audio output
 667  * @param[out] size The suggested buffer size (in bytes, the maximum size is 1 MB)
 668  * @return  @c 0 on success,
 669  *          otherwise a negative error value
 670  * @retval  #AUDIO_IO_ERROR_NONE Successful
 671  * @retval  #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 672  *
 673  * @see audio_out_write()
 674 */
 675 int audio_out_get_buffer_size(audio_out_h output, int *size);
 676
 677 /**
 678  * @brief Gets the sample rate of the audio output data stream.
 679  *
 680  * @since_tizen 2.3
 681  *
 682  * @param[in] output The handle to the audio output
 683  * @param[out] sample_rate The audio sample rate in Hertz (8000 ~ 48000)
 684  * @return  @c 0 on success,
 685  *          otherwise a negative error value
 686  * @retval  #AUDIO_IO_ERROR_NONE Successful
 687  * @retval  #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 688 */
 689 int audio_out_get_sample_rate(audio_out_h output, int *sample_rate);
 690
 691 /**
 692  * @brief Gets the channel type of the audio output data stream.
 693  * @details The audio channel type defines whether the audio is mono or stereo.
 694  *
 695  * @since_tizen 2.3
 696  *
 697  * @param[in] output The handle to the audio output
 698  * @param[out] channel The audio channel type
 699  * @return @c 0 on success,
 700  *         otherwise a negative error value
 701  * @retval #AUDIO_IO_ERROR_NONE Successful
 702  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 703 */
 704 int audio_out_get_channel(audio_out_h output, audio_channel_e *channel);
 705
 706 /**
 707  * @brief Gets the sample audio format (8-bit or 16-bit) of the audio output data stream.
 708  *
 709  * @since_tizen 2.3
 710  *
 711  * @param[in] output The handle to the audio output
 712  * @param[out] type The audio sample type
 713  * @return @c 0 on success,
 714  *         otherwise a negative error value
 715  * @retval #AUDIO_IO_ERROR_NONE Successful
 716  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 717 */
 718 int audio_out_get_sample_type(audio_out_h output, audio_sample_type_e *type);
 719
 720
 721 /**
 722  * @brief Gets the sound type supported by the audio output device.
 723  *
 724  * @since_tizen 2.3
 725  *
 726  * @param[in] output The handle to the audio output
 727  * @param[out] type The sound type
 728  * @return @c 0 on success,
 729  *         otherwise a negative error value
 730  * @retval #AUDIO_IO_ERROR_NONE Successful
 731  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 732 */
 733 int audio_out_get_sound_type(audio_out_h output, sound_type_e *type);
 734
 735 /**
 736  * @brief Registers a callback function to be invoked when the audio output handle is interrupted or the interrupt is completed.
 737  *
 738  * @since_tizen 2.3
 739  *
 740  * @param[in] output The handle to the audio output
 741  * @param[in] callback  The callback function to register
 742  * @param[in] user_data The user data to be passed to the callback function
 743  * @return @c 0 on success,
 744  *         otherwise a negative error value
 745  * @retval #AUDIO_IO_ERROR_NONE Successful
 746  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 747  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 748  *
 749  * @post audio_io_interrupted_cb() will be invoked.
 750  * @see audio_out_unset_interrupted_cb()
 751  * @see audio_io_interrupted_cb()
 752  */
 753 int audio_out_set_interrupted_cb(audio_out_h output, audio_io_interrupted_cb callback, void *user_data);
 754
 755 /**
 756  * @brief Unregisters the callback function.
 757  *
 758  * @since_tizen 2.3
 759  *
 760  * @param[in] output The handle to the audio output
 761  * @return @c 0 on success,
 762  *         otherwise a negative error value
 763  * @retval #AUDIO_IO_ERROR_NONE Successful
 764  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 765  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 766  *
 767  * @see audio_out_set_interrupted_cb()
 768  */
 769 int audio_out_unset_interrupted_cb(audio_out_h output);
 770
 771 /**
 772  * @brief Ignores session for output.
 773  *
 774  * @since_tizen 2.3
 775  *
 776  * @param[in] output The handle to the audio output
 777  * @return @c 0 on success,
 778  *         otherwise a negative error value
 779  * @retval #AUDIO_IO_ERROR_NONE Successful
 780  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 781  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 782  */
 783 int audio_out_ignore_session(audio_out_h output);
 784
 785 /**
 786  * @brief Sets an asynchronous(event) callback function to handle playing PCM (pulse-code modulation) data.
 787  *
 788  * @since_tizen 2.3
 789  *
 790  * @details @a callback will be called when you can write a PCM data.
 791  * It might cause dead lock if change the state of audio handle in callback.
 792  * (ex: audio_in_destroy, audio_in_prepare, audio_in_unprepare)
 793  * Recommend to use as a VOIP only.
 794  * Recommend not to hold callback too long.(it affects latency)
 795  *
 796  * @remarks @a output must be created using audio_out_create().
 797  *
 798  * @param[in] output   An audio output handle
 799  * @param[in] callback notify stream callback when user can write data (#audio_out_stream_cb)
 800  * @param[in] userdata user data to be retrieved when callback is called
 801  * @return 0 on success, otherwise a negative error value
 802  * @retval #AUDIO_IO_ERROR_NONE Successful
 803  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 804  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 805  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
 806  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 807  *
 808  * @see audio_in_set_stream_cb()
 809  */
 810 int audio_out_set_stream_cb(audio_out_h output, audio_out_stream_cb callback, void* userdata);
 811
 812 /**
 813  * @brief Unregisters the callback function.
 814  *
 815  * @since_tizen 2.3
 816  *
 817  * @param[in] output The handle to the audio output
 818  * @return 0 on success, otherwise a negative error value
 819  * @retval #AUDIO_IO_ERROR_NONE Successful
 820  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 821  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 822  *
 823  * @see audio_out_set_stream_cb()
 824  */
 825 int audio_out_unset_stream_cb(audio_out_h output);
 826 /**
 827  * @}
 828 */
 829
 830 #ifdef __cplusplus
 831 }
 832 #endif
 833
 834 #endif /* __TIZEN_MEDIA_AUDIO_IO_H__ */