include/sound_manager.h

   1 /*
   2 * Copyright (c) 2011 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
  18
  19
  20 #ifndef __TIZEN_MEDIA_SOUND_MANAGER_H__
  21 #define __TIZEN_MEDIA_SOUND_MANAGER_H__
  22
  23 #include <tizen.h>
  24
  25 #ifdef __cplusplus
  26 extern "C"
  27 {
  28 #endif
  29
  30 #define SOUND_MANAGER_ERROR_CLASS          TIZEN_ERROR_MULTIMEDIA_CLASS | 0x30
  31
  32 /**
  33  * @file sound_manager.h
  34  * @brief This file contains the Sound Manager API
  35  */
  36
  37 /**
  38  * @addtogroup CAPI_MEDIA_SOUND_MANAGER_MODULE
  39  * @{
  40  */
  41
  42 /**
  43  * @brief Enumerations of sound type
  44  */
  45 typedef enum
  46 {
  47     SOUND_TYPE_SYSTEM,          /**< Sound type for system */
  48     SOUND_TYPE_NOTIFICATION,    /**< Sound type for notifications */
  49     SOUND_TYPE_ALARM,           /**< Sound type for alarm */
  50     SOUND_TYPE_RINGTONE,        /**< Sound type for ringtones */
  51     SOUND_TYPE_MEDIA,           /**< Sound type for media */
  52     SOUND_TYPE_CALL,            /**< Sound type for call */
  53 } sound_type_e;
  54
  55
  56 /**
  57  * @brief Enumerations of sound route policy
  58  */
  59 typedef enum {
  60     SOUND_ROUTE_DEFAULT,        /**< Audio device priority: 1. bluetooth headset, 2. wired headset 3. built-in speaker and microphone. */
  61     SOUND_ROUTE_IGNORE_A2DP,    /**< Audio device priority: 1. wired headset, 2. built-in speaker and microphone. */
  62     SOUND_ROUTE_HANDSET_ONLY    /**< Use only built-in speaker and microphone */
  63 } sound_route_policy_e;
  64
  65 /**
  66  * @brief Enumerations of sound device
  67  */
  68 typedef enum {
  69     SOUND_DEVICE_NONE,          /**< Abnormal case */
  70     SOUND_DEVICE_HANDSET,       /**< Speaker, Wired headset, Wired earpiece */
  71     SOUND_DEVICE_BLUETOOTH      /**< Bluetooth */
  72 } sound_device_e;
  73
  74 /**
  75  * @brief error codes for sound manager
  76  */
  77 typedef enum{
  78     SOUND_MANAGER_ERROR_NONE        = TIZEN_ERROR_NONE,                      /**< Successful */
  79     SOUND_MANAGER_ERROR_OUT_OF_MEMORY       = TIZEN_ERROR_OUT_OF_MEMORY,           /**< Out of memory */
  80     SOUND_MANAGER_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,       /**< Invalid parameter */
  81     SOUND_MANAGER_ERROR_INVALID_OPERATION = TIZEN_ERROR_INVALID_OPERATION,       /**< Invalid operation */
  82     SOUND_MANAGER_ERROR_NO_PLAYING_SOUND  = SOUND_MANAGER_ERROR_CLASS | 01,    /**< No playing sound */
  83 } sound_manager_error_e;
  84
  85 /**
  86  * @brief Enumerations of session type
  87  */
  88 typedef enum{
  89         SOUND_SESSION_TYPE_SHARE = 0,                   /**< Share type : shares it's session with other share type application. */
  90         SOUND_SESSION_TYPE_EXCLUSIVE,                   /**< Exclusive type : make previous session stop.*/
  91 } sound_session_type_e;
  92
  93 /**
  94  * @brief Enumerations of session notification
  95  */
  96 typedef enum{
  97         SOUND_SESSION_NOTIFY_STOP = 0,                  /**< Stop : session of application has interrupted by policy. */
  98         SOUND_SESSION_NOTIFY_RESUME,               /**< Resume : session interrupt of application has ended. */
  99 } sound_session_notify_e;
 100
 101
 102 /**
 103  * @brief Called when the sound session notification has occured.
 104  * @param[in]   notify  The sound session notification
 105  * @param[in]   user_data       The user data passed from the callback registration function
 106  * @pre You should register this callback by sound_manager_set_session_notify_cb()
 107  * @see sound_manager_set_session_notify_cb()
 108  */
 109 typedef void (*sound_session_notify_cb) (sound_session_notify_e notify, void *user_data);
 110
 111 /**
 112  * @brief Called when the system volume has changed.
 113  * @param[in]   type    The sound type of changed volume
 114  * @param[in]   volume  The new volume value
 115  * @param[in]   user_data       The user data passed from the callback registration function
 116  * @pre sound_manager_set_volume() will invoke this callback if you register it using sound_manager_set_volume_changed_cb()
 117  * @see sound_manager_set_volume_changed_cb()
 118  * @see sound_manager_unset_volume_changed_cb()
 119  */
 120 typedef void (*sound_manager_volume_changed_cb)(sound_type_e type, unsigned int volume, void *user_data);
 121
 122 /**
 123  * @brief Called when the sound route policy has changes.
 124  * @param[in]   route The new sound route policy
 125  * @param[in]   user_data The user data passed from the callback registration function
 126  * @pre sound_manager_set_route_policy() will invoke this callback if you register it using sound_manager_set_route_policy_changed_cb()
 127  * @see sound_manager_set_route_policy_changed_cb()
 128  * @see sound_manager_unset_route_policy_changed_cb()
 129  */
 130 typedef void (*sound_manager_route_policy_changed_cb)(sound_route_policy_e route, void *user_data);
 131
 132 /**
 133  * @brief Gets the maximum volume level supported for a particular sound type
 134  * @param[in]           type The sound type
 135  * @param[out]  max     The maximum volume level
 136  * @return 0 on success, otherwise a negative error value.
 137  * @retval #SOUND_MANAGER_ERROR_NONE Success
 138  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 139  * @see sound_manager_set_volume()
 140  */
 141 int sound_manager_get_max_volume(sound_type_e type, int *max);
 142
 143 /**
 144  * @brief Sets the volume level specified for a particular sound type
 145  * @param[in]           type The sound type
 146  * @param[out]  volume  The volume level to be set
 147  * @return 0 on success, otherwise a negative error value.
 148  * @retval #SOUND_MANAGER_ERROR_NONE Success
 149  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 150  * @see sound_manager_get_max_volume()
 151  * @see sound_manager_get_volume()
 152  */
 153 int sound_manager_set_volume(sound_type_e type, int volume);
 154
 155 /**
 156  * @brief Gets the volume level specified for a particular sound type
 157  * @param[in]           type The sound type
 158  * @param[out]  volume  The current volume level
 159  * @return 0 on success, otherwise a negative error value.
 160  * @retval #SOUND_MANAGER_ERROR_NONE Success
 161  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 162  * @see sound_manager_get_max_volume()
 163  * @see sound_manager_set_volume()
 164  */
 165 int sound_manager_get_volume(sound_type_e type, int *volume);
 166
 167 /**
 168  * @brief Sets the application's sound route policy
 169  * @param[in]           route  The route policy to set
 170  * @return 0 on success, otherwise a negative error value
 171  * @retval #SOUND_MANAGER_ERROR_NONE Success
 172  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 173  * @see sound_manager_get_route_policy()
 174  */
 175 int sound_manager_set_route_policy (sound_route_policy_e route);
 176
 177 /**
 178  * @brief Gets the current application's route policy
 179  * @param[out]  route  The current route policy
 180  * @return 0 on success, 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_set_route_policy()
 184  */
 185 int sound_manager_get_route_policy (sound_route_policy_e *route);
 186
 187 /**
 188  * @brief Gets the current playing sound type
 189  * @param[out]          type The current sound type
 190  * @return 0 on success, otherwise a negative error value.
 191  * @retval #SOUND_MANAGER_ERROR_NONE Success
 192  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 193  * @retval #SOUND_MANAGER_ERROR_NO_PLAYING_SOUND No playing sound
 194  * @see sound_manager_get_current_sound_device()
 195  * @see player_set_sound_type()
 196  * @see audio_out_create()
 197  * @see wav_player_start()
 198  */
 199 int sound_manager_get_current_sound_type(sound_type_e *type);
 200
 201 /**
 202  * @brief Gets the current device type
 203  * @param[out]  device The current sound device
 204  * @return 0 on success, otherwise a negative error value.
 205  * @retval #SOUND_MANAGER_ERROR_NONE Success
 206  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 207  * @retval #SOUND_MANAGER_ERROR_NO_PLAYING_SOUND No playing sound
 208  * @see sound_manager_get_current_sound_type()
 209  */
 210 int sound_manager_get_current_sound_device(sound_device_e *device);
 211
 212 /**
 213  * @brief Registers a callback function to be invoked when the volume level is changed.
 214  * @param[in]   callback        Callback function to indicate change in volume
 215  * @param[in]   user_data       The user data to be passed to the callback function
 216  * @return 0 on success, otherwise a negative error value.
 217  * @retval #SOUND_MANAGER_ERROR_NONE Success
 218  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 219  * @post  sound_manager_volume_changed_cb() will be invoked
 220  * @see sound_manager_unset_volume_changed_cb()
 221  * @see sound_manager_volume_changed_cb()
 222  */
 223 int sound_manager_set_volume_changed_cb(sound_manager_volume_changed_cb callback, void *user_data);
 224
 225 /**
 226  * @brief Unregisters the volume change callback
 227  * @see sound_manager_set_volume_changed_cb()
 228  */
 229 void sound_manager_unset_volume_changed_cb(void);
 230
 231 /**
 232  * @brief Registers a callback function to be invoked when the route policy is changed.
 233  * @param[in]   callback        Callback function to indicate change in route policy
 234  * @param[in]   user_data       The user data to be passed to the callback function
 235  * @return 0 on success, otherwise a negative error value.
 236  * @retval #SOUND_MANAGER_ERROR_NONE Success
 237  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 238  * @post  sound_manager_route_policy_changed_cb() will be invoked
 239  * @see sound_manager_unset_route_policy_changed_cb()
 240  * @see sound_manager_route_policy_changed_cb()
 241  */
 242 int sound_manager_set_route_policy_changed_cb(sound_manager_route_policy_changed_cb callback, void *user_data);
 243
 244 /**
 245  * @brief Unregisters the callback for sound route policy change
 246  * @see sound_manager_set_route_policy_changed_cb()
 247  */
 248 void sound_manager_unset_route_policy_changed_cb(void);
 249
 250
 251 /**
 252  * @brief Gets the A2DP activation information.
 253  * @remarks If @a connected is @c true,  @a bt_name must be released with free() by you. If @a connected is @c false, @a bt_name is set to NULL.
 254  * @param[out] connected The Bluetooth A2DP connection status (@c true = connected, @c false = disconnected)
 255  * @param[out] bt_name The Bluetooth A2DP connected device name
 256  * @return 0 on success, otherwise a negative error value.
 257  * @retval #SOUND_MANAGER_ERROR_NONE Success
 258  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 259  * @retval #SOUND_MANAGER_ERROR_INVALID_OPERATION Invalid operation
 260  */
 261 int sound_manager_get_a2dp_status(bool *connected, char **bt_name);
 262
 263
 264 /**
 265  * @brief Sets the application's sound session type
 266  * @param[in] type The session type to set
 267  * @return 0 on success, otherwise a negative error value.
 268  * @retval #SOUND_MANAGER_ERROR_NONE Success
 269  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 270  */
 271 int sound_manager_set_session_type(sound_session_type_e type);
 272
 273 /**
 274  * @brief Registers a callback function to be invoked when the sound session notification is occured.
 275  * @param[in]   callback        The session notify callback function
 276  * @param[in]   user_data       The user data to be passed to the callback function
 277  * @return 0 on success, otherwise a negative error value.
 278  * @retval #SOUND_MANAGER_ERROR_NONE Success
 279  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 280  * @post  sound_session_notify_cb() will be invoked
 281  * @see sound_manager_unset_session_notify_cb()
 282  * @see sound_session_notify_cb()
 283  */
 284 int sound_manager_set_session_notify_cb(sound_session_notify_cb callback, void *user_data);
 285
 286 /**
 287  * @brief Unregisters the callback function which is called when the session notification is occured
 288  * @see sound_manager_set_session_notify_cb()
 289  */
 290 void sound_manager_unset_session_notify_cb(void);
 291
 292
 293
 294 /**
 295  * @}
 296  */
 297
 298 #ifdef __cplusplus
 299 }
 300 #endif
 301
 302 #endif /* __TIZEN_MEDIA_SOUND_MANAGER_H__ */