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_SOLO,                /**< Sound stream type for solo */
  71 } sound_stream_type_internal_e;
  72
  73 /**
  74  * @internal
  75  * @brief Gets the maximum master volume level.
  76  * @since_tizen 3.0
  77  * @param[out]  max_level       The maximum volume level
  78  * @return @c 0 on success,
  79  *         otherwise a negative error value
  80  * @retval #SOUND_MANAGER_ERROR_NONE Success
  81  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
  82  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
  83  * @see sound_manager_set_master_volume()
  84  * @see sound_manager_get_master_volume()
  85  */
  86 int sound_manager_get_max_master_volume(int *max_level);
  87
  88 /**
  89  * @internal
  90  * @brief Sets the master volume level.
  91  * @since_tizen 3.0
  92  * @param[in]   level   The volume level to be set
  93  * @return @c 0 on success,
  94  *         otherwise a negative error value
  95  * @retval #SOUND_MANAGER_ERROR_NONE Success
  96  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
  97  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
  98  * @see sound_manager_get_max_master_volume()
  99  * @see sound_manager_get_master_volume()
 100  */
 101 int sound_manager_set_master_volume(int level);
 102
 103 /**
 104  * @internal
 105  * @brief Gets the master volume level.
 106  * @since_tizen 3.0
 107  * @param[out]  level   The current master volume level
 108  * @return @c 0 on success,
 109  *         otherwise a negative error value
 110  * @retval #SOUND_MANAGER_ERROR_NONE Success
 111  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 112  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 113  * @see sound_manager_get_max_master_volume()
 114  * @see sound_manager_set_master_volume()
 115  */
 116 int sound_manager_get_master_volume(int *level);
 117
 118 /**
 119  * @internal
 120  * @brief Creates a handle for stream information.
 121  * @since_tizen 3.0
 122  * @details     To apply the stream policy according to this stream information, this handle should be passed to other APIs\n
 123  *      related to playback or recording. (e.g., player, wav-player, audio-io, etc.)
 124  * @param[in]   stream_type     The type of stream for internal usage
 125  * @param[in]   callback        The focus state change callback function (mandatory)
 126  * @param[in]   user_data       The user data to be passed to the callback function
 127  * @param[out]  stream_info     The handle of stream information
 128  *
 129  * @remarks     Do not call this API within sound_stream_focus_state_changed_cb() and sound_stream_focus_state_watch_cb(),\n
 130  *      otherwise SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned.
 131  *
 132  * @return @c 0 on success,
 133  *         otherwise a negative error value
 134  * @retval #SOUND_MANAGER_ERROR_NONE Success
 135  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 136  * @retval #SOUND_MANAGER_ERROR_INVALID_OPERATION Invalid operation
 137  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 138  * @see sound_manager_destroy_stream_information()
 139  * @see sound_manager_add_device_for_stream_routing()
 140  * @see sound_manager_remove_device_for_stream_routing()
 141  * @see sound_manager_apply_stream_routing()
 142  * @see sound_manager_acquire_focus()
 143  * @see sound_manager_destroy_focus()
 144  * @see sound_manager_get_focus_state()
 145  */
 146 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);
 147
 148 /**
 149  * @internal
 150  * @brief Sets the stream routing option.
 151  * @since_tizen 3.0
 152  * @param[in]   stream_info     The handle of stream information
 153  * @param[in]   name    The name of option
 154  * @param[in]   value   The value of option
 155  *
 156  * @remarks     If the stream has not been made yet, this setting will be applied when the stream starts to play.
 157  *
 158  * @return @c 0 on success,
 159  *         otherwise a negative error value
 160  * @retval #SOUND_MANAGER_ERROR_NONE Success
 161  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 162  * @retval #SOUND_MANAGER_ERROR_INVALID_STATE Invalid state
 163  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 164  * @pre Call sound_manager_create_stream_information() before calling this function.
 165  * @see sound_manager_create_stream_information()
 166  * @see sound_manager_create_stream_information_internal()
 167  * @see sound_manager_destroy_stream_information()
 168  */
 169 int sound_manager_set_stream_routing_option(sound_stream_info_h stream_info, const char *name, int value);
 170
 171 /**
 172  * @internal
 173  * @brief Queries if this stream information handle is available for the API.
 174  * @since_tizen 3.0
 175  * @param[in]   stream_info     The handle of stream information
 176  * @param[in]   api_name        The native API name
 177  * @param[out]  is_available    If @c true the api_name is available, @c false the api_name is not available for this strema_info
 178  *
 179  * @return @c 0 on success,
 180  *         otherwise a negative error value
 181  * @retval #SOUND_MANAGER_ERROR_NONE Success
 182  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 183  * @see sound_manager_create_stream_information()
 184  * @see sound_manager_destroy_stream_information()
 185  */
 186 int sound_manager_is_available_stream_information(sound_stream_info_h stream_info, native_api_e api_name, bool *is_available);
 187
 188 /**
 189  * @internal
 190  * @brief Gets stream type from the stream information handle.
 191  * @since_tizen 3.0
 192  * @param[in]   stream_info     The handle of stream information
 193  * @param[out]  type    The stream type
 194  *
 195  * @return @c 0 on success,
 196  *         otherwise a negative error value
 197  * @retval #SOUND_MANAGER_ERROR_NONE Success
 198  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 199  * @see sound_manager_create_stream_information()
 200  * @see sound_manager_destroy_stream_information()
 201  */
 202 int sound_manager_get_type_from_stream_information(sound_stream_info_h stream_info, char **type);
 203
 204 /**
 205  * @internal
 206  * @brief Gets the index of the stream information handle.
 207  * @since_tizen 3.0
 208  * @param[in]   stream_info     The handle of stream information
 209  * @param[out]  index   The unique index
 210  *
 211  * @return @c 0 on success,
 212  *         otherwise a negative error value
 213  * @retval #SOUND_MANAGER_ERROR_NONE Success
 214  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 215  * @see sound_manager_create_stream_information()
 216  * @see sound_manager_destroy_stream_information()
 217  */
 218 int sound_manager_get_index_from_stream_information(sound_stream_info_h stream_info, int *index);
 219
 220 /**
 221  * @internal
 222  * @brief Gets the reason for the current acquired playback focus.
 223  * @since_tizen 3.0
 224  * @param[out]  acquired_by     The reason for the current acquired playback focus
 225  * @param[out]  additional_info The additional information of the acquired playback focus (this can be null)
 226  *
 227  * @remarks     If there is no acquired playback focus in this system, it'll return #SOUND_MANAGER_ERROR_NO_DATA.
 228  *
 229  * @return @c 0 on success,
 230  *         otherwise a negative error value
 231  * @retval #SOUND_MANAGER_ERROR_NONE Success
 232  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 233  * @retval #SOUND_MANAGER_ERROR_NO_DATA No data
 234  * @see sound_manager_get_reason_for_current_recording_focus()
 235  */
 236 int sound_manager_get_reason_for_current_playback_focus(sound_stream_focus_change_reason_e *acquired_by, char **additional_info);
 237
 238 /**
 239  * @internal
 240  * @brief Gets the reason for the current acquired recording focus.
 241  * @since_tizen 3.0
 242  * @param[out]  acquired_by     The reason for the current acquired recording focus
 243  * @param[out]  additional_info The additional information of the acquired recording focus (this can be null)
 244  *
 245  * @remarks     If there is no acquired recording focus in this system, it'll return #SOUND_MANAGER_ERROR_NO_DATA.
 246  *
 247  * @return @c 0 on success,
 248  *         otherwise a negative error value
 249  * @retval #SOUND_MANAGER_ERROR_NONE Success
 250  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 251  * @retval #SOUND_MANAGER_ERROR_NO_DATA No data
 252  * @see sound_manager_get_reason_for_current_playback_focus()
 253  */
 254 int sound_manager_get_reason_for_current_recording_focus(sound_stream_focus_change_reason_e *acquired_by, char **additional_info);
 255
 256 /**
 257  * @internal
 258  * @brief Creates a virtual stream handle.
 259  * @since_tizen 3.0
 260  * @param[in]   stream_info     The handle of stream information
 261  * @param[out]  virtual_stream  The handle of virtual stream
 262  *
 263  * @return @c 0 on success,
 264  *         otherwise a negative error value
 265  * @retval #SOUND_MANAGER_ERROR_NONE Success
 266  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 267  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 268  * @retval #SOUND_MANAGER_ERROR_NOT_SUPPORTED Not supported
 269  * @see sound_manager_create_stream_information()
 270  * @see sound_manager_destroy_stream_information()
 271  * @see sound_manager_destroy_virtual_stream()
 272  * @see sound_manager_start_virtual_stream()
 273  * @see sound_manager_stop_virtual_stream()
 274  */
 275 int sound_manager_create_virtual_stream(sound_stream_info_h stream_info, virtual_sound_stream_h *virtual_stream);
 276
 277 /**
 278  * @internal
 279  * @brief Destroys the virtual stream handle.
 280  * @since_tizen 3.0
 281  * @param[in]   virtual_stream  The handle of virtual stream
 282  *
 283  * @return @c 0 on success,
 284  *         otherwise a negative error value
 285  * @retval #SOUND_MANAGER_ERROR_NONE Success
 286  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 287  * @retval #SOUND_MANAGER_ERROR_INVALID_STATE Invalid state
 288  * @see sound_manager_create_virtual_stream()
 289  * @see sound_manager_start_virtual_stream()
 290  * @see sound_manager_stop_virtual_stream()
 291  */
 292 int sound_manager_destroy_virtual_stream(virtual_sound_stream_h virtual_stream);
 293
 294 /**
 295  * @internal
 296  * @brief Starts the virtual stream.
 297  * @since_tizen 3.0
 298  * @param[in]   virtual_stream  The handle of virtual stream
 299  *
 300  * @return @c 0 on success,
 301  *         otherwise a negative error value
 302  * @retval #SOUND_MANAGER_ERROR_NONE Success
 303  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 304  * @retval #SOUND_MANAGER_ERROR_INVALID_STATE Invalid state
 305  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 306  * @see sound_manager_create_virtual_stream()
 307  * @see sound_manager_destroy_virtual_stream()
 308  * @see sound_manager_stop_virtual_stream()
 309  */
 310 int sound_manager_start_virtual_stream(virtual_sound_stream_h virtual_stream);
 311
 312 /**
 313  * @internal
 314  * @brief Stops the virtual stream.
 315  * @since_tizen 3.0
 316  * @param[in]   virtual_stream  The handle of virtual stream
 317  *
 318  * @return @c 0 on success,
 319  *         otherwise a negative error value
 320  * @retval #SOUND_MANAGER_ERROR_NONE Success
 321  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 322  * @retval #SOUND_MANAGER_ERROR_INVALID_STATE Invalid state
 323  * @see sound_manager_create_virtual_stream()
 324  * @see sound_manager_destroy_virtual_stream()
 325  * @see sound_manager_start_virtual_stream()
 326  */
 327 int sound_manager_stop_virtual_stream(virtual_sound_stream_h virtual_stream);
 328
 329 /**
 330  * @}
 331  */
 332
 333 #ifdef __cplusplus
 334 }
 335 #endif
 336
 337 #endif /* __TIZEN_MEDIA_SOUND_MANAGER_INTERNAL_H__ */