#ifndef __TIZEN_SOUND_POOL_H__
#define __TIZEN_SOUND_POOL_H__
+#include "sound_pool_type.h"
+
#ifdef __cplusplus
extern "C" {
#endif
* @brief This file contains Tizen Sound Pool API.
*/
+/**
+ * @addtogroup CAPI_SOUND_POOL_MODULE
+ * @{
+ */
+
+/**
+ * @brief Called when sound pool state is changed.
+ *
+ * @since_tizen 3.0
+ * @param [in] pool The handle to the sound pool
+ * @param [in] prev_state Previous pool state
+ * @param [in] cur_state Current pool state
+ * @param [in] user_data The user data passed from the code where
+ * @ref sound_pool_set_state_change_callback() was
+ * called.
+ *
+ * @pre Create sound pool handler by calling @ref sound_pool_create()
+ * @pre Call @ref sound_pool_set_state_change_callback()
+ *
+ * @see sound_pool_create()
+ * @see sound_pool_set_state_change_callback()
+ * @see sound_pool_state_e
+ */
+typedef void (*sound_pool_state_change_cb) (sound_pool_h pool,
+ sound_pool_state_e prev_state, sound_pool_state_e cur_state,
+ void *user_data);
+
+/**
+ * @brief Called when sound pool stream state is changed.
+ *
+ * @since_tizen 3.0
+ * @param [in] pool The handle to the sound pool
+ * @param [in] tag Unique string that identifies source which was used
+ * for stream creation
+ * @param [in] id Unique stream identifier
+ * @param [in] prev_state Previous stream state
+ * @param [in] cur_state Current stream state
+ * @param [in] data The user data passed from the code where
+ * @ref sound_pool_stream_set_state_change_callback() was
+ * called.
+ *
+ * @pre Create sound pool handler by calling @ref sound_pool_create()
+ * @pre Load source to pool by calling @ref sound_pool_load_source_from_file()
+ * @pre Start source playback by calling @ref sound_pool_stream_play()
+ * @pre Call @ref sound_pool_stream_set_state_change_callback()
+ *
+ * @see sound_pool_create()
+ * @see sound_pool_load_source_from_file()
+ * @see sound_pool_stream_play()
+ * @see sound_pool_stream_set_state_change_callback()
+ * @see sound_pool_stream_state_e
+ */
+typedef void (*sound_pool_stream_state_change_cb) (sound_pool_h pool,
+ const char *tag, unsigned id, sound_pool_stream_state_e prev_state,
+ sound_pool_stream_state_e cur_state, void *user_data);
+
+/**
+ * @brief Creates sound pool instance that can be used for sound sources
+ * loading/unloading.
+ * @details Up to 32 sound pools can be created. Several pools can be active
+ * at the same time. Streams can be in playing state only when pool is
+ * active.
+ * @remarks When pool has been created, pool state is
+ * SOUND_POOL_STATE_INACTIVE. To activate a pool use
+ * @ref sound_pool_activate() function.
+ *
+ * @since_tizen 3.0
+ * @param [in] max_streams Maximum number of active streams
+ * @param [out] pool The handle to the pool that will be created
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER
+ * Invalid parameter (@a pool is NULL or @ max_streams is 0)
+ * @retval #SOUND_POOL_ERROR_OUT_OF_MEMORY
+ * Not enough memory to create sound pool
+ * @retval #SOUND_POOL_ERROR_INVALID_OPERATION
+ * Maximal amount of sound pools is exceeded (usually, 32 pools allowed)
+ *
+ * @see sound_pool_destroy()
+ */
+int sound_pool_create(unsigned max_streams, sound_pool_h *pool);
+
+/**
+ * @brief Destroys sound pool and cleans allocated memory.
+ * @details Stops all streams and unloads all sources associated with pool.
+ *
+ * @since_tizen 3.0
+ * @param [in] pool The handle to the pool that will be destroyed
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER
+ * Invalid parameter (@a pool is NULL or corrupted)
+ *
+ * @pre Create sound pool handler by calling @ref sound_pool_create()
+ *
+ * @see sound_pool_create()
+ */
+int sound_pool_destroy(sound_pool_h pool);
+
+/**
+ * @brief Loads sound source data from file to pool.
+ * @details After calling this routine the source can be accessed by its @a tag.
+ * @remarks Input data can be either raw or encoded.
+ * Each of loaded sources must have unique @a tag
+ * It is synchronous operation.
+ *
+ * @since_tizen 3.0
+ * @param [in] pool The handle to the sound pool
+ * @param [in] file_name The name of file that contains sound data
+ * @param [in] tag Unique string that will be used to identify source
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER
+ * Invalid parameter (@a pool is NULL or corrupted, @a file_name is
+ * NULL, @a tag is NULL or @a tag/@a file_name length is too long)
+ * @retval #SOUND_POOL_ERROR_OUT_OF_MEMORY Not enough memory to allocate source
+ * @retval #SOUND_POOL_ERROR_NO_SUCH_FILE No file determined by @a file_name
+ * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
+ *
+ * @pre Create sound @a pool handler by calling @ref sound_pool_create()
+ * @post Unload source from pool by calling @ref sound_pool_unload_source()
+ *
+ * @see sound_pool_create()
+ * @see sound_pool_destroy()
+ * @see sound_pool_unload_source()
+ */
+int sound_pool_load_source_from_file(sound_pool_h pool, const char *file_name,
+ const char *tag);
+
+/**
+ * @brief Unloads source from @a pool.
+ * @details Cleans memory. It is synchronous operation.
+ * @remarks The usage of @a tag name that was associated with unloaded source
+ * has no effect. It can be reused as well.
+ *
+ * @since_tizen 3.0
+ * @param [in] pool The handle to the sound pool
+ * @param [in] tag Unique string that identifies source
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER
+ * Invalid parameter (@a pool is NULL or corrupted, @a tag is NULL)
+ * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No sources tagged by @a tag exist
+ * in pool
+ *
+ * @pre Create sound @a pool handler by calling @ref sound_pool_create()
+ * @pre Load source to pool by calling @ref sound_pool_load_source_from_file()
+ *
+ * @see sound_pool_create()
+ * @see sound_pool_load_source_from_file()
+ */
+int sound_pool_unload_source(sound_pool_h pool, const char *tag);
+
+/**
+ * @brief Gets current @a state of @a pool.
+ *
+ * @since_tizen 3.0
+ * @param [in] pool The handle to the sound pool
+ * @param [out] state Current state of @a pool
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER
+ * Invalid parameter (@a pool is NULL or corrupted, @a tag is NULL)
+ * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No sources tagged by @a tag exist
+ * in pool
+ *
+ * @pre Create sound @a pool handler by calling @ref sound_pool_create()
+ *
+ * @see sound_pool_create()
+ * @see sound_pool_state_e
+ */
+int sound_pool_get_state(sound_pool_h pool,
+ sound_pool_state_e *state);
+
+/**
+ * @brief Changes current @a state of @a pool to SOUND_POOL_STATE_ACTIVE.
+ *
+ * @since_tizen 3.0
+ * @param [in] pool The handle to the sound pool
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
+ * (@a pool is NULL or corrupted)
+ * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation or sound pool
+ * is already in @c SOUND_POOL_STATE_ACTIVE state
+ *
+ * @pre Create sound @a pool handler by calling @ref sound_pool_create()
+ *
+ * @see sound_pool_create()
+ * @see sound_pool_get_state()
+ * @see sound_pool_deactivate()
+ * @see sound_pool_state_e
+ */
+int sound_pool_activate(sound_pool_h pool);
+
+/**
+ * @brief Changes current @a state of @a pool to SOUND_POOL_STATE_INACTIVE.
+ *
+ * @since_tizen 3.0
+ * @param [in] pool The handle to the sound pool
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
+ * (@a pool is NULL or corrupted)
+ * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation or sound pool
+ * is already in @c SOUND_POOL_STATE_INACTIVE state
+ *
+ * @pre Create sound @a pool handler by calling @ref sound_pool_create()
+ * @pre @a pool has to be in SOUND_POOL_STATE_ACTIVE state
+ *
+ * @see sound_pool_create()
+ * @see sound_pool_get_state()
+ * @see sound_pool_activate()
+ * @see sound_pool_state_e
+ */
+int sound_pool_deactivate(sound_pool_h pool);
+
+/**
+ * @brief Sets callback for handling sound @a pool state change.
+ *
+ * @since_tizen 3.0
+ * @param [in] pool The handle to the sound pool
+ * @param [in] callback The callback that will be called after pool state
+ * will be changed. @a callback will be called
+ * synchronously
+ * @param [in] data The user data to be passed to the @a callback
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
+ * (@a pool is NULL or corrupted, or @a callback is NULL)
+ *
+ * @pre Create sound @a pool handler by calling @ref sound_pool_create()
+ * @post Use @ref sound_pool_unset_state_change_callback() function to unset the
+ * @a callback
+ *
+ * @see sound_pool_create()
+ * @see sound_pool_pool_state_change_cb
+ */
+int sound_pool_set_state_change_callback(sound_pool_h pool,
+ sound_pool_state_change_cb callback, void *user_data);
+
+/**
+ * @brief Unsets callback for handling sound @a pool state change.
+ *
+ * @since_tizen 3.0
+ * @param [in] pool The handle to the pool
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
+ * (@a pool is NULL or corrupted)
+ *
+ * @pre Create sound @a pool handler by calling @ref sound_pool_create()
+ * @pre Set state change callback by calling @ref sound_pool_set_state_change_callback()
+ *
+ * @see sound_pool_create()
+ * @see sound_pool_set_state_change_callback()
+ */
+int sound_pool_unset_state_change_callback(sound_pool_h pool);
+
+/**
+ * @brief Plays source by @a tag.
+ * @details Creates stream with @a id that can be used to change parameters and
+ * get additional information.
+ * Sets stream state to SOUND_POOL_STREAM_STATE_PLAYING
+ * @remarks In case maximum active streams number after calling
+ * @ref sound_pool_stream_play() was exceeded the stream
+ * with lowest @a priority will be stopped.
+ * Resultant stream volume will depend on global pool volume.
+ *
+ * @since_tizen 3.0
+ * @param [in] pool The handle to the sound pool
+ * @param [in] tag Unique string that identifies source
+ * @param [in] loop Number of times stream will be repeated
+ * (pass 0 if stream should be repeated continuously)
+ * @param [in] volume Stream volume in 0.0~1.0 range
+ * @param [in] priority Stream priority (0 = lowest priority)
+ * @param [in] callback The callback that will be called after stream state
+ * will be changed, or NULL if this callback call
+ * isn't needed. If @a callback is set, then it will
+ * be called asynchronously
+ * @param [in] user_data The user data to be passed to the @a callback
+ * @param [out] id Unique stream identifier that can be used to
+ * change parameters and get additional information
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
+ * (@a pool is NULL or corrupted, @a tag is NULL, @a volume is out of
+ * 0.0~1.0 range, or @a id is NULL)
+ * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No sources tagged by @a tag exist
+ * in pool
+ * @retval #SOUND_POOL_ERROR_OUT_OF_MEMORY Not enough memory to allocate new
+ * sound stream
+ * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
+ *
+ * @pre Create sound pool handler by calling @ref sound_pool_create()
+ * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
+ * @post When playback is finished normally (i.e. @ref sound_pool_stop_stream()
+ * will be not used for stream termination) state will be changed to
+ * SOUND_POOL_STREAM_STATE_FINISHED and memory will be cleared from the
+ * stream allocated resources automatically
+ *
+ * @see sound_pool_create()
+ * @see sound_pool_load_source_from_file()
+ * @see sound_pool_set_volume
+ * @see sound_pool_get_volume
+ */
+int sound_pool_stream_play(sound_pool_h pool, const char *tag, unsigned loop,
+ float volume, unsigned priority,
+ sound_pool_stream_state_change_cb callback, void *user_data,
+ unsigned *id);
+
+/**
+ * @brief Pauses stream by @a id.
+ * @details Sets stream state to SOUND_POOL_STREAM_STATE_PAUSED.
+ * @remarks Stream state has to be SOUND_POOL_STATE_PLAYING
+ *
+ * @since_tizen 3.0
+ * @param [in] pool The handle to the sound pool
+ * @param [in] id Unique stream identifier
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
+ * (@a pool is NULL or corrupted)
+ * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
+ * exist in pool
+ * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation or stream is in
+ * the state which is not allowed for pause operation
+ *
+ * @pre Create sound @a pool handler by calling @ref sound_pool_create()
+ * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
+ * @pre Start stream playback by calling @ref sound_pool_stream_play()
+ *
+ * @see sound_pool_create()
+ * @see sound_pool_load_source_from_file()
+ * @see sound_pool_stream_play()
+ */
+int sound_pool_stream_pause(sound_pool_h pool, unsigned id);
+
+/**
+ * @brief Resumes stream by @a id.
+ * @details Sets stream state to SOUND_POOL_STREAM_STATE_PLAYING.
+ * @remarks Stream state has to be SOUND_POOL_STATE_PAUSED
+ *
+ * @since_tizen 3.0
+ * @param [in] pool The handle to the sound pool
+ * @param [in] id Unique stream identifier
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
+ * (@a pool is NULL or corrupted)
+ * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
+ * exist in pool
+ * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation or stream is in
+ * the state which is not allowed for resume operation
+ *
+ * @pre Create sound @a pool handler by calling @ref sound_pool_create()
+ * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
+ * @pre Start stream playback by calling @ref sound_pool_stream_play()
+ * @pre Pause stream playback by calling @ref sound_pool_stream_pause()
+ *
+ * @see sound_pool_create()
+ * @see sound_pool_load_source_from_file()
+ * @see sound_pool_stream_play()
+ * @see sound_pool_stream_pause()
+ */
+int sound_pool_stream_resume(sound_pool_h pool, unsigned id);
+
+/**
+ * @brief Stops stream by @a id.
+ * @details Sets stream state to SOUND_POOL_STREAM_STATE_STOPPED.
+ * After stream was stopped it can not be resumed and @a id value
+ * becomes invalid. Moreover, stream will never gets
+ * @c SOUND_POOL_STREAM_STATE_FINISHED state as it will be terminated
+ * after this function call.
+ *
+ * @since_tizen 3.0
+ * @param [in] pool The handle to the sound pool
+ * @param [in] id Unique stream identifier
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
+ * (@a pool is NULL or corrupted)
+ * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
+ * exist in pool
+ * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation or stream is in
+ * the state which is not allowed for stop operation
+ *
+ * @pre Create sound pool handler by calling @ref sound_pool_create()
+ * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
+ * @pre Start stream playback by calling @ref sound_pool_stream_play()
+ *
+ * @see sound_pool_create()
+ * @see sound_pool_load_source_from_file()
+ * @see sound_pool_stream_play()
+ */
+int sound_pool_stream_stop(sound_pool_h pool, unsigned id);
+
+/**
+ * @brief Sets pool global volume parameter.
+ * @details Volume of all streams related to @a pool will be scaled
+ * in accordance to global pool volume parameter
+ * (i.e. [stream real volume] = [global volume] * [stream volume],
+ * where [stream volume] is the volume parameter of arbitrary stream).
+ *
+ * @since_tizen 3.0
+ * @param [in] pool The handle to the sound pool
+ * @param [in] volume Pool global volume in 0.0~1.0 range
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
+ * (@a pool is NULL or corrupted, or @a volume isn't in 0.0~1.0 range)
+ * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
+ *
+ * @pre Create sound @a pool handler by calling @ref sound_pool_create()
+ *
+ * @see sound_pool_create()
+ */
+int sound_pool_set_volume(sound_pool_h pool, float volume);
+
+/**
+ * @brief Gets pool global volume parameter.
+ *
+ * @since_tizen 3.0
+ * @param [in] pool The handle to the sound pool
+ * @param [out] volume Pool global volume in 0.0~1.0 range
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
+ * (@a pool is NULL or corrupted, or @a volume is NULL)
+ * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
+ *
+ * @pre Create sound @a pool handler by calling @ref sound_pool_create()
+ *
+ * @see sound_pool_create()
+ */
+int sound_pool_get_volume(sound_pool_h pool, float *volume);
+
+/**
+ * @brief Gets current @a state of stream by @a id.
+ *
+ * @since_tizen 3.0
+ * @param [in] pool The handle to the sound pool
+ * @param [in] id Unique stream identifier
+ * @param [out] state Current state of stream
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
+ * (@a pool is NULL or corrupted, or @a state is NULL)
+ * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
+ * exist in pool
+ * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
+ *
+ * @pre Create sound pool handler by calling @ref sound_pool_create()
+ * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
+ * @pre Start stream playback by calling @ref sound_pool_stream_play()
+ *
+ * @see sound_pool_create()
+ * @see sound_pool_load_source_from_file()
+ * @see sound_pool_stream_play()
+ * @see sound_pool_stream_state_e
+ */
+int sound_pool_stream_get_state(sound_pool_h pool, unsigned id,
+ sound_pool_stream_state_e *state);
+
+/**
+ * @brief Sets stream @a loop parameter by stream @a id.
+ *
+ * @since_tizen 3.0
+ * @param [in] pool The handle to the sound pool
+ * @param [in] id Unique stream identifier
+ * @param [in] loop Number of times stream will be repeated
+ * (pass 0 if stream should be repeated continuously)
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
+ * (@a pool is NULL or corrupted)
+ * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
+ * exist in pool
+ * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
+ *
+ * @pre Create sound @a pool handler by calling @ref sound_pool_create()
+ * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
+ * @pre Start stream playback by calling @ref sound_pool_stream_play()
+ *
+ * @see sound_pool_create()
+ * @see sound_pool_load_source_from_file()
+ * @see sound_pool_stream_play()
+ */
+int sound_pool_stream_set_loop(sound_pool_h pool, unsigned id, unsigned loop);
+
+/**
+ * @brief Gets stream @a loop parameter by stream @a id.
+ *
+ * @since_tizen 3.0
+ * @param [in] pool The handle to the sound pool
+ * @param [in] id Unique stream identifier
+ * @param [out] loop Number of times stream will be repeated before
+ * finishing (getting state SOUND_POOL_STREAM_STATE_FINISHED)
+ * and releasing of the memory and resources
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
+ * (@a pool is NULL or corrupted, or @a loop is NULL)
+ * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
+ * exist in pool
+ * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
+ *
+ * @pre Create sound @a pool handler by calling @ref sound_pool_create()
+ * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
+ * @pre Start source playback by calling @ref sound_pool_stream_play()
+ *
+ * @see sound_pool_create()
+ * @see sound_pool_load_source_from_file()
+ * @see sound_pool_stream_play()
+ */
+int sound_pool_stream_get_loop(sound_pool_h pool, unsigned id, unsigned *loop);
+
+/**
+ * @brief Sets stream volume parameters by stream @a id.
+ * @remarks Resultant stream volume will depend on global pool volume.
+ *
+ * @since_tizen 3.0
+ * @param [in] pool The handle to the sound pool
+ * @param [in] id Unique stream identifier
+ * @param [in] volume Stream volume in 0.0~1.0 range
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
+ * (@a pool is NULL or corrupted, or @a volume isn't in 0.0~1.0 range)
+ * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
+ * exist in pool
+ * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
+ *
+ * @pre Create sound @a pool handler by calling @ref sound_pool_create()
+ * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
+ * @pre Start stream playback by calling @ref sound_pool_stream_play()
+ *
+ * @see sound_pool_create()
+ * @see sound_pool_load_source_from_file()
+ * @see sound_pool_stream_play()
+ * @see sound_pool_set_volume
+ * @see sound_pool_get_volume
+ */
+int sound_pool_stream_set_volume(sound_pool_h pool, unsigned id,
+ float volume);
+
+/**
+ * @brief Gets stream volume parameters by stream @a id.
+ *
+ * @since_tizen 3.0
+ * @param [in] pool The handle to the sound pool
+ * @param [in] id Unique stream identifier
+ * @param [out] volume Stream volume in 0.0~1.0 range
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
+ * (@a pool is NULL or corrupted, or @a volume is NULL)
+ * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
+ * exist in pool
+ * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
+ *
+ * @pre Create sound @a pool handler by calling @ref sound_pool_create()
+ * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
+ * @pre Start stream playback by calling @ref sound_pool_stream_play()
+ *
+ * @see sound_pool_create()
+ * @see sound_pool_load_source_from_file()
+ * @see sound_pool_stream_play()
+ */
+int sound_pool_stream_get_volume(sound_pool_h pool, unsigned id,
+ float *volume);
+
+/**
+ * @brief Sets stream priority parameter by stream @a id.
+ *
+ * @since_tizen 3.0
+ * @param [in] pool The handle to the sound pool
+ * @param [in] id Unique stream identifier
+ * @param [in] priority Stream priority (0 = lowest priority)
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
+ * (@a pool is NULL or corrupted)
+ * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
+ * exist in pool
+ * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
+ *
+ * @pre Create sound @a pool handler by calling @ref sound_pool_create()
+ * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
+ * @pre Start stream playback by calling @ref sound_pool_stream_play()
+ *
+ * @see sound_pool_create()
+ * @see sound_pool_load_source_from_file()
+ * @see sound_pool_stream_play()
+ */
+int sound_pool_stream_set_priority(sound_pool_h pool, unsigned id,
+ unsigned priority);
+
+/**
+ * @brief Gets stream priority parameter by stream @a id.
+ *
+ * @since_tizen 3.0
+ * @param [in] pool The handle to the sound pool
+ * @param [in] id Unique stream identifier
+ * @param [in] priority Stream priority (0 = lowest priority)
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
+ * (@a pool is NULL or corrupted, or @a priority is NULL)
+ * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
+ * exist in pool
+ * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
+ *
+ * @pre Create sound @a pool handler by calling @ref sound_pool_create()
+ * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
+ * @pre Start stream playback by calling @ref sound_pool_stream_play()
+ *
+ * @see sound_pool_create()
+ * @see sound_pool_load_source_from_file()
+ * @see sound_pool_stream_play()
+ */
+int sound_pool_stream_get_priority(sound_pool_h pool, unsigned id,
+ unsigned *priority);
+
+/**
+ * @brief Sets callback for handling stream state change events.
+ *
+ * @since_tizen 3.0
+ * @param [in] pool The handle to the sound pool
+ * @param [in] id Unique stream identifier
+ * @param [in] callback The callback that will be called after stream state
+ * will be changed. @a callback will be called
+ * asynchronously
+ * @param [in] data The user data to be passed to the @a callback
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
+ * (@a pool is NULL or corrupted, or @a callback is NULL)
+ * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
+ * exist in pool
+ * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
+ *
+ * @pre Create sound pool handler by calling @ref sound_pool_create()
+ * @pre Load source to pool by calling @ref sound_pool_load_source_from_file()
+ * @pre Start source playback by calling @ref sound_pool_stream_play()
+ * @post Use @ref sound_pool_stream_unset_state_change_callback() function to
+ * unset the @a callback
+ *
+ * @see sound_pool_create()
+ * @see sound_pool_load_source_from_file()
+ * @see sound_pool_stream_play()
+ * @see sound_pool_stream_state_change_cb
+ */
+int sound_pool_stream_set_state_change_callback(sound_pool_h pool, unsigned id,
+ sound_pool_stream_state_change_cb callback, void *user_data);
+
+/**
+ * @brief Unsets callback for handling stream state change events.
+ *
+ * @since_tizen 3.0
+ * @param [in] pool The handle to the sound pool
+ * @param [in] id Unique stream identifier
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
+ * (@a pool is NULL or corrupted)
+ * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
+ * exist in pool
+ *
+ * @pre Create sound @a pool handler by calling @ref sound_pool_create()
+ * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
+ * @pre Start stream playback by calling @ref sound_pool_stream_play()
+ * @pre Set stream state change callback by calling @ref sound_pool_stream_set_state_change_callback()
+ *
+ * @see sound_pool_create()
+ * @see sound_pool_load_source_from_file()
+ * @see sound_pool_stream_play()
+ * @see sound_pool_stream_state_change_cb
+ */
+int sound_pool_stream_unset_state_change_callback(sound_pool_h pool,
+ unsigned id);
+
+/**
+ * @}
+ */
+
+
#ifdef __cplusplus
}
#endif
projects / platform / core / api / sound-pool.git / commitdiff