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