include/audio_io.h

   1 /*
   2  * Copyright (c) 2015 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 <sys/types.h>
  21 #include <tizen.h>
  22 #include <sound_manager.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 @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  42  */
  43 typedef struct audio_io_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 @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  57  */
  58 typedef struct audio_io_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 @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  72  */
  73 typedef enum {
  74     AUDIO_SAMPLE_TYPE_U8 = 0x70,    /**< Unsigned 8-bit audio samples */
  75     AUDIO_SAMPLE_TYPE_S16_LE,       /**< Signed 16-bit audio samples */
  76 } audio_sample_type_e;
  77
  78 /**
  79  * @brief Enumeration for audio channel.
  80  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  81  */
  82 typedef enum {
  83     AUDIO_CHANNEL_MONO = 0x80,                  /**< 1 channel, mono */
  84     AUDIO_CHANNEL_STEREO,                       /**< 2 channel, stereo */
  85 } audio_channel_e;
  86
  87 /**
  88  * @brief Enumeration for audio input and output state.
  89  * @since_tizen 3.0
  90  */
  91 typedef enum {
  92     AUDIO_IO_STATE_IDLE,      /**< Audio-io handle is created, but not prepared */
  93     AUDIO_IO_STATE_RUNNING,   /**< Audio-io handle is ready and the stream is running */
  94     AUDIO_IO_STATE_PAUSED,    /**< Audio-io handle is ready and the stream is paused */
  95 } audio_io_state_e;
  96
  97 /**
  98  * @brief Enumeration for audio input and output error.
  99  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 100  */
 101 typedef enum {
 102     AUDIO_IO_ERROR_NONE                = TIZEN_ERROR_NONE,              /**< Successful */
 103     AUDIO_IO_ERROR_OUT_OF_MEMORY       = TIZEN_ERROR_OUT_OF_MEMORY,     /**< Out of memory */
 104     AUDIO_IO_ERROR_INVALID_PARAMETER   = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
 105     AUDIO_IO_ERROR_INVALID_OPERATION   = TIZEN_ERROR_INVALID_OPERATION, /**< Invalid operation */
 106     AUDIO_IO_ERROR_PERMISSION_DENIED   = TIZEN_ERROR_PERMISSION_DENIED, /**< Device open error by security */
 107     AUDIO_IO_ERROR_NOT_SUPPORTED       = TIZEN_ERROR_NOT_SUPPORTED,     /**< Not supported */
 108     AUDIO_IO_ERROR_DEVICE_NOT_OPENED   = TIZEN_ERROR_AUDIO_IO | 0x01,   /**< Device open error */
 109     AUDIO_IO_ERROR_DEVICE_NOT_CLOSED   = TIZEN_ERROR_AUDIO_IO | 0x02,   /**< Device close error */
 110     AUDIO_IO_ERROR_INVALID_BUFFER      = TIZEN_ERROR_AUDIO_IO | 0x03,   /**< Invalid buffer pointer */
 111     AUDIO_IO_ERROR_SOUND_POLICY        = TIZEN_ERROR_AUDIO_IO | 0x04,   /**< Sound policy error */
 112     AUDIO_IO_ERROR_INVALID_STATE       = TIZEN_ERROR_AUDIO_IO | 0x05,   /**< Invalid state (Since 3.0) */
 113     AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE  = TIZEN_ERROR_AUDIO_IO | 0x06,   /**< Not supported stream type (Since 3.0) */
 114 } audio_io_error_e;
 115
 116 /**
 117  * @deprecated Deprecated since 3.0
 118  * @brief Enumeration for audio IO interrupted messages.
 119  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 120  */
 121 typedef enum {
 122     AUDIO_IO_INTERRUPTED_COMPLETED = 0,         /**< Interrupt completed */
 123     AUDIO_IO_INTERRUPTED_BY_MEDIA,              /**< Interrupted by a media application */
 124     AUDIO_IO_INTERRUPTED_BY_CALL,               /**< Interrupted by an incoming call */
 125     AUDIO_IO_INTERRUPTED_BY_EARJACK_UNPLUG,     /**< Interrupted by unplugging headphones */
 126     AUDIO_IO_INTERRUPTED_BY_RESOURCE_CONFLICT,  /**< Interrupted by a resource conflict */
 127     AUDIO_IO_INTERRUPTED_BY_ALARM,              /**< Interrupted by an alarm */
 128     AUDIO_IO_INTERRUPTED_BY_EMERGENCY,          /**< Interrupted by an emergency */
 129     AUDIO_IO_INTERRUPTED_BY_NOTIFICATION,       /**< Interrupted by a notification */
 130 } audio_io_interrupted_code_e;
 131
 132 /**
 133  * @deprecated Deprecated since 3.0. Use sound_stream_focus_state_changed_cb instead.
 134  * @brief Called when audio input or output is interrupted.
 135  *
 136  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 137  * @param[in] error_code The interrupted error code
 138  * @param[in] user_data The user data passed from the callback registration function
 139  *
 140  * @see audio_in_set_interrupted_cb()
 141  * @see audio_out_set_interrupted_cb()
 142  * @see audio_in_unset_interrupted_cb()
 143  * @see audio_out_unset_interrupted_cb()
 144  */
 145 typedef void (*audio_io_interrupted_cb)(audio_io_interrupted_code_e code, void *user_data);
 146
 147 /**
 148  * @}
 149  */
 150
 151 /**
 152  * @addtogroup CAPI_MEDIA_AUDIO_IN_MODULE
 153  * @{
 154  */
 155
 156 /**
 157  * @brief Called when audio input data is available in asynchronous(event) mode.
 158  *
 159  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 160  *
 161  * @remarks @a use audio_in_peek() to get audio in data inside callback, use audio_in_drop() after use of peeked data.
 162  *
 163  * @param[in] handle The handle to the audio input
 164  * @param[in] nbytes The amount of available audio in data which can be peeked.
 165  * @param[in] user_data The user data passed from the callback registration function
 166  *
 167  * @see audio_in_set_stream_cb()
 168  */
 169 typedef void (*audio_in_stream_cb)(audio_in_h handle, size_t nbytes, void *user_data);
 170
 171 /**
 172  * @brief Called when the state of audio input is changed.
 173  *
 174  * @since_tizen 3.0
 175  *
 176  * @param[in] handle The handle of the audio input
 177  * @param[in] previous The previous state of the audio input
 178  * @param[in] current The current state of the audio input
 179  * @param[in] by_policy @c true if the state is changed by policy, otherwise @c false if the state is not changed by policy
 180  * @param[in] user_data The user data passed from the callback registration function
 181  *
 182  * @see audio_in_set_state_changed_cb()
 183  * @see audio_in_unset_state_changed_cb()
 184  */
 185 typedef void (*audio_in_state_changed_cb)(audio_in_h handle, audio_io_state_e previous, audio_io_state_e current, bool by_policy, void *user_data);
 186
 187 /**
 188  * @brief Creates an audio device instance and returns an input handle to record PCM (pulse-code modulation) data.
 189  *
 190  * @details This function is used for audio input initialization.
 191  *
 192  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 193  * @privlevel public
 194  * @privilege %http://tizen.org/privilege/recorder
 195  *
 196  * @remarks @a input must be released using audio_in_destroy().
 197  *
 198  * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
 199  * @param[in] channel The audio channel type (mono or stereo)
 200  * @param[in] type The type of audio sample (8- or 16-bit)
 201  * @param[out] input An audio input handle is created on success
 202  * @return @c 0 on success,
 203  *         otherwise a negative error value
 204  * @retval #AUDIO_IO_ERROR_NONE Successful
 205  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 206  * @retval #AUDIO_IO_ERROR_PERMISSION_DENIED Permission denied
 207  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 208  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
 209  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 210  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 211  *
 212  * @post The state will be #AUDIO_IO_STATE_IDLE.\n
 213  *       audio_in_set_stream_info() is recommended to be called after this API.
 214  * @see audio_in_destroy()
 215  */
 216 int audio_in_create(int sample_rate, audio_channel_e channel, audio_sample_type_e type, audio_in_h *input);
 217
 218 /**
 219  * @deprecated Deprecated since 3.0. Use sound_manager_create_stream_information() instead.
 220  * @brief Creates an audio loopback device instance and returns an input handle to record PCM (pulse-code modulation) data.
 221  *
 222  * @details This function is used for audio loopback input initialization.
 223  *
 224  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 225  * @privlevel public
 226  * @privilege %http://tizen.org/privilege/recorder
 227  *
 228  * @remarks @a input must be released using audio_in_destroy().
 229  *
 230  * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
 231  * @param[in] channel The audio channel type, mono, or stereo
 232  * @param[in] type The type of audio sample (8- or 16-bit)
 233  * @param[out] input An audio input handle will be created, if successful
 234  * @return @c 0 on success,
 235  *         otherwise a negative error value
 236  * @retval #AUDIO_IO_ERROR_NONE Successful
 237  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 238  * @retval #AUDIO_IO_ERROR_PERMISSION_DENIED Permission denied
 239  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 240  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
 241  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 242  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 243  *
 244  * @see audio_in_destroy()
 245  */
 246 int audio_in_create_loopback(int sample_rate, audio_channel_e channel, audio_sample_type_e type , audio_in_h* input);
 247
 248 /**
 249  * @brief Releases the audio input handle and all its resources associated with an audio stream.
 250  *
 251  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 252  *
 253  * @param[in] input The handle to the audio input to destroy
 254  * @return @c 0 on success,
 255  *         otherwise a negative error value
 256  * @retval #AUDIO_IO_ERROR_NONE Successful
 257  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 258  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
 259  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 260  *
 261  * @see audio_in_create()
 262  */
 263 int audio_in_destroy(audio_in_h input);
 264
 265 /**
 266  * @brief Sets the sound stream information to the audio input.
 267  *
 268  * @since_tizen 3.0
 269  *
 270  * @remarks @a the sound stream information includes audio routing and volume type.
 271  *          For more details, you can refer to @ref CAPI_MEDIA_SOUND_MANAGER_MODULE
 272  *          System, Alarm, Notification, Emergency, Voice Information, Ringtone VOIP and Ringtone Call stream types are not supported in this API.
 273  *
 274  * @param[in] input The handle to the audio input
 275  * @param[in] stream_info The handle of stream information
 276  * @return @c 0 on success,
 277  *         otherwise a negative error value
 278  * @retval #AUDIO_IO_ERROR_NONE Successful
 279  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 280  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 281  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 282  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE Not supported stream type
 283  *
 284  * @pre The state should be #AUDIO_IO_STATE_IDLE.\n
 285  *      Call audio_in_create() before calling this function.
 286  * @post Call audio_in_prepare() after calling this function.
 287  * @see sound_manager_create_stream_information()
 288  * @see sound_manager_destroy_stream_information()
 289  */
 290 int audio_in_set_stream_info(audio_in_h input, sound_stream_info_h stream_info);
 291
 292 /**
 293  * @brief Prepares the audio input for reading audio data by starting buffering of audio data from the device.
 294  *
 295  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 296  *
 297  * @param[in] input The handle to the audio input
 298  * @return @c 0 on success,
 299  *         otherwise a negative error value
 300  * @retval #AUDIO_IO_ERROR_NONE Successful
 301  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 302  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 303  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 304  *
 305  * @post The state will be #AUDIO_IO_STATE_RUNNING.
 306  * @see audio_in_unprepare()
 307  */
 308 int audio_in_prepare(audio_in_h input);
 309
 310 /**
 311  * @brief Unprepares the audio input.
 312  *
 313  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 314  *
 315  * @param[in] input The handle to the audio input
 316  * @return @c 0 on success,
 317  *         otherwise a negative error value
 318  * @retval #AUDIO_IO_ERROR_NONE Successful
 319  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 320  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 321  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 322  *
 323  * @post The state will be #AUDIO_IO_STATE_IDLE.
 324  * @see audio_in_prepare()
 325  */
 326 int audio_in_unprepare(audio_in_h input);
 327
 328 /**
 329  * @brief Pauses buffering of audio data from the device.
 330  *
 331  * @since_tizen 3.0
 332  *
 333  * @param[in] input The handle to the audio input
 334  * @return @c 0 on success,
 335  *         otherwise a negative error value
 336  * @retval #AUDIO_IO_ERROR_NONE Successful
 337  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 338  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 339  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 340  *
 341  * @pre The state should be #AUDIO_IO_STATE_RUNNING.
 342  * @post The state will be #AUDIO_IO_STATE_PAUSED.
 343  * @see audio_in_resume()
 344  */
 345 int audio_in_pause(audio_in_h input);
 346
 347 /**
 348  * @brief Resumes buffering audio data from the device.
 349  *
 350  * @since_tizen 3.0
 351  *
 352  * @param[in] input The handle to the audio input
 353  * @return @c 0 on success,
 354  *         otherwise a negative error value
 355  * @retval #AUDIO_IO_ERROR_NONE Successful
 356  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 357  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 358  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 359  *
 360  * @pre The state should be #AUDIO_IO_STATE_PAUSED.
 361  * @post The state will be #AUDIO_IO_STATE_RUNNING.
 362  * @see audio_in_pause()
 363  */
 364 int audio_in_resume(audio_in_h input);
 365
 366 /**
 367  * @brief Flushes and discards buffered audio data from the input stream.
 368  *
 369  * @since_tizen 2.4
 370  *
 371  * @param[in] input The handle to the audio input
 372  * @return @c 0 on success,
 373  *         otherwise a negative error value
 374  * @retval #AUDIO_IO_ERROR_NONE Successful
 375  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 376  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 377  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 378  *
 379  * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
 380  */
 381 int audio_in_flush(audio_in_h input);
 382
 383 /**
 384  * @brief Reads audio data from the audio input buffer.
 385  *
 386  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 387  *
 388  * @param[in] input The handle to the audio input
 389  * @param[out] buffer The PCM buffer address
 390  * @param[in] length The length of the PCM data buffer (in bytes)
 391  * @return The number of read bytes on success,
 392  *         otherwise a negative error value
 393  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 394  * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
 395  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 396  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 397  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 398  *
 399  * @pre The state should be #AUDIO_IO_STATE_RUNNING.
 400  */
 401 int audio_in_read(audio_in_h input, void *buffer, unsigned int length);
 402
 403 /**
 404  * @brief Gets the size to be allocated for the audio input buffer.
 405  *
 406  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 407  *
 408  * @param[in] input The handle to the audio input
 409  * @param[out] size The buffer size (in bytes, the maximum size is 1 MB)
 410  * @return @c 0 on success,
 411  *         otherwise a negative error value
 412  * @retval #AUDIO_IO_ERROR_NONE Successful
 413  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 414  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 415  * @see audio_in_read()
 416  */
 417 int audio_in_get_buffer_size(audio_in_h input, int *size);
 418
 419 /**
 420  * @brief Gets the sample rate of the audio input data stream.
 421  *
 422  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 423  *
 424  * @param[in] input The handle to the audio input
 425  * @param[out] sample_rate The audio sample rate in Hertz (8000 ~ 48000)
 426  * @return @c 0 on success,
 427  *         otherwise a negative error value
 428  * @retval #AUDIO_IO_ERROR_NONE Successful
 429  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 430  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 431  */
 432 int audio_in_get_sample_rate(audio_in_h input, int *sample_rate);
 433
 434 /**
 435  * @brief Gets the channel type of the audio input data stream.
 436  *
 437  * @details The audio channel type defines whether the audio is mono or stereo.
 438  *
 439  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 440  *
 441  * @param[in] input The handle to the audio input
 442  * @param[out] channel The audio channel type
 443  * @return @c 0 on success,
 444  *         otherwise a negative error value
 445  * @retval #AUDIO_IO_ERROR_NONE Successful
 446  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 447  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 448  */
 449 int audio_in_get_channel(audio_in_h input, audio_channel_e *channel);
 450
 451 /**
 452  * @brief Gets the sample audio format (8-bit or 16-bit) of the audio input data stream.
 453  *
 454  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 455  *
 456  * @param[in] input The handle to the audio input
 457  * @param[out] type The audio sample type
 458  * @return @c 0 on success,
 459  *         otherwise a negative error value
 460  * @retval #AUDIO_IO_ERROR_NONE Successful
 461  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 462  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 463  */
 464 int audio_in_get_sample_type(audio_in_h input, audio_sample_type_e *type);
 465
 466 /**
 467  * @deprecated Deprecated since 3.0. Use sound_manager_create_stream_information() instead.
 468  * @brief Registers a callback function to be invoked when the audio input handle is interrupted or the interrupt is completed.
 469  *
 470  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 471  *
 472  * @param[in] input The handle to the audio input
 473  * @param[in] callback The callback function to register
 474  * @param[in] user_data The user data to be passed to the callback function
 475  * @return @c 0 on success,
 476  *         otherwise a negative error value
 477  * @retval #AUDIO_IO_ERROR_NONE Successful
 478  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 479  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 480  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 481  * @post audio_io_interrupted_cb() will be invoked.
 482  *
 483  * @see audio_in_unset_interrupted_cb()
 484  * @see audio_io_interrupted_cb()
 485  */
 486 int audio_in_set_interrupted_cb(audio_in_h input, audio_io_interrupted_cb callback, void *user_data);
 487
 488 /**
 489  * @deprecated Deprecated since 3.0
 490  * @brief Unregisters the callback function.
 491  *
 492  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 493  *
 494  * @param[in] input The handle to the audio input
 495  * @return @c 0 on success,
 496  *         otherwise a negative error value
 497  * @retval #AUDIO_IO_ERROR_NONE Successful
 498  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 499  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 500  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 501  *
 502  * @see audio_in_set_interrupted_cb()
 503  */
 504 int audio_in_unset_interrupted_cb(audio_in_h input);
 505
 506 /**
 507  * @deprecated Deprecated since 3.0
 508  * @brief Ignores session for input.
 509  *
 510  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 511  *
 512  * @param[in] input The handle to the audio input
 513  * @return @c 0 on success,
 514  *         otherwise a negative error value
 515  * @retval #AUDIO_IO_ERROR_NONE Successful
 516  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 517  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 518  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 519  */
 520 int audio_in_ignore_session(audio_in_h input);
 521
 522 /**
 523  * @brief Sets an asynchronous(event) callback function to handle recording PCM (pulse-code modulation) data.
 524  *
 525  * @details @a callback will be called when you can read a PCM data.
 526  * It might cause dead lock if change the state of audio handle in callback.
 527  * (ex: audio_in_destroy, audio_in_prepare, audio_in_unprepare)
 528  * Recommend to use as a VOIP only.
 529  * Recommend not to hold callback too long.(it affects latency)
 530  *
 531  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 532  *
 533  * @remarks @a input must be created using audio_in_create().
 534  *
 535  * @param[in] input    An audio input handle
 536  * @param[in] callback notify stream callback when user can read data (#audio_in_stream_cb)
 537  * @param[in] user_data user data to be retrieved when callback is called
 538  * @return @c 0 on success,
 539  *         otherwise a negative error value
 540  * @retval #AUDIO_IO_ERROR_NONE Successful
 541  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 542  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 543  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
 544  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 545  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 546  *
 547  * @see audio_out_set_stream_cb()
 548  */
 549 int audio_in_set_stream_cb(audio_in_h input, audio_in_stream_cb callback, void* user_data);
 550
 551 /**
 552  * @brief Unregisters the callback function.
 553  *
 554  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 555  *
 556  * @param[in] input The handle to the audio input
 557  * @return @c 0 on success,
 558  *         otherwise a negative error value
 559  * @retval #AUDIO_IO_ERROR_NONE Successful
 560  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 561  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 562  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 563  *
 564  * @see audio_in_set_interrupted_cb()
 565  */
 566 int audio_in_unset_stream_cb(audio_in_h input);
 567
 568 /**
 569  * @brief peek from audio in buffer
 570  *
 571  * @details This function works correctly only with read, write callback. Otherwise it won't operate as intended.
 572  *
 573  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 574  *
 575  * @remarks @a Works only in asynchronous(event) mode. This will just retrieve buffer pointer from audio in buffer. Drop after use.
 576  *
 577  * @param[in] input The handle to the audio input
 578  * @param[out] buffer start buffer pointer of peeked audio in data
 579  * @param[in,out] length amount of audio in data to be peeked
 580  * @return @c 0 on success,
 581  *         otherwise a negative error value
 582  * @retval #AUDIO_IO_ERROR_NONE Successful
 583  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 584  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 585  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 586  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 587  *
 588  * @pre The state should be #AUDIO_IO_STATE_RUNNING.
 589  * @see audio_in_drop()
 590  */
 591 int audio_in_peek(audio_in_h input, const void **buffer, unsigned int *length);
 592
 593 /**
 594  * @brief drop peeked audio buffer.
 595  *
 596  * @details This function works correctly only with read, write callback. Otherwise it won't operate as intended.
 597  *
 598  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 599  *
 600  * @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.
 601  *
 602  * @param[in] input The handle to the audio input
 603  * @return 0 on success, otherwise a negative error value
 604  * @retval #AUDIO_IO_ERROR_NONE Successful
 605  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 606  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 607  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 608  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 609  *
 610  * @pre The state should be #AUDIO_IO_STATE_RUNNING.
 611  * @see audio_in_peek()
 612  */
 613 int audio_in_drop(audio_in_h input);
 614
 615 /**
 616  * @brief Sets the state changed callback function to the audio input handle.
 617  *
 618  * @since_tizen 3.0
 619  *
 620  * @remarks @a input must be created using audio_in_create().
 621  *
 622  * @param[in] input    The audio input handle
 623  * @param[in] callback the state changed callback called when the state of the handle is changed (#audio_in_state_changed_cb)
 624  * @param[in] user_data user data to be retrieved when callback is called
 625  * @return @c 0 on success,
 626  *         otherwise a negative error value
 627  * @retval #AUDIO_IO_ERROR_NONE Successful
 628  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 629  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 630  *
 631  * @see audio_in_unset_state_changed_cb()
 632  */
 633 int audio_in_set_state_changed_cb(audio_in_h input, audio_in_state_changed_cb callback, void* user_data);
 634
 635 /**
 636  * @brief Unregisters the state changed callback function of the audio input handle.
 637  *
 638  * @since_tizen 3.0
 639  *
 640  * @param[in] input The handle to the audio input
 641  * @return @c 0 on success,
 642  *         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_NOT_SUPPORTED Not supported
 646  *
 647  * @see audio_in_set_state_changed_cb()
 648  */
 649 int audio_in_unset_state_changed_cb(audio_in_h input);
 650
 651 /**
 652  * @}
 653  */
 654
 655 /**
 656  * @addtogroup CAPI_MEDIA_AUDIO_OUT_MODULE
 657  * @{
 658  */
 659
 660 /**
 661  * @brief Called when audio out data can be written in asynchronous(event) mode.
 662  *
 663  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 664  *
 665  * @remarks @a use audio_out_write() to write pcm data inside this callback.
 666  * @param[in] handle The handle to the audio output
 667  * @param[in] nbytes The amount of audio in data which can be written.
 668  * @param[in] user_data The user data passed from the callback registration function
 669  *
 670  * @see audio_out_set_stream_cb()
 671  */
 672 typedef void (*audio_out_stream_cb)(audio_out_h handle, size_t nbytes, void *user_data);
 673
 674 /**
 675  * @brief Called when the state of audio output is changed.
 676  *
 677  * @since_tizen 3.0
 678  *
 679  * @param[in] handle The handle of the audio output
 680  * @param[in] previous The previous state of the audio output
 681  * @param[in] current The current state of the audio output
 682  * @param[in] by_policy @c true if the state is changed by policy, otherwise @c false if the state is not changed by policy
 683  * @param[in] user_data The user data passed from the callback registration function
 684  *
 685  * @see audio_out_set_state_changed_cb()
 686  * @see audio_out_unset_state_changed_cb()
 687  */
 688 typedef void (*audio_out_state_changed_cb)(audio_out_h handle, audio_io_state_e previous, audio_io_state_e current, bool by_policy, void *user_data);
 689
 690 /**
 691  * @deprecated Deprecated since 3.0. Use audio_out_create_new() instead.
 692  * @brief Creates an audio device instance and returns an output handle to play PCM (pulse-code modulation) data.
 693  *
 694  * @details This function is used for audio output initialization.
 695  *
 696  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 697  *
 698  * @remarks @a output must be released by audio_out_destroy().
 699  *
 700  * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
 701  * @param[in] channel The audio channel type (mono or stereo)
 702  * @param[in] type The type of audio sample (8-bit or 16-bit)
 703  * @param[in] sound_type The type of sound (#sound_type_e)
 704  * @param[out] output An audio output handle is created on success
 705  * @return @c 0 on success,
 706  *         otherwise a negative error value
 707  * @retval #AUDIO_IO_ERROR_NONE Successful
 708  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 709  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 710  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
 711  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 712  *
 713  * @see audio_out_destroy()
 714  */
 715 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);
 716
 717 /**
 718  * @brief Creates an audio device instance and returns an output handle to play PCM (pulse-code modulation) data.
 719  *
 720  * @details This function is used for audio output initialization.
 721  *
 722  * @since_tizen 3.0
 723  *
 724  * @remarks @a output must be released by audio_out_destroy().
 725  *          It is recommended to call audio_out_set_stream_info() after this API.
 726  *
 727  * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
 728  * @param[in] channel The audio channel type (mono or stereo)
 729  * @param[in] type The type of audio sample (8-bit or 16-bit)
 730  * @param[out] output An audio output handle is created on success
 731  * @return @c 0 on success,
 732  *         otherwise a negative error value
 733  * @retval #AUDIO_IO_ERROR_NONE Successful
 734  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 735  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 736  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
 737  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 738  *
 739  * @post The state will be #AUDIO_IO_STATE_IDLE.\n
 740  *       audio_out_set_stream_info() is recommended to be called after this API.
 741  * @see audio_out_destroy()
 742  */
 743 int audio_out_create_new(int sample_rate, audio_channel_e channel, audio_sample_type_e type, audio_out_h *output);
 744
 745 /**
 746  * @brief Releases the audio output handle, along with all its resources.
 747  *
 748  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 749  *
 750  * @param[in] output The handle to the audio output to destroy
 751  * @return @c 0 on success,
 752  *         otherwise a negative error value
 753  * @retval #AUDIO_IO_ERROR_NONE Successful
 754  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 755  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 756  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
 757  *
 758  * @see audio_out_create()
 759  */
 760 int audio_out_destroy(audio_out_h output);
 761
 762 /**
 763  * @brief Sets the sound stream information to the audio output.
 764  *
 765  * @since_tizen 3.0
 766  *
 767  * @remarks @a the sound stream information includes audio routing and volume type.
 768  *          For more details, you can refer to @ref CAPI_MEDIA_SOUND_MANAGER_MODULE
 769  *          Voice Recognition and Loopback stream types are not supported in this API.
 770  *
 771  * @param[in] output The handle to the audio output
 772  * @param[in] stream_info The handle of stream information
 773  * @return @c 0 on success,
 774  *         otherwise a negative error value
 775  * @retval #AUDIO_IO_ERROR_NONE Successful
 776  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 777  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 778  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 779  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE Not supported stream type
 780  *
 781  * @pre The state should be #AUDIO_IO_STATE_IDLE.\n
 782  *      Call audio_out_create_new() before calling this function.
 783  * @post Call audio_out_prepare() after calling this function.
 784  * @see sound_manager_create_stream_information()
 785  * @see sound_manager_destroy_stream_information()
 786  */
 787 int audio_out_set_stream_info(audio_out_h output, sound_stream_info_h stream_info);
 788
 789 /**
 790  * @brief Prepares the audio output for playback, this must be called before audio_out_write().
 791  *
 792  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 793  *
 794  * @param[in] output The handle to the audio output
 795  * @return @c 0 on success,
 796  *         otherwise a negative error value
 797  * @retval #AUDIO_IO_ERROR_NONE Successful
 798  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 799  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 800  *
 801  * @post The state will be #AUDIO_IO_STATE_RUNNING.
 802  * @see audio_out_unprepare()
 803  */
 804 int audio_out_prepare(audio_out_h output);
 805
 806 /**
 807  * @brief Unprepares the audio output.
 808  *
 809  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 810  *
 811  * @param[in] output The handle to the audio output
 812  * @return @c 0 on success,
 813  *         otherwise a negative error value
 814  * @retval #AUDIO_IO_ERROR_NONE Successful
 815  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 816  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 817  *
 818  * @post The state will be #AUDIO_IO_STATE_IDLE.
 819  * @see audio_out_prepare()
 820  */
 821 int audio_out_unprepare(audio_out_h output);
 822
 823 /**
 824  * @brief Pauses feeding of audio data to the device.
 825  *
 826  * @since_tizen 3.0
 827  *
 828  * @param[in] output The handle to the audio output
 829  * @return @c 0 on success,
 830  *         otherwise a negative error value
 831  * @retval #AUDIO_IO_ERROR_NONE Successful
 832  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 833  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 834  *
 835  * @pre The state should be #AUDIO_IO_STATE_RUNNING.
 836  * @post The state will be #AUDIO_IO_STATE_PAUSED.
 837  * @see audio_out_resume()
 838  */
 839 int audio_out_pause(audio_out_h output);
 840
 841 /**
 842  * @brief Resumes feeding of audio data to the device.
 843  *
 844  * @since_tizen 3.0
 845  *
 846  * @param[in] output The handle to the audio output
 847  * @return @c 0 on success,
 848  *         otherwise a negative error value
 849  * @retval #AUDIO_IO_ERROR_NONE Successful
 850  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 851  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 852  *
 853  * @pre The state should be #AUDIO_IO_STATE_PAUSED.
 854  * @post The state will be #AUDIO_IO_STATE_RUNNING.
 855  * @see audio_out_pause()
 856  */
 857 int audio_out_resume(audio_out_h output);
 858
 859 /**
 860  * @brief Drains buffered audio data from the output stream.
 861  *
 862  * @details This function waits until drains stream buffer completely. (e.g end of playback)
 863  *
 864  * @since_tizen 2.4
 865  *
 866  * @param[in] output The handle to the audio output
 867  * @return @c 0 on success,
 868  *         otherwise a negative error value
 869  * @retval #AUDIO_IO_ERROR_NONE Successful
 870  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 871  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 872  *
 873  * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
 874  * @see audio_out_flush()
 875  */
 876 int audio_out_drain(audio_out_h output);
 877
 878 /**
 879  * @brief Flushes and discards buffered audio data from the output stream.
 880  *
 881  * @since_tizen 2.4
 882  *
 883  * @param[in] output The handle to the audio output
 884  * @return @c 0 on success,
 885  *         otherwise a negative error value
 886  * @retval #AUDIO_IO_ERROR_NONE Successful
 887  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 888  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 889  *
 890  * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
 891  * @see audio_out_drain()
 892  */
 893 int audio_out_flush(audio_out_h output);
 894
 895 /**
 896  * @brief Starts writing the audio data to the device.
 897  *
 898  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 899  *
 900  * @param[in] output The handle to the audio output
 901  * @param[in,out] buffer The PCM buffer address
 902  * @param[in] length The length of the PCM buffer (in bytes)
 903  * @return The written data size on success,
 904  *         otherwise a negative error value
 905  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 906  * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
 907  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 908  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 909  *
 910  * @pre The state should be #AUDIO_IO_STATE_RUNNING.
 911  */
 912 int audio_out_write(audio_out_h output, void *buffer, unsigned int length);
 913
 914 /**
 915  * @brief Gets the size to be allocated for the audio output buffer.
 916  *
 917  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 918  *
 919  * @param[in] output The handle to the audio output
 920  * @param[out] size The suggested buffer size (in bytes, the maximum size is 1 MB)
 921  * @return  @c 0 on success,
 922  *          otherwise a negative error value
 923  * @retval  #AUDIO_IO_ERROR_NONE Successful
 924  * @retval  #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 925  *
 926  * @see audio_out_write()
 927  */
 928 int audio_out_get_buffer_size(audio_out_h output, int *size);
 929
 930 /**
 931  * @brief Gets the sample rate of the audio output data stream.
 932  *
 933  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 934  *
 935  * @param[in] output The handle to the audio output
 936  * @param[out] sample_rate The audio sample rate in Hertz (8000 ~ 48000)
 937  * @return  @c 0 on success,
 938  *          otherwise a negative error value
 939  * @retval  #AUDIO_IO_ERROR_NONE Successful
 940  * @retval  #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 941  */
 942 int audio_out_get_sample_rate(audio_out_h output, int *sample_rate);
 943
 944 /**
 945  * @brief Gets the channel type of the audio output data stream.
 946  *
 947  * @details The audio channel type defines whether the audio is mono or stereo.
 948  *
 949  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 950  *
 951  * @param[in] output The handle to the audio output
 952  * @param[out] channel The audio channel type
 953  * @return @c 0 on success,
 954  *         otherwise a negative error value
 955  * @retval #AUDIO_IO_ERROR_NONE Successful
 956  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 957  */
 958 int audio_out_get_channel(audio_out_h output, audio_channel_e *channel);
 959
 960 /**
 961  * @brief Gets the sample audio format (8-bit or 16-bit) of the audio output data stream.
 962  *
 963  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 964  *
 965  * @param[in] output The handle to the audio output
 966  * @param[out] type The audio sample type
 967  * @return @c 0 on success,
 968  *         otherwise a negative error value
 969  * @retval #AUDIO_IO_ERROR_NONE Successful
 970  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 971  */
 972 int audio_out_get_sample_type(audio_out_h output, audio_sample_type_e *type);
 973
 974 /**
 975  * @brief Gets the sound type supported by the audio output device.
 976  *
 977  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 978  *
 979  * @param[in] output The handle to the audio output
 980  * @param[out] type The sound type
 981  * @return @c 0 on success,
 982  *         otherwise a negative error value
 983  * @retval #AUDIO_IO_ERROR_NONE Successful
 984  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 985  */
 986 int audio_out_get_sound_type(audio_out_h output, sound_type_e *type);
 987
 988 /**
 989  * @deprecated Deprecated since 3.0. Use sound_manager_create_stream_information() instead.
 990  * @brief Registers a callback function to be invoked when the audio output handle is interrupted or the interrupt is completed.
 991  *
 992  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 993  *
 994  * @param[in] output The handle to the audio output
 995  * @param[in] callback The callback function to register
 996  * @param[in] user_data The user data to be passed to the callback function
 997  * @return @c 0 on success,
 998  *         otherwise a negative error value
 999  * @retval #AUDIO_IO_ERROR_NONE Successful
1000  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1001  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
1002  *
1003  * @post audio_io_interrupted_cb() will be invoked.
1004  * @see audio_out_unset_interrupted_cb()
1005  * @see audio_io_interrupted_cb()
1006  */
1007 int audio_out_set_interrupted_cb(audio_out_h output, audio_io_interrupted_cb callback, void *user_data);
1008
1009 /**
1010  * @deprecated Deprecated since 3.0
1011  * @brief Unregisters the callback function.
1012  *
1013  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1014  *
1015  * @param[in] output The handle to the audio output
1016  * @return @c 0 on success,
1017  *         otherwise a negative error value
1018  * @retval #AUDIO_IO_ERROR_NONE Successful
1019  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1020  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
1021  *
1022  * @see audio_out_set_interrupted_cb()
1023  */
1024 int audio_out_unset_interrupted_cb(audio_out_h output);
1025
1026 /**
1027  * @deprecated Deprecated since 3.0
1028  * @brief Ignores session for output.
1029  *
1030  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1031  *
1032  * @param[in] output The handle to the audio output
1033  * @return @c 0 on success,
1034  *         otherwise a negative error value
1035  * @retval #AUDIO_IO_ERROR_NONE Successful
1036  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1037  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
1038  */
1039 int audio_out_ignore_session(audio_out_h output);
1040
1041 /**
1042  * @brief Sets an asynchronous(event) callback function to handle playing PCM (pulse-code modulation) data.
1043  *
1044  * @details @a callback will be called when you can write a PCM data.
1045  * It might cause dead lock if change the state of audio handle in callback.
1046  * (ex: audio_out_destroy, audio_out_prepare, audio_out_unprepare)
1047  * Recommend to use as a VOIP only.
1048  * Recommend not to hold callback too long.(it affects latency)
1049  *
1050  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1051  *
1052  * @remarks @a output must be created using audio_out_create().
1053  *
1054  * @param[in] output   An audio output handle
1055  * @param[in] callback notify stream callback when user can write data (#audio_out_stream_cb)
1056  * @param[in] user_data user data to be retrieved when callback is called
1057  * @return 0 on success, otherwise a negative error value
1058  * @retval #AUDIO_IO_ERROR_NONE Successful
1059  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1060  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
1061  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
1062  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
1063  *
1064  * @see audio_out_unset_stream_cb()
1065  */
1066 int audio_out_set_stream_cb(audio_out_h output, audio_out_stream_cb callback, void* user_data);
1067
1068 /**
1069  * @brief Unregisters the callback function.
1070  *
1071  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1072  *
1073  * @param[in] output The handle to the audio output
1074  * @return 0 on success, otherwise a negative error value
1075  * @retval #AUDIO_IO_ERROR_NONE Successful
1076  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1077  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
1078  *
1079  * @see audio_out_set_stream_cb()
1080  */
1081 int audio_out_unset_stream_cb(audio_out_h output);
1082
1083 /**
1084  * @brief Sets the state changed callback function to the audio output handle.
1085  *
1086  * @since_tizen 3.0
1087  *
1088  * @remarks @a input must be created using audio_out_create_new().
1089  *
1090  * @param[in] output    The audio output handle
1091  * @param[in] callback the state changed callback called when the state of the handle is changed (#audio_out_state_changed_cb)
1092  * @param[in] user_data user data to be retrieved when callback is called
1093  * @return @c 0 on success,
1094  *         otherwise a negative error value
1095  * @retval #AUDIO_IO_ERROR_NONE Successful
1096  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1097  *
1098  * @see audio_out_unset_state_changed_cb()
1099  */
1100 int audio_out_set_state_changed_cb(audio_out_h output, audio_out_state_changed_cb callback, void* user_data);
1101
1102 /**
1103  * @brief Unregisters the state changed callback function of the audio output handle.
1104  *
1105  * @since_tizen 3.0
1106  *
1107  * @param[in] output The handle to the audio output
1108  * @return @c 0 on success,
1109  *         otherwise a negative error value
1110  * @retval #AUDIO_IO_ERROR_NONE Successful
1111  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1112  *
1113  * @see audio_out_set_state_changed_cb()
1114  */
1115 int audio_out_unset_state_changed_cb(audio_out_h output);
1116
1117 /**
1118  * @}
1119  */
1120
1121 #ifdef __cplusplus
1122 }
1123 #endif
1124
1125 #endif /* __TIZEN_MEDIA_AUDIO_IO_H__ */