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