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