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