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 Reads audio data from the audio input buffer.
 268  *
 269  * @since_tizen 2.3
 270  *
 271  * @param[in] input The handle to the audio input
 272  * @param[out] buffer The PCM buffer address
 273  * @param[in] length The length of the PCM data buffer (in bytes)
 274  * @return The number of read bytes on success,
 275  *         otherwise a negative error value
 276  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 277  * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
 278  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 279  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 280  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 281  * @pre audio_in_start_recording().
 282 */
 283 int audio_in_read(audio_in_h input, void *buffer, unsigned int length);
 284
 285 /**
 286  * @brief Gets the size to be allocated for the audio input buffer.
 287  *
 288  * @since_tizen 2.3
 289  *
 290  * @param[in] input The handle to the audio input
 291  * @param[out] size The buffer size (in bytes, the maximum size is 1 MB)
 292  * @return @c 0 on success,
 293  *         otherwise a negative error value
 294  * @retval #AUDIO_IO_ERROR_NONE Successful
 295  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 296  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 297  * @see audio_in_read()
 298 */
 299 int audio_in_get_buffer_size(audio_in_h input, int *size);
 300
 301 /**
 302  * @brief Gets the sample rate of the audio input data stream.
 303  *
 304  * @since_tizen 2.3
 305  *
 306  * @param[in] input The handle to the audio input
 307  * @param[out] sample_rate The audio sample rate in Hertz (8000 ~ 48000)
 308  * @return @c 0 on success,
 309  *         otherwise a negative error value
 310  * @retval #AUDIO_IO_ERROR_NONE Successful
 311  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 312  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 313 */
 314 int audio_in_get_sample_rate(audio_in_h input, int *sample_rate);
 315
 316 /**
 317  * @brief Gets the channel type of the audio input data stream.
 318  *
 319  * @since_tizen 2.3
 320  *
 321  * @details The audio channel type defines whether the audio is mono or stereo.
 322  *
 323  * @param[in] input The handle to the audio input
 324  * @param[out] channel The audio channel type
 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_channel(audio_in_h input, audio_channel_e *channel);
 332
 333 /**
 334  * @brief Gets the sample audio format (8-bit or 16-bit) of the audio input data stream.
 335  *
 336  * @since_tizen 2.3
 337  *
 338  * @param[in] input The handle to the audio input
 339  * @param[out] type The audio sample type
 340  * @return @c 0 on success,
 341  *         otherwise a negative error value
 342  * @retval #AUDIO_IO_ERROR_NONE Successful
 343  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 344  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 345 */
 346 int audio_in_get_sample_type(audio_in_h input, audio_sample_type_e *type);
 347
 348 /**
 349  * @brief Registers a callback function to be invoked when the audio input handle is interrupted or the interrupt is completed.
 350  *
 351  * @since_tizen 2.3
 352  *
 353  * @param[in] input The handle to the audio input
 354  * @param[in] callback The callback function to register
 355  * @param[in] user_data The user data to be passed to the callback function
 356  * @return @c 0 on success,
 357  *         otherwise a negative error value
 358  * @retval #AUDIO_IO_ERROR_NONE Successful
 359  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 360  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 361  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 362  * @post audio_io_interrupted_cb() will be invoked.
 363  *
 364  * @see audio_in_unset_interrupted_cb()
 365  * @see audio_io_interrupted_cb()
 366  */
 367 int audio_in_set_interrupted_cb(audio_in_h input, audio_io_interrupted_cb callback, void *user_data);
 368
 369 /**
 370  * @brief Unregisters the callback function.
 371  *
 372  * @since_tizen 2.3
 373  *
 374  * @param[in] input The handle to the audio input
 375  * @return @c 0 on success,
 376  *         otherwise a negative error value
 377  * @retval #AUDIO_IO_ERROR_NONE Successful
 378  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 379  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 380  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 381  *
 382  * @see audio_in_set_interrupted_cb()
 383  */
 384 int audio_in_unset_interrupted_cb(audio_in_h input);
 385
 386 /**
 387  * @brief Ignores session for input.
 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 int audio_in_ignore_session(audio_in_h input);
 400
 401 /**
 402  * @brief Sets an asynchronous(event) callback function to handle recording PCM (pulse-code modulation) data.
 403  *
 404  * @since_tizen 2.3
 405  *
 406  * @details @a callback will be called when you can read a PCM data.
 407  * It might cause dead lock if change the state of audio handle in callback.
 408  * (ex: audio_in_destroy, audio_in_prepare, audio_in_unprepare)
 409  * Recommend to use as a VOIP only.
 410  * Recommend not to hold callback too long.(it affects latency)
 411  *
 412  * @remarks @a input must be created using audio_in_create().
 413  *
 414  * @param[in] input    An audio input handle
 415  * @param[in] callback notify stream callback when user can read data (#audio_in_stream_cb)
 416  * @param[in] userdata user data to be retrieved when callback is called
 417  * @return @c 0 on success,
 418  *         otherwise a negative error value
 419  * @retval #AUDIO_IO_ERROR_NONE Successful
 420  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 421  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 422  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
 423  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 424  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 425  *
 426  * @see audio_out_set_stream_cb()
 427  */
 428 int audio_in_set_stream_cb(audio_in_h input, audio_in_stream_cb callback, void* userdata);
 429
 430 /**
 431  * @brief Unregisters the callback function.
 432  *
 433  * @since_tizen 2.3
 434  *
 435  * @param[in] input The handle to the audio input
 436  * @return @c 0 on success,
 437  *         otherwise a negative error value
 438  * @retval #AUDIO_IO_ERROR_NONE Successful
 439  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 440  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 441  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 442  *
 443  * @see audio_in_set_interrupted_cb()
 444  */
 445 int audio_in_unset_stream_cb(audio_in_h input);
 446
 447 /**
 448  * @brief peek from audio in buffer
 449  *
 450  * @since_tizen 2.3
 451  *
 452  * @details This function works correctly only with read, write callback. Otherwise it won't operate as intended.
 453  *
 454  * @remarks @a Works only in asynchronous(event) mode. This will just retrieve buffer pointer from audio in buffer. Drop after use.
 455  *
 456  * @param[in] input The handle to the audio input
 457  * @param[out] buffer start buffer pointer of peeked audio in data
 458  * @param[in,out] length amount of audio in data to be peeked
 459  * @return @c 0 on success,
 460  *         otherwise a negative error value
 461  * @retval #AUDIO_IO_ERROR_NONE Successful
 462  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 463  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 464  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 465  *
 466  * @see audio_in_drop()
 467  */
 468 int audio_in_peek(audio_in_h input, const void **buffer, unsigned int *length);
 469
 470 /**
 471  * @brief drop peeked audio buffer.
 472  *
 473  * @details This function works correctly only with read, write callback. Otherwise it won't operate as intended.
 474  *
 475  * @since_tizen 2.3
 476  *
 477  * @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.
 478  *
 479  * @param[in] input The handle to the audio input
 480  * @return 0 on success, otherwise a negative error value
 481  * @retval #AUDIO_IO_ERROR_NONE Successful
 482  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 483  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 484  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 485  *
 486  * @see audio_in_peek()
 487  */
 488 int audio_in_drop(audio_in_h input);
 489
 490
 491
 492 //
 493 // AUDIO OUTPUT
 494 //
 495
 496 /**
 497  * @}
 498 */
 499
 500 /**
 501  * @addtogroup CAPI_MEDIA_AUDIO_OUT_MODULE
 502  * @{
 503  */
 504
 505 /**
 506  * @brief Called when audio out data can be written in asynchronous(event) mode.
 507  *
 508  * @since_tizen 2.3
 509  *
 510  * @remarks @a use audio_out_write() to write pcm data inside this callback.
 511  * @param[in] handle The handle to the audio output
 512  * @param[in] nbytes The amount of audio in data which can be written.
 513  * @param[in] userdata The user data passed from the callback registration function
 514  *
 515  * @see audio_out_set_stream_cb()
 516  */
 517 typedef void (*audio_out_stream_cb)(audio_out_h handle, size_t nbytes, void *userdata);
 518
 519 /**
 520  * @brief Creates an audio device instance and returns an output handle to play PCM (pulse-code modulation) data.
 521
 522  * @since_tizen 2.3
 523  *
 524  * @details This function is used for audio output initialization.
 525  *
 526  * @remarks @a output must be released by audio_out_destroy().
 527  *
 528  * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
 529  * @param[in] channel The audio channel type (mono or stereo)
 530  * @param[in] type The type of audio sample (8- or 16-bit)
 531  * @param[in] sound_type The type of sound (#sound_type_e)
 532  * @param[out] output An audio output handle is created on success
 533  * @return @c 0 on success,
 534  *         otherwise a negative error value
 535  * @retval #AUDIO_IO_ERROR_NONE Successful
 536  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 537  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 538  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
 539  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 540  *
 541  * @see audio_out_destroy()
 542 */
 543 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);
 544
 545 /**
 546  * @brief Releases the audio output handle, along with all its resources.
 547  *
 548  * @since_tizen 2.3
 549  *
 550  * @param[in] output The handle to the audio output to destroy
 551  * @return @c 0 on success,
 552  *         otherwise a negative error value
 553  * @retval #AUDIO_IO_ERROR_NONE Successful
 554  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 555  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 556  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
 557  *
 558  * @see audio_out_create()
 559 */
 560 int audio_out_destroy(audio_out_h output);
 561
 562 /**
 563  * @brief Prepares playing audio output, this must be called before audio_out_write().
 564  *
 565  * @since_tizen 2.3
 566  *
 567  * @param[in] output The handle to the audio output
 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  *
 573  * @see audio_out_unprepare()
 574  */
 575 int audio_out_prepare(audio_out_h output);
 576
 577 /**
 578  * @brief Unprepares playing audio output.
 579  *
 580  * @since_tizen 2.3
 581  *
 582  * @param[in] output The handle to the audio output
 583  * @return @c 0 on success,
 584  *         otherwise a negative error value
 585  * @retval #AUDIO_IO_ERROR_NONE Successful
 586  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 587  *
 588  * @see audio_out_prepare()
 589  */
 590 int audio_out_unprepare(audio_out_h output);
 591
 592 /**
 593  * @brief Starts writing the audio data to the device.
 594  *
 595  * @since_tizen 2.3
 596  *
 597  * @param[in] output The handle to the audio output
 598  * @param[in,out] buffer The PCM buffer address
 599  * @param[in] length The length of the PCM buffer (in bytes)
 600  * @return The written data size on success,
 601  *         otherwise a negative error value
 602  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 603  * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
 604  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 605 */
 606 int audio_out_write(audio_out_h output, void *buffer, unsigned int length);
 607
 608 /**
 609  * @brief Gets the size to be allocated for the audio output buffer.
 610  *
 611  * @since_tizen 2.3
 612  *
 613  * @param[in] output The handle to the audio output
 614  * @param[out] size The suggested buffer size (in bytes, the maximum size is 1 MB)
 615  * @return  @c 0 on success,
 616  *          otherwise a negative error value
 617  * @retval  #AUDIO_IO_ERROR_NONE Successful
 618  * @retval  #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 619  *
 620  * @see audio_out_write()
 621 */
 622 int audio_out_get_buffer_size(audio_out_h output, int *size);
 623
 624 /**
 625  * @brief Gets the sample rate of the audio output data stream.
 626  *
 627  * @since_tizen 2.3
 628  *
 629  * @param[in] output The handle to the audio output
 630  * @param[out] sample_rate The audio sample rate in Hertz (8000 ~ 48000)
 631  * @return  @c 0 on success,
 632  *          otherwise a negative error value
 633  * @retval  #AUDIO_IO_ERROR_NONE Successful
 634  * @retval  #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 635 */
 636 int audio_out_get_sample_rate(audio_out_h output, int *sample_rate);
 637
 638 /**
 639  * @brief Gets the channel type of the audio output data stream.
 640  * @details The audio channel type defines whether the audio is mono or stereo.
 641  *
 642  * @since_tizen 2.3
 643  *
 644  * @param[in] output The handle to the audio output
 645  * @param[out] channel The audio channel type
 646  * @return @c 0 on success,
 647  *         otherwise a negative error value
 648  * @retval #AUDIO_IO_ERROR_NONE Successful
 649  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 650 */
 651 int audio_out_get_channel(audio_out_h output, audio_channel_e *channel);
 652
 653 /**
 654  * @brief Gets the sample audio format (8-bit or 16-bit) of the audio output data stream.
 655  *
 656  * @since_tizen 2.3
 657  *
 658  * @param[in] output The handle to the audio output
 659  * @param[out] type The audio sample type
 660  * @return @c 0 on success,
 661  *         otherwise a negative error value
 662  * @retval #AUDIO_IO_ERROR_NONE Successful
 663  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 664 */
 665 int audio_out_get_sample_type(audio_out_h output, audio_sample_type_e *type);
 666
 667
 668 /**
 669  * @brief Gets the sound type supported by the audio output device.
 670  *
 671  * @since_tizen 2.3
 672  *
 673  * @param[in] output The handle to the audio output
 674  * @param[out] type The sound type
 675  * @return @c 0 on success,
 676  *         otherwise a negative error value
 677  * @retval #AUDIO_IO_ERROR_NONE Successful
 678  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 679 */
 680 int audio_out_get_sound_type(audio_out_h output, sound_type_e *type);
 681
 682 /**
 683  * @brief Registers a callback function to be invoked when the audio output handle is interrupted or the interrupt is completed.
 684  *
 685  * @since_tizen 2.3
 686  *
 687  * @param[in] output The handle to the audio output
 688  * @param[in] callback  The callback function to register
 689  * @param[in] user_data The user data to be passed to the callback function
 690  * @return @c 0 on success,
 691  *         otherwise a negative error value
 692  * @retval #AUDIO_IO_ERROR_NONE Successful
 693  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 694  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 695  *
 696  * @post audio_io_interrupted_cb() will be invoked.
 697  * @see audio_out_unset_interrupted_cb()
 698  * @see audio_io_interrupted_cb()
 699  */
 700 int audio_out_set_interrupted_cb(audio_out_h output, audio_io_interrupted_cb callback, void *user_data);
 701
 702 /**
 703  * @brief Unregisters the callback function.
 704  *
 705  * @since_tizen 2.3
 706  *
 707  * @param[in] output The handle to the audio output
 708  * @return @c 0 on success,
 709  *         otherwise a negative error value
 710  * @retval #AUDIO_IO_ERROR_NONE Successful
 711  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 712  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 713  *
 714  * @see audio_out_set_interrupted_cb()
 715  */
 716 int audio_out_unset_interrupted_cb(audio_out_h output);
 717
 718 /**
 719  * @brief Ignores session for output.
 720  *
 721  * @since_tizen 2.3
 722  *
 723  * @param[in] output The handle to the audio output
 724  * @return @c 0 on success,
 725  *         otherwise a negative error value
 726  * @retval #AUDIO_IO_ERROR_NONE Successful
 727  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 728  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 729  */
 730 int audio_out_ignore_session(audio_out_h output);
 731
 732 /**
 733  * @brief Sets an asynchronous(event) callback function to handle playing PCM (pulse-code modulation) data.
 734  *
 735  * @since_tizen 2.3
 736  *
 737  * @details @a callback will be called when you can write a PCM data.
 738  * It might cause dead lock if change the state of audio handle in callback.
 739  * (ex: audio_in_destroy, audio_in_prepare, audio_in_unprepare)
 740  * Recommend to use as a VOIP only.
 741  * Recommend not to hold callback too long.(it affects latency)
 742  *
 743  * @remarks @a output must be created using audio_out_create().
 744  *
 745  * @param[in] output   An audio output handle
 746  * @param[in] callback notify stream callback when user can write data (#audio_out_stream_cb)
 747  * @param[in] userdata user data to be retrieved when callback is called
 748  * @return 0 on success, otherwise a negative error value
 749  * @retval #AUDIO_IO_ERROR_NONE Successful
 750  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 751  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 752  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
 753  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 754  *
 755  * @see audio_in_set_stream_cb()
 756  */
 757 int audio_out_set_stream_cb(audio_out_h output, audio_out_stream_cb callback, void* userdata);
 758
 759 /**
 760  * @brief Unregisters the callback function.
 761  *
 762  * @since_tizen 2.3
 763  *
 764  * @param[in] output The handle to the audio output
 765  * @return 0 on success, otherwise a negative error value
 766  * @retval #AUDIO_IO_ERROR_NONE Successful
 767  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 768  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 769  *
 770  * @see audio_out_set_stream_cb()
 771  */
 772 int audio_out_unset_stream_cb(audio_out_h output);
 773 /**
 774  * @}
 775 */
 776
 777 #ifdef __cplusplus
 778 }
 779 #endif
 780
 781 #endif /* __TIZEN_MEDIA_AUDIO_IO_H__ */