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