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