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