include/sound_manager_internal.h

   1 /*
   2 * Copyright (c) 2015 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_MEDIA_SOUND_MANAGER_INTERNAL_H__
  18 #define __TIZEN_MEDIA_SOUND_MANAGER_INTERNAL_H__
  19
  20 #ifdef __cplusplus
  21 extern "C"
  22 {
  23 #endif
  24
  25 /**
  26  * @file sound_manager_internal.h
  27  * @brief This file contains the Sound Manager Internal API.
  28  */
  29
  30 /**
  31  * @addtogroup CAPI_MEDIA_SOUND_MANAGER_MODULE
  32  * @{
  33  */
  34
  35 #define SOUND_TYPE_NUM                SOUND_TYPE_VOICE + 1
  36
  37 /**
  38  * @internal
  39  * @brief Virtual sound stream handle.
  40  * @since_tizen 3.0
  41  */
  42 typedef struct virtual_sound_stream_s* virtual_sound_stream_h;
  43
  44 /**
  45  * @internal
  46  * @brief Enumeration for Native API.
  47  * @since_tizen 3.0
  48  */
  49 typedef enum {
  50         NATIVE_API_SOUND_MANAGER,   /**< Sound-manager Native API */
  51         NATIVE_API_PLAYER,          /**< Player Native API */
  52         NATIVE_API_WAV_PLAYER,      /**< Wav-player Native API */
  53         NATIVE_API_TONE_PLAYER,     /**< Tone-player Native API */
  54         NATIVE_API_AUDIO_IO,        /**< Audio-io Native API */
  55         NATIVE_API_RECORDER,        /**< Recorder Native API */
  56 } native_api_e;
  57
  58 /**
  59  * @internal
  60  * @brief Enumeration for sound stream type for internal.
  61  * @since_tizen 3.0
  62  */
  63 typedef enum {
  64         SOUND_STREAM_TYPE_RINGTONE_CALL = 100, /**< Sound stream type for ringtone for call */
  65         SOUND_STREAM_TYPE_RINGBACKTONE_CALL,   /**< Sound stream type for ringback tone for call */
  66         SOUND_STREAM_TYPE_VOICE_CALL,          /**< Sound stream type for voice-call */
  67         SOUND_STREAM_TYPE_VIDEO_CALL,          /**< Sound stream type for video-call */
  68         SOUND_STREAM_TYPE_RADIO,               /**< Sound stream type for radio */
  69         SOUND_STREAM_TYPE_LOOPBACK,            /**< Sound stream type for loopback */
  70         SOUND_STREAM_TYPE_LOOPBACK_MIRRORING,  /**< Sound stream type for loopback-mirroring */
  71         SOUND_STREAM_TYPE_SOLO,                /**< Sound stream type for solo */
  72 } sound_stream_type_internal_e;
  73
  74 /**
  75  * @internal
  76  * @brief Enumeration for sound filters.
  77  * @since_tizen 4.0
  78  */
  79 typedef enum {
  80         SOUND_FILTER_NONE = 0,
  81         SOUND_FILTER_SOUNDALIVE,
  82 } sound_filter_e;
  83
  84 /**
  85  * @internal
  86  * @brief Enumeration for filter preset.
  87  * @since_tizen 4.0
  88  */
  89 typedef enum {
  90         SOUND_FILTER_PRESET_SOUNDALIVE_NORMAL = 0,   /**< Filter preset for SOUND_FILTER_SOUNDALIVE */
  91         SOUND_FILTER_PRESET_SOUNDALIVE_TUBE,         /**< Filter preset for SOUND_FILTER_SOUNDALIVE */
  92         SOUND_FILTER_PRESET_SOUNDALIVE_VIRT71,       /**< Filter preset for SOUND_FILTER_SOUNDALIVE */
  93         SOUND_FILTER_PRESET_SOUNDALIVE_STUDIO,       /**< Filter preset for SOUND_FILTER_SOUNDALIVE */
  94         SOUND_FILTER_PRESET_SOUNDALIVE_CLUB,         /**< Filter preset for SOUND_FILTER_SOUNDALIVE */
  95         SOUND_FILTER_PRESET_SOUNDALIVE_CONCERT_HALL, /**< Filter preset for SOUND_FILTER_SOUNDALIVE */
  96 } sound_filter_preset_e;
  97
  98 /**
  99  * @internal
 100  * @brief Gets the maximum master volume level.
 101  * @since_tizen 3.0
 102  * @param[out]  max_level       The maximum volume level
 103  * @return @c 0 on success,
 104  *         otherwise a negative error value
 105  * @retval #SOUND_MANAGER_ERROR_NONE Success
 106  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 107  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 108  * @see sound_manager_set_master_volume()
 109  * @see sound_manager_get_master_volume()
 110  */
 111 int sound_manager_get_max_master_volume(int *max_level);
 112
 113 /**
 114  * @internal
 115  * @brief Sets the master volume level.
 116  * @since_tizen 3.0
 117  * @param[in]   level   The volume level to be set
 118  * @return @c 0 on success,
 119  *         otherwise a negative error value
 120  * @retval #SOUND_MANAGER_ERROR_NONE Success
 121  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 122  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 123  * @see sound_manager_get_max_master_volume()
 124  * @see sound_manager_get_master_volume()
 125  */
 126 int sound_manager_set_master_volume(int level);
 127
 128 /**
 129  * @internal
 130  * @brief Gets the master volume level.
 131  * @since_tizen 3.0
 132  * @param[out]  level   The current master volume level
 133  * @return @c 0 on success,
 134  *         otherwise a negative error value
 135  * @retval #SOUND_MANAGER_ERROR_NONE Success
 136  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 137  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 138  * @see sound_manager_get_max_master_volume()
 139  * @see sound_manager_set_master_volume()
 140  */
 141 int sound_manager_get_master_volume(int *level);
 142
 143 /**
 144  * @internal
 145  * @brief Creates a handle for stream information.
 146  * @since_tizen 3.0
 147  *
 148  * @remarks     Do not call this API within sound_stream_focus_state_changed_cb() and sound_stream_focus_state_watch_cb(),\n
 149  *      otherwise SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned.\n
 150  *      To apply the stream policy according to this stream information, this handle should be passed to other APIs\n
 151  *      related to playback or recording.(e.g. player, wav-player, audio-io, etc.)
 152  *
 153  * @param[in]   stream_type     The type of stream for internal usage
 154  * @param[in]   callback        The focus state change callback function
 155  * @param[in]   user_data       The user data to be passed to the callback function
 156  * @param[out]  stream_info     The handle of stream information
 157  * @return @c 0 on success,
 158  *         otherwise a negative error value
 159  * @retval #SOUND_MANAGER_ERROR_NONE Success
 160  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 161  * @retval #SOUND_MANAGER_ERROR_INVALID_OPERATION Invalid operation
 162  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 163  * @see sound_manager_destroy_stream_information()
 164  * @see sound_manager_add_device_for_stream_routing()
 165  * @see sound_manager_remove_device_for_stream_routing()
 166  * @see sound_manager_apply_stream_routing()
 167  * @see sound_manager_acquire_focus()
 168  * @see sound_manager_destroy_focus()
 169  * @see sound_manager_get_focus_state()
 170  */
 171 int sound_manager_create_stream_information_internal(sound_stream_type_internal_e stream_type, sound_stream_focus_state_changed_cb callback, void *user_data, sound_stream_info_h *stream_info);
 172
 173 /**
 174  * @internal
 175  * @brief Sets the stream routing option.
 176  * @since_tizen 3.0
 177  *
 178  * @remarks     If the stream has not been made yet, this setting will be applied when the stream starts to play.
 179  *
 180  * @param[in]   stream_info     The handle of stream information
 181  * @param[in]   name    The name of option
 182  * @param[in]   value   The value of option
 183  * @return @c 0 on success,
 184  *         otherwise a negative error value
 185  * @retval #SOUND_MANAGER_ERROR_NONE Success
 186  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 187  * @retval #SOUND_MANAGER_ERROR_INVALID_STATE Invalid state
 188  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 189  * @pre Call sound_manager_create_stream_information() before calling this function.
 190  * @see sound_manager_create_stream_information()
 191  * @see sound_manager_create_stream_information_internal()
 192  * @see sound_manager_destroy_stream_information()
 193  */
 194 int sound_manager_set_stream_routing_option(sound_stream_info_h stream_info, const char *name, int value);
 195
 196 /**
 197  * @internal
 198  * @brief Queries if this stream information handle is available for the API.
 199  * @since_tizen 3.0
 200  * @param[in]   stream_info     The handle of stream information
 201  * @param[in]   api_name        The native API name
 202  * @param[out]  is_available    If @c true the api_name is available, @c false the api_name is not available for this strema_info
 203  * @return @c 0 on success,
 204  *         otherwise a negative error value
 205  * @retval #SOUND_MANAGER_ERROR_NONE Success
 206  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 207  * @see sound_manager_create_stream_information()
 208  * @see sound_manager_destroy_stream_information()
 209  */
 210 int sound_manager_is_available_stream_information(sound_stream_info_h stream_info, native_api_e api_name, bool *is_available);
 211
 212 /**
 213  * @internal
 214  * @brief Gets stream type from the stream information handle.
 215  * @since_tizen 3.0
 216  * @param[in]   stream_info     The handle of stream information
 217  * @param[out]  type    The stream type
 218  * @return @c 0 on success,
 219  *         otherwise a negative error value
 220  * @retval #SOUND_MANAGER_ERROR_NONE Success
 221  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 222  * @see sound_manager_create_stream_information()
 223  * @see sound_manager_destroy_stream_information()
 224  */
 225 int sound_manager_get_type_from_stream_information(sound_stream_info_h stream_info, char **type);
 226
 227 /**
 228  * @internal
 229  * @brief Gets the index of the stream information handle.
 230  * @since_tizen 3.0
 231  * @param[in]   stream_info     The handle of stream information
 232  * @param[out]  index   The unique index
 233  *
 234  * @return @c 0 on success,
 235  *         otherwise a negative error value
 236  * @retval #SOUND_MANAGER_ERROR_NONE Success
 237  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 238  * @see sound_manager_create_stream_information()
 239  * @see sound_manager_destroy_stream_information()
 240  */
 241 int sound_manager_get_index_from_stream_information(sound_stream_info_h stream_info, int *index);
 242
 243 /**
 244  * @internal
 245  * @brief Gets the internal stream information handle for VoIP session.
 246  * @since_tizen 3.0
 247  *
 248  * @remarks     If VoIP session is not set in this process, it'll return #SOUND_MANAGER_ERROR_NO_DATA.
 249  *
 250  * @param[out]  stream_info     The handle of stream information
 251  *
 252  * @return @c 0 on success,
 253  *         otherwise a negative error value
 254  * @retval #SOUND_MANAGER_ERROR_NONE Success
 255  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 256  * @retval #SOUND_MANAGER_ERROR_NO_DATA No data
 257  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 258  * @see sound_manager_set_session_type()
 259  * @see sound_manager_set_voip_session_mode()
 260  */
 261 int sound_manager_get_internal_voip_stream_information(sound_stream_info_h *stream_info);
 262
 263 /**
 264  * @internal
 265  * @brief Disable session backward compatibility.
 266  * @since_tizen 3.0
 267  *
 268  * @remarks     Multimedia framework support backward compatibility of legacy sound session. \n
 269  *      If a process does not want legacy sound session behavior in each multimedia framework, \n
 270  *      this function can be used explicitly not to support that.
 271  *
 272  * @return @c 0 on success,
 273  *         otherwise a negative error value
 274  * @retval #SOUND_MANAGER_ERROR_NONE Success
 275  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 276  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 277  */
 278 int sound_manager_disable_session_backward_compatibility(void);
 279
 280 /**
 281  * @internal
 282  * @brief Creates a virtual stream handle.
 283  * @since_tizen 3.0
 284  * @param[in]   stream_info     The handle of stream information
 285  * @param[out]  virtual_stream  The handle of virtual stream
 286  * @return @c 0 on success,
 287  *         otherwise a negative error value
 288  * @retval #SOUND_MANAGER_ERROR_NONE Success
 289  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 290  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 291  * @retval #SOUND_MANAGER_ERROR_NOT_SUPPORTED Not supported
 292  * @see sound_manager_create_stream_information()
 293  * @see sound_manager_destroy_stream_information()
 294  * @see sound_manager_destroy_virtual_stream()
 295  * @see sound_manager_start_virtual_stream()
 296  * @see sound_manager_stop_virtual_stream()
 297  */
 298 int sound_manager_create_virtual_stream(sound_stream_info_h stream_info, virtual_sound_stream_h *virtual_stream);
 299
 300 /**
 301  * @internal
 302  * @brief Destroys the virtual stream handle.
 303  * @since_tizen 3.0
 304  * @param[in]   virtual_stream  The handle of virtual stream
 305  * @return @c 0 on success,
 306  *         otherwise a negative error value
 307  * @retval #SOUND_MANAGER_ERROR_NONE Success
 308  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 309  * @retval #SOUND_MANAGER_ERROR_INVALID_STATE Invalid state
 310  * @see sound_manager_create_virtual_stream()
 311  * @see sound_manager_start_virtual_stream()
 312  * @see sound_manager_stop_virtual_stream()
 313  */
 314 int sound_manager_destroy_virtual_stream(virtual_sound_stream_h virtual_stream);
 315
 316 /**
 317  * @internal
 318  * @brief Starts the virtual stream.
 319  * @since_tizen 3.0
 320  * @param[in]   virtual_stream  The handle of virtual stream
 321  * @return @c 0 on success,
 322  *         otherwise a negative error value
 323  * @retval #SOUND_MANAGER_ERROR_NONE Success
 324  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 325  * @retval #SOUND_MANAGER_ERROR_INVALID_STATE Invalid state
 326  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 327  * @see sound_manager_create_virtual_stream()
 328  * @see sound_manager_destroy_virtual_stream()
 329  * @see sound_manager_stop_virtual_stream()
 330  */
 331 int sound_manager_start_virtual_stream(virtual_sound_stream_h virtual_stream);
 332
 333 /**
 334  * @internal
 335  * @brief Stops the virtual stream.
 336  * @since_tizen 3.0
 337  * @param[in]   virtual_stream  The handle of virtual stream
 338  * @return @c 0 on success,
 339  *         otherwise a negative error value
 340  * @retval #SOUND_MANAGER_ERROR_NONE Success
 341  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 342  * @retval #SOUND_MANAGER_ERROR_INVALID_STATE Invalid state
 343  * @see sound_manager_create_virtual_stream()
 344  * @see sound_manager_destroy_virtual_stream()
 345  * @see sound_manager_start_virtual_stream()
 346  */
 347 int sound_manager_stop_virtual_stream(virtual_sound_stream_h virtual_stream);
 348
 349 /**
 350  * @internal
 351  * @brief Set sound filter and apply to audio streams given selected stream type.
 352  * @since_tizen 4.0
 353  * @param[in]   stream_type             stream type to apply
 354  * @param[in]   filter                  sound filter to apply
 355  * @return @c 0 on success,
 356  *         otherwise a negative error value
 357  * @retval #SOUND_MANAGER_ERROR_NONE Success
 358  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 359  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 360  * @retval #SOUND_MANAGER_ERROR_NOT_SUPPORTED Not supported
 361  * @see sound_manager_unset_filter()
 362  */
 363 int sound_manager_set_filter(sound_stream_type_e stream_type, sound_filter_e filter);
 364
 365 /**
 366  * @internal
 367  * @brief Unset sound filter and remove from audio streams given selected stream type.
 368  * @since_tizen 4.0
 369  * @param[in]   stream_type             stream type to remove
 370  * @return @c 0 on success,
 371  *         otherwise a negative error value
 372  * @retval #SOUND_MANAGER_ERROR_NONE Success
 373  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 374  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 375  * @retval #SOUND_MANAGER_ERROR_NOT_SUPPORTED Not supported
 376  * @see sound_manager_set_filter()
 377  */
 378 int sound_manager_unset_filter(sound_stream_type_e stream_type);
 379
 380 /**
 381  * @internal
 382  * @brief Apply preset configuration to the filter according to selected stream type.
 383  * @since_tizen 4.0
 384  * @param[in]   stream_type             given stream type
 385  * @param[in]   filter                  given sound filter
 386  * @param[in]   preset                  filter preset to apply
 387  * @return @c 0 on success,
 388  *         otherwise a negative error value
 389  * @retval #SOUND_MANAGER_ERROR_NONE Success
 390  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 391  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 392  * @retval #SOUND_MANAGER_ERROR_NOT_SUPPORTED Not supported
 393  * @see sound_manager_set_filter()
 394  */
 395 int sound_manager_set_filter_preset(sound_stream_type_e stream_type, sound_filter_e filter, sound_filter_preset_e preset);
 396
 397 /**
 398  * @}
 399  */
 400
 401 #ifdef __cplusplus
 402 }
 403 #endif
 404
 405 #endif /* __TIZEN_MEDIA_SOUND_MANAGER_INTERNAL_H__ */