include/sound_pool.h

   1 /*
   2  * Copyright (c) 2016 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_SOUND_POOL_H__
  18 #define __TIZEN_SOUND_POOL_H__
  19
  20 #include "sound_pool_type.h"
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif
  25
  26 /**
  27  * @file   sound_pool.h
  28  * @brief  This file contains Tizen Sound Pool API.
  29  */
  30
  31 /**
  32  * @addtogroup CAPI_SOUND_POOL_MODULE
  33  * @{
  34  */
  35
  36 /**
  37  * @brief Called when sound pool state is changed.
  38  *
  39  * @since_tizen 3.0
  40  * @param [in]  pool          The handle to the sound pool
  41  * @param [in]  prev_state    Previous pool state
  42  * @param [in]  cur_state     Current pool state
  43  * @param [in]  user_data     The user data passed from the code where
  44  *                            @ref sound_pool_set_state_change_callback() was
  45  *                            called.
  46  *
  47  * @pre Create sound pool handler by calling @ref sound_pool_create()
  48  * @pre Call @ref sound_pool_set_state_change_callback()
  49  *
  50  * @see sound_pool_create()
  51  * @see sound_pool_set_state_change_callback()
  52  * @see sound_pool_state_e
  53  */
  54 typedef void (*sound_pool_state_change_cb) (sound_pool_h pool,
  55                 sound_pool_state_e prev_state, sound_pool_state_e cur_state,
  56                 void *user_data);
  57
  58 /**
  59  * @brief Called when sound pool stream state is changed.
  60  *
  61  * @since_tizen 3.0
  62  * @param [in]  pool        The handle to the sound pool
  63  * @param [in]  tag         Unique string that identifies source which was used
  64  *                          for stream creation
  65  * @param [in]  id          Unique stream identifier
  66  * @param [in]  prev_state  Previous stream state
  67  * @param [in]  cur_state   Current stream state
  68  * @param [in]  data        The user data passed from the code where
  69  *                          @ref sound_pool_stream_set_state_change_callback() was
  70  *                          called.
  71  *
  72  * @pre Create sound pool handler by calling @ref sound_pool_create()
  73  * @pre Load source to pool by calling @ref sound_pool_load_source_from_file()
  74  * @pre Start source playback by calling @ref sound_pool_stream_play()
  75  * @pre Call @ref sound_pool_stream_set_state_change_callback()
  76  *
  77  * @see sound_pool_create()
  78  * @see sound_pool_load_source_from_file()
  79  * @see sound_pool_stream_play()
  80  * @see sound_pool_stream_set_state_change_callback()
  81  * @see sound_pool_stream_state_e
  82  */
  83 typedef void (*sound_pool_stream_state_change_cb) (sound_pool_h pool,
  84                 const char *tag, unsigned id, sound_pool_stream_state_e prev_state,
  85                 sound_pool_stream_state_e cur_state, void *user_data);
  86
  87 /**
  88  * @brief Creates sound pool instance that can be used for sound sources
  89  *        loading/unloading.
  90  * @details Up to 32 sound pools can be created. Several pools can be active
  91  *          at the same time. Streams can be in playing state only when pool is
  92  *          active.
  93  * @remarks When pool has been created, pool state is
  94  *          SOUND_POOL_STATE_INACTIVE. To activate a pool use
  95  *          @ref sound_pool_activate() function.
  96  *
  97  * @since_tizen 3.0
  98  * @param [in]   max_streams    Maximum number of active streams
  99  * @param [out]  pool           The handle to the pool that will be created
 100  * @return @c 0 on success, otherwise a negative error value
 101  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER
 102  *         Invalid parameter (@a pool is NULL or @a max_streams is 0)
 103  * @retval #SOUND_POOL_ERROR_OUT_OF_MEMORY
 104  *         Not enough memory to create sound pool
 105  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION
 106  *         Maximal amount of sound pools is exceeded (usually, 32 pools allowed)
 107  *
 108  * @see sound_pool_destroy()
 109  */
 110 sound_pool_error_e sound_pool_create(unsigned max_streams, sound_pool_h *pool);
 111
 112 /**
 113  * @brief Destroys sound pool and cleans allocated memory.
 114  * @details Stops all streams and unloads all sources associated with pool.
 115  *
 116  * @since_tizen 3.0
 117  * @param [in]  pool     The handle to the pool that will be destroyed
 118  * @return @c 0 on success, otherwise a negative error value
 119  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER
 120  *         Invalid parameter (@a pool is NULL or corrupted)
 121  *
 122  * @pre Create sound pool handler by calling @ref sound_pool_create()
 123  *
 124  * @see sound_pool_create()
 125  */
 126 sound_pool_error_e sound_pool_destroy(sound_pool_h pool);
 127
 128 /**
 129  * @brief Loads sound source data from file to pool.
 130  * @details After calling this routine the source can be accessed by its @a tag.
 131  * @remarks Input data can be either raw or encoded.
 132  *          Each of loaded sources must have unique @a tag
 133  *          It is synchronous operation.
 134  *
 135  * @since_tizen 3.0
 136  * @param [in]  pool         The handle to the sound pool
 137  * @param [in]  file_name    The name of file that contains sound data
 138  * @param [in]  tag          Unique string that will be used to identify source
 139  * @return @c 0 on success, otherwise a negative error value
 140  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER
 141  *         Invalid parameter (@a pool is NULL or corrupted, @a file_name is
 142  *         NULL, @a tag is NULL or @a tag/@a file_name length is too long)
 143  * @retval #SOUND_POOL_ERROR_OUT_OF_MEMORY Not enough memory to allocate source
 144  * @retval #SOUND_POOL_ERROR_NO_SUCH_FILE No file determined by @a file_name
 145  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
 146  *
 147  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 148  * @post Unload source from pool by calling @ref sound_pool_unload_source()
 149  *
 150  * @see sound_pool_create()
 151  * @see sound_pool_destroy()
 152  * @see sound_pool_unload_source()
 153  */
 154 sound_pool_error_e sound_pool_load_source_from_file(sound_pool_h pool, const char *file_name,
 155                 const char *tag);
 156
 157 /**
 158  * @brief Unloads source from @a pool.
 159  * @details Cleans memory. It is synchronous operation.
 160  * @remarks The usage of @a tag name that was associated with unloaded source
 161  *          has no effect. It can be reused as well.
 162  *
 163  * @since_tizen 3.0
 164  * @param [in]  pool    The handle to the sound pool
 165  * @param [in]  tag     Unique string that identifies source
 166  * @return @c 0 on success, otherwise a negative error value
 167  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER
 168  *         Invalid parameter (@a pool is NULL or corrupted, @a tag is NULL)
 169  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No sources tagged by @a tag exist
 170  *         in pool
 171  *
 172  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 173  * @pre Load source to pool by calling @ref sound_pool_load_source_from_file()
 174  *
 175  * @see sound_pool_create()
 176  * @see sound_pool_load_source_from_file()
 177  */
 178 sound_pool_error_e sound_pool_unload_source(sound_pool_h pool, const char *tag);
 179
 180 /**
 181  * @brief Gets current @a state of @a pool.
 182  *
 183  * @since_tizen 3.0
 184  * @param [in]  pool     The handle to the sound pool
 185  * @param [out] state    Current state of @a pool
 186  * @return @c 0 on success, otherwise a negative error value
 187  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER
 188  *         Invalid parameter (@a pool is NULL or corrupted, @a tag is NULL)
 189  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No sources tagged by @a tag exist
 190  *         in pool
 191  *
 192  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 193  *
 194  * @see sound_pool_create()
 195  * @see sound_pool_state_e
 196  */
 197 sound_pool_error_e sound_pool_get_state(sound_pool_h pool,
 198                 sound_pool_state_e *state);
 199
 200 /**
 201  * @brief Changes current @a state of @a pool to SOUND_POOL_STATE_ACTIVE.
 202  *
 203  * @since_tizen 3.0
 204  * @param [in]  pool     The handle to the sound pool
 205  * @return @c 0 on success, otherwise a negative error value
 206  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 207  *         (@a pool is NULL or corrupted)
 208  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation or sound pool
 209  *         is already in @c SOUND_POOL_STATE_ACTIVE state
 210  *
 211  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 212  *
 213  * @see sound_pool_create()
 214  * @see sound_pool_get_state()
 215  * @see sound_pool_deactivate()
 216  * @see sound_pool_state_e
 217  */
 218 sound_pool_error_e sound_pool_activate(sound_pool_h pool);
 219
 220 /**
 221  * @brief Changes current @a state of @a pool to SOUND_POOL_STATE_INACTIVE.
 222  *
 223  * @since_tizen 3.0
 224  * @param [in]  pool     The handle to the sound pool
 225  * @return @c 0 on success, otherwise a negative error value
 226  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 227  *         (@a pool is NULL or corrupted)
 228  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation or sound pool
 229  *         is already in @c SOUND_POOL_STATE_INACTIVE state
 230  *
 231  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 232  * @pre @a pool has to be in SOUND_POOL_STATE_ACTIVE state
 233  *
 234  * @see sound_pool_create()
 235  * @see sound_pool_get_state()
 236  * @see sound_pool_activate()
 237  * @see sound_pool_state_e
 238  */
 239 sound_pool_error_e sound_pool_deactivate(sound_pool_h pool);
 240
 241 /**
 242  * @brief Sets callback for handling sound @a pool state change.
 243  *
 244  * @since_tizen 3.0
 245  * @param [in]  pool        The handle to the sound pool
 246  * @param [in]  callback    The callback that will be called after pool state
 247  *                          will be changed.  @a callback will be called
 248  *                          synchronously
 249  * @param [in]  data        The user data to be passed to the @a callback
 250  * @return @c 0 on success, otherwise a negative error value
 251  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 252  *         (@a pool is NULL or corrupted, or @a callback is NULL)
 253  *
 254  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 255  * @post Use @ref sound_pool_unset_state_change_callback() function to unset the
 256  *       @a callback
 257  *
 258  * @see sound_pool_create()
 259  * @see sound_pool_pool_state_change_cb
 260  */
 261 sound_pool_error_e sound_pool_set_state_change_callback(sound_pool_h pool,
 262                 sound_pool_state_change_cb callback, void *user_data);
 263
 264 /**
 265  * @brief Unsets callback for handling sound @a pool state change.
 266  *
 267  * @since_tizen 3.0
 268  * @param [in]  pool     The handle to the pool
 269  * @return @c 0 on success, otherwise a negative error value
 270  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 271  *         (@a pool is NULL or corrupted)
 272  *
 273  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 274  * @pre Set state change callback by calling @ref sound_pool_set_state_change_callback()
 275  *
 276  * @see sound_pool_create()
 277  * @see sound_pool_set_state_change_callback()
 278  */
 279 sound_pool_error_e sound_pool_unset_state_change_callback(sound_pool_h pool);
 280
 281 /**
 282  * @brief Plays source by @a tag.
 283  * @details Creates stream with @a id that can be used to change parameters and
 284  *          get additional information.
 285  *          Sets stream state to SOUND_POOL_STREAM_STATE_PLAYING
 286  * @remarks In case maximum active streams number after calling
 287  *          @ref sound_pool_stream_play() was exceeded the stream
 288  *          with lowest @a priority will be stopped.
 289  *          Resultant stream volume will depend on global pool volume.
 290  *
 291  * @since_tizen 3.0
 292  * @param [in]  pool        The handle to the sound pool
 293  * @param [in]  tag         Unique string that identifies source
 294  * @param [in]  loop        Number of times stream will be repeated
 295  *                          (pass 0 if stream should be repeated continuously)
 296  * @param [in]  volume      Stream volume in 0.0~1.0 range
 297  * @param [in]  priority    Stream priority (0 = lowest priority)
 298  * @param [in]  callback    The callback that will be called after stream state
 299  *                          will be changed, or NULL if this callback call
 300  *                          isn't needed. If @a callback is set, then it will
 301  *                          be called asynchronously
 302  * @param [in]  user_data   The user data to be passed to the @a callback
 303  * @param [out] id          Unique stream identifier that can be used to
 304  *                          change parameters and get additional information
 305  * @return @c 0 on success, otherwise a negative error value
 306  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 307  *         (@a pool is NULL or corrupted, @a tag is NULL, @a volume is out of
 308  *         0.0~1.0 range, or @a id is NULL)
 309  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No sources tagged by @a tag exist
 310  *         in pool
 311  * @retval #SOUND_POOL_ERROR_OUT_OF_MEMORY Not enough memory to allocate new
 312  *         sound stream
 313  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
 314  *
 315  * @pre Create sound pool handler by calling @ref sound_pool_create()
 316  * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
 317  * @post When playback is finished normally (i.e. @ref sound_pool_stop_stream()
 318  *       will be not used for stream termination) state will be changed to
 319  *       SOUND_POOL_STREAM_STATE_FINISHED and memory will be cleared from the
 320  *       stream allocated resources automatically
 321  *
 322  * @see sound_pool_create()
 323  * @see sound_pool_load_source_from_file()
 324  * @see sound_pool_set_volume
 325  * @see sound_pool_get_volume
 326  */
 327 sound_pool_error_e sound_pool_stream_play(sound_pool_h pool, const char *tag, unsigned loop,
 328                 float volume, unsigned priority,
 329                 sound_pool_stream_state_change_cb callback, void *user_data,
 330                 unsigned *id);
 331
 332 /**
 333  * @brief Pauses stream by @a id.
 334  * @details Sets stream state to SOUND_POOL_STREAM_STATE_PAUSED.
 335  * @remarks Stream state has to be SOUND_POOL_STATE_PLAYING
 336  *
 337  * @since_tizen 3.0
 338  * @param [in]  pool    The handle to the sound pool
 339  * @param [in]  id      Unique stream identifier
 340  * @return @c 0 on success, otherwise a negative error value
 341  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 342  *         (@a pool is NULL or corrupted)
 343  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
 344  *         exist in pool
 345  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation or stream is in
 346  *         the state which is not allowed for pause operation
 347  *
 348  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 349  * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
 350  * @pre Start stream playback by calling @ref sound_pool_stream_play()
 351  *
 352  * @see sound_pool_create()
 353  * @see sound_pool_load_source_from_file()
 354  * @see sound_pool_stream_play()
 355  */
 356 sound_pool_error_e sound_pool_stream_pause(sound_pool_h pool, unsigned id);
 357
 358 /**
 359  * @brief Resumes stream by @a id.
 360  * @details Sets stream state to SOUND_POOL_STREAM_STATE_PLAYING.
 361  * @remarks Stream state has to be SOUND_POOL_STATE_PAUSED
 362  *
 363  * @since_tizen 3.0
 364  * @param [in]  pool    The handle to the sound pool
 365  * @param [in]  id      Unique stream identifier
 366  * @return @c 0 on success, otherwise a negative error value
 367  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 368  *         (@a pool is NULL or corrupted)
 369  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
 370  *         exist in pool
 371  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation or stream is in
 372  *         the state which is not allowed for resume operation
 373  *
 374  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 375  * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
 376  * @pre Start stream playback by calling @ref sound_pool_stream_play()
 377  * @pre Pause stream playback by calling @ref sound_pool_stream_pause()
 378  *
 379  * @see sound_pool_create()
 380  * @see sound_pool_load_source_from_file()
 381  * @see sound_pool_stream_play()
 382  * @see sound_pool_stream_pause()
 383  */
 384 sound_pool_error_e sound_pool_stream_resume(sound_pool_h pool, unsigned id);
 385
 386 /**
 387  * @brief Stops stream by @a id.
 388  * @details Sets stream state to SOUND_POOL_STREAM_STATE_STOPPED.
 389  *          After stream was stopped it can not be resumed and @a id value
 390  *          becomes invalid. Moreover, stream will never gets
 391  *          @c SOUND_POOL_STREAM_STATE_FINISHED state as it will be terminated
 392  *          after this function call.
 393  *
 394  * @since_tizen 3.0
 395  * @param [in]  pool    The handle to the sound pool
 396  * @param [in]  id      Unique stream identifier
 397  * @return @c 0 on success, otherwise a negative error value
 398  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 399  *         (@a pool is NULL or corrupted)
 400  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
 401  *         exist in pool
 402  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation or stream is in
 403  *         the state which is not allowed for stop operation
 404  *
 405  * @pre Create sound pool handler by calling @ref sound_pool_create()
 406  * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
 407  * @pre Start stream playback by calling @ref sound_pool_stream_play()
 408  *
 409  * @see sound_pool_create()
 410  * @see sound_pool_load_source_from_file()
 411  * @see sound_pool_stream_play()
 412  */
 413 sound_pool_error_e sound_pool_stream_stop(sound_pool_h pool, unsigned id);
 414
 415 /**
 416  * @brief Sets pool global volume parameter.
 417  * @details Volume of all streams related to @a pool will be scaled
 418  *          in accordance to global pool volume parameter
 419  *          (i.e. [stream real volume] = [global volume] * [stream volume],
 420  *          where [stream volume] is the volume parameter of arbitrary stream).
 421  *
 422  * @since_tizen 3.0
 423  * @param [in]  pool      The handle to the sound pool
 424  * @param [in]  volume    Pool global volume in 0.0~1.0 range
 425  * @return @c 0 on success, otherwise a negative error value
 426  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 427  *         (@a pool is NULL or corrupted, or @a volume isn't in 0.0~1.0 range)
 428  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
 429  *
 430  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 431  *
 432  * @see sound_pool_create()
 433  */
 434 sound_pool_error_e sound_pool_set_volume(sound_pool_h pool, float volume);
 435
 436 /**
 437  * @brief Gets pool global volume parameter.
 438  *
 439  * @since_tizen 3.0
 440  * @param [in]   pool      The handle to the sound pool
 441  * @param [out]  volume    Pool global volume in 0.0~1.0 range
 442  * @return @c 0 on success, otherwise a negative error value
 443  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 444  *         (@a pool is NULL or corrupted, or @a volume is NULL)
 445  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
 446  *
 447  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 448  *
 449  * @see sound_pool_create()
 450  */
 451 sound_pool_error_e sound_pool_get_volume(sound_pool_h pool, float *volume);
 452
 453 /**
 454  * @brief Gets current @a state of stream by @a id.
 455  *
 456  * @since_tizen 3.0
 457  * @param [in]  pool     The handle to the sound pool
 458  * @param [in]  id       Unique stream identifier
 459  * @param [out] state    Current state of stream
 460  * @return @c 0 on success, otherwise a negative error value
 461  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 462  *         (@a pool is NULL or corrupted, or @a state is NULL)
 463  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
 464  *         exist in pool
 465  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
 466  *
 467  * @pre Create sound pool handler by calling @ref sound_pool_create()
 468  * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
 469  * @pre Start stream playback by calling @ref sound_pool_stream_play()
 470  *
 471  * @see sound_pool_create()
 472  * @see sound_pool_load_source_from_file()
 473  * @see sound_pool_stream_play()
 474  * @see sound_pool_stream_state_e
 475  */
 476 sound_pool_error_e sound_pool_stream_get_state(sound_pool_h pool, unsigned id,
 477                 sound_pool_stream_state_e *state);
 478
 479 /**
 480  * @brief Sets stream @a loop parameter by stream @a id.
 481  *
 482  * @since_tizen 3.0
 483  * @param [in]  pool    The handle to the sound pool
 484  * @param [in]  id      Unique stream identifier
 485  * @param [in]  loop    Number of times stream will be repeated
 486  *                      (pass 0 if stream should be repeated continuously)
 487  * @return @c 0 on success, otherwise a negative error value
 488  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 489  *         (@a pool is NULL or corrupted)
 490  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
 491  *         exist in pool
 492  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
 493  *
 494  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 495  * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
 496  * @pre Start stream playback by calling @ref sound_pool_stream_play()
 497  *
 498  * @see sound_pool_create()
 499  * @see sound_pool_load_source_from_file()
 500  * @see sound_pool_stream_play()
 501  */
 502 sound_pool_error_e sound_pool_stream_set_loop(sound_pool_h pool, unsigned id, unsigned loop);
 503
 504 /**
 505  * @brief Gets stream @a loop parameter by stream @a id.
 506  *
 507  * @since_tizen 3.0
 508  * @param [in]  pool    The handle to the sound pool
 509  * @param [in]  id      Unique stream identifier
 510  * @param [out] loop    Number of times stream will be repeated before
 511  *                      finishing (getting state SOUND_POOL_STREAM_STATE_FINISHED)
 512  *                      and releasing of the memory and resources
 513  * @return @c 0 on success, otherwise a negative error value
 514  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 515  *         (@a pool is NULL or corrupted, or @a loop is NULL)
 516  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
 517  *         exist in pool
 518  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
 519  *
 520  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 521  * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
 522  * @pre Start source playback by calling @ref sound_pool_stream_play()
 523  *
 524  * @see sound_pool_create()
 525  * @see sound_pool_load_source_from_file()
 526  * @see sound_pool_stream_play()
 527  */
 528 sound_pool_error_e sound_pool_stream_get_loop(sound_pool_h pool, unsigned id, unsigned *loop);
 529
 530 /**
 531  * @brief Sets stream volume parameters by stream @a id.
 532  * @remarks Resultant stream volume will depend on global pool volume.
 533  *
 534  * @since_tizen 3.0
 535  * @param [in]  pool      The handle to the sound pool
 536  * @param [in]  id        Unique stream identifier
 537  * @param [in]  volume    Stream volume in 0.0~1.0 range
 538  * @return @c 0 on success, otherwise a negative error value
 539  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 540  *         (@a pool is NULL or corrupted, or @a volume isn't in 0.0~1.0 range)
 541  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
 542  *         exist in pool
 543  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
 544  *
 545  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 546  * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
 547  * @pre Start stream playback by calling @ref sound_pool_stream_play()
 548  *
 549  * @see sound_pool_create()
 550  * @see sound_pool_load_source_from_file()
 551  * @see sound_pool_stream_play()
 552  * @see sound_pool_set_volume
 553  * @see sound_pool_get_volume
 554  */
 555 sound_pool_error_e sound_pool_stream_set_volume(sound_pool_h pool, unsigned id,
 556                 float volume);
 557
 558 /**
 559  * @brief Gets stream volume parameters by stream @a id.
 560  *
 561  * @since_tizen 3.0
 562  * @param [in]  pool      The handle to the sound pool
 563  * @param [in]  id        Unique stream identifier
 564  * @param [out] volume    Stream volume in 0.0~1.0 range
 565  * @return @c 0 on success, otherwise a negative error value
 566  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 567  *         (@a pool is NULL or corrupted, or @a volume is NULL)
 568  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
 569  *         exist in pool
 570  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
 571  *
 572  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 573  * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
 574  * @pre Start stream playback by calling @ref sound_pool_stream_play()
 575  *
 576  * @see sound_pool_create()
 577  * @see sound_pool_load_source_from_file()
 578  * @see sound_pool_stream_play()
 579  */
 580 sound_pool_error_e sound_pool_stream_get_volume(sound_pool_h pool, unsigned id,
 581                 float *volume);
 582
 583 /**
 584  * @brief Sets stream priority parameter by stream @a id.
 585  *
 586  * @since_tizen 3.0
 587  * @param [in]  pool        The handle to the sound pool
 588  * @param [in]  id          Unique stream identifier
 589  * @param [in]  priority    Stream priority (0 = lowest priority)
 590  * @return @c 0 on success, otherwise a negative error value
 591  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 592  *         (@a pool is NULL or corrupted)
 593  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
 594  *         exist in pool
 595  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
 596  *
 597  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 598  * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
 599  * @pre Start stream playback by calling @ref sound_pool_stream_play()
 600  *
 601  * @see sound_pool_create()
 602  * @see sound_pool_load_source_from_file()
 603  * @see sound_pool_stream_play()
 604  */
 605 sound_pool_error_e sound_pool_stream_set_priority(sound_pool_h pool, unsigned id,
 606                 unsigned priority);
 607
 608 /**
 609  * @brief Gets stream priority parameter by stream @a id.
 610  *
 611  * @since_tizen 3.0
 612  * @param [in]  pool        The handle to the sound pool
 613  * @param [in]  id          Unique stream identifier
 614  * @param [in]  priority    Stream priority (0 = lowest priority)
 615  * @return @c 0 on success, otherwise a negative error value
 616  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 617  *         (@a pool is NULL or corrupted, or @a priority is NULL)
 618  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
 619  *         exist in pool
 620  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
 621  *
 622  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 623  * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
 624  * @pre Start stream playback by calling @ref sound_pool_stream_play()
 625  *
 626  * @see sound_pool_create()
 627  * @see sound_pool_load_source_from_file()
 628  * @see sound_pool_stream_play()
 629  */
 630 sound_pool_error_e sound_pool_stream_get_priority(sound_pool_h pool, unsigned id,
 631                 unsigned *priority);
 632
 633 /**
 634  * @brief Sets callback for handling stream state change events.
 635  *
 636  * @since_tizen 3.0
 637  * @param [in]  pool        The handle to the sound pool
 638  * @param [in]  id          Unique stream identifier
 639  * @param [in]  callback    The callback that will be called after stream state
 640  *                          will be changed. @a callback will be called
 641  *                          asynchronously
 642  * @param [in]  data        The user data to be passed to the @a callback
 643  * @return @c 0 on success, otherwise a negative error value
 644  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 645  *         (@a pool is NULL or corrupted, or @a callback is NULL)
 646  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
 647  *         exist in pool
 648  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
 649  *
 650  * @pre Create sound pool handler by calling @ref sound_pool_create()
 651  * @pre Load source to pool by calling @ref sound_pool_load_source_from_file()
 652  * @pre Start source playback by calling @ref sound_pool_stream_play()
 653  * @post Use @ref sound_pool_stream_unset_state_change_callback() function to
 654  *       unset the @a callback
 655  *
 656  * @see sound_pool_create()
 657  * @see sound_pool_load_source_from_file()
 658  * @see sound_pool_stream_play()
 659  * @see sound_pool_stream_state_change_cb
 660  */
 661 sound_pool_error_e sound_pool_stream_set_state_change_callback(sound_pool_h pool, unsigned id,
 662                 sound_pool_stream_state_change_cb callback, void *user_data);
 663
 664 /**
 665  * @brief Unsets callback for handling stream state change events.
 666  *
 667  * @since_tizen 3.0
 668  * @param [in]  pool    The handle to the sound pool
 669  * @param [in]  id      Unique stream identifier
 670  * @return @c 0 on success, otherwise a negative error value
 671  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 672  *         (@a pool is NULL or corrupted)
 673  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
 674  *         exist in pool
 675  *
 676  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 677  * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
 678  * @pre Start stream playback by calling @ref sound_pool_stream_play()
 679  * @pre Set stream state change callback by calling @ref sound_pool_stream_set_state_change_callback()
 680  *
 681  * @see sound_pool_create()
 682  * @see sound_pool_load_source_from_file()
 683  * @see sound_pool_stream_play()
 684  * @see sound_pool_stream_state_change_cb
 685  */
 686 sound_pool_error_e sound_pool_stream_unset_state_change_callback(sound_pool_h pool,
 687                 unsigned id);
 688
 689 /**
 690  * @}
 691  */
 692
 693
 694 #ifdef __cplusplus
 695 }
 696 #endif
 697
 698 #endif /* __TIZEN_SOUND_POOL_H__ */