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  *
 123  * @remarks     Do not call this API within sound_stream_focus_state_changed_cb() and sound_stream_focus_state_watch_cb(),\n
 124  *      otherwise SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned.\n
 125  *      To apply the stream policy according to this stream information, this handle should be passed to other APIs\n
 126  *      related to playback or recording.(e.g. player, wav-player, audio-io, etc.)
 127  *
 128  * @param[in]   stream_type     The type of stream for internal usage
 129  * @param[in]   callback        The focus state change callback function
 130  * @param[in]   user_data       The user data to be passed to the callback function
 131  * @param[out]  stream_info     The handle of stream information
 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  *
 153  * @remarks     If the stream has not been made yet, this setting will be applied when the stream starts to play.
 154  *
 155  * @param[in]   stream_info     The handle of stream information
 156  * @param[in]   name    The name of option
 157  * @param[in]   value   The value of option
 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  * @return @c 0 on success,
 179  *         otherwise a negative error value
 180  * @retval #SOUND_MANAGER_ERROR_NONE Success
 181  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 182  * @see sound_manager_create_stream_information()
 183  * @see sound_manager_destroy_stream_information()
 184  */
 185 int sound_manager_is_available_stream_information(sound_stream_info_h stream_info, native_api_e api_name, bool *is_available);
 186
 187 /**
 188  * @internal
 189  * @brief Gets stream type from the stream information handle.
 190  * @since_tizen 3.0
 191  * @param[in]   stream_info     The handle of stream information
 192  * @param[out]  type    The stream type
 193  * @return @c 0 on success,
 194  *         otherwise a negative error value
 195  * @retval #SOUND_MANAGER_ERROR_NONE Success
 196  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 197  * @see sound_manager_create_stream_information()
 198  * @see sound_manager_destroy_stream_information()
 199  */
 200 int sound_manager_get_type_from_stream_information(sound_stream_info_h stream_info, char **type);
 201
 202 /**
 203  * @internal
 204  * @brief Gets the index of the stream information handle.
 205  * @since_tizen 3.0
 206  * @param[in]   stream_info     The handle of stream information
 207  * @param[out]  index   The unique index
 208  *
 209  * @return @c 0 on success,
 210  *         otherwise a negative error value
 211  * @retval #SOUND_MANAGER_ERROR_NONE Success
 212  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 213  * @see sound_manager_create_stream_information()
 214  * @see sound_manager_destroy_stream_information()
 215  */
 216 int sound_manager_get_index_from_stream_information(sound_stream_info_h stream_info, int *index);
 217
 218 /**
 219  * @internal
 220  * @brief Gets the reason for the current acquired playback focus.
 221  * @since_tizen 3.0
 222  *
 223  * @remarks     If there is no acquired playback focus in this system, it'll return #SOUND_MANAGER_ERROR_NO_DATA.
 224  *
 225  * @param[out]  acquired_by     The reason for the current acquired playback focus
 226  * @param[out]  extra_info The extra information of the acquired playback focus (this can be null)
 227  * @return @c 0 on success,
 228  *         otherwise a negative error value
 229  * @retval #SOUND_MANAGER_ERROR_NONE Success
 230  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 231  * @retval #SOUND_MANAGER_ERROR_NO_DATA No data
 232  * @see sound_manager_get_reason_for_current_recording_focus()
 233  */
 234 int sound_manager_get_reason_for_current_playback_focus(sound_stream_focus_change_reason_e *acquired_by, char **extra_info);
 235
 236 /**
 237  * @internal
 238  * @brief Gets the reason for the current acquired recording focus.
 239  * @since_tizen 3.0
 240  *
 241  * @remarks     If there is no acquired recording focus in this system, it'll return #SOUND_MANAGER_ERROR_NO_DATA.
 242  *
 243  * @param[out]  acquired_by     The reason for the current acquired recording focus
 244  * @param[out]  extra_info The extra information of the acquired recording focus (this can be null)
 245  * @return @c 0 on success,
 246  *         otherwise a negative error value
 247  * @retval #SOUND_MANAGER_ERROR_NONE Success
 248  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 249  * @retval #SOUND_MANAGER_ERROR_NO_DATA No data
 250  * @see sound_manager_get_reason_for_current_playback_focus()
 251  */
 252 int sound_manager_get_reason_for_current_recording_focus(sound_stream_focus_change_reason_e *acquired_by, char **extra_info);
 253
 254 /**
 255  * @internal
 256  * @brief Creates a virtual stream handle.
 257  * @since_tizen 3.0
 258  * @param[in]   stream_info     The handle of stream information
 259  * @param[out]  virtual_stream  The handle of virtual stream
 260  * @return @c 0 on success,
 261  *         otherwise a negative error value
 262  * @retval #SOUND_MANAGER_ERROR_NONE Success
 263  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 264  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 265  * @retval #SOUND_MANAGER_ERROR_NOT_SUPPORTED Not supported
 266  * @see sound_manager_create_stream_information()
 267  * @see sound_manager_destroy_stream_information()
 268  * @see sound_manager_destroy_virtual_stream()
 269  * @see sound_manager_start_virtual_stream()
 270  * @see sound_manager_stop_virtual_stream()
 271  */
 272 int sound_manager_create_virtual_stream(sound_stream_info_h stream_info, virtual_sound_stream_h *virtual_stream);
 273
 274 /**
 275  * @internal
 276  * @brief Destroys the virtual stream handle.
 277  * @since_tizen 3.0
 278  * @param[in]   virtual_stream  The handle of virtual stream
 279  * @return @c 0 on success,
 280  *         otherwise a negative error value
 281  * @retval #SOUND_MANAGER_ERROR_NONE Success
 282  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 283  * @retval #SOUND_MANAGER_ERROR_INVALID_STATE Invalid state
 284  * @see sound_manager_create_virtual_stream()
 285  * @see sound_manager_start_virtual_stream()
 286  * @see sound_manager_stop_virtual_stream()
 287  */
 288 int sound_manager_destroy_virtual_stream(virtual_sound_stream_h virtual_stream);
 289
 290 /**
 291  * @internal
 292  * @brief Starts the virtual stream.
 293  * @since_tizen 3.0
 294  * @param[in]   virtual_stream  The handle of virtual stream
 295  * @return @c 0 on success,
 296  *         otherwise a negative error value
 297  * @retval #SOUND_MANAGER_ERROR_NONE Success
 298  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 299  * @retval #SOUND_MANAGER_ERROR_INVALID_STATE Invalid state
 300  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 301  * @see sound_manager_create_virtual_stream()
 302  * @see sound_manager_destroy_virtual_stream()
 303  * @see sound_manager_stop_virtual_stream()
 304  */
 305 int sound_manager_start_virtual_stream(virtual_sound_stream_h virtual_stream);
 306
 307 /**
 308  * @internal
 309  * @brief Stops the virtual stream.
 310  * @since_tizen 3.0
 311  * @param[in]   virtual_stream  The handle of virtual stream
 312  * @return @c 0 on success,
 313  *         otherwise a negative error value
 314  * @retval #SOUND_MANAGER_ERROR_NONE Success
 315  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 316  * @retval #SOUND_MANAGER_ERROR_INVALID_STATE Invalid state
 317  * @see sound_manager_create_virtual_stream()
 318  * @see sound_manager_destroy_virtual_stream()
 319  * @see sound_manager_start_virtual_stream()
 320  */
 321 int sound_manager_stop_virtual_stream(virtual_sound_stream_h virtual_stream);
 322
 323 /**
 324  * @}
 325  */
 326
 327 #ifdef __cplusplus
 328 }
 329 #endif
 330
 331 #endif /* __TIZEN_MEDIA_SOUND_MANAGER_INTERNAL_H__ */