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