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()
  70  *                          was 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 [out] pool    The handle to the pool that will be created
  99  * @return @c 0 on success, otherwise a negative error value
 100  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER
 101  *         Invalid parameter (@a pool is NULL)
 102  * @retval #SOUND_POOL_ERROR_OUT_OF_MEMORY
 103  *         Not enough memory to create sound pool
 104  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION
 105  *         Maximal amount of sound pools is exceeded (usually, 32 pools allowed)
 106  *
 107  * @see sound_pool_destroy()
 108  */
 109 sound_pool_error_e sound_pool_create(sound_pool_h *pool);
 110
 111 /**
 112  * @brief Destroys sound pool and cleans allocated memory.
 113  * @details Stops all streams and unloads all sources associated with pool.
 114  *
 115  * @since_tizen 3.0
 116  * @param [in]  pool     The handle to the pool that will be destroyed
 117  * @return @c 0 on success, otherwise a negative error value
 118  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER
 119  *         Invalid parameter (@a pool is NULL or corrupted)
 120  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
 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,
 155                 const char *file_name, 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 Changes current @a state of @a pool to SOUND_POOL_STATE_ACTIVE.
 182  * @remarks When activation is performed, all suspended streams with highest
 183  *          priority in the pool will resume their playback. Paused streams will
 184  *          remain their state.
 185  *
 186  * @since_tizen 3.0
 187  * @param [in]  pool     The handle to the sound pool
 188  * @return @c 0 on success, otherwise a negative error value
 189  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 190  *         (@a pool is NULL or corrupted)
 191  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation or sound pool
 192  *         is already in @c SOUND_POOL_STATE_ACTIVE state
 193  *
 194  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 195  *
 196  * @see sound_pool_create()
 197  * @see sound_pool_get_state()
 198  * @see sound_pool_deactivate()
 199  * @see sound_pool_state_e
 200  */
 201 sound_pool_error_e sound_pool_activate(sound_pool_h pool);
 202
 203 /**
 204  * @brief Changes current @a state of @a pool to SOUND_POOL_STATE_INACTIVE.
 205  * @remarks When deactivation is performed, all playing streams in the pool will
 206  *          be suspended (change state to SOUND_POOL_STREAM_STATE_SUSPENDED).
 207  *          Paused streams will remain their state.
 208  *
 209  * @since_tizen 3.0
 210  * @param [in]  pool     The handle to the sound pool
 211  * @return @c 0 on success, otherwise a negative error value
 212  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 213  *         (@a pool is NULL or corrupted)
 214  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation or sound pool
 215  *         is already in @c SOUND_POOL_STATE_INACTIVE state
 216  *
 217  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 218  * @pre @a pool has to be in SOUND_POOL_STATE_ACTIVE state
 219  *
 220  * @see sound_pool_create()
 221  * @see sound_pool_get_state()
 222  * @see sound_pool_activate()
 223  * @see sound_pool_state_e
 224  */
 225 sound_pool_error_e sound_pool_deactivate(sound_pool_h pool);
 226
 227 /**
 228  * @brief Sets pool global volume parameter.
 229  * @details Volume of all streams related to @a pool will be scaled
 230  *          in accordance to global pool volume parameter
 231  *          (i.e. [stream real volume] = [global volume] * [stream volume],
 232  *          where [stream volume] is the volume parameter of arbitrary stream).
 233  *
 234  * @since_tizen 3.0
 235  * @param [in]  pool      The handle to the sound pool
 236  * @param [in]  volume    Pool global volume in 0.0~1.0 range
 237  * @return @c 0 on success, otherwise a negative error value
 238  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 239  *         (@a pool is NULL or corrupted, or @a volume isn't in 0.0~1.0 range)
 240  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
 241  *
 242  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 243  *
 244  * @see sound_pool_create()
 245  */
 246 sound_pool_error_e sound_pool_set_volume(sound_pool_h pool, float volume);
 247
 248 /**
 249  * @brief Gets pool global volume parameter.
 250  *
 251  * @since_tizen 3.0
 252  * @param [in]   pool      The handle to the sound pool
 253  * @param [out]  volume    Pool global volume in 0.0~1.0 range
 254  * @return @c 0 on success, otherwise a negative error value
 255  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 256  *         (@a pool is NULL or corrupted, or @a volume is NULL)
 257  *
 258  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 259  *
 260  * @see sound_pool_create()
 261  */
 262 sound_pool_error_e sound_pool_get_volume(sound_pool_h pool, float *volume);
 263
 264 /**
 265  * @brief Gets current @a state of @a pool.
 266  *
 267  * @since_tizen 3.0
 268  * @param [in]  pool     The handle to the sound pool
 269  * @param [out] state    Current state of @a pool
 270  * @return @c 0 on success, otherwise a negative error value
 271  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER
 272  *         Invalid parameter (@a pool is NULL or corrupted, @a tag is NULL)
 273  *
 274  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 275  *
 276  * @see sound_pool_create()
 277  * @see sound_pool_state_e
 278  */
 279 sound_pool_error_e sound_pool_get_state(sound_pool_h pool,
 280                 sound_pool_state_e *state);
 281
 282 /**
 283  * @brief Sets callback for handling sound @a pool state change.
 284  *
 285  * @since_tizen 3.0
 286  * @param [in]  pool        The handle to the sound pool
 287  * @param [in]  callback    The callback that will be called after pool state
 288  *                          will be changed.  @a callback will be called
 289  *                          synchronously
 290  * @param [in]  user_data   The user data to be passed to the @a callback
 291  * @return @c 0 on success, otherwise a negative error value
 292  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 293  *         (@a pool is NULL or corrupted, or @a callback is NULL)
 294  *
 295  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 296  * @post Use @ref sound_pool_unset_state_change_callback() function to unset the
 297  *       @a callback
 298  *
 299  * @see sound_pool_create()
 300  * @see sound_pool_pool_state_change_cb
 301  */
 302 sound_pool_error_e sound_pool_set_state_change_callback(sound_pool_h pool,
 303                 sound_pool_state_change_cb callback, void *user_data);
 304
 305 /**
 306  * @brief Unsets callback for handling sound @a pool state change.
 307  *
 308  * @since_tizen 3.0
 309  * @param [in]  pool     The handle to the pool
 310  * @return @c 0 on success, otherwise a negative error value
 311  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 312  *         (@a pool is NULL or corrupted)
 313  *
 314  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 315  * @pre Set state change callback by calling
 316  *      @ref sound_pool_set_state_change_callback()
 317  *
 318  * @see sound_pool_create()
 319  * @see sound_pool_set_state_change_callback()
 320  */
 321 sound_pool_error_e sound_pool_unset_state_change_callback(sound_pool_h pool);
 322
 323 /**
 324  * @brief Plays source by @a tag.
 325  * @details Creates stream with @a id that can be used to change parameters and
 326  *          get additional information.
 327  *          Sets stream state to SOUND_POOL_STREAM_STATE_PLAYING
 328  * @remarks Resultant stream volume will depend on global pool volume.
 329  *
 330  * @since_tizen 3.0
 331  * @param [in]  pool        The handle to the sound pool
 332  * @param [in]  tag         Unique string that identifies source
 333  * @param [in]  loop        Number of times stream will be repeated
 334  *                          (pass 0 if stream should be repeated continuously)
 335  * @param [in]  volume      Stream volume in 0.0~1.0 range
 336  * @param [in]  priority    Stream priority (0 = lowest priority). Check
 337  *                          @ref sound_pool_stream_set_priority() documentation
 338  *                          for details on prioritization rules.
 339  * @param [in]  callback    The callback that will be called after stream state
 340  *                          will be changed, or NULL if this callback call
 341  *                          isn't needed. If @a callback is set, then it will
 342  *                          be called asynchronously
 343  * @param [in]  user_data   The user data to be passed to the @a callback
 344  * @param [out] id          Unique stream identifier that can be used to
 345  *                          change parameters and get additional information
 346  * @return @c 0 on success, otherwise a negative error value
 347  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 348  *         (@a pool is NULL or corrupted, @a tag is NULL, @a volume is out of
 349  *         0.0~1.0 range, or @a id is NULL)
 350  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No sources tagged by @a tag exist
 351  *         in pool
 352  * @retval #SOUND_POOL_ERROR_OUT_OF_MEMORY Not enough memory to allocate new
 353  *         sound stream
 354  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
 355  *
 356  * @pre Create sound pool handler by calling @ref sound_pool_create()
 357  * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
 358  * @post When playback is finished normally (i.e. @ref sound_pool_stream_stop()
 359  *       will be not used for stream termination) state will be changed to
 360  *       SOUND_POOL_STREAM_STATE_FINISHED and memory will be cleared from the
 361  *       stream allocated resources automatically
 362  *
 363  * @see sound_pool_create()
 364  * @see sound_pool_load_source_from_file()
 365  * @see sound_pool_set_volume
 366  * @see sound_pool_get_volume
 367  */
 368 sound_pool_error_e sound_pool_stream_play(sound_pool_h pool, const char *tag,
 369                 unsigned loop, float volume, unsigned priority,
 370                 sound_pool_stream_state_change_cb callback, void *user_data,
 371                 unsigned *id);
 372
 373 /**
 374  * @brief Pauses stream by @a id.
 375  * @details Sets stream state to SOUND_POOL_STREAM_STATE_PAUSED.
 376  * @remarks Stream state has to be SOUND_POOL_STATE_PLAYING
 377  *
 378  * @since_tizen 3.0
 379  * @param [in]  pool    The handle to the sound pool
 380  * @param [in]  id      Unique stream identifier
 381  * @return @c 0 on success, otherwise a negative error value
 382  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 383  *         (@a pool is NULL or corrupted)
 384  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
 385  *         exist in pool
 386  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation or stream is in
 387  *         the state which is not allowed for pause operation
 388  *
 389  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 390  * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
 391  * @pre Start stream playback by calling @ref sound_pool_stream_play()
 392  *
 393  * @see sound_pool_create()
 394  * @see sound_pool_load_source_from_file()
 395  * @see sound_pool_stream_play()
 396  */
 397 sound_pool_error_e sound_pool_stream_pause(sound_pool_h pool, unsigned id);
 398
 399 /**
 400  * @brief Resumes stream by @a id.
 401  * @details Sets stream state to SOUND_POOL_STREAM_STATE_PLAYING.
 402  * @remarks Stream state has to be SOUND_POOL_STATE_PAUSED
 403  *
 404  * @since_tizen 3.0
 405  * @param [in]  pool    The handle to the sound pool
 406  * @param [in]  id      Unique stream identifier
 407  * @return @c 0 on success, otherwise a negative error value
 408  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 409  *         (@a pool is NULL or corrupted)
 410  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
 411  *         exist in pool
 412  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation or stream is in
 413  *         the state which is not allowed for resume operation
 414  *
 415  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 416  * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
 417  * @pre Start stream playback by calling @ref sound_pool_stream_play()
 418  * @pre Pause stream playback by calling @ref sound_pool_stream_pause()
 419  *
 420  * @see sound_pool_create()
 421  * @see sound_pool_load_source_from_file()
 422  * @see sound_pool_stream_play()
 423  * @see sound_pool_stream_pause()
 424  */
 425 sound_pool_error_e sound_pool_stream_resume(sound_pool_h pool, unsigned id);
 426
 427 /**
 428  * @brief Stops stream by @a id.
 429  * @details Sets stream state to SOUND_POOL_STREAM_STATE_STOPPED.
 430  *          After stream was stopped it can not be resumed and @a id value
 431  *          becomes invalid. Moreover, stream will never gets
 432  *          @c SOUND_POOL_STREAM_STATE_FINISHED state as it will be terminated
 433  *          after this function call.
 434  *
 435  * @since_tizen 3.0
 436  * @param [in]  pool    The handle to the sound pool
 437  * @param [in]  id      Unique stream identifier
 438  * @return @c 0 on success, otherwise a negative error value
 439  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 440  *         (@a pool is NULL or corrupted)
 441  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
 442  *         exist in pool
 443  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation or stream is in
 444  *         the state which is not allowed for stop operation
 445  *
 446  * @pre Create sound pool handler by calling @ref sound_pool_create()
 447  * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
 448  * @pre Start stream playback by calling @ref sound_pool_stream_play()
 449  *
 450  * @see sound_pool_create()
 451  * @see sound_pool_load_source_from_file()
 452  * @see sound_pool_stream_play()
 453  */
 454 sound_pool_error_e sound_pool_stream_stop(sound_pool_h pool, unsigned id);
 455
 456 /**
 457  * @brief Sets stream @a loop parameter by stream @a id.
 458  *
 459  * @since_tizen 3.0
 460  * @param [in]  pool    The handle to the sound pool
 461  * @param [in]  id      Unique stream identifier
 462  * @param [in]  loop    Number of times stream will be repeated
 463  *                      (pass 0 if stream should be repeated continuously)
 464  * @return @c 0 on success, otherwise a negative error value
 465  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 466  *         (@a pool is NULL or corrupted)
 467  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
 468  *         exist in pool
 469  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
 470  *
 471  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 472  * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
 473  * @pre Start stream playback by calling @ref sound_pool_stream_play()
 474  *
 475  * @see sound_pool_create()
 476  * @see sound_pool_load_source_from_file()
 477  * @see sound_pool_stream_play()
 478  */
 479 sound_pool_error_e sound_pool_stream_set_loop(sound_pool_h pool, unsigned id,
 480                 unsigned loop);
 481
 482 /**
 483  * @brief Gets stream @a loop parameter by stream @a id.
 484  *
 485  * @since_tizen 3.0
 486  * @param [in]  pool    The handle to the sound pool
 487  * @param [in]  id      Unique stream identifier
 488  * @param [out] loop    Number of times stream will be repeated before
 489  *                      finishing (getting state SOUND_POOL_STREAM_STATE_FINISHED)
 490  *                      and releasing of the memory and resources
 491  * @return @c 0 on success, otherwise a negative error value
 492  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 493  *         (@a pool is NULL or corrupted, or @a loop is NULL)
 494  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
 495  *         exist in pool
 496  *
 497  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 498  * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
 499  * @pre Start source playback by calling @ref sound_pool_stream_play()
 500  *
 501  * @see sound_pool_create()
 502  * @see sound_pool_load_source_from_file()
 503  * @see sound_pool_stream_play()
 504  */
 505 sound_pool_error_e sound_pool_stream_get_loop(sound_pool_h pool, unsigned id,
 506                 unsigned *loop);
 507
 508 /**
 509  * @brief Sets stream volume parameters by stream @a id.
 510  * @remarks Resultant stream volume will depend on global pool volume.
 511  *
 512  * @since_tizen 3.0
 513  * @param [in]  pool      The handle to the sound pool
 514  * @param [in]  id        Unique stream identifier
 515  * @param [in]  volume    Stream volume in 0.0~1.0 range
 516  * @return @c 0 on success, otherwise a negative error value
 517  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 518  *         (@a pool is NULL or corrupted, or @a volume isn't in 0.0~1.0 range)
 519  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
 520  *         exist in pool
 521  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
 522  *
 523  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 524  * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
 525  * @pre Start stream playback by calling @ref sound_pool_stream_play()
 526  *
 527  * @see sound_pool_create()
 528  * @see sound_pool_load_source_from_file()
 529  * @see sound_pool_stream_play()
 530  * @see sound_pool_set_volume
 531  * @see sound_pool_get_volume
 532  */
 533 sound_pool_error_e sound_pool_stream_set_volume(sound_pool_h pool, unsigned id,
 534                 float volume);
 535
 536 /**
 537  * @brief Gets stream volume parameters by stream @a id.
 538  *
 539  * @since_tizen 3.0
 540  * @param [in]  pool      The handle to the sound pool
 541  * @param [in]  id        Unique stream identifier
 542  * @param [out] volume    Stream volume in 0.0~1.0 range
 543  * @return @c 0 on success, otherwise a negative error value
 544  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 545  *         (@a pool is NULL or corrupted, or @a volume is NULL)
 546  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
 547  *         exist in pool
 548  *
 549  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 550  * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
 551  * @pre Start stream playback by calling @ref sound_pool_stream_play()
 552  *
 553  * @see sound_pool_create()
 554  * @see sound_pool_load_source_from_file()
 555  * @see sound_pool_stream_play()
 556  */
 557 sound_pool_error_e sound_pool_stream_get_volume(sound_pool_h pool, unsigned id,
 558                 float *volume);
 559
 560 /**
 561  * @brief Sets stream priority parameter by stream @a id.
 562  * @remarks Only streams with highest priority in the active Sound Pool can be
 563  *          played. If at least one stream with highest priority gets
 564  *          #SOUND_POOL_STREAM_STATE_PLAYING state, then all has been playing
 565  *          streams with lower priorities will be transfered to the
 566  *          #SOUND_POOL_STREAM_STATE_SUSPENDED state. If there is no more
 567  *          playing streams in some priority group (group of streams with the
 568  *          same priority), then all suspended previously streams in the group
 569  *          with one level lower priority will be resumed. For example, if we
 570  *          have N suspended streams in 'LOW' group, M suspended streams in
 571  *          'MEDIUM' group and K playing streams in 'HIGH' group then the
 572  *          following rules are valid: When all K streams in HIGH priority group
 573  *          will be finished, paused, or stopped and Sound Pool is in active
 574  *          state, only then M streams from MEDIUM priority group will be
 575  *          resumed. When all M+K streams from HIGH and MEDIUM priority groups
 576  *          will be finished, paused or stopped and Sound Pool is in active
 577  *          state, only then N streams from LOW priority group will be resumed.
 578  *          Transfering at least one stream from higher priority group will lead
 579  *          to suspending of all the streams from lower priorities group(s).
 580  *          Priorities don't make any effect in inactive Sound Pools. But after
 581  *          pool activation, all mentioned rules will be applied.
 582  *
 583  * @since_tizen 3.0
 584  * @param [in]  pool        The handle to the sound pool
 585  * @param [in]  id          Unique stream identifier
 586  * @param [in]  priority    Stream priority (0 = lowest priority)
 587  * @return @c 0 on success, otherwise a negative error value
 588  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 589  *         (@a pool is NULL or corrupted)
 590  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
 591  *         exist in pool
 592  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
 593  *
 594  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 595  * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
 596  * @pre Start stream playback by calling @ref sound_pool_stream_play()
 597  *
 598  * @see sound_pool_create()
 599  * @see sound_pool_load_source_from_file()
 600  * @see sound_pool_stream_play()
 601  */
 602 sound_pool_error_e sound_pool_stream_set_priority(sound_pool_h pool, unsigned id,
 603                 unsigned priority);
 604
 605 /**
 606  * @brief Gets stream priority parameter by stream @a id.
 607  *
 608  * @since_tizen 3.0
 609  * @param [in]   pool        The handle to the sound pool
 610  * @param [in]   id          Unique stream identifier
 611  * @param [out]  priority    Stream priority (0 = lowest priority). Check
 612  *                           @ref sound_pool_stream_set_priority() documentation
 613  *                           for details on prioritization rules.
 614  * @return @c 0 on success, otherwise a negative error value
 615  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 616  *         (@a pool is NULL or corrupted, or @a priority is NULL)
 617  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
 618  *         exist in pool
 619  *
 620  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 621  * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
 622  * @pre Start stream playback by calling @ref sound_pool_stream_play()
 623  *
 624  * @see sound_pool_create()
 625  * @see sound_pool_load_source_from_file()
 626  * @see sound_pool_stream_play()
 627  */
 628 sound_pool_error_e sound_pool_stream_get_priority(sound_pool_h pool, unsigned id,
 629                 unsigned *priority);
 630
 631 /**
 632  * @brief Gets current @a state of stream by @a id.
 633  *
 634  * @since_tizen 3.0
 635  * @param [in]  pool     The handle to the sound pool
 636  * @param [in]  id       Unique stream identifier
 637  * @param [out] state    Current state of stream
 638  * @return @c 0 on success, otherwise a negative error value
 639  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 640  *         (@a pool is NULL or corrupted, or @a state is NULL)
 641  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
 642  *         exist in pool
 643  *
 644  * @pre Create sound pool handler by calling @ref sound_pool_create()
 645  * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
 646  * @pre Start stream playback by calling @ref sound_pool_stream_play()
 647  *
 648  * @see sound_pool_create()
 649  * @see sound_pool_load_source_from_file()
 650  * @see sound_pool_stream_play()
 651  * @see sound_pool_stream_state_e
 652  */
 653 sound_pool_error_e sound_pool_stream_get_state(sound_pool_h pool, unsigned id,
 654                 sound_pool_stream_state_e *state);
 655
 656 /**
 657  * @brief Sets callback for handling stream state change events.
 658  *
 659  * @since_tizen 3.0
 660  * @param [in]  pool        The handle to the sound pool
 661  * @param [in]  id          Unique stream identifier
 662  * @param [in]  callback    The callback that will be called after stream state
 663  *                          will be changed. @a callback will be called
 664  *                          asynchronously
 665  * @param [in]  user_data   The user data to be passed to the @a callback
 666  * @return @c 0 on success, otherwise a negative error value
 667  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 668  *         (@a pool is NULL or corrupted, or @a callback is NULL)
 669  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
 670  *         exist in pool
 671  * @retval #SOUND_POOL_ERROR_INVALID_OPERATION Invalid operation
 672  *
 673  * @pre Create sound pool handler by calling @ref sound_pool_create()
 674  * @pre Load source to pool by calling @ref sound_pool_load_source_from_file()
 675  * @pre Start source playback by calling @ref sound_pool_stream_play()
 676  * @post Use @ref sound_pool_stream_unset_state_change_callback() function to
 677  *       unset the @a callback
 678  *
 679  * @see sound_pool_create()
 680  * @see sound_pool_load_source_from_file()
 681  * @see sound_pool_stream_play()
 682  * @see sound_pool_stream_state_change_cb
 683  */
 684 sound_pool_error_e sound_pool_stream_set_state_change_callback(sound_pool_h pool,
 685                 unsigned id, sound_pool_stream_state_change_cb callback, void *user_data);
 686
 687 /**
 688  * @brief Unsets callback for handling stream state change events.
 689  *
 690  * @since_tizen 3.0
 691  * @param [in]  pool    The handle to the sound pool
 692  * @param [in]  id      Unique stream identifier
 693  * @return @c 0 on success, otherwise a negative error value
 694  * @retval #SOUND_POOL_ERROR_INVALID_PARAMETER Invalid parameter
 695  *         (@a pool is NULL or corrupted)
 696  * @retval #SOUND_POOL_ERROR_KEY_NOT_AVAILABLE No streams identified by @a id
 697  *         exist in pool
 698  *
 699  * @pre Create sound @a pool handler by calling @ref sound_pool_create()
 700  * @pre Load source to @a pool by calling @ref sound_pool_load_source_from_file()
 701  * @pre Start stream playback by calling @ref sound_pool_stream_play()
 702  * @pre Set stream state change callback by calling @ref sound_pool_stream_set_state_change_callback()
 703  *
 704  * @see sound_pool_create()
 705  * @see sound_pool_load_source_from_file()
 706  * @see sound_pool_stream_play()
 707  * @see sound_pool_stream_state_change_cb
 708  */
 709 sound_pool_error_e sound_pool_stream_unset_state_change_callback(sound_pool_h pool,
 710                 unsigned id);
 711
 712 /**
 713  * @}
 714  */
 715
 716
 717 #ifdef __cplusplus
 718 }
 719 #endif
 720
 721 #endif /* __TIZEN_SOUND_POOL_H__ */