#include <tizen.h>
#include <sound_manager.h>
+#include <sys/types.h>
#ifdef __cplusplus
extern "C"
{
#endif
-#define AUDIO_IO_ERROR_CLASS TIZEN_ERROR_MULTIMEDIA_CLASS | 0x40
-
/**
* @file audio_io.h
- * @brief This file contains the Audio Input and Output API.
+ * @brief This file contains the Audio Input and Audio Output API.
*/
/**
*/
/**
- * @brief Audio input handle type.
+ * @brief The audio input handle.
+ * @since_tizen 2.3
*/
typedef struct audio_in_s *audio_in_h;
*/
/**
- * @brief Audio output handle type.
+ * @brief The audio output handle.
+ * @since_tizen 2.3
*/
typedef struct audio_out_s *audio_out_h;
*/
/**
- * @brief Enumerations of audio sample type with bit depth
+ * @brief Enumeration for audio sample type with bit depth.
+ * @since_tizen 2.3
*/
typedef enum
{
- AUDIO_SAMPLE_TYPE_U8 = 0x70, /**< Unsigned 8-bit audio samples */
- AUDIO_SAMPLE_TYPE_S16_LE, /**< Signed 16-bit audio samples */
+ AUDIO_SAMPLE_TYPE_U8 = 0x70, /**< Unsigned 8-bit audio samples */
+ AUDIO_SAMPLE_TYPE_S16_LE, /**< Signed 16-bit audio samples */
} audio_sample_type_e;
/**
- * @brief Enumerations of audio channel
+ * @brief Enumeration for audio channel.
+ * @since_tizen 2.3
*/
typedef enum {
- AUDIO_CHANNEL_MONO = 0x80, /**< 1 channel, mono */
- AUDIO_CHANNEL_STEREO, /**< 2 channel, stereo */
+ AUDIO_CHANNEL_MONO = 0x80, /**< 1 channel, mono */
+ AUDIO_CHANNEL_STEREO, /**< 2 channel, stereo */
} audio_channel_e;
/**
- * @brief Enumerations of audio input and output error code
+ * @brief Enumeration for audio input and output error.
+ * @since_tizen 2.3
*/
typedef enum{
- AUDIO_IO_ERROR_NONE = TIZEN_ERROR_NONE, /**<Successful */
+ AUDIO_IO_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
AUDIO_IO_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
AUDIO_IO_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
AUDIO_IO_ERROR_INVALID_OPERATION = TIZEN_ERROR_INVALID_OPERATION, /**< Invalid operation */
- AUDIO_IO_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Device open error by security */
- AUDIO_IO_ERROR_DEVICE_NOT_OPENED = AUDIO_IO_ERROR_CLASS | 0x01, /**< Device open error */
- AUDIO_IO_ERROR_DEVICE_NOT_CLOSED = AUDIO_IO_ERROR_CLASS | 0x02, /**< Device close error */
- AUDIO_IO_ERROR_INVALID_BUFFER = AUDIO_IO_ERROR_CLASS | 0x03, /**< Invalid buffer pointer */
- AUDIO_IO_ERROR_SOUND_POLICY = AUDIO_IO_ERROR_CLASS | 0x04, /**< Sound policy error */
+ AUDIO_IO_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Device open error by security */
+ AUDIO_IO_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported */
+ AUDIO_IO_ERROR_DEVICE_NOT_OPENED = TIZEN_ERROR_AUDIO_IO | 0x01, /**< Device open error */
+ AUDIO_IO_ERROR_DEVICE_NOT_CLOSED = TIZEN_ERROR_AUDIO_IO | 0x02, /**< Device close error */
+ AUDIO_IO_ERROR_INVALID_BUFFER = TIZEN_ERROR_AUDIO_IO | 0x03, /**< Invalid buffer pointer */
+ AUDIO_IO_ERROR_SOUND_POLICY = TIZEN_ERROR_AUDIO_IO | 0x04, /**< Sound policy error */
} audio_io_error_e;
/**
- * @brief Enumerations of audio io interrupted type
+ * @brief Enumeration for audio IO interrupted messages.
+ * @since_tizen 2.3
*/
typedef enum
{
} audio_io_interrupted_code_e;
/**
- * @brief Called when the audio input or output is interrupted.
- * @param[in] error_code The interrupted error code
- * @param[in] user_data The user data passed from the callback registration function
+ * @brief Called when audio input or output is interrupted.
+ *
+ * @since_tizen 2.3
+ * @param[in] error_code The interrupted error code
+ * @param[in] user_data The user data passed from the callback registration function
+ *
* @see audio_in_set_interrupted_cb()
* @see audio_out_set_interrupted_cb()
* @see audio_in_unset_interrupted_cb()
* @{
*/
-
//
//AUDIO INPUT
//
/**
* @brief Called when audio input data is available in asynchronous(event) mode.
*
+ * @since_tizen 2.3
*
* @remarks @a use audio_in_peek() to get audio in data inside callback, use audio_in_drop() after use of peeked data.
*
typedef void (*audio_in_stream_cb)(audio_in_h handle, size_t nbytes, void *userdata);
/**
- * @brief Creates an audio device instance and returns an input handle to record PCM (pulse-code modulation) data
- * @details This function is used for audio input initialization.
+ * @brief Creates an audio device instance and returns an input handle to record PCM (pulse-code modulation) data.
*
- * @remarks @a input must be release audio_in_destroy() by you.
+ * @since_tizen 2.3
+ * @privlevel public
+ * @privilege %http://tizen.org/privilege/recorder
*
- * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
- * @param[in] channel The audio channel type, mono, or stereo
- * @param[in] type The type of audio sample (8- or 16-bit)
- * @param[out] input An audio input handle will be created, if successful
+ * @details This function is used for audio input initialization.
*
- * @return 0 on success, otherwise a negative error value.
+ * @remarks @a input must be released using audio_in_destroy().
+ *
+ * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
+ * @param[in] channel The audio channel type (mono or stereo)
+ * @param[in] type The type of audio sample (8- or 16-bit)
+ * @param[out] input An audio input handle is created on success
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #AUDIO_IO_ERROR_NONE Successful
* @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #AUDIO_IO_ERROR_PERMISSION_DENIED Permission denied
* @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
* @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
- * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
+ * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
+ * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
* @see audio_in_destroy()
*/
-int audio_in_create(int sample_rate, audio_channel_e channel, audio_sample_type_e type , audio_in_h *input);
+int audio_in_create(int sample_rate, audio_channel_e channel, audio_sample_type_e type, audio_in_h *input);
/**
* @brief Creates an audio loopback device instance and returns an input handle to record PCM (pulse-code modulation) data.
*
+ * @since_tizen 2.3
+ * @privlevel public
+ * @privilege %http://tizen.org/privilege/recorder
*
* @details This function is used for audio loopback input initialization.
*
* @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
* @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
* @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
+ * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
* @see audio_in_destroy()
*/
int audio_in_create_loopback(int sample_rate, audio_channel_e channel, audio_sample_type_e type , audio_in_h* input);
/**
- * @brief Releases the audio input handle and all its resources associated with an audio stream
+ * @brief Releases the audio input handle and all its resources associated with an audio stream.
*
- * @param[in] input The handle to the audio input to destroy
+ * @since_tizen 2.3
*
- * @return 0 on success, otherwise a negative error value.
+ * @param[in] input The handle to the audio input to destroy
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #AUDIO_IO_ERROR_NONE Successful
* @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
+ * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
* @see audio_in_create()
*/
int audio_in_destroy(audio_in_h input);
-
-
/**
- * @brief Prepare reading audio in by starting buffering the audio data from the device
- * @param[in] input The handle to the audio input
- * @return 0 on success, otherwise a negative error value.
+ * @brief Prepares reading audio input by starting buffering of audio data from the device.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] input The handle to the audio input
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #AUDIO_IO_ERROR_NONE Successful
* @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
+ *
* @see audio_in_unprepare()
*/
int audio_in_prepare(audio_in_h input);
-
-
/**
- * @brief Unprepare reading audio in by stopping buffering the audio data from the device
- * @param[in] input The handle to the audio input
- * @return 0 on success, otherwise a negative error value.
+ * @brief Unprepares reading audio input by stopping buffering the audio data from the device.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] input The handle to the audio input
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #AUDIO_IO_ERROR_NONE Successful
* @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
* @see audio_in_prepare()
*/
int audio_in_unprepare(audio_in_h input);
-
-
/**
- * @brief Reads audio data from the audio input buffer
+ * @brief Reads audio data from the audio input buffer.
*
- * @param[in] input The handle to the audio input
- * @param[out] buffer The PCM buffer address
- * @param[in] length The length of PCM data buffer (in bytes)
+ * @since_tizen 2.3
*
- * @return Number of read bytes on success, otherwise a negative error value.
- * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
- * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
- * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
- * @pre audio_in_start_recording()
+ * @param[in] input The handle to the audio input
+ * @param[out] buffer The PCM buffer address
+ * @param[in] length The length of the PCM data buffer (in bytes)
+ * @return The number of read bytes on success,
+ * otherwise a negative error value
+ * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
+ * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
+ * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
+ * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
+ * @pre audio_in_start_recording().
*/
int audio_in_read(audio_in_h input, void *buffer, unsigned int length);
-
-
/**
- * @brief Gets the size to be allocated for audio input buffer
- * @param[in] input The handle to the audio input
- * @param[out] size The buffer size (in bytes). \n The maximum size is 1 MB.
+ * @brief Gets the size to be allocated for the audio input buffer.
*
- * @return 0 on success, otherwise a negative error value.
- * @retval #AUDIO_IO_ERROR_NONE Successful
- * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
+ * @since_tizen 2.3
+ *
+ * @param[in] input The handle to the audio input
+ * @param[out] size The buffer size (in bytes, the maximum size is 1 MB)
+ * @return @c 0 on success,
+ * otherwise a negative error value
+ * @retval #AUDIO_IO_ERROR_NONE Successful
+ * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
* @see audio_in_read()
*/
int audio_in_get_buffer_size(audio_in_h input, int *size);
-
-
/**
- * @brief Gets the sample rate of the audio input data stream
+ * @brief Gets the sample rate of the audio input data stream.
*
- * @param[in] input The handle to the audio input
- * @param[out] sample_rate The audio sample rate in Hertz (8000 ~ 48000)
+ * @since_tizen 2.3
*
- * @return 0 on success, otherwise a negative error value.
- * @retval #AUDIO_IO_ERROR_NONE Successful
- * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
+ * @param[in] input The handle to the audio input
+ * @param[out] sample_rate The audio sample rate in Hertz (8000 ~ 48000)
+ * @return @c 0 on success,
+ * otherwise a negative error value
+ * @retval #AUDIO_IO_ERROR_NONE Successful
+ * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
*/
int audio_in_get_sample_rate(audio_in_h input, int *sample_rate);
-
-
/**
- * @brief Gets the channel type of audio input data stream
+ * @brief Gets the channel type of the audio input data stream.
*
- * @details The audio channel type defines whether the audio is mono or stereo.
+ * @since_tizen 2.3
*
- * @param[in] input The handle to the audio input
- * @param[out] channel The audio channel type
+ * @details The audio channel type defines whether the audio is mono or stereo.
*
- * @return 0 on success, otherwise a negative error value.
+ * @param[in] input The handle to the audio input
+ * @param[out] channel The audio channel type
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #AUDIO_IO_ERROR_NONE Successful
* @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
*/
int audio_in_get_channel(audio_in_h input, audio_channel_e *channel);
-
-
/**
- * @brief Gets the sample audio format (8-bit or 16-bit) of audio input data stream
+ * @brief Gets the sample audio format (8-bit or 16-bit) of the audio input data stream.
*
- * @param[in] input The handle to the audio input
- * @param[out] type The audio sample type
+ * @since_tizen 2.3
*
- * @return 0 on success, otherwise a negative error value.
+ * @param[in] input The handle to the audio input
+ * @param[out] type The audio sample type
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #AUDIO_IO_ERROR_NONE Successful
* @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
*/
int audio_in_get_sample_type(audio_in_h input, audio_sample_type_e *type);
-
/**
- * @brief Registers a callback function to be invoked when the audio input handle is interrupted or interrupt completed.
- * @param[in] input The handle to the audio input
- * @param[in] callback The callback function to register
- * @param[in] user_data The user data to be passed to the callback function
- * @return 0 on success, otherwise a negative error value.
+ * @brief Registers a callback function to be invoked when the audio input handle is interrupted or the interrupt is completed.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] input The handle to the audio input
+ * @param[in] callback The callback function to register
+ * @param[in] user_data The user data to be passed to the callback function
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #AUDIO_IO_ERROR_NONE Successful
* @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
- * @post audio_io_interrupted_cb() will be invoked
+ * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
+ * @post audio_io_interrupted_cb() will be invoked.
+ *
* @see audio_in_unset_interrupted_cb()
* @see audio_io_interrupted_cb()
*/
/**
* @brief Unregisters the callback function.
- * @param[in] input The handle to the audio input
- * @return 0 on success, otherwise a negative error value.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] input The handle to the audio input
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #AUDIO_IO_ERROR_NONE Successful
* @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
+ * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
+ *
* @see audio_in_set_interrupted_cb()
*/
int audio_in_unset_interrupted_cb(audio_in_h input);
/**
- * @brief Ignore session for input
- * @param[in] input The handle to the audio input
- * @return 0 on success, otherwise a negative error value.
+ * @brief Ignores session for input.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] input The handle to the audio input
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #AUDIO_IO_ERROR_NONE Successful
* @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
- * @see
+ * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
*/
int audio_in_ignore_session(audio_in_h input);
/**
* @brief Sets an asynchronous(event) callback function to handle recording PCM (pulse-code modulation) data.
*
+ * @since_tizen 2.3
*
* @details @a callback will be called when you can read a PCM data.
* It might cause dead lock if change the state of audio handle in callback.
* @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
* @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
* @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
+ * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
*
* @see audio_out_set_stream_cb()
*/
/**
* @brief Unregisters the callback function.
*
+ * @since_tizen 2.3
*
* @param[in] input The handle to the audio input
* @return @c 0 on success,
* @retval #AUDIO_IO_ERROR_NONE Successful
* @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
+ * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
*
* @see audio_in_set_interrupted_cb()
*/
/**
* @brief peek from audio in buffer
*
+ * @since_tizen 2.3
*
* @details This function works correctly only with read, write callback. Otherwise it won't operate as intended.
*
* @retval #AUDIO_IO_ERROR_NONE Successful
* @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
+ * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
*
* @see audio_in_drop()
*/
*
* @details This function works correctly only with read, write callback. Otherwise it won't operate as intended.
*
+ * @since_tizen 2.3
*
* @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.
*
* @retval #AUDIO_IO_ERROR_NONE Successful
* @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
+ * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
*
* @see audio_in_peek()
*/
//
-// AUDIO OUTPUT
+// AUDIO OUTPUT
//
/**
/**
* @brief Called when audio out data can be written in asynchronous(event) mode.
*
+ * @since_tizen 2.3
*
* @remarks @a use audio_out_write() to write pcm data inside this callback.
* @param[in] handle The handle to the audio output
/**
* @brief Creates an audio device instance and returns an output handle to play PCM (pulse-code modulation) data.
+ * @since_tizen 2.3
*
* @details This function is used for audio output initialization.
*
* @remarks @a output must be released by audio_out_destroy().
*
- * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
- * @param[in] channel The audio channel type, mono, or stereo
- * @param[in] type The type of audio sample (8- or 16-bit)
- * @param[in] sound_type The type of sound (#sound_type_e)
- * @param[out] output An audio output handle will be created, if successful
- *
- * @return 0 on success, otherwise a negative error value.
+ * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
+ * @param[in] channel The audio channel type (mono or stereo)
+ * @param[in] type The type of audio sample (8- or 16-bit)
+ * @param[in] sound_type The type of sound (#sound_type_e)
+ * @param[out] output An audio output handle is created on success
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #AUDIO_IO_ERROR_NONE Successful
* @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
* @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
- * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
+ * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
*
* @see audio_out_destroy()
*/
-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);
-
-
+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);
/**
- * @brief Releases the audio output handle, along with all its resources
+ * @brief Releases the audio output handle, along with all its resources.
*
- * @param[in] output The handle to the audio output to destroy
+ * @since_tizen 2.3
*
- * @return 0 on success, otherwise a negative error value.
- * @retval #AUDIO_IO_ERROR_NONE Successful
- * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
- * @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
+ * @param[in] output The handle to the audio output to destroy
+ * @return @c 0 on success,
+ * otherwise a negative error value
+ * @retval #AUDIO_IO_ERROR_NONE Successful
+ * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
+ * @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
*
* @see audio_out_create()
*/
int audio_out_destroy(audio_out_h output);
/**
- * @brief Prepare playing audio out, this must be called before audio_out_write()
- * @param[in] output The handle to the audio output
- * @return 0 on success, otherwise a negative error value.
+ * @brief Prepares playing audio output, this must be called before audio_out_write().
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] output The handle to the audio output
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #AUDIO_IO_ERROR_NONE Successful
* @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
+ *
* @see audio_out_unprepare()
*/
int audio_out_prepare(audio_out_h output);
-
-
/**
- * @brief Unprepare playing audio out.
- * @param[in] output The handle to the audio output
- * @return 0 on success, otherwise a negative error value.
+ * @brief Unprepares playing audio output.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] output The handle to the audio output
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #AUDIO_IO_ERROR_NONE Successful
* @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
+ *
* @see audio_out_prepare()
*/
int audio_out_unprepare(audio_out_h output);
-
-
-
/**
- * @brief Starts writing the audio data to the device
+ * @brief Starts writing the audio data to the device.
*
- * @param[in] output The handle to the audio output
- * @param[in,out] buffer The PCM buffer address
- * @param[in] length The length of PCM buffer (in bytes)
+ * @since_tizen 2.3
*
- * @return Written data size on success, otherwise a negative error value.
- * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
- * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
+ * @param[in] output The handle to the audio output
+ * @param[in,out] buffer The PCM buffer address
+ * @param[in] length The length of the PCM buffer (in bytes)
+ * @return The written data size on success,
+ * otherwise a negative error value
+ * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
+ * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
*/
int audio_out_write(audio_out_h output, void *buffer, unsigned int length);
-
-
/**
- * @brief Gets the size to be allocated for audio output buffer
- * @param[in] output The handle to the audio output
- * @param[out] size The suggested buffer size (in bytes). \n The maximum size is 1 MB.
+ * @brief Gets the size to be allocated for the audio output buffer.
+ *
+ * @since_tizen 2.3
*
- * @return 0 on success, otherwise a negative error value.
+ * @param[in] output The handle to the audio output
+ * @param[out] size The suggested buffer size (in bytes, the maximum size is 1 MB)
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #AUDIO_IO_ERROR_NONE Successful
* @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
- * @see audio_out_write()
*
+ * @see audio_out_write()
*/
int audio_out_get_buffer_size(audio_out_h output, int *size);
-
-
/**
- * @brief Gets the sample rate of audio output data stream
+ * @brief Gets the sample rate of the audio output data stream.
*
- * @param[in] output The handle to the audio output
- * @param[out] sample_rate The audio sample rate in Hertz (8000 ~ 48000)
+ * @since_tizen 2.3
*
- * @return 0 on success, otherwise a negative error value.
+ * @param[in] output The handle to the audio output
+ * @param[out] sample_rate The audio sample rate in Hertz (8000 ~ 48000)
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #AUDIO_IO_ERROR_NONE Successful
* @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
*/
int audio_out_get_sample_rate(audio_out_h output, int *sample_rate);
-
-
/**
- * @brief Gets the channel type of audio output data stream
- *
- * @details The audio channel type defines whether the audio is mono or stereo.
+ * @brief Gets the channel type of the audio output data stream.
+ * @details The audio channel type defines whether the audio is mono or stereo.
*
- * @param[in] output The handle to the audio output
- * @param[out] channel The audio channel type
+ * @since_tizen 2.3
*
- * @return 0 on success, otherwise a negative error value.
+ * @param[in] output The handle to the audio output
+ * @param[out] channel The audio channel type
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #AUDIO_IO_ERROR_NONE Successful
* @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
*/
int audio_out_get_channel(audio_out_h output, audio_channel_e *channel);
-
-
/**
- * @brief Gets the sample audio format (8-bit or 16-bit) of audio output data stream
+ * @brief Gets the sample audio format (8-bit or 16-bit) of the audio output data stream.
*
- * @param[in] output The handle to the audio output
- * @param[out] type The audio sample type
- * @return 0 on success, otherwise a negative error value.
+ * @since_tizen 2.3
+ *
+ * @param[in] output The handle to the audio output
+ * @param[out] type The audio sample type
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #AUDIO_IO_ERROR_NONE Successful
* @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
*/
int audio_out_get_sample_type(audio_out_h output, audio_sample_type_e *type);
-
/**
- * @brief Gets the sound type supported by the audio output device
- * @param[in] output The handle to the audio output
- * @param[out] type The sound type
+ * @brief Gets the sound type supported by the audio output device.
*
- * @return 0 on success, otherwise a negative error value.
+ * @since_tizen 2.3
+ *
+ * @param[in] output The handle to the audio output
+ * @param[out] type The sound type
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #AUDIO_IO_ERROR_NONE Successful
* @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
*/
int audio_out_get_sound_type(audio_out_h output, sound_type_e *type);
-
/**
- * @brief Registers a callback function to be invoked when the audio out handle is interrupted or interrupt completed.
- * @param[in] output The handle to the audio output
+ * @brief Registers a callback function to be invoked when the audio output handle is interrupted or the interrupt is completed.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] output The handle to the audio output
* @param[in] callback The callback function to register
* @param[in] user_data The user data to be passed to the callback function
- * @return 0 on success, otherwise a negative error value.
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #AUDIO_IO_ERROR_NONE Successful
* @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
- * @post audio_io_interrupted_cb() will be invoked
+ *
+ * @post audio_io_interrupted_cb() will be invoked.
* @see audio_out_unset_interrupted_cb()
* @see audio_io_interrupted_cb()
*/
/**
* @brief Unregisters the callback function.
- * @param[in] output The handle to the audio output
- * @return 0 on success, otherwise a negative error value.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] output The handle to the audio output
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #AUDIO_IO_ERROR_NONE Successful
* @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
+ *
* @see audio_out_set_interrupted_cb()
*/
int audio_out_unset_interrupted_cb(audio_out_h output);
/**
- * @brief Ignore session for output
- * @param[in] output The handle to the audio output
- * @return 0 on success, otherwise a negative error value.
+ * @brief Ignores session for output.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] output The handle to the audio output
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #AUDIO_IO_ERROR_NONE Successful
* @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
- * @see
*/
int audio_out_ignore_session(audio_out_h output);
/**
* @brief Sets an asynchronous(event) callback function to handle playing PCM (pulse-code modulation) data.
*
+ * @since_tizen 2.3
*
* @details @a callback will be called when you can write a PCM data.
* It might cause dead lock if change the state of audio handle in callback.
/**
* @brief Unregisters the callback function.
*
+ * @since_tizen 2.3
*
* @param[in] output The handle to the audio output
* @return 0 on success, otherwise a negative error value
projects / platform / core / api / audio-io.git / commitdiff