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 #ifndef __TIZEN_MEDIA_SOUND_MANAGER_H__
  18 #define __TIZEN_MEDIA_SOUND_MANAGER_H__
  19
  20 #include <tizen.h>
  21
  22 #ifdef __cplusplus
  23 extern "C"
  24 {
  25 #endif
  26
  27 /**
  28  * @file sound_manager.h
  29  * @brief This file contains the Sound Manager API.
  30  */
  31
  32 /**
  33  * @addtogroup CAPI_MEDIA_SOUND_MANAGER_MODULE
  34  * @{
  35  */
  36
  37 /**
  38  * @brief Enumeration for sound manager's error codes.
  39  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  40  */
  41 typedef enum {
  42         SOUND_MANAGER_ERROR_NONE              = TIZEN_ERROR_NONE,                    /**< Successful */
  43         SOUND_MANAGER_ERROR_OUT_OF_MEMORY     = TIZEN_ERROR_OUT_OF_MEMORY,           /**< Out of memory */
  44         SOUND_MANAGER_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,       /**< Invalid parameter */
  45         SOUND_MANAGER_ERROR_INVALID_OPERATION = TIZEN_ERROR_INVALID_OPERATION,       /**< Invalid operation */
  46         SOUND_MANAGER_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED,       /**< Permission denied */
  47         SOUND_MANAGER_ERROR_NOT_SUPPORTED     = TIZEN_ERROR_NOT_SUPPORTED,           /**< Not supported */
  48         SOUND_MANAGER_ERROR_NO_DATA           = TIZEN_ERROR_NO_DATA,                 /**< No data */
  49         SOUND_MANAGER_ERROR_INTERNAL          = TIZEN_ERROR_SOUND_MANAGER | 01,      /**< Internal error inside the sound system */
  50         SOUND_MANAGER_ERROR_POLICY            = TIZEN_ERROR_SOUND_MANAGER | 02,      /**< Noncompliance with the sound system policy */
  51         SOUND_MANAGER_ERROR_NO_PLAYING_SOUND  = TIZEN_ERROR_SOUND_MANAGER | 03,      /**< No playing sound */
  52         SOUND_MANAGER_ERROR_INVALID_STATE     = TIZEN_ERROR_SOUND_MANAGER | 04,      /**< Invalid state (Since 3.0) */
  53 } sound_manager_error_e;
  54
  55 /**
  56  * @addtogroup CAPI_MEDIA_SOUND_MANAGER_VOLUME_MODULE
  57  * @{
  58  */
  59
  60 /**
  61  * @brief Enumeration for sound type.
  62  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  63  */
  64 typedef enum {
  65         SOUND_TYPE_SYSTEM,          /**< Sound type for system */
  66         SOUND_TYPE_NOTIFICATION,    /**< Sound type for notifications */
  67         SOUND_TYPE_ALARM,           /**< Sound type for alarm */
  68         SOUND_TYPE_RINGTONE,        /**< Sound type for ringtones (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif) */
  69         SOUND_TYPE_MEDIA,           /**< Sound type for media */
  70         SOUND_TYPE_CALL,            /**< Sound type for call (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif) */
  71         SOUND_TYPE_VOIP,            /**< Sound type for voip (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif) */
  72         SOUND_TYPE_VOICE,           /**< Sound type for voice */
  73 } sound_type_e;
  74
  75 /**
  76  * @}
  77  */
  78
  79 /**
  80  * @addtogroup CAPI_MEDIA_SOUND_MANAGER_STREAM_POLICY_MODULE
  81  * @{
  82  */
  83
  84 /**
  85  * @brief Sound stream information handle.
  86  * @since_tizen 3.0
  87  */
  88 typedef struct sound_stream_info_s* sound_stream_info_h;
  89
  90 /**
  91  * @brief Enumeration for sound stream type.
  92  * @since_tizen 3.0
  93  */
  94 typedef enum {
  95         SOUND_STREAM_TYPE_MEDIA,              /**< Sound stream type for media */
  96         SOUND_STREAM_TYPE_SYSTEM,             /**< Sound stream type for system */
  97         SOUND_STREAM_TYPE_ALARM,              /**< Sound stream type for alarm */
  98         SOUND_STREAM_TYPE_NOTIFICATION,       /**< Sound stream type for notification */
  99         SOUND_STREAM_TYPE_EMERGENCY,          /**< Sound stream type for emergency */
 100         SOUND_STREAM_TYPE_VOICE_INFORMATION,  /**< Sound stream type for voice information */
 101         SOUND_STREAM_TYPE_VOICE_RECOGNITION,  /**< Sound stream type for voice recognition */
 102         SOUND_STREAM_TYPE_RINGTONE_VOIP,      /**< Sound stream type for ringtone for VoIP */
 103         SOUND_STREAM_TYPE_VOIP,               /**< Sound stream type for VoIP */
 104         SOUND_STREAM_TYPE_MEDIA_EXTERNAL_ONLY,/**< Sound stream type for media only for external devices */
 105 } sound_stream_type_e;
 106
 107 /**
 108  * @brief Enumeration for change reason of sound stream focus state.
 109  * @since_tizen 3.0
 110  */
 111 typedef enum {
 112         SOUND_STREAM_FOCUS_CHANGED_BY_MEDIA,              /**< Changed by the stream type for media */
 113         SOUND_STREAM_FOCUS_CHANGED_BY_SYSTEM,             /**< Changed by the stream type for system */
 114         SOUND_STREAM_FOCUS_CHANGED_BY_ALARM,              /**< Changed by the stream type for alarm */
 115         SOUND_STREAM_FOCUS_CHANGED_BY_NOTIFICATION,       /**< Changed by the stream type for notification */
 116         SOUND_STREAM_FOCUS_CHANGED_BY_EMERGENCY,          /**< Changed by the stream type for emergency */
 117         SOUND_STREAM_FOCUS_CHANGED_BY_VOICE_INFORMATION,  /**< Changed by the stream type for voice information */
 118         SOUND_STREAM_FOCUS_CHANGED_BY_VOICE_RECOGNITION,  /**< Changed by the stream type for voice recognition */
 119         SOUND_STREAM_FOCUS_CHANGED_BY_RINGTONE,           /**< Changed by the stream type for ringtone */
 120         SOUND_STREAM_FOCUS_CHANGED_BY_VOIP,               /**< Changed by the stream type for VoIP */
 121         SOUND_STREAM_FOCUS_CHANGED_BY_CALL,               /**< Changed by the stream type for voice-call or video-call */
 122         SOUND_STREAM_FOCUS_CHANGED_BY_MEDIA_EXTERNAL_ONLY,/**< Changed by the stream type for media only for external devices */
 123 } sound_stream_focus_change_reason_e;
 124
 125 /**
 126  * @brief Enumeration for sound stream focus mask.
 127  * @since_tizen 3.0
 128  */
 129 typedef enum {
 130         SOUND_STREAM_FOCUS_FOR_PLAYBACK    = 0x0001,   /**< Mask for playback focus */
 131         SOUND_STREAM_FOCUS_FOR_RECORDING   = 0x0002,   /**< Mask for recording focus */
 132         SOUND_STREAM_FOCUS_FOR_BOTH        = 0x0003,   /**< Mask for both playback and recording focus */
 133 } sound_stream_focus_mask_e;
 134
 135 /**
 136  * @brief Enumeration for sound stream focus state.
 137  * @since_tizen 3.0
 138  */
 139 typedef enum {
 140         SOUND_STREAM_FOCUS_STATE_RELEASED,   /**< Focus state for release */
 141         SOUND_STREAM_FOCUS_STATE_ACQUIRED,   /**< Focus state for acquisition */
 142 } sound_stream_focus_state_e;
 143
 144 /**
 145  * @brief Enumeration for sound behavior.
 146  * @since_tizen 3.0
 147  * @remarks These values can be combined with bitwise 'or'.
 148  * @see sound_manager_get_current_playback_focus()
 149  * @see sound_manager_get_current_recording_focus()
 150  */
 151 typedef enum {
 152         SOUND_BEHAVIOR_NONE          = 0x0000,   /**< None (default) */
 153         SOUND_BEHAVIOR_NO_RESUME     = 0x0001,   /**< No resumption */
 154         SOUND_BEHAVIOR_FADING        = 0x0002,   /**< Fading effect */
 155 } sound_behavior_e;
 156
 157 /**
 158  * @}
 159  */
 160
 161 /**
 162  * @addtogroup CAPI_MEDIA_SOUND_MANAGER_SESSION_MODULE
 163  * @{
 164  */
 165
 166 /**
 167  * @deprecated Deprecated since 3.0. Use sound_manager_create_stream_information() and sound_stream_type_e instead.
 168  * @brief Enumeration for session type.
 169  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 170  */
 171 typedef enum {
 172         SOUND_SESSION_TYPE_MEDIA = 0,      /**< Media type */
 173         SOUND_SESSION_TYPE_ALARM,          /**< Alarm type */
 174         SOUND_SESSION_TYPE_NOTIFICATION,   /**< Notification type */
 175         SOUND_SESSION_TYPE_EMERGENCY,      /**< Emergency type */
 176         SOUND_SESSION_TYPE_VOIP,           /**< VoIP type */
 177 } sound_session_type_e;
 178
 179 /**
 180  * @deprecated Deprecated since 3.0. Use sound_manager_acquire_focus() or not instead.
 181  * @brief Enumeration for session option for starting.
 182  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 183  */
 184 typedef enum {
 185         SOUND_SESSION_OPTION_MIX_WITH_OTHERS_WHEN_START = 0, /**< This session will be mixed with others when starting (default) */
 186         SOUND_SESSION_OPTION_PAUSE_OTHERS_WHEN_START,        /**< This session will interrupt other sessions when starting */
 187 } sound_session_option_for_starting_e;
 188
 189 /**
 190  * @deprecated Deprecated since 3.0. In sound_stream_focus_state_changed_cb, you can choose to stop playing or not.
 191  * @brief Enumeration for session option during play.
 192  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 193  */
 194 typedef enum {
 195         SOUND_SESSION_OPTION_INTERRUPTIBLE_DURING_PLAY = 0,  /**< This session will be interrupted by other sessions during play (default) */
 196         SOUND_SESSION_OPTION_UNINTERRUPTIBLE_DURING_PLAY,    /**< This session will not be interrupted by other media sessions */
 197 } sound_session_option_for_during_play_e;
 198
 199 /**
 200  * @deprecated Deprecated since 3.0. In sound_stream_focus_state_changed_cb, you can choose to resume playing or not.
 201  * @brief Enumeration for session option for resumption.
 202  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 203  */
 204 typedef enum {
 205         SOUND_SESSION_OPTION_RESUMPTION_BY_SYSTEM = 0,             /**< This session will be resumed according to system policy (default) */
 206         SOUND_SESSION_OPTION_RESUMPTION_BY_SYSTEM_OR_MEDIA_PAUSED, /**< This session will be resumed according to system policy and when the media session which interrupted this session is paused */
 207 } sound_session_option_for_resumption_e;
 208
 209 /**
 210  * @deprecated Deprecated since 3.0. Use sound_manager_apply_stream_routing() instead.
 211  * @brief Enumeration for voip session mode.
 212  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 213  */
 214 typedef enum {
 215         SOUND_SESSION_VOIP_MODE_RINGTONE = 0,                /**< voip mode for ringtone */
 216         SOUND_SESSION_VOIP_MODE_VOICE_WITH_BUILTIN_RECEIVER, /**< voip mode for during call with built-in receiver */
 217         SOUND_SESSION_VOIP_MODE_VOICE_WITH_BUILTIN_SPEAKER,  /**< voip mode for during call with built-in speaker */
 218         SOUND_SESSION_VOIP_MODE_VOICE_WITH_AUDIO_JACK,       /**< voip mode for during call with audio jack */
 219         SOUND_SESSION_VOIP_MODE_VOICE_WITH_BLUETOOTH,        /**< voip mode for during call with bluetooth */
 220 } sound_session_voip_mode_e;
 221
 222 /**
 223  * @deprecated Deprecated since 3.0. Use sound_stream_focus_state_changed_cb instead.
 224  * @brief Enumeration for sound session interrupted type.
 225  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 226  */
 227 typedef enum {
 228         SOUND_SESSION_INTERRUPTED_COMPLETED = 0,        /**< Interrupt completed*/
 229         SOUND_SESSION_INTERRUPTED_BY_MEDIA,             /**< Interrupted by media application*/
 230         SOUND_SESSION_INTERRUPTED_BY_CALL,              /**< Interrupted by an incoming call*/
 231         SOUND_SESSION_INTERRUPTED_BY_EARJACK_UNPLUG,    /**< Interrupted by unplugging headphones*/
 232         SOUND_SESSION_INTERRUPTED_BY_RESOURCE_CONFLICT, /**< Interrupted by a resource conflict*/
 233         SOUND_SESSION_INTERRUPTED_BY_ALARM,             /**< Interrupted by an alarm*/
 234         SOUND_SESSION_INTERRUPTED_BY_EMERGENCY,         /**< Interrupted by an emergency*/
 235         SOUND_SESSION_INTERRUPTED_BY_NOTIFICATION,      /**< Interrupted by a notification*/
 236 } sound_session_interrupted_code_e;
 237
 238 /**
 239  * @}
 240  */
 241
 242 /**
 243  * @addtogroup CAPI_MEDIA_SOUND_MANAGER_DEVICE_MODULE
 244  * @{
 245  */
 246
 247 /**
 248  * @brief Sound device handle.
 249  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 250  */
 251 typedef void* sound_device_h;
 252
 253 /**
 254  * @brief Sound device list handle.
 255  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 256  */
 257 typedef void* sound_device_list_h;
 258
 259 /**
 260 * @brief Enumeration for sound device type.
 261 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 262 */
 263 typedef enum {
 264         SOUND_DEVICE_BUILTIN_SPEAKER,   /**< Built-in speaker */
 265         SOUND_DEVICE_BUILTIN_RECEIVER,  /**< Built-in receiver */
 266         SOUND_DEVICE_BUILTIN_MIC,       /**< Built-in mic */
 267         SOUND_DEVICE_AUDIO_JACK,        /**< Audio jack that can be connected to wired accessory such as headphone, headset, and so on */
 268         SOUND_DEVICE_BLUETOOTH,         /**< Bluetooth (Deprecated since 3.0) */
 269         SOUND_DEVICE_BLUETOOTH_MEDIA = SOUND_DEVICE_BLUETOOTH,  /**< Bluetooth device representing media (A2DP) profile (Since 3.0) */
 270         SOUND_DEVICE_HDMI,              /**< HDMI */
 271         SOUND_DEVICE_MIRRORING,         /**< MIRRORING (Deprecated since 3.0) */
 272         SOUND_DEVICE_FORWARDING = SOUND_DEVICE_MIRRORING,       /**< Device for forwarding (Since 3.0) */
 273         SOUND_DEVICE_USB_AUDIO,         /**< USB Audio */
 274         SOUND_DEVICE_BLUETOOTH_VOICE,   /**< Bluetooth device representing voice (SCO) profile (Since 3.0) */
 275 } sound_device_type_e;
 276
 277 /**
 278 * @brief Enumeration for sound device direction.
 279 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 280 */
 281 typedef enum {
 282         SOUND_DEVICE_IO_DIRECTION_IN,   /**< Input device */
 283         SOUND_DEVICE_IO_DIRECTION_OUT,  /**< Output device */
 284         SOUND_DEVICE_IO_DIRECTION_BOTH, /**< Input/output device (both directions are available) */
 285 } sound_device_io_direction_e;
 286
 287
 288 /**
 289 * @brief Enumeration for sound device state.
 290 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 291 */
 292 typedef enum {
 293         SOUND_DEVICE_STATE_DEACTIVATED, /**< Deactivated state */
 294         SOUND_DEVICE_STATE_ACTIVATED,   /**< Activated state */
 295 } sound_device_state_e;
 296
 297 /**
 298 * @brief Enumeration for sound device mask.
 299 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 300 */
 301 typedef enum {
 302         SOUND_DEVICE_IO_DIRECTION_IN_MASK      = 0x0001,  /**< Mask for input devices */
 303         SOUND_DEVICE_IO_DIRECTION_OUT_MASK     = 0x0002,  /**< Mask for output devices */
 304         SOUND_DEVICE_IO_DIRECTION_BOTH_MASK    = 0x0004,  /**< Mask for input/output devices (both directions are available) */
 305         SOUND_DEVICE_TYPE_INTERNAL_MASK        = 0x0010,  /**< Mask for built-in devices */
 306         SOUND_DEVICE_TYPE_EXTERNAL_MASK        = 0x0020,  /**< Mask for external devices */
 307         SOUND_DEVICE_STATE_DEACTIVATED_MASK    = 0x1000,  /**< Mask for deactivated devices */
 308         SOUND_DEVICE_STATE_ACTIVATED_MASK      = 0x2000,  /**< Mask for activated devices */
 309         SOUND_DEVICE_ALL_MASK                  = 0xFFFF,  /**< Mask for all devices */
 310 } sound_device_mask_e;
 311
 312 /**
 313 * @deprecated Deprecated since 3.0. Use sound_manager_add_device_state_changed_cb() instead.
 314 * @brief Enumeration for changed information of sound device.
 315 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 316 */
 317 typedef enum {
 318         SOUND_DEVICE_CHANGED_INFO_STATE,                 /**< State of the device was changed */
 319         SOUND_DEVICE_CHANGED_INFO_IO_DIRECTION,          /**< IO direction of the device was changed */
 320 } sound_device_changed_info_e;
 321
 322 /**
 323  * @}
 324  */
 325
 326 /**
 327  * @addtogroup CAPI_MEDIA_SOUND_MANAGER_VOLUME_MODULE
 328  * @{
 329  */
 330
 331 /**
 332  * @brief Called when the system volume has changed.
 333  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 334  * @param[in]   type    The sound type of the changed volume
 335  * @param[in]   volume  The new volume value
 336  * @param[in]   user_data       The user data passed from the callback registration function
 337  * @pre sound_manager_set_volume() will invoke this callback if you register it using sound_manager_set_volume_changed_cb().
 338  * @see sound_manager_set_volume_changed_cb()
 339  * @see sound_manager_unset_volume_changed_cb()
 340  */
 341 typedef void (*sound_manager_volume_changed_cb) (sound_type_e type, unsigned int volume, void *user_data);
 342
 343 /**
 344  * @}
 345  */
 346
 347 /**
 348  * @addtogroup CAPI_MEDIA_SOUND_MANAGER_STREAM_POLICY_MODULE
 349  * @{
 350  */
 351
 352 /**
 353  * @brief Called when the state of focus that belongs to the stream_info is changed.
 354  * @since_tizen 3.0
 355  *
 356  * @remarks     This function is issued in the internal thread of the sound manager.\n
 357  *      Therefore it is recommended not to call UI update function in this function.
 358  *
 359  * @param[in]   stream_info     The handle of stream information
 360  * @param[in]   focus_mask      The changed focus mask
 361  * @param[in]   focus_state     The changed focus state
 362  * @param[in]   reason          The reason for state change of the focus
 363  * @param[in]   sound_behavior  The requested sound behavior that should be followed, values of #sound_behavior_e combined with bitwise 'or'
 364  * @param[in]   extra_info      The extra information
 365  * @param[in]   user_data       The user data passed from the callback registration function
 366  * @pre You should register this callback using sound_manager_create_stream_information().
 367  * @see sound_manager_create_stream_information()
 368  * @see sound_manager_destroy_stream_information()
 369  * @see sound_manager_get_focus_state()
 370  */
 371 typedef void (*sound_stream_focus_state_changed_cb) (sound_stream_info_h stream_info,
 372                                                                                                         sound_stream_focus_mask_e focus_mask,
 373                                                                                                         sound_stream_focus_state_e focus_state,
 374                                                                                                         sound_stream_focus_change_reason_e reason,
 375                                                                                                         int sound_behavior,
 376                                                                                                         const char *extra_info,
 377                                                                                                         void *user_data);
 378
 379 /**
 380  * @brief Called when the focus state for each sound stream type is changed regardless of the process.
 381  * @since_tizen 3.0
 382  *
 383  * @remarks     This function is invoked by the internal thread of the sound manager.\n
 384  *      Therefore it is recommended not to call functions which update the UI from this callback.
 385  *
 386  * @param[in]   id              The focus state change watch cb id
 387  * @param[in]   focus_mask      The changed focus mask
 388  * @param[in]   focus_state     The changed focus state
 389  * @param[in]   reason          The reason for state change of the focus
 390  * @param[in]   extra_info      The extra information
 391  * @param[in]   user_data       The user data passed from the callback registration function
 392  * @pre You should register this callback using sound_manager_add_focus_state_watch_cb().
 393  * @see sound_manager_add_focus_state_watch_cb()
 394  * @see sound_manager_remove_focus_state_watch_cb()
 395  */
 396 typedef void (*sound_stream_focus_state_watch_cb) (int id, sound_stream_focus_mask_e focus_mask, sound_stream_focus_state_e focus_state, sound_stream_focus_change_reason_e reason, const char *extra_info, void *user_data);
 397
 398 /**
 399  * @}
 400  */
 401
 402 /**
 403  * @addtogroup CAPI_MEDIA_SOUND_MANAGER_SESSION_MODULE
 404  * @{
 405  */
 406
 407 /**
 408  * @deprecated Deprecated since 3.0. Use sound_stream_focus_state_changed_cb instead.
 409  * @brief Called when the playing sound session is interrupted.
 410  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 411  * @param[in]   code    The interrupted code
 412  * @param[in]   user_data       The user data passed from the callback registration function
 413  * @pre You should register this callback using sound_manager_set_session_interrupted_cb().
 414  * @see sound_manager_set_session_interrupted_cb()
 415  * @see sound_manager_unset_session_interrupted_cb()
 416  */
 417 typedef void (*sound_session_interrupted_cb) (sound_session_interrupted_code_e code, void *user_data);
 418
 419 /**
 420  * @}
 421  */
 422
 423 /**
 424  * @addtogroup CAPI_MEDIA_SOUND_MANAGER_DEVICE_MODULE
 425  * @{
 426  */
 427
 428 /**
 429  * @deprecated Deprecated since 3.0. Use sound_device_connection_changed_cb() instead.
 430  * @brief Called when the state of connection of a sound device was changed.
 431  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 432  * @param[in]   sound_device_h  The sound_device
 433  * @param[in]   is_connected    The state of device connection: (@c true = connected, @c false = disconnected)
 434  * @param[in]   user_data       The user data passed from the callback registration function
 435  * @pre You should register this callback using sound_manager_set_device_connected_cb().
 436  * @see sound_manager_set_device_connected_cb()
 437  * @see sound_manager_unset_device_connected_cb()
 438  */
 439 typedef void (*sound_device_connected_cb) (sound_device_h device, bool is_connected, void *user_data);
 440
 441 /**
 442  * @deprecated Deprecated since 3.0.
 443  * @brief Called when the information of a sound device was changed.
 444  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 445  * @param[in]   sound_device_h  The sound_device
 446  * @param[in]   changed_info    The entry of sound device information
 447  * @param[in]   user_data       The user data passed from the callback registration function
 448  * @pre You should register this callback using sound_manager_set_device_information_changed_cb().
 449  * @see sound_manager_set_device_information_changed_cb()
 450  * @see sound_manager_unset_device_information_changed_cb()
 451  */
 452 typedef void (*sound_device_information_changed_cb) (sound_device_h device, sound_device_changed_info_e changed_info, void *user_data);
 453
 454 /**
 455  * @brief Called when the connection state of a sound device was changed.
 456  * @since_tizen 3.0
 457  * @param[in]   device  The sound_device
 458  * @param[in]   is_connected    The state of device connection: @c true = connected, @c false = disconnected
 459  * @param[in]   user_data       The user data passed from the callback registration function
 460  * @pre You should add this callback using sound_manager_add_device_connection_changed_cb().
 461  * @see sound_manager_add_device_connection_changed_cb()
 462  * @see sound_manager_remove_device_connection_changed_cb()
 463  */
 464 typedef void (*sound_device_connection_changed_cb) (sound_device_h device, bool is_connected, void *user_data);
 465
 466 /**
 467  * @brief Called when the state of a sound device was changed.
 468  * @since_tizen 3.0
 469  * @param[in]   device  The sound_device
 470  * @param[in]   state   The state of the device
 471  * @param[in]   user_data       The user data passed from the callback registration function
 472  * @pre You should add this callback using sound_manager_add_device_state_changed_cb().
 473  * @see sound_manager_add_device_state_changed_cb()
 474  * @see sound_manager_remove_device_state_changed_cb()
 475  */
 476 typedef void (*sound_device_state_changed_cb) (sound_device_h device, sound_device_state_e state, void *user_data);
 477
 478 /**
 479  * @}
 480  */
 481
 482 /**
 483  * @addtogroup CAPI_MEDIA_SOUND_MANAGER_VOLUME_MODULE
 484  * @{
 485  */
 486
 487 /**
 488  * @brief Gets the maximum volume level supported for a particular sound type.
 489  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 490  * @param[in]           type The sound type
 491  * @param[out]  max     The maximum volume level
 492  * @return @c 0 on success,
 493  *         otherwise a negative error value
 494  * @retval #SOUND_MANAGER_ERROR_NONE Success
 495  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 496  * @see sound_manager_set_volume()
 497  * @see sound_manager_get_volume()
 498  */
 499 int sound_manager_get_max_volume(sound_type_e type, int *max);
 500
 501 /**
 502  * @brief Sets the volume level specified for a particular sound type.
 503  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 504  * @privlevel public
 505  * @privilege %http://tizen.org/privilege/volume.set
 506  * @param[in]           type The sound type
 507  * @param[in]           volume  The volume level to be set
 508  * @return @c 0 on success,
 509  *         otherwise a negative error value
 510  * @retval #SOUND_MANAGER_ERROR_NONE Success
 511  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 512  * @retval #SOUND_MANAGER_ERROR_PERMISSION_DENIED Permission denied
 513  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 514  * @see sound_manager_get_max_volume()
 515  * @see sound_manager_get_volume()
 516  */
 517 int sound_manager_set_volume(sound_type_e type, int volume);
 518
 519 /**
 520  * @brief Gets the volume level specified for a particular sound type.
 521  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 522  * @param[in]           type The sound type
 523  * @param[out]  volume  The current volume level
 524  * @return @c 0 on success,
 525  *         otherwise a negative error value
 526  * @retval #SOUND_MANAGER_ERROR_NONE Success
 527  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 528  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 529  * @see sound_manager_get_max_volume()
 530  * @see sound_manager_set_volume()
 531  */
 532 int sound_manager_get_volume(sound_type_e type, int *volume);
 533
 534 /**
 535  * @deprecated Deprecated since 3.0.
 536  * @brief Sets the type of the sound being currently played.
 537  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 538  * @param[in]           type The sound type to set
 539  * @return @c 0 on success,
 540  *         otherwise a negative error value
 541  * @retval #SOUND_MANAGER_ERROR_NONE Success
 542  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 543  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 544  * @see sound_manager_get_current_sound_type()
 545  * @see sound_manager_unset_current_sound_type()
 546  */
 547 int sound_manager_set_current_sound_type(sound_type_e type) TIZEN_DEPRECATED_API;
 548
 549 /**
 550  * @brief Gets the type of the sound being currently played.
 551  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 552  * @param[out]  type The current sound type
 553  * @return @c 0 on success,
 554  *         otherwise a negative error value
 555  * @retval #SOUND_MANAGER_ERROR_NONE Success
 556  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 557  * @retval #SOUND_MANAGER_ERROR_NO_PLAYING_SOUND No playing sound
 558  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 559  * @see sound_manager_set_current_sound_type()
 560  * @see sound_manager_unset_current_sound_type()
 561  */
 562 int sound_manager_get_current_sound_type(sound_type_e *type);
 563
 564 /**
 565  * @deprecated Deprecated since 3.0.
 566  * @brief Unsets the type of the sound being currently played.
 567  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 568  * @return @c 0 on success,
 569  *         otherwise a negative error value
 570  * @retval #SOUND_MANAGER_ERROR_NONE Success
 571  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 572  * @see sound_manager_set_current_sound_type()
 573  * @see sound_manager_get_current_sound_type()
 574  */
 575 int sound_manager_unset_current_sound_type(void) TIZEN_DEPRECATED_API;
 576
 577 /**
 578  * @deprecated Deprecated since 3.0. Use sound_manager_add_volume_changed_cb() instead.
 579  * @brief Registers a callback function to be invoked when the volume level is changed.
 580  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 581  * @param[in]   callback        Callback function to indicate change in volume
 582  * @param[in]   user_data       The user data to be passed to the callback function
 583  * @return @c 0 on success,
 584  *         otherwise a negative error value
 585  * @retval #SOUND_MANAGER_ERROR_NONE Success
 586  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 587  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 588  * @post sound_manager_volume_changed_cb() will be invoked.
 589  * @see sound_manager_unset_volume_changed_cb()
 590  * @see sound_manager_volume_changed_cb()
 591  */
 592 int sound_manager_set_volume_changed_cb(sound_manager_volume_changed_cb callback, void *user_data) TIZEN_DEPRECATED_API;
 593
 594 /**
 595  * @deprecated Deprecated since 3.0. Use sound_manager_remove_volume_changed_cb() instead.
 596  * @brief Unregisters the volume change callback.
 597  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 598  * @return 0 on success, otherwise a negative error value
 599  * @retval #SOUND_MANAGER_ERROR_NONE Success
 600  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 601  * @see sound_manager_set_volume_changed_cb()
 602  */
 603 int sound_manager_unset_volume_changed_cb(void) TIZEN_DEPRECATED_API;
 604
 605 /**
 606  * @brief Adds a callback function to be invoked when the volume level is changed.
 607  * @since_tizen 3.0
 608  * @param[in]   callback        Callback function to indicate change in volume
 609  * @param[in]   user_data       The user data to be passed to the callback function
 610  * @param[out]  id      The callback id
 611  * @return @c 0 on success,
 612  *         otherwise a negative error value
 613  * @retval #SOUND_MANAGER_ERROR_NONE Success
 614  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 615  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 616  * @post sound_manager_volume_changed_cb() will be invoked.
 617  * @see sound_manager_remove_volume_changed_cb()
 618  * @see sound_manager_volume_changed_cb()
 619  */
 620 int sound_manager_add_volume_changed_cb(sound_manager_volume_changed_cb callback, void *user_data, int *id);
 621
 622 /**
 623  * @brief Removes the volume change callback.
 624  * @since_tizen 3.0
 625  * @param[in]   id      The id of the callback to remove
 626  * @return 0 on success, otherwise a negative error value
 627  * @retval #SOUND_MANAGER_ERROR_NONE Success
 628  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 629  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 630  * @see sound_manager_add_volume_changed_cb()
 631  */
 632 int sound_manager_remove_volume_changed_cb(int id);
 633
 634 /**
 635  * @}
 636  */
 637
 638 /**
 639  * @addtogroup CAPI_MEDIA_SOUND_MANAGER_STREAM_POLICY_MODULE
 640  * @{
 641  */
 642
 643 /**
 644  * @brief Creates a handle for stream information.
 645  * @since_tizen 3.0
 646  *
 647  * @remarks     The registered callback is issued in the internal thread of the sound manager.\n
 648  *      Do not call this function within sound_stream_focus_state_changed_cb() or sound_stream_focus_state_watch_cb(),\n
 649  *      otherwise #SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned.\n
 650  *      To apply the stream policy according to this stream information, this handle should be passed to other APIs\n
 651  *      related to playback or recording.(e.g. player, wav-player, audio-io, etc.)
 652  *
 653  * @param[in]   stream_type     The type of stream
 654  * @param[in]   callback        The focus state change callback function (optional, this can be NULL)
 655  * @param[in]   user_data       The user data to be passed to the callback function (optional, this can be NULL)
 656  * @param[out]  stream_info     The handle of stream information
 657  * @return @c 0 on success,
 658  *         otherwise a negative error value
 659  * @retval #SOUND_MANAGER_ERROR_NONE Success
 660  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 661  * @retval #SOUND_MANAGER_ERROR_INVALID_OPERATION Invalid operation
 662  * @retval #SOUND_MANAGER_ERROR_NOT_SUPPORTED Not supported
 663  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 664  * @see sound_manager_destroy_stream_information()
 665  * @see sound_manager_add_device_for_stream_routing()
 666  * @see sound_manager_remove_device_for_stream_routing()
 667  * @see sound_manager_apply_stream_routing()
 668  * @see sound_manager_acquire_focus()
 669  * @see sound_manager_destroy_focus()
 670  * @see sound_manager_get_focus_state()
 671  */
 672 int sound_manager_create_stream_information(sound_stream_type_e stream_type, sound_stream_focus_state_changed_cb callback, void *user_data, sound_stream_info_h *stream_info);
 673
 674 /**
 675  * @brief Destroys the handle for stream information.
 676  * @since_tizen 3.0
 677  *
 678  * @remarks     Do not call this function within sound_stream_focus_state_changed_cb() or sound_stream_focus_state_watch_cb(),\n
 679  *      otherwise #SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned.
 680  *
 681  * @param[in]   stream_info     The handle of stream information
 682  * @return @c 0 on success,
 683  *         otherwise a negative error value
 684  * @retval #SOUND_MANAGER_ERROR_NONE Success
 685  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 686  * @retval #SOUND_MANAGER_ERROR_INVALID_OPERATION Invalid operation
 687  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 688  * @see sound_manager_create_stream_information()
 689  * @see sound_manager_add_device_for_stream_routing()
 690  * @see sound_manager_remove_device_for_stream_routing()
 691  * @see sound_manager_apply_stream_routing()
 692  * @see sound_manager_acquire_focus()
 693  * @see sound_manager_destroy_focus()
 694  * @see sound_manager_get_focus_state()
 695  */
 696 int sound_manager_destroy_stream_information(sound_stream_info_h stream_info);
 697
 698 /**
 699  * @brief Gets the sound type of the stream information.
 700  * @since_tizen 3.0
 701  *
 702  * @remarks     In case of a @a stream_info made with #SOUND_STREAM_TYPE_EMERGENCY, it'll return #SOUND_MANAGER_ERROR_NO_DATA.\n
 703  *      The reason is that there is no #sound_type_e matched with this @a stream_info.
 704  *
 705  * @param[in]   stream_info     The handle of stream information
 706  * @param[out]  sound_type      The sound type
 707  * @return @c 0 on success,
 708  *         otherwise a negative error value
 709  * @retval #SOUND_MANAGER_ERROR_NONE Success
 710  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 711  * @retval #SOUND_MANAGER_ERROR_NO_DATA No data
 712  * @pre Call sound_manager_create_stream_information() before calling this function.
 713  * @see sound_manager_create_stream_information()
 714  * @see sound_manager_set_volume()
 715  * @see sound_manager_get_max_volume()
 716  * @see sound_manager_get_volume()
 717  */
 718 int sound_manager_get_sound_type(sound_stream_info_h stream_info, sound_type_e *sound_type);
 719
 720 /**
 721  * @brief Adds the device to the stream information for the stream routing.
 722  * @since_tizen 3.0
 723  *
 724  * @remarks     Use sound_manager_get_device_list() and sound_manager_get_next_device() to get the device.\n
 725  *      #SOUND_MANAGER_ERROR_POLICY could be returned according to the stream type of the @a stream_info.\n
 726  *      The available types of the @a stream_info for this function are #SOUND_STREAM_TYPE_VOIP and #SOUND_STREAM_TYPE_MEDIA_EXTERNAL_ONLY.
 727  *
 728  * @param[in]   stream_info     The handle of stream information
 729  * @param[in]   device          The device item from sound_device_list_h
 730  * @return @c 0 on success,
 731  *         otherwise a negative error value
 732  * @retval #SOUND_MANAGER_ERROR_NONE Success
 733  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 734  * @retval #SOUND_MANAGER_ERROR_POLICY Noncompliance with the sound system policy
 735  * @pre Call sound_manager_create_stream_information() before calling this function.
 736  * @post You can apply this setting by calling sound_manager_apply_stream_routing().
 737  * @see sound_manager_create_stream_information()
 738  * @see sound_manager_destroy_stream_information()
 739  * @see sound_manager_remove_device_for_stream_routing()
 740  * @see sound_manager_apply_stream_routing()
 741  */
 742 int sound_manager_add_device_for_stream_routing(sound_stream_info_h stream_info, sound_device_h device);
 743
 744 /**
 745  * @brief Removes the device to the stream information for the stream routing.
 746  * @since_tizen 3.0
 747  *
 748  * @remarks     Use sound_manager_get_device_list() and sound_manager_get_next_device() to get the device.\n
 749  *
 750  * @param[in]   stream_info     The handle of stream information
 751  * @param[in]   device          The device item from sound_device_list_h
 752  * @return @c 0 on success,
 753  *         otherwise a negative error value
 754  * @retval #SOUND_MANAGER_ERROR_NONE Success
 755  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 756  * @pre Call sound_manager_create_stream_information() and sound_manager_add_device_for_stream_routing() before calling this function.
 757  * @post You can apply this setting by calling sound_manager_apply_stream_routing().
 758  * @see sound_manager_create_stream_information()
 759  * @see sound_manager_destroy_stream_information()
 760  * @see sound_manager_add_device_for_stream_routing()
 761  * @see sound_manager_apply_stream_routing()
 762  */
 763 int sound_manager_remove_device_for_stream_routing(sound_stream_info_h stream_info, sound_device_h device);
 764
 765 /**
 766  * @brief Applies the stream routing.
 767  * @since_tizen 3.0
 768  *
 769  * @remarks     If the stream has not been made yet, this setting will be applied when the stream starts to play.\n
 770  *
 771  * @param[in]   stream_info     The handle of stream information
 772  * @return @c 0 on success,
 773  *         otherwise a negative error value
 774  * @retval #SOUND_MANAGER_ERROR_NONE Success
 775  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 776  * @retval #SOUND_MANAGER_ERROR_INVALID_STATE Invalid state
 777  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 778  * @pre Call sound_manager_create_stream_information() and sound_manager_add_device_for_stream_routing() before calling this function.
 779  * @see sound_manager_create_stream_information()
 780  * @see sound_manager_destroy_stream_information()
 781  * @see sound_manager_add_device_for_stream_routing()
 782  * @see sound_manager_remove_device_for_stream_routing()
 783  */
 784 int sound_manager_apply_stream_routing(sound_stream_info_h stream_info);
 785
 786 /**
 787  * @brief Acquires the stream focus.
 788  * @since_tizen 3.0
 789  *
 790  * @remarks     Do not call this function within sound_stream_focus_state_changed_cb() or sound_stream_focus_state_watch_cb(),\n
 791  *      otherwise #SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned.
 792  *
 793  * @param[in]   stream_info     The handle of stream information
 794  * @param[in]   focus_mask      The focus mask that user wants to acquire
 795  * @param[in]   sound_behavior  The requesting sound behavior, values of #sound_behavior_e combined with bitwise 'or'
 796  * @param[in]   extra_info      The extra information for this request (optional, this can be NULL)
 797  * @return @c 0 on success,
 798  *         otherwise a negative error value
 799  * @retval #SOUND_MANAGER_ERROR_NONE Success
 800  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 801  * @retval #SOUND_MANAGER_ERROR_INVALID_OPERATION Invalid operation
 802  * @retval #SOUND_MANAGER_ERROR_INVALID_STATE Invalid state
 803  * @retval #SOUND_MANAGER_ERROR_POLICY Noncompliance with the sound system policy
 804  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 805  * @pre Call sound_manager_create_stream_information() with its parameter for sound_stream_focus_state_changed_cb before calling this function.
 806  * @see sound_manager_create_stream_information()
 807  * @see sound_manager_destroy_stream_information()
 808  * @see sound_manager_release_focus()
 809  * @see sound_manager_get_focus_state()
 810  */
 811 int sound_manager_acquire_focus(sound_stream_info_h stream_info, sound_stream_focus_mask_e focus_mask, int sound_behavior, const char *extra_info);
 812
 813 /**
 814  * @brief Releases the acquired focus.
 815  * @since_tizen 3.0
 816  *
 817  * @remarks     Do not call this function within sound_stream_focus_state_changed_cb() or sound_stream_focus_state_watch_cb(),\n
 818  *      otherwise #SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned.
 819  *
 820  * @param[in]   stream_info     The handle of stream information
 821  * @param[in]   focus_mask      The focus mask that user wants to release
 822  * @param[in]   sound_behavior  The requesting sound behavior, values of #sound_behavior_e combined with bitwise 'or'
 823  * @param[in]   extra_info      The extra information for this request (optional, this can be NULL)
 824  * @return @c 0 on success,
 825  *         otherwise a negative error value
 826  * @retval #SOUND_MANAGER_ERROR_NONE Success
 827  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 828  * @retval #SOUND_MANAGER_ERROR_INVALID_OPERATION Invalid operation
 829  * @retval #SOUND_MANAGER_ERROR_INVALID_STATE Invalid state
 830  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 831  * @pre Call sound_manager_create_stream_information() and sound_manager_acquire_focus() before calling this function.
 832  * @see sound_manager_create_stream_information()
 833  * @see sound_manager_destroy_stream_information()
 834  * @see sound_manager_acquire_focus()
 835  * @see sound_manager_get_focus_state()
 836  */
 837 int sound_manager_release_focus(sound_stream_info_h stream_info, sound_stream_focus_mask_e focus_mask, int sound_behavior, const char *extra_info);
 838
 839 /**
 840  * @brief Gets the state of focus.
 841  * @since_tizen 3.0
 842  * @param[in]   stream_info     The handle of stream information
 843  * @param[out]  state_for_playback      The state of playback focus
 844  * @param[out]  state_for_recording     The state of recording focus
 845  *
 846  * @return @c 0 on success,
 847  *         otherwise a negative error value
 848  * @retval #SOUND_MANAGER_ERROR_NONE Success
 849  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 850  * @pre Call sound_manager_create_stream_information() before calling this function.
 851  * @see sound_manager_create_stream_information()
 852  * @see sound_manager_destroy_stream_information()
 853  * @see sound_manager_acquire_focus()
 854  * @see sound_manager_release_focus()
 855  */
 856 int sound_manager_get_focus_state(sound_stream_info_h stream_info, sound_stream_focus_state_e *state_for_playback, sound_stream_focus_state_e *state_for_recording);
 857
 858 /**
 859  * @brief Sets auto focus reacquisition property.
 860  * @since_tizen 3.0
 861  *
 862  * @remarks     The focus reacquisition is set as default.
 863  *      If you don't want to reacquire the focus you've lost automatically, disable the focus reacquisition setting by using this function and vice versa.
 864  *
 865  * @param[in]   stream_info     The handle of stream information
 866  * @param[in]   enable  The auto focus reacquisition property to set : (@c true = enable, @c false = disable)
 867  * @return @c 0 on success,
 868  *         otherwise a negative error value
 869  * @retval #SOUND_MANAGER_ERROR_NONE Success
 870  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 871  * @pre Call sound_manager_create_stream_information() before calling this function.
 872  * @see sound_manager_create_stream_information()
 873  */
 874 int sound_manager_set_focus_reacquisition(sound_stream_info_h stream_info, bool enable);
 875
 876 /**
 877  * @brief Gets auto focus reacquisition property.
 878  * @since_tizen 3.0
 879  *
 880  * @remarks     The default value is true.
 881  *
 882  * @param[in]   stream_info     The handle of stream information
 883  * @param[out]  enabled The value of focus auto reacquisition property : (@c true = enabled, @c false = disabled)
 884  * @return @c 0 on success,
 885  *         otherwise a negative error value
 886  * @retval #SOUND_MANAGER_ERROR_NONE Success
 887  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 888  * @pre Call sound_manager_create_stream_information() before calling this function.
 889  * @see sound_manager_create_stream_information()
 890  */
 891 int sound_manager_get_focus_reacquisition(sound_stream_info_h stream_info, bool *enabled);
 892
 893 /**
 894  * @brief Checks if the stream information is using the device.
 895  * @since_tizen 3.0
 896  *
 897  * @param[in]   stream_info     The handle of stream information
 898  * @param[in]   device  The device item
 899  * @param[out]  is_on   Whether the stream info is using the device or not : (@c true = use, @c false = not use)
 900  * @return @c 0 on success,
 901  *         otherwise a negative error value
 902  * @retval #SOUND_MANAGER_ERROR_NONE Success
 903  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 904  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 905  * @see sound_manager_get_device_list()
 906  * @see sound_manager_get_next_device()
 907  * @see sound_manager_get_prev_device()
 908  * @see sound_manager_get_device_type()
 909  * @see sound_manager_get_device_io_direction()
 910  * @see sound_manager_get_device_id()
 911  * @see sound_manager_get_device_name()
 912  * @see sound_manager_free_device_list()
 913  */
 914 int sound_manager_is_stream_on_device(sound_stream_info_h stream_info, sound_device_h device, bool *is_on);
 915
 916 /**
 917  * @brief Gets the current device type for media playback stream.
 918  * @since_tizen 3.0
 919  *
 920  * @param[out]  device_type     The output device type that a media playback stream can go out
 921  * @return @c 0 on success,
 922  *         otherwise a negative error value
 923  * @retval #SOUND_MANAGER_ERROR_NONE Success
 924  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 925  * @retval #SOUND_MANAGER_ERROR_NO_DATA No data
 926  * @see sound_manager_get_device_type()
 927  * @see sound_manager_get_device_io_direction()
 928  * @see sound_manager_get_device_id()
 929  * @see sound_manager_get_device_name()
 930  */
 931 int sound_manager_get_current_media_playback_device_type(sound_device_type_e *device_type);
 932
 933 /**
 934  * @brief Gets the reason for the current acquired playback focus.
 935  * @since_tizen 3.0
 936  *
 937  * @remarks     If there is no acquired playback focus in this system, it'll return #SOUND_MANAGER_ERROR_NO_DATA.\n
 938  *      Do not call this function within sound_stream_focus_state_changed_cb() or sound_stream_focus_state_watch_cb(),\n
 939  *      otherwise #SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned.\n
 940  *      The @a extra_info should be released using free().
 941  *
 942  * @param[out]  acquired_by     The reason for the current acquired playback focus
 943  * @param[out]  sound_behavior  The requested sound behavior that should be followed, values of #sound_behavior_e combined with bitwise 'or'
 944  * @param[out]  extra_info The extra information of the acquired playback focus (optional, this can be NULL)
 945  * @return @c 0 on success,
 946  *         otherwise a negative error value
 947  * @retval #SOUND_MANAGER_ERROR_NONE Success
 948  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 949  * @retval #SOUND_MANAGER_ERROR_INVALID_OPERATION Invalid operation
 950  * @retval #SOUND_MANAGER_ERROR_NO_DATA No data
 951  * @see sound_manager_get_current_recording_focus()
 952  */
 953 int sound_manager_get_current_playback_focus(sound_stream_focus_change_reason_e *acquired_by, int *sound_behavior, char **extra_info);
 954
 955 /**
 956  * @brief Gets the reason for the current acquired recording focus.
 957  * @since_tizen 3.0
 958  *
 959  * @remarks     If there is no acquired recording focus in this system, it'll return #SOUND_MANAGER_ERROR_NO_DATA.\n
 960  *      Do not call this function within sound_stream_focus_state_changed_cb() or sound_stream_focus_state_watch_cb(),\n
 961  *      otherwise #SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned.\n
 962  *      The @a extra_info should be released using free().
 963  *
 964  * @param[out]  acquired_by     The reason for the current acquired recording focus
 965  * @param[out]  sound_behavior  The requested sound behavior that should be followed, values of #sound_behavior_e combined with bitwise 'or'
 966  * @param[out]  extra_info The extra information of the acquired recording focus (optional, this can be NULL)
 967  * @return @c 0 on success,
 968  *         otherwise a negative error value
 969  * @retval #SOUND_MANAGER_ERROR_NONE Success
 970  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 971  * @retval #SOUND_MANAGER_ERROR_INVALID_OPERATION Invalid operation
 972  * @retval #SOUND_MANAGER_ERROR_NO_DATA No data
 973  * @see sound_manager_get_current_playback_focus()
 974  */
 975 int sound_manager_get_current_recording_focus(sound_stream_focus_change_reason_e *acquired_by, int *sound_behavior, char **extra_info);
 976
 977 /**
 978  * @brief Registers the watch callback function to be invoked when the focus state for each sound stream type is changed regardless of the process.
 979  * @since_tizen 3.0
 980  *
 981  * @remarks     The registered callback is invoked by the internal thread of the sound manager.\n
 982  *      Do not call this function within sound_stream_focus_state_changed_cb() or sound_stream_focus_state_watch_cb(),\n
 983  *      otherwise #SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned.
 984  *
 985  * @param[in]   focus_mask      The focus mask that user wants to watch
 986  * @param[in]   callback        The focus state change watch callback function
 987  * @param[in]   user_data       The user data to be passed to the callback function
 988  * @param[out]  id              The focus state change watch callback id
 989  * @return @c 0 on success,
 990  *         otherwise a negative error value
 991  * @retval #SOUND_MANAGER_ERROR_NONE Success
 992  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 993  * @retval #SOUND_MANAGER_ERROR_INVALID_OPERATION Invalid operation
 994  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 995  * @see sound_manager_remove_focus_state_watch_cb()
 996  */
 997 int sound_manager_add_focus_state_watch_cb(sound_stream_focus_mask_e focus_mask, sound_stream_focus_state_watch_cb callback, void *user_data, int *id);
 998
 999 /**
1000  * @brief Unregisters the focus state change watch callback.
1001  * @since_tizen 3.0
1002  *
1003  * @remarks     Do not call this function within sound_stream_focus_state_changed_cb() or sound_stream_focus_state_watch_cb(),\n
1004  *      otherwise #SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned.
1005  *
1006  * @param[in]   id              The focus state change watch callback id
1007  * @return @c 0 on success,
1008  *         otherwise a negative error value
1009  * @retval #SOUND_MANAGER_ERROR_NONE Success
1010  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1011  * @retval #SOUND_MANAGER_ERROR_INVALID_OPERATION Invalid operation
1012  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
1013  * @see sound_manager_add_focus_state_watch_cb()
1014  */
1015 int sound_manager_remove_focus_state_watch_cb(int id);
1016
1017 /**
1018  * @}
1019  */
1020
1021 /**
1022  * @addtogroup CAPI_MEDIA_SOUND_MANAGER_SESSION_MODULE
1023  * @{
1024  */
1025
1026 /**
1027  * @deprecated Deprecated since 3.0. Use sound_manager_create_stream_information() instead.
1028  * @brief Sets the application's sound session type.
1029  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1030  * @param[in] type The session type to set
1031  * @return @c 0 on success,
1032  *         otherwise a negative error value
1033  * @retval #SOUND_MANAGER_ERROR_NONE Success
1034  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1035  * @retval #SOUND_MANAGER_ERROR_NOT_SUPPORTED Not supported
1036  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
1037  * @retval #SOUND_MANAGER_ERROR_POLICY Noncompliance with the sound system policy
1038  * @see sound_manager_get_session_type()
1039  * @see sound_manager_set_media_session_option()
1040  * @see sound_manager_get_media_session_option()
1041  * @see sound_manager_set_media_session_resumption_option()
1042  * @see sound_manager_get_media_session_resumption_option()
1043  * @see sound_manager_set_voip_session_mode()
1044  * @see sound_manager_get_voip_session_mode()
1045  */
1046 int sound_manager_set_session_type(sound_session_type_e type) TIZEN_DEPRECATED_API;
1047
1048 /**
1049  * @deprecated Deprecated since 3.0.
1050  * @brief Gets the application's sound session type.
1051  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1052  * @param[in] type The session type
1053  * @return @c 0 on success,
1054  *         otherwise a negative error value
1055  * @retval #SOUND_MANAGER_ERROR_NONE Success
1056  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1057  * @see sound_manager_set_session_type()
1058  * @see sound_manager_set_media_session_option()
1059  * @see sound_manager_get_media_session_option()
1060  * @see sound_manager_set_media_session_resumption_option()
1061  * @see sound_manager_get_media_session_resumption_option()
1062  * @see sound_manager_set_voip_session_mode()
1063  * @see sound_manager_get_voip_session_mode()
1064  */
1065 int sound_manager_get_session_type(sound_session_type_e *type) TIZEN_DEPRECATED_API;
1066
1067 /**
1068  * @deprecated Deprecated since 3.0. Use sound_manager_create_stream_information() instead.
1069  * @brief Sets the media sound session option.
1070  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1071  * @param[in] s_option The session option for starting
1072  * @param[in] d_option The session option for during play
1073  * @return @c 0 on success,
1074  *         otherwise a negative error value
1075  * @retval #SOUND_MANAGER_ERROR_NONE Success
1076  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1077  * @retval #SOUND_MANAGER_ERROR_INVALID_OPERATION Invalid operation
1078  * @retval #SOUND_MANAGER_ERROR_POLICY Noncompliance with the sound system policy
1079  * @see sound_manager_set_session_type()
1080  * @see sound_manager_get_session_type()
1081  * @see sound_manager_get_media_session_option()
1082  * @see sound_manager_set_media_session_resumption_option()
1083  * @see sound_manager_get_media_session_resumption_option()
1084  */
1085 int sound_manager_set_media_session_option(sound_session_option_for_starting_e s_option, sound_session_option_for_during_play_e d_option) TIZEN_DEPRECATED_API;
1086
1087 /**
1088  * @deprecated Deprecated since 3.0. Use sound_manager_create_stream_information() instead.
1089  * @brief Gets the media sound session option.
1090  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1091  * @param[out] s_option The session option for starting
1092  * @param[out] d_option The session option for during play
1093  * @return @c 0 on success,
1094  *         otherwise a negative error value
1095  * @retval #SOUND_MANAGER_ERROR_NONE Success
1096  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1097  * @retval #SOUND_MANAGER_ERROR_INVALID_OPERATION Invalid operation
1098  * @retval #SOUND_MANAGER_ERROR_POLICY Noncompliance with the sound system policy
1099  * @see sound_manager_set_session_type()
1100  * @see sound_manager_get_session_type()
1101  * @see sound_manager_set_media_session_option()
1102  * @see sound_manager_set_media_session_resumption_option()
1103  * @see sound_manager_get_media_session_resumption_option()
1104  */
1105 int sound_manager_get_media_session_option(sound_session_option_for_starting_e *s_option, sound_session_option_for_during_play_e *d_option) TIZEN_DEPRECATED_API;
1106
1107 /**
1108  * @deprecated Deprecated since 3.0. Use sound_manager_create_stream_information() instead.
1109  * @brief Sets the media sound session resumption option.
1110  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1111  * @param[in] option The session resumption option
1112  * @return @c 0 on success,
1113  *         otherwise a negative error value
1114  * @retval #SOUND_MANAGER_ERROR_NONE Success
1115  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1116  * @retval #SOUND_MANAGER_ERROR_INVALID_OPERATION Invalid operation
1117  * @retval #SOUND_MANAGER_ERROR_POLICY Noncompliance with the sound system policy
1118  * @see sound_manager_set_session_type()
1119  * @see sound_manager_get_session_type()
1120  * @see sound_manager_set_media_session_option()
1121  * @see sound_manager_get_media_session_option()
1122  * @see sound_manager_get_media_session_resumption_option()
1123  */
1124 int sound_manager_set_media_session_resumption_option(sound_session_option_for_resumption_e option) TIZEN_DEPRECATED_API;
1125
1126 /**
1127  * @deprecated Deprecated since 3.0. Use sound_manager_create_stream_information() instead.
1128  * @brief Gets the media sound session resumption option.
1129  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1130  * @param[out] option The session resumption option
1131  * @return @c 0 on success,
1132  *         otherwise a negative error value
1133  * @retval #SOUND_MANAGER_ERROR_NONE Success
1134  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1135  * @retval #SOUND_MANAGER_ERROR_INVALID_OPERATION Invalid operation
1136  * @retval #SOUND_MANAGER_ERROR_POLICY Noncompliance with the sound system policy
1137  * @see sound_manager_set_session_type()
1138  * @see sound_manager_get_session_type()
1139  * @see sound_manager_set_media_session_option()
1140  * @see sound_manager_get_media_session_option()
1141  * @see sound_manager_set_media_session_resumption_option()
1142  */
1143 int sound_manager_get_media_session_resumption_option(sound_session_option_for_resumption_e *option) TIZEN_DEPRECATED_API;
1144
1145 /**
1146  * @deprecated Deprecated since 3.0. Use sound_manager_create_stream_information() instead.
1147  * @brief Sets the mode of the voip sound session.
1148  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1149  * @param[in] mode The voip session mode
1150  * @return @c 0 on success,
1151  *         otherwise a negative error value
1152  * @retval #SOUND_MANAGER_ERROR_NONE Success
1153  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1154  * @retval #SOUND_MANAGER_ERROR_NOT_SUPPORTED Not supported
1155  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
1156  * @retval #SOUND_MANAGER_ERROR_POLICY Noncompliance with the sound system policy
1157  * @pre Call sound_manager_set_session_type(#SOUND_SESSION_TYPE_VOIP) before calling this function.
1158  * @see sound_manager_set_session_type()
1159  * @see sound_manager_get_session_type()
1160  * @see sound_manager_get_voip_session_mode()
1161 */
1162 int sound_manager_set_voip_session_mode(sound_session_voip_mode_e mode) TIZEN_DEPRECATED_API;
1163
1164 /**
1165  * @deprecated Deprecated since 3.0. Use sound_manager_create_stream_information() instead.
1166  * @brief Gets the mode of the voip sound session.
1167  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1168  * @param[out] mode The voip session mode
1169  * @return @c 0 on success,
1170  *         otherwise a negative error value
1171  * @retval #SOUND_MANAGER_ERROR_NONE Success
1172  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1173  * @retval #SOUND_MANAGER_ERROR_NOT_SUPPORTED Not supported
1174  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
1175  * @retval #SOUND_MANAGER_ERROR_POLICY Noncompliance with the sound system policy
1176  * @pre Call sound_manager_set_session_type(#SOUND_SESSION_TYPE_VOIP) before calling this function.
1177  * @see sound_manager_set_session_type()
1178  * @see sound_manager_get_session_type()
1179  * @see sound_manager_set_voip_session_mode()
1180 */
1181 int sound_manager_get_voip_session_mode(sound_session_voip_mode_e *mode) TIZEN_DEPRECATED_API;
1182
1183 /**
1184  * @deprecated Deprecated since 3.0. Use sound_manager_create_stream_information() instead.
1185  * @brief Registers a callback function to be invoked when the sound session being played was interrupted.
1186  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1187  * @param[in]   callback        The interrupted callback function
1188  * @param[in]   user_data       The user data to be passed to the callback function
1189  * @return @c 0 on success,
1190  *         otherwise a negative error value
1191  * @retval #SOUND_MANAGER_ERROR_NONE Success
1192  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1193  * @retval #SOUND_MANAGER_ERROR_POLICY Noncompliance with the sound system policy
1194  * @post  sound_session_interrupted_cb() will be invoked.
1195  * @see sound_manager_unset_session_interrupted_cb()
1196  * @see sound_session_interrupted_cb()
1197  */
1198 int sound_manager_set_session_interrupted_cb(sound_session_interrupted_cb callback, void *user_data) TIZEN_DEPRECATED_API;
1199
1200 /**
1201  * @deprecated Deprecated since 3.0.
1202  * @brief Unregisters the callback function which is called when the sound session being played is interrupted.
1203  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1204  * @return 0 on success,
1205  *         otherwise a negative error value
1206  * @retval #SOUND_MANAGER_ERROR_NONE Success
1207  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
1208  * @see sound_manager_set_session_interrupted_cb()
1209  */
1210 int sound_manager_unset_session_interrupted_cb(void) TIZEN_DEPRECATED_API;
1211
1212 /**
1213  * @}
1214  */
1215
1216 /**
1217  * @addtogroup CAPI_MEDIA_SOUND_MANAGER_DEVICE_MODULE
1218  * @{
1219  */
1220
1221 /**
1222  * @deprecated Deprecated since 3.0. Use sound_manager_get_device_list() instead.
1223  * @brief Gets the list consisting of connected devices.
1224  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1225  *
1226  * @remarks     @a Calling this API will deallocate previously obtained list and each item.\n
1227  *      Use sound_manager_get_next_device() to get the first node of the list.
1228  *
1229  * @param[in]   device_mask     The mask value
1230  * @param[out]  device_list     The list of connected devices
1231  * @return @c 0 on success,
1232  *         otherwise a negative error value
1233  * @retval #SOUND_MANAGER_ERROR_NONE Success
1234  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1235  * @retval #SOUND_MANAGER_ERROR_NO_DATA No data
1236  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
1237  * @see sound_manager_get_next_device()
1238  * @see sound_manager_get_prev_device()
1239  * @see sound_manager_get_device_type()
1240  * @see sound_manager_get_device_io_direction()
1241  * @see sound_manager_get_device_id()
1242  * @see sound_manager_get_device_name()
1243  * @see sound_manager_get_device_state()
1244  */
1245 int sound_manager_get_current_device_list(sound_device_mask_e device_mask, sound_device_list_h *device_list) TIZEN_DEPRECATED_API;
1246
1247 /**
1248  * @brief Gets the list consisting of connected devices.
1249  * @since_tizen 3.0
1250  *
1251  * @remarks     @a device_list should be freed using sound_manager_free_device_list().\n
1252  *      Use sound_manager_get_next_device() to get the first node of the list.
1253  *
1254  * @param[in]   device_mask     The mask values of #sound_device_mask_e combined with bitwise 'or'
1255  * @param[out]  device_list     The list of connected devices
1256  * @return @c 0 on success,
1257  *         otherwise a negative error value
1258  * @retval #SOUND_MANAGER_ERROR_NONE Success
1259  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1260  * @retval #SOUND_MANAGER_ERROR_NO_DATA No data
1261  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
1262  * @see sound_manager_get_next_device()
1263  * @see sound_manager_get_prev_device()
1264  * @see sound_manager_get_device_type()
1265  * @see sound_manager_get_device_io_direction()
1266  * @see sound_manager_get_device_id()
1267  * @see sound_manager_get_device_name()
1268  * @see sound_manager_get_device_state()
1269  * @see sound_manager_free_device_list()
1270  */
1271 int sound_manager_get_device_list(int device_mask, sound_device_list_h *device_list);
1272
1273 /**
1274  * @brief Frees device list and each item of list.
1275  * @since_tizen 3.0
1276  *
1277  * @remarks     This function will deallocate not only device list itself but also each item.
1278  *
1279  * @param[in]   device_list     The device list got with sound_manager_get_device_list.
1280  * @return @c 0 on success,
1281  *         otherwise a negative error value
1282  * @retval #SOUND_MANAGER_ERROR_NONE Success
1283  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1284  *
1285  *
1286  * @see sound_manager_get_device_list()
1287  * @see sound_manager_get_next_device()
1288  * @see sound_manager_get_prev_device()
1289  * @see sound_manager_get_device_type()
1290  * @see sound_manager_get_device_io_direction()
1291  * @see sound_manager_get_device_id()
1292  * @see sound_manager_get_device_name()
1293  * @see sound_manager_get_device_state()
1294  */
1295 int sound_manager_free_device_list(sound_device_list_h device_list);
1296
1297 /**
1298  * @brief Gets the next item of the device list.
1299  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1300  * @param[in]   device_list     The list of connected devices
1301  * @param[out]  device  The device item
1302  * @return @c 0 on success,
1303  *         otherwise a negative error value
1304  * @retval #SOUND_MANAGER_ERROR_NONE Success
1305  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1306  * @retval #SOUND_MANAGER_ERROR_NO_DATA No data
1307  * @see sound_manager_get_device_list()
1308  * @see sound_manager_get_prev_device()
1309  * @see sound_manager_get_device_type()
1310  * @see sound_manager_get_device_io_direction()
1311  * @see sound_manager_get_device_id()
1312  * @see sound_manager_get_device_name()
1313  * @see sound_manager_get_device_state()
1314  * @see sound_manager_free_device_list()
1315  */
1316 int sound_manager_get_next_device(sound_device_list_h device_list, sound_device_h *device);
1317
1318 /**
1319  * @brief Gets the previous item of the device list.
1320  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1321  * @param[in]   device_list     The list of connected devices
1322  * @param[out]  device  The device item
1323  * @return @c 0 on success,
1324  *         otherwise a negative error value
1325  * @retval #SOUND_MANAGER_ERROR_NONE Success
1326  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1327  * @retval #SOUND_MANAGER_ERROR_NO_DATA No data
1328  * @see sound_manager_get_device_list()
1329  * @see sound_manager_get_next_device()
1330  * @see sound_manager_get_device_type()
1331  * @see sound_manager_get_device_io_direction()
1332  * @see sound_manager_get_device_id()
1333  * @see sound_manager_get_device_name()
1334  * @see sound_manager_get_device_state()
1335  * @see sound_manager_free_device_list()
1336  */
1337 int sound_manager_get_prev_device(sound_device_list_h device_list, sound_device_h *device);
1338
1339 /**
1340  * @brief Gets the type of the device.
1341  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1342  * @param[in]   device  The device item
1343  * @param[out]  type    The type of the device
1344  * @return @c 0 on success,
1345  *         otherwise a negative error value
1346  * @retval #SOUND_MANAGER_ERROR_NONE Success
1347  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1348  * @see sound_manager_get_device_list()
1349  * @see sound_manager_get_next_device()
1350  * @see sound_manager_get_prev_device()
1351  * @see sound_manager_get_device_io_direction()
1352  * @see sound_manager_get_device_id()
1353  * @see sound_manager_get_device_name()
1354  * @see sound_manager_get_device_state()
1355  * @see sound_manager_free_device_list()
1356  */
1357 int sound_manager_get_device_type(sound_device_h device, sound_device_type_e *type);
1358
1359 /**
1360  * @brief Gets the io direction of the device.
1361  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1362  * @param[in]   device  The device item
1363  * @param[out]  io_direction    The io direction of the device
1364  * @return @c 0 on success,
1365  *         otherwise a negative error value
1366  * @retval #SOUND_MANAGER_ERROR_NONE Success
1367  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1368  * @see sound_manager_get_device_list()
1369  * @see sound_manager_get_next_device()
1370  * @see sound_manager_get_prev_device()
1371  * @see sound_manager_get_device_type()
1372  * @see sound_manager_get_device_id()
1373  * @see sound_manager_get_device_name()
1374  * @see sound_manager_get_device_state()
1375  * @see sound_manager_free_device_list()
1376  */
1377 int sound_manager_get_device_io_direction(sound_device_h device, sound_device_io_direction_e *io_direction);
1378
1379 /**
1380  * @brief Gets the id of the device.
1381  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1382  * @param[in]   device  The device item
1383  * @param[out]  id      The id of the device
1384  * @return @c 0 on success,
1385  *         otherwise a negative error value
1386  * @retval #SOUND_MANAGER_ERROR_NONE Success
1387  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1388  * @see sound_manager_get_device_list()
1389  * @see sound_manager_get_next_device()
1390  * @see sound_manager_get_prev_device()
1391  * @see sound_manager_get_device_type()
1392  * @see sound_manager_get_device_io_direction()
1393  * @see sound_manager_get_device_name()
1394  * @see sound_manager_get_device_state()
1395  * @see sound_manager_free_device_list()
1396  */
1397 int sound_manager_get_device_id(sound_device_h device, int *id);
1398
1399 /**
1400  * @brief Gets the name of the device.
1401  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1402  * @param[in]   device  The device item
1403  * @param[out]  name    The name of the device
1404  * @return @c 0 on success,
1405  *         otherwise a negative error value
1406  * @retval #SOUND_MANAGER_ERROR_NONE Success
1407  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1408  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
1409  * @see sound_manager_get_device_list()
1410  * @see sound_manager_get_next_device()
1411  * @see sound_manager_get_prev_device()
1412  * @see sound_manager_get_device_type()
1413  * @see sound_manager_get_device_io_direction()
1414  * @see sound_manager_get_device_id()
1415  * @see sound_manager_get_device_state()
1416  * @see sound_manager_free_device_list()
1417  */
1418 int sound_manager_get_device_name(sound_device_h device, char **name);
1419
1420 /**
1421  * @brief Gets the state of the device.
1422  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1423  * @param[in]   device  The device item
1424  * @param[out]  state   The state of the device
1425  * @return @c 0 on success,
1426  *         otherwise a negative error value
1427  * @retval #SOUND_MANAGER_ERROR_NONE Success
1428  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1429  * @see sound_manager_get_device_list()
1430  * @see sound_manager_get_next_device()
1431  * @see sound_manager_get_prev_device()
1432  * @see sound_manager_get_device_type()
1433  * @see sound_manager_get_device_io_direction()
1434  * @see sound_manager_get_device_id()
1435  * @see sound_manager_get_device_name()
1436  * @see sound_manager_free_device_list()
1437  */
1438 int sound_manager_get_device_state(sound_device_h device, sound_device_state_e *state);
1439
1440 /**
1441  * @brief Registers a callback function to be invoked when the state of connection of a sound device was changed.
1442  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1443  *
1444  * @remarks     The initial state of sound devices connected is deactivated.
1445  *
1446  * @param[in]   device_mask     The mask value
1447  * @param[in]   callback        The interrupted callback function
1448  * @param[in]   user_data       The user data to be passed to the callback function
1449  * @return @c 0 on success,
1450  *         otherwise a negative error value
1451  * @retval #SOUND_MANAGER_ERROR_NONE Success
1452  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1453  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
1454  * @post  sound_device_connected_cb() will be invoked.
1455  * @see sound_manager_unset_device_connected_cb()
1456  * @see sound_device_connected_cb()
1457  */
1458 int sound_manager_set_device_connected_cb(sound_device_mask_e device_mask, sound_device_connected_cb callback, void *user_data) TIZEN_DEPRECATED_API;
1459
1460 /**
1461  * @deprecated Deprecated since 3.0. Use sound_manager_remove_device_connection_changed_cb() instead.
1462  * @brief Unregisters the callback function which is called when the state of connection of a sound device was changed.
1463  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1464  * @return @c 0 on success,
1465  *         otherwise a negative error value
1466  * @retval #SOUND_MANAGER_ERROR_NONE Success
1467  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
1468  * @see sound_manager_set_device_connected_cb()
1469  */
1470 int sound_manager_unset_device_connected_cb(void) TIZEN_DEPRECATED_API;
1471
1472 /**
1473  * @brief Adds a callback function to be invoked when the connection state of a sound device was changed.
1474  * @since_tizen 3.0
1475  *
1476  * @param[in]   device_mask     Device masks for which changes should be tracked, values of #sound_device_mask_e combined with bitwise 'or'
1477  * @param[in]   callback        The device connection state changed callback function
1478  * @param[in]   user_data       The user data to be passed to the callback function
1479  * @param[out]  id      The callback id
1480  * @return @c 0 on success,
1481  *         otherwise a negative error value
1482  * @retval #SOUND_MANAGER_ERROR_NONE Success
1483  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1484  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
1485  * @post  sound_device_connected_cb() will be invoked.
1486  * @see sound_manager_remove_device_connection_changed_cb()
1487  * @see sound_device_connection_changed_cb()
1488  */
1489 int sound_manager_add_device_connection_changed_cb(int device_mask, sound_device_connection_changed_cb callback, void *user_data, int *id);
1490
1491 /**
1492  * @brief Removes a callback function invoked when the connection of a sound device was changed.
1493  * @since_tizen 3.0
1494  *
1495  * @param[in]   id      The id of the callback to remove
1496  * @return @c 0 on success,
1497  *         otherwise a negative error value
1498  * @retval #SOUND_MANAGER_ERROR_NONE Success
1499  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1500  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
1501  * @see sound_manager_add_device_connection_changed_cb()
1502  */
1503 int sound_manager_remove_device_connection_changed_cb(int id);
1504
1505 /**
1506  * @deprecated Deprecated since 3.0. Use sound_manager_add_device_state_changed_cb() instead.
1507  * @brief Registers a callback function to be invoked when the information of a sound device was changed.
1508  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1509  * @param[in]   device_mask     The mask value
1510  * @param[in]   callback        The interrupted callback function
1511  * @param[in]   user_data       The user data to be passed to the callback function
1512  * @return @c 0 on success,
1513  *         otherwise a negative error value
1514  * @retval #SOUND_MANAGER_ERROR_NONE Success
1515  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1516  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
1517  * @post  sound_device_information_changed_cb() will be invoked.
1518  * @see sound_manager_unset_device_information_changed_cb()
1519  * @see sound_device_information_changed_cb()
1520  */
1521 int sound_manager_set_device_information_changed_cb(sound_device_mask_e device_mask, sound_device_information_changed_cb callback, void *user_data) TIZEN_DEPRECATED_API;
1522
1523 /**
1524  * @deprecated Deprecated since 3.0. Use sound_manager_remove_device_state_changed_cb() instead.
1525  * @brief Unregisters the callback function which is called when the information of a sound device was changed.
1526  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1527  * @return @c 0 on success,
1528  *         otherwise a negative error value
1529  * @retval #SOUND_MANAGER_ERROR_NONE Success
1530  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
1531  * @see sound_manager_set_device_information_changed_cb()
1532  */
1533 int sound_manager_unset_device_information_changed_cb(void) TIZEN_DEPRECATED_API;
1534
1535 /**
1536  * @brief Adds a callback function to be invoked when the state of a sound device was changed.
1537  * @since_tizen 3.0
1538  *
1539  * @param[in]   device_mask     Device masks for which changes should be tracked, values of #sound_device_mask_e combined with bitwise 'or'
1540  * @param[in]   callback        The device state changed callback function
1541  * @param[in]   user_data       The user data to be passed to the callback function
1542  * @param[out]  id      The callback id
1543  * @return @c 0 on success,
1544  *         otherwise a negative error value
1545  * @retval #SOUND_MANAGER_ERROR_NONE Success
1546  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1547  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
1548  * @post  sound_device_state_changed_cb() will be invoked.
1549  * @see sound_manager_remove_device_state_changed_cb()
1550  * @see sound_device_state_connected_cb()
1551  */
1552 int sound_manager_add_device_state_changed_cb(int device_mask, sound_device_state_changed_cb callback, void *user_data, int *id);
1553
1554 /**
1555  * @brief Removes a callback function invoked when the state of a sound device was changed.
1556  * @since_tizen 3.0
1557  *
1558  * @param[in]   id      The id of the callback to remove
1559  * @return @c 0 on success,
1560  *         otherwise a negative error value
1561  * @retval #SOUND_MANAGER_ERROR_NONE Success
1562  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1563  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
1564  * @see sound_manager_add_device_state_changed_cb()
1565  */
1566 int sound_manager_remove_device_state_changed_cb(int id);
1567
1568 /**
1569  * @}
1570  */
1571
1572 /**
1573  * @}
1574  */
1575
1576 #ifdef __cplusplus
1577 }
1578 #endif
1579
1580 #endif /* __TIZEN_MEDIA_SOUND_MANAGER_H__ */