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_DEVICE_MODULE
 163  * @{
 164  */
 165
 166 /**
 167  * @brief Sound device handle.
 168  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 169  */
 170 typedef void* sound_device_h;
 171
 172 /**
 173  * @brief Sound device list handle.
 174  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 175  */
 176 typedef void* sound_device_list_h;
 177
 178 /**
 179 * @brief Enumeration for sound device type.
 180 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 181 */
 182 typedef enum {
 183         SOUND_DEVICE_BUILTIN_SPEAKER,   /**< Built-in speaker */
 184         SOUND_DEVICE_BUILTIN_RECEIVER,  /**< Built-in receiver */
 185         SOUND_DEVICE_BUILTIN_MIC,       /**< Built-in mic */
 186         SOUND_DEVICE_AUDIO_JACK,        /**< Audio jack that can be connected to wired accessory such as headphone, headset, and so on */
 187         SOUND_DEVICE_BLUETOOTH_MEDIA,   /**< Bluetooth device representing media (A2DP) profile (Since 3.0) */
 188         SOUND_DEVICE_HDMI,              /**< HDMI */
 189         SOUND_DEVICE_FORWARDING,        /**< Device for forwarding (Since 3.0) */
 190         SOUND_DEVICE_USB_AUDIO,         /**< USB Audio */
 191         SOUND_DEVICE_BLUETOOTH_VOICE,   /**< Bluetooth device representing voice (SCO) profile (Since 3.0) */
 192 } sound_device_type_e;
 193
 194 /**
 195 * @brief Enumeration for sound device direction.
 196 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 197 */
 198 typedef enum {
 199         SOUND_DEVICE_IO_DIRECTION_IN,   /**< Input device */
 200         SOUND_DEVICE_IO_DIRECTION_OUT,  /**< Output device */
 201         SOUND_DEVICE_IO_DIRECTION_BOTH, /**< Input/output device (both directions are available) */
 202 } sound_device_io_direction_e;
 203
 204
 205 /**
 206 * @deprecated Deprecated since 4.0.
 207 * @brief Enumeration for sound device state.
 208 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 209 */
 210 typedef enum {
 211         SOUND_DEVICE_STATE_DEACTIVATED, /**< Deactivated state */
 212         SOUND_DEVICE_STATE_ACTIVATED,   /**< Activated state */
 213 } sound_device_state_e;
 214
 215 /**
 216 * @brief Enumeration for sound device mask.
 217 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 218 */
 219 typedef enum {
 220         SOUND_DEVICE_IO_DIRECTION_IN_MASK      = 0x0001,  /**< Mask for input devices */
 221         SOUND_DEVICE_IO_DIRECTION_OUT_MASK     = 0x0002,  /**< Mask for output devices */
 222         SOUND_DEVICE_IO_DIRECTION_BOTH_MASK    = 0x0004,  /**< Mask for input/output devices (both directions are available) */
 223         SOUND_DEVICE_TYPE_INTERNAL_MASK        = 0x0010,  /**< Mask for built-in devices */
 224         SOUND_DEVICE_TYPE_EXTERNAL_MASK        = 0x0020,  /**< Mask for external devices */
 225         SOUND_DEVICE_STATE_DEACTIVATED_MASK    = 0x1000,  /**< Mask for deactivated devices (Deprecated since 4.0) */
 226         SOUND_DEVICE_STATE_ACTIVATED_MASK      = 0x2000,  /**< Mask for activated devices (Deprecated since 4.0) */
 227         SOUND_DEVICE_ALL_MASK                  = 0xFFFF,  /**< Mask for all devices */
 228 } sound_device_mask_e;
 229
 230 /**
 231  * @}
 232  */
 233
 234 /**
 235  * @addtogroup CAPI_MEDIA_SOUND_MANAGER_VOLUME_MODULE
 236  * @{
 237  */
 238
 239 /**
 240  * @brief Called when the system volume has changed.
 241  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 242  * @param[in]   type    The sound type of the changed volume
 243  * @param[in]   volume  The new volume value
 244  * @param[in]   user_data       The user data passed from the callback registration function
 245  * @pre sound_manager_set_volume() will invoke this callback if you register it using sound_manager_set_volume_changed_cb().
 246  * @see sound_manager_set_volume_changed_cb()
 247  * @see sound_manager_unset_volume_changed_cb()
 248  */
 249 typedef void (*sound_manager_volume_changed_cb) (sound_type_e type, unsigned int volume, void *user_data);
 250
 251 /**
 252  * @}
 253  */
 254
 255 /**
 256  * @addtogroup CAPI_MEDIA_SOUND_MANAGER_STREAM_POLICY_MODULE
 257  * @{
 258  */
 259
 260 /**
 261  * @brief Called when the state of focus that belongs to the stream_info is changed.
 262  * @since_tizen 3.0
 263  *
 264  * @remarks     This function is issued in the internal thread of the sound manager.\n
 265  *      Therefore it is recommended not to call UI update function in this function.
 266  *
 267  * @param[in]   stream_info     The handle of stream information
 268  * @param[in]   focus_mask      The changed focus mask
 269  * @param[in]   focus_state     The changed focus state
 270  * @param[in]   reason          The reason for state change of the focus
 271  * @param[in]   sound_behavior  The requested sound behavior that should be followed, values of #sound_behavior_e combined with bitwise 'or'
 272  * @param[in]   extra_info      The extra information
 273  * @param[in]   user_data       The user data passed from the callback registration function
 274  * @pre You should register this callback using sound_manager_create_stream_information().
 275  * @see sound_manager_create_stream_information()
 276  * @see sound_manager_destroy_stream_information()
 277  * @see sound_manager_get_focus_state()
 278  */
 279 typedef void (*sound_stream_focus_state_changed_cb) (sound_stream_info_h stream_info,
 280                                                                                                         sound_stream_focus_mask_e focus_mask,
 281                                                                                                         sound_stream_focus_state_e focus_state,
 282                                                                                                         sound_stream_focus_change_reason_e reason,
 283                                                                                                         int sound_behavior,
 284                                                                                                         const char *extra_info,
 285                                                                                                         void *user_data);
 286
 287 /**
 288  * @brief Called when the focus state for each sound stream type is changed regardless of the process.
 289  * @since_tizen 3.0
 290  *
 291  * @remarks     This function is invoked by the internal thread of the sound manager.\n
 292  *      Therefore it is recommended not to call functions which update the UI from this callback.
 293  *
 294  * @param[in]   id              The focus state change watch cb id
 295  * @param[in]   focus_mask      The changed focus mask
 296  * @param[in]   focus_state     The changed focus state
 297  * @param[in]   reason          The reason for state change of the focus
 298  * @param[in]   extra_info      The extra information
 299  * @param[in]   user_data       The user data passed from the callback registration function
 300  * @pre You should register this callback using sound_manager_add_focus_state_watch_cb().
 301  * @see sound_manager_add_focus_state_watch_cb()
 302  * @see sound_manager_remove_focus_state_watch_cb()
 303  */
 304 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);
 305
 306 /**
 307  * @}
 308  */
 309
 310 /**
 311  * @addtogroup CAPI_MEDIA_SOUND_MANAGER_DEVICE_MODULE
 312  * @{
 313  */
 314
 315 /**
 316  * @brief Called when the connection state of a sound device was changed.
 317  * @since_tizen 3.0
 318  *
 319  * @remarks @a device is freed by the platform after this callback exits.
 320  *
 321  * @param[in]   device  The sound_device
 322  * @param[in]   is_connected    The state of device connection : (@c true = connected, @c false = disconnected)
 323  * @param[in]   user_data       The user data passed from the callback registration function
 324  * @pre You should add this callback using sound_manager_add_device_connection_changed_cb().
 325  * @see sound_manager_add_device_connection_changed_cb()
 326  * @see sound_manager_remove_device_connection_changed_cb()
 327  */
 328 typedef void (*sound_device_connection_changed_cb) (sound_device_h device, bool is_connected, void *user_data);
 329
 330 /**
 331  * @brief Called when the state of a sound device was changed.
 332  * @since_tizen 5.0
 333  *
 334  * @remarks @a device is freed by the platform after this callback exits.
 335  *
 336  * @param[in]   device  The sound_device
 337  * @param[in]   is_running      The state of the device : (@c true = running, @c false = not runnning)
 338  * @param[in]   user_data       The user data passed from the callback registration function
 339  * @pre You should add this callback using sound_manager_add_device_running_changed_cb().
 340  * @see sound_manager_add_device_running_changed_cb()
 341  * @see sound_manager_remove_device_running_changed_cb()
 342  */
 343 typedef void (*sound_device_running_changed_cb) (sound_device_h device, bool is_running, void *user_data);
 344
 345 /**
 346  * @deprecated Deprecated since 4.0. Use sound_device_running_changed_cb() instead.
 347  * @brief Called when the state of a sound device was changed.
 348  * @since_tizen 3.0
 349  *
 350  * @remarks @a device is freed by the platform after this callback exits.
 351  *
 352  * @param[in]   device  The sound_device
 353  * @param[in]   state   The state of the device
 354  * @param[in]   user_data       The user data passed from the callback registration function
 355  * @pre You should add this callback using sound_manager_add_device_state_changed_cb().
 356  * @see sound_manager_add_device_state_changed_cb()
 357  * @see sound_manager_remove_device_state_changed_cb()
 358  */
 359 typedef void (*sound_device_state_changed_cb) (sound_device_h device, sound_device_state_e state, void *user_data);
 360
 361 /**
 362  * @}
 363  */
 364
 365 /**
 366  * @addtogroup CAPI_MEDIA_SOUND_MANAGER_VOLUME_MODULE
 367  * @{
 368  */
 369
 370 /**
 371  * @brief Gets the maximum volume level supported for a particular sound type.
 372  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 373  * @param[in]           type The sound type
 374  * @param[out]  max     The maximum volume level
 375  * @return @c 0 on success,
 376  *         otherwise a negative error value
 377  * @retval #SOUND_MANAGER_ERROR_NONE Success
 378  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 379  * @see sound_manager_set_volume()
 380  * @see sound_manager_get_volume()
 381  */
 382 int sound_manager_get_max_volume(sound_type_e type, int *max);
 383
 384 /**
 385  * @brief Sets the volume level specified for a particular sound type.
 386  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 387  * @privlevel public
 388  * @privilege %http://tizen.org/privilege/volume.set
 389  * @param[in]           type The sound type
 390  * @param[in]           volume  The volume level to be set
 391  * @return @c 0 on success,
 392  *         otherwise a negative error value
 393  * @retval #SOUND_MANAGER_ERROR_NONE Success
 394  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 395  * @retval #SOUND_MANAGER_ERROR_PERMISSION_DENIED Permission denied
 396  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 397  * @see sound_manager_get_max_volume()
 398  * @see sound_manager_get_volume()
 399  */
 400 int sound_manager_set_volume(sound_type_e type, int volume);
 401
 402 /**
 403  * @brief Gets the volume level specified for a particular sound type.
 404  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 405  * @param[in]           type The sound type
 406  * @param[out]  volume  The current volume level
 407  * @return @c 0 on success,
 408  *         otherwise a negative error value
 409  * @retval #SOUND_MANAGER_ERROR_NONE Success
 410  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 411  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 412  * @see sound_manager_get_max_volume()
 413  * @see sound_manager_set_volume()
 414  */
 415 int sound_manager_get_volume(sound_type_e type, int *volume);
 416
 417 /**
 418  * @brief Gets the type of the sound being currently played.
 419  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 420  * @param[out]  type The current sound type
 421  * @return @c 0 on success,
 422  *         otherwise a negative error value
 423  * @retval #SOUND_MANAGER_ERROR_NONE Success
 424  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 425  * @retval #SOUND_MANAGER_ERROR_NO_PLAYING_SOUND No playing sound
 426  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 427  */
 428 int sound_manager_get_current_sound_type(sound_type_e *type);
 429
 430 /**
 431  * @brief Adds a callback function to be invoked when the volume level is changed.
 432  * @since_tizen 3.0
 433  * @param[in]   callback        Callback function to indicate change in volume
 434  * @param[in]   user_data       The user data to be passed to the callback function
 435  * @param[out]  id      The callback id
 436  * @return @c 0 on success,
 437  *         otherwise a negative error value
 438  * @retval #SOUND_MANAGER_ERROR_NONE Success
 439  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 440  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 441  * @post sound_manager_volume_changed_cb() will be invoked.
 442  * @see sound_manager_remove_volume_changed_cb()
 443  * @see sound_manager_volume_changed_cb()
 444  */
 445 int sound_manager_add_volume_changed_cb(sound_manager_volume_changed_cb callback, void *user_data, int *id);
 446
 447 /**
 448  * @brief Removes the volume change callback.
 449  * @since_tizen 3.0
 450  * @param[in]   id      The id of the callback to remove
 451  * @return 0 on success, otherwise a negative error value
 452  * @retval #SOUND_MANAGER_ERROR_NONE Success
 453  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 454  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 455  * @see sound_manager_add_volume_changed_cb()
 456  */
 457 int sound_manager_remove_volume_changed_cb(int id);
 458
 459 /**
 460  * @}
 461  */
 462
 463 /**
 464  * @addtogroup CAPI_MEDIA_SOUND_MANAGER_STREAM_POLICY_MODULE
 465  * @{
 466  */
 467
 468 /**
 469  * @brief Creates a handle for stream information.
 470  * @since_tizen 3.0
 471  *
 472  * @remarks     The registered callback is issued in the internal thread of the sound manager.\n
 473  *      Do not call this function within sound_stream_focus_state_changed_cb() or sound_stream_focus_state_watch_cb(),\n
 474  *      otherwise #SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned.\n
 475  *      To apply the stream policy according to this stream information, this handle should be passed to other APIs\n
 476  *      related to playback or recording.(e.g. player, wav-player, audio-io, etc.)
 477  *
 478  * @param[in]   stream_type     The type of stream
 479  * @param[in]   callback        The focus state change callback function (optional, this can be NULL)
 480  * @param[in]   user_data       The user data to be passed to the callback function (optional, this can be NULL)
 481  * @param[out]  stream_info     The handle of stream information
 482  * @return @c 0 on success,
 483  *         otherwise a negative error value
 484  * @retval #SOUND_MANAGER_ERROR_NONE Success
 485  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 486  * @retval #SOUND_MANAGER_ERROR_INVALID_OPERATION Invalid operation
 487  * @retval #SOUND_MANAGER_ERROR_NOT_SUPPORTED Not supported
 488  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 489  * @see sound_manager_destroy_stream_information()
 490  * @see sound_manager_add_device_for_stream_routing()
 491  * @see sound_manager_remove_device_for_stream_routing()
 492  * @see sound_manager_remove_all_devices_for_stream_routing()
 493  * @see sound_manager_apply_stream_routing()
 494  * @see sound_manager_acquire_focus()
 495  * @see sound_manager_destroy_focus()
 496  * @see sound_manager_get_focus_state()
 497  */
 498 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);
 499
 500 /**
 501  * @brief Destroys the handle for stream information.
 502  * @since_tizen 3.0
 503  *
 504  * @remarks     Do not call this function within sound_stream_focus_state_changed_cb() or sound_stream_focus_state_watch_cb(),\n
 505  *      otherwise #SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned.
 506  *
 507  * @param[in]   stream_info     The handle of stream information
 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_INVALID_OPERATION Invalid operation
 513  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 514  * @see sound_manager_create_stream_information()
 515  * @see sound_manager_add_device_for_stream_routing()
 516  * @see sound_manager_remove_device_for_stream_routing()
 517  * @see sound_manager_remove_all_devices_for_stream_routing()
 518  * @see sound_manager_apply_stream_routing()
 519  * @see sound_manager_acquire_focus()
 520  * @see sound_manager_destroy_focus()
 521  * @see sound_manager_get_focus_state()
 522  */
 523 int sound_manager_destroy_stream_information(sound_stream_info_h stream_info);
 524
 525 /**
 526  * @brief Gets the sound type of the stream information.
 527  * @since_tizen 3.0
 528  *
 529  * @remarks     In case of a @a stream_info made with #SOUND_STREAM_TYPE_EMERGENCY, it'll return #SOUND_MANAGER_ERROR_NO_DATA.\n
 530  *      The reason is that there is no #sound_type_e matched with this @a stream_info.
 531  *
 532  * @param[in]   stream_info     The handle of stream information
 533  * @param[out]  sound_type      The sound type
 534  * @return @c 0 on success,
 535  *         otherwise a negative error value
 536  * @retval #SOUND_MANAGER_ERROR_NONE Success
 537  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 538  * @retval #SOUND_MANAGER_ERROR_NO_DATA No data
 539  * @pre Call sound_manager_create_stream_information() before calling this function.
 540  * @see sound_manager_create_stream_information()
 541  * @see sound_manager_set_volume()
 542  * @see sound_manager_get_max_volume()
 543  * @see sound_manager_get_volume()
 544  */
 545 int sound_manager_get_sound_type(sound_stream_info_h stream_info, sound_type_e *sound_type);
 546
 547 /**
 548  * @brief Adds the device to the stream information for the stream routing.
 549  * @since_tizen 3.0
 550  *
 551  * @remarks     Use sound_manager_get_device_list() and sound_manager_get_next_device() to get the device.\n
 552  *      #SOUND_MANAGER_ERROR_POLICY could be returned according to the stream type of the @a stream_info.\n
 553  *      The available types of the @a stream_info for this function are #SOUND_STREAM_TYPE_VOIP and #SOUND_STREAM_TYPE_MEDIA_EXTERNAL_ONLY.
 554  *
 555  * @param[in]   stream_info     The handle of stream information
 556  * @param[in]   device          The device item from sound_device_list_h
 557  * @return @c 0 on success,
 558  *         otherwise a negative error value
 559  * @retval #SOUND_MANAGER_ERROR_NONE Success
 560  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 561  * @retval #SOUND_MANAGER_ERROR_POLICY Noncompliance with the sound system policy
 562  * @pre Call sound_manager_create_stream_information() before calling this function.
 563  * @post You can apply this setting by calling sound_manager_apply_stream_routing().
 564  * @see sound_manager_create_stream_information()
 565  * @see sound_manager_destroy_stream_information()
 566  * @see sound_manager_remove_device_for_stream_routing()
 567  * @see sound_manager_remove_all_devices_for_stream_routing()
 568  * @see sound_manager_apply_stream_routing()
 569  */
 570 int sound_manager_add_device_for_stream_routing(sound_stream_info_h stream_info, sound_device_h device);
 571
 572 /**
 573  * @brief Removes the device from the stream information for the stream routing.
 574  * @since_tizen 3.0
 575  *
 576  * @remarks     Use sound_manager_get_device_list() and sound_manager_get_next_device() to get the device.\n
 577  *
 578  * @param[in]   stream_info     The handle of stream information
 579  * @param[in]   device          The device item from sound_device_list_h
 580  * @return @c 0 on success,
 581  *         otherwise a negative error value
 582  * @retval #SOUND_MANAGER_ERROR_NONE Success
 583  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 584  * @pre Call sound_manager_create_stream_information() and sound_manager_add_device_for_stream_routing() before calling this function.
 585  * @post You can apply this setting by calling sound_manager_apply_stream_routing().
 586  * @see sound_manager_create_stream_information()
 587  * @see sound_manager_destroy_stream_information()
 588  * @see sound_manager_add_device_for_stream_routing()
 589  * @see sound_manager_remove_all_devices_for_stream_routing()
 590  * @see sound_manager_apply_stream_routing()
 591  */
 592 int sound_manager_remove_device_for_stream_routing(sound_stream_info_h stream_info, sound_device_h device);
 593
 594 /**
 595  * @brief Removes all devices from the stream information for the stream routing.
 596  * @since_tizen 4.0
 597  *
 598  * @param[in]   stream_info     The handle of stream information
 599  * @return @c 0 on success,
 600  *         otherwise a negative error value
 601  * @retval #SOUND_MANAGER_ERROR_NONE Success
 602  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 603  * @retval #SOUND_MANAGER_ERROR_POLICY Noncompliance with the sound system policy
 604  * @pre Call sound_manager_create_stream_information() before calling this function.
 605  * @see sound_manager_create_stream_information()
 606  * @see sound_manager_destroy_stream_information()
 607  * @see sound_manager_add_device_for_stream_routing()
 608  * @see sound_manager_remove_device_for_stream_routing()
 609  * @see sound_manager_apply_stream_routing()
 610  */
 611 int sound_manager_remove_all_devices_for_stream_routing(sound_stream_info_h stream_info);
 612
 613 /**
 614  * @brief Applies the stream routing.
 615  * @since_tizen 3.0
 616  *
 617  * @remarks     If the stream has not been made yet, this setting will be applied when the stream starts to play.\n
 618  *
 619  * @param[in]   stream_info     The handle of stream information
 620  * @return @c 0 on success,
 621  *         otherwise a negative error value
 622  * @retval #SOUND_MANAGER_ERROR_NONE Success
 623  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 624  * @retval #SOUND_MANAGER_ERROR_INVALID_STATE Invalid state
 625  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 626  * @pre Call sound_manager_create_stream_information() and sound_manager_add_device_for_stream_routing() before calling this function.
 627  * @see sound_manager_create_stream_information()
 628  * @see sound_manager_destroy_stream_information()
 629  * @see sound_manager_add_device_for_stream_routing()
 630  * @see sound_manager_remove_device_for_stream_routing()
 631  * @see sound_manager_remove_all_devices_for_stream_routing()
 632  */
 633 int sound_manager_apply_stream_routing(sound_stream_info_h stream_info);
 634
 635 /**
 636  * @brief Acquires the stream focus.
 637  * @since_tizen 3.0
 638  *
 639  * @remarks     Do not call this function within sound_stream_focus_state_changed_cb() or sound_stream_focus_state_watch_cb(),\n
 640  *      otherwise #SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned. Since 4.0, it is allowed and does not return the error.
 641  *
 642  * @param[in]   stream_info     The handle of stream information
 643  * @param[in]   focus_mask      The focus mask that user wants to acquire
 644  * @param[in]   sound_behavior  The requesting sound behavior, values of #sound_behavior_e combined with bitwise 'or'
 645  * @param[in]   extra_info      The extra information for this request (optional, this can be NULL)
 646  * @return @c 0 on success,
 647  *         otherwise a negative error value
 648  * @retval #SOUND_MANAGER_ERROR_NONE Success
 649  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 650  * @retval #SOUND_MANAGER_ERROR_INVALID_OPERATION Invalid operation
 651  * @retval #SOUND_MANAGER_ERROR_INVALID_STATE Invalid state
 652  * @retval #SOUND_MANAGER_ERROR_POLICY Noncompliance with the sound system policy
 653  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 654  * @pre Call sound_manager_create_stream_information() with its parameter for sound_stream_focus_state_changed_cb\n
 655  *      before calling this function.
 656  * @see sound_manager_create_stream_information()
 657  * @see sound_manager_destroy_stream_information()
 658  * @see sound_manager_acquire_focus_all()
 659  * @see sound_manager_release_focus()
 660  * @see sound_manager_release_focus_all()
 661  * @see sound_manager_get_focus_state()
 662  */
 663 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);
 664
 665 /**
 666  * @brief Releases the acquired stream focus.
 667  * @since_tizen 3.0
 668  *
 669  * @remarks     Do not call this function within sound_stream_focus_state_changed_cb() or sound_stream_focus_state_watch_cb(),\n
 670  *      otherwise #SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned. Since 4.0, it is allowed and does not return the error.
 671  *
 672  * @param[in]   stream_info     The handle of stream information
 673  * @param[in]   focus_mask      The focus mask that user wants to release
 674  * @param[in]   sound_behavior  The requesting sound behavior, values of #sound_behavior_e combined with bitwise 'or'
 675  * @param[in]   extra_info      The extra information for this request (optional, this can be NULL)
 676  * @return @c 0 on success,
 677  *         otherwise a negative error value
 678  * @retval #SOUND_MANAGER_ERROR_NONE Success
 679  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 680  * @retval #SOUND_MANAGER_ERROR_INVALID_OPERATION Invalid operation
 681  * @retval #SOUND_MANAGER_ERROR_INVALID_STATE Invalid state
 682  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 683  * @pre Call sound_manager_create_stream_information() and sound_manager_acquire_focus() before calling this function.
 684  * @see sound_manager_create_stream_information()
 685  * @see sound_manager_destroy_stream_information()
 686  * @see sound_manager_acquire_focus()
 687  * @see sound_manager_acquire_focus_all()
 688  * @see sound_manager_release_focus_all()
 689  * @see sound_manager_get_focus_state()
 690  */
 691 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);
 692
 693 /**
 694  * @brief Acquires all the stream focuses.
 695  * @since_tizen 4.0
 696  *
 697  * @remarks     This function does not return error even though one or all of focuses have already been acquired.\n
 698  *      Use sound_manager_get_focus_state() to get acquired focus state if it returns #SOUND_MANAGER_ERROR_POLICY.
 699  *
 700  * @param[in]   stream_info     The handle of stream information
 701  * @param[in]   sound_behavior  The requesting sound behavior, values of #sound_behavior_e combined with bitwise 'or'
 702  * @param[in]   extra_info      The extra information for this request (optional, this can be NULL)
 703  * @return @c 0 on success,
 704  *         otherwise a negative error value
 705  * @retval #SOUND_MANAGER_ERROR_NONE Success
 706  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 707  * @retval #SOUND_MANAGER_ERROR_POLICY Noncompliance with the sound system policy
 708  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 709  * @pre Call sound_manager_create_stream_information() with its parameter for sound_stream_focus_state_changed_cb\n
 710  *      before calling this function.
 711  * @see sound_manager_create_stream_information()
 712  * @see sound_manager_destroy_stream_information()
 713  * @see sound_manager_acquire_focus()
 714  * @see sound_manager_release_focus()
 715  * @see sound_manager_release_focus_all()
 716  * @see sound_manager_get_focus_state()
 717  */
 718 int sound_manager_acquire_focus_all(sound_stream_info_h stream_info, int sound_behavior, const char *extra_info);
 719
 720 /**
 721  * @brief Releases all the acquired stream focuses.
 722  * @since_tizen 4.0
 723  *
 724  * @remarks     This function does not return error even though one or all of focuses have already been released.
 725  *
 726  * @param[in]   stream_info     The handle of stream information
 727  * @param[in]   sound_behavior  The requesting sound behavior, values of #sound_behavior_e combined with bitwise 'or'
 728  * @param[in]   extra_info      The extra information for this request (optional, this can be NULL)
 729  * @return @c 0 on success,
 730  *         otherwise a negative error value
 731  * @retval #SOUND_MANAGER_ERROR_NONE Success
 732  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 733  * @retval #SOUND_MANAGER_ERROR_POLICY Noncompliance with the sound system policy
 734  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 735  * @pre Call sound_manager_create_stream_information(), sound_manager_acquire_focus() and sound_manager_acquire_focus_all()\n
 736  *      before calling this function.
 737  * @see sound_manager_create_stream_information()
 738  * @see sound_manager_destroy_stream_information()
 739  * @see sound_manager_acquire_focus()
 740  * @see sound_manager_acquire_focus_all()
 741  * @see sound_manager_release_focus()
 742  * @see sound_manager_get_focus_state()
 743  */
 744 int sound_manager_release_focus_all(sound_stream_info_h stream_info, int sound_behavior, const char *extra_info);
 745
 746 /**
 747  * @brief Gets the state of focus.
 748  * @since_tizen 3.0
 749  * @param[in]   stream_info     The handle of stream information
 750  * @param[out]  state_for_playback      The state of playback focus
 751  * @param[out]  state_for_recording     The state of recording focus
 752  *
 753  * @return @c 0 on success,
 754  *         otherwise a negative error value
 755  * @retval #SOUND_MANAGER_ERROR_NONE Success
 756  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 757  * @pre Call sound_manager_create_stream_information() before calling this function.
 758  * @see sound_manager_create_stream_information()
 759  * @see sound_manager_destroy_stream_information()
 760  * @see sound_manager_acquire_focus()
 761  * @see sound_manager_release_focus()
 762  */
 763 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);
 764
 765 /**
 766  * @brief Sets auto focus reacquisition property.
 767  * @since_tizen 3.0
 768  *
 769  * @remarks     The focus reacquisition is set as default.
 770  *      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.
 771  *
 772  * @param[in]   stream_info     The handle of stream information
 773  * @param[in]   enable  The auto focus reacquisition property to set : (@c true = enable, @c false = disable)
 774  * @return @c 0 on success,
 775  *         otherwise a negative error value
 776  * @retval #SOUND_MANAGER_ERROR_NONE Success
 777  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 778  * @pre Call sound_manager_create_stream_information() before calling this function.
 779  * @see sound_manager_create_stream_information()
 780  */
 781 int sound_manager_set_focus_reacquisition(sound_stream_info_h stream_info, bool enable);
 782
 783 /**
 784  * @brief Gets auto focus reacquisition property.
 785  * @since_tizen 3.0
 786  *
 787  * @remarks     The default value is true.
 788  *
 789  * @param[in]   stream_info     The handle of stream information
 790  * @param[out]  enabled The value of focus auto reacquisition property : (@c true = enabled, @c false = disabled)
 791  * @return @c 0 on success,
 792  *         otherwise a negative error value
 793  * @retval #SOUND_MANAGER_ERROR_NONE Success
 794  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 795  * @pre Call sound_manager_create_stream_information() before calling this function.
 796  * @see sound_manager_create_stream_information()
 797  */
 798 int sound_manager_get_focus_reacquisition(sound_stream_info_h stream_info, bool *enabled);
 799
 800 /**
 801  * @brief Delivers focuses to another stream information.
 802  * @since_tizen 4.0
 803  *
 804  * @remarks     This function does not affect any invocation of sound_stream_focus_state_changed_cb() or\n
 805  *      sound_stream_focus_state_watch_cb(). Do not call this function within sound_stream_focus_state_changed_cb() or\n
 806  *      sound_stream_focus_state_watch_cb(), otherwise #SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned.
 807  *
 808  * @param[in]   source  The source handle of stream information which has focuses
 809  * @param[in]   destination     The destination handle of stream information which will receive focuses
 810  * @param[in]   focus_mask      The focus mask to deliver
 811  * @return @c 0 on success,
 812  *         otherwise a negative error value
 813  * @retval #SOUND_MANAGER_ERROR_NONE Success
 814  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 815  * @retval #SOUND_MANAGER_ERROR_INVALID_OPERATION Invalid operation
 816  * @retval #SOUND_MANAGER_ERROR_INVALID_STATE Invalid state
 817  * @retval #SOUND_MANAGER_ERROR_POLICY Noncompliance with the sound system policy
 818  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 819  * @pre Call sound_manager_create_stream_information(), sound_manager_acquire_focus() and sound_manager_acquire_focus_all()\n
 820  *      before calling this function.
 821  * @see sound_manager_create_stream_information()
 822  * @see sound_manager_acquire_focus()
 823  * @see sound_manager_acquire_focus_all()
 824  */
 825 int sound_manager_deliver_focus(sound_stream_info_h source, sound_stream_info_h destination, sound_stream_focus_mask_e focus_mask);
 826
 827 /**
 828  * @brief Checks if the stream information is using the device.
 829  * @since_tizen 3.0
 830  *
 831  * @param[in]   stream_info     The handle of stream information
 832  * @param[in]   device  The device item
 833  * @param[out]  is_on   Whether the stream info is using the device or not : (@c true = use, @c false = not use)
 834  * @return @c 0 on success,
 835  *         otherwise a negative error value
 836  * @retval #SOUND_MANAGER_ERROR_NONE Success
 837  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 838  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 839  * @see sound_manager_get_device_list()
 840  * @see sound_manager_get_next_device()
 841  * @see sound_manager_get_prev_device()
 842  * @see sound_manager_get_device_type()
 843  * @see sound_manager_get_device_io_direction()
 844  * @see sound_manager_get_device_id()
 845  * @see sound_manager_get_device_name()
 846  * @see sound_manager_free_device_list()
 847  */
 848 int sound_manager_is_stream_on_device(sound_stream_info_h stream_info, sound_device_h device, bool *is_on);
 849
 850 /**
 851  * @brief Gets the current device type for media playback stream.
 852  * @since_tizen 3.0
 853  *
 854  * @param[out]  device_type     The output device type that a media playback stream can go out
 855  * @return @c 0 on success,
 856  *         otherwise a negative error value
 857  * @retval #SOUND_MANAGER_ERROR_NONE Success
 858  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 859  * @retval #SOUND_MANAGER_ERROR_NO_DATA No data
 860  * @see sound_manager_get_device_type()
 861  * @see sound_manager_get_device_io_direction()
 862  * @see sound_manager_get_device_id()
 863  * @see sound_manager_get_device_name()
 864  */
 865 int sound_manager_get_current_media_playback_device_type(sound_device_type_e *device_type);
 866
 867 /**
 868  * @brief Gets the reason for the current acquired playback focus.
 869  * @since_tizen 3.0
 870  *
 871  * @remarks     If there is no acquired playback focus in this system, it'll return #SOUND_MANAGER_ERROR_NO_DATA.\n
 872  *      Do not call this function within sound_stream_focus_state_changed_cb() or sound_stream_focus_state_watch_cb(),\n
 873  *      otherwise #SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned.\n
 874  *      The @a extra_info should be released using free().
 875  *
 876  * @param[out]  acquired_by     The reason for the current acquired playback focus
 877  * @param[out]  sound_behavior  The requested sound behavior that should be followed, values of #sound_behavior_e combined with bitwise 'or'
 878  * @param[out]  extra_info The extra information of the acquired playback focus (optional, this can be NULL)
 879  * @return @c 0 on success,
 880  *         otherwise a negative error value
 881  * @retval #SOUND_MANAGER_ERROR_NONE Success
 882  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 883  * @retval #SOUND_MANAGER_ERROR_INVALID_OPERATION Invalid operation
 884  * @retval #SOUND_MANAGER_ERROR_NO_DATA No data
 885  * @see sound_manager_get_current_recording_focus()
 886  */
 887 int sound_manager_get_current_playback_focus(sound_stream_focus_change_reason_e *acquired_by, int *sound_behavior, char **extra_info);
 888
 889 /**
 890  * @brief Gets the reason for the current acquired recording focus.
 891  * @since_tizen 3.0
 892  *
 893  * @remarks     If there is no acquired recording focus in this system, it'll return #SOUND_MANAGER_ERROR_NO_DATA.\n
 894  *      Do not call this function within sound_stream_focus_state_changed_cb() or sound_stream_focus_state_watch_cb(),\n
 895  *      otherwise #SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned.\n
 896  *      The @a extra_info should be released using free().
 897  *
 898  * @param[out]  acquired_by     The reason for the current acquired recording focus
 899  * @param[out]  sound_behavior  The requested sound behavior that should be followed, values of #sound_behavior_e combined with bitwise 'or'
 900  * @param[out]  extra_info The extra information of the acquired recording focus (optional, this can be NULL)
 901  * @return @c 0 on success,
 902  *         otherwise a negative error value
 903  * @retval #SOUND_MANAGER_ERROR_NONE Success
 904  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 905  * @retval #SOUND_MANAGER_ERROR_INVALID_OPERATION Invalid operation
 906  * @retval #SOUND_MANAGER_ERROR_NO_DATA No data
 907  * @see sound_manager_get_current_playback_focus()
 908  */
 909 int sound_manager_get_current_recording_focus(sound_stream_focus_change_reason_e *acquired_by, int *sound_behavior, char **extra_info);
 910
 911 /**
 912  * @brief Registers the watch callback function to be invoked when the focus state for each sound stream type is changed regardless of the process.
 913  * @since_tizen 3.0
 914  *
 915  * @remarks     The registered callback is invoked by the internal thread of the sound manager.\n
 916  *      Do not call this function within sound_stream_focus_state_changed_cb() or sound_stream_focus_state_watch_cb(),\n
 917  *      otherwise #SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned.
 918  *
 919  * @param[in]   focus_mask      The focus mask that user wants to watch
 920  * @param[in]   callback        The focus state change watch callback function
 921  * @param[in]   user_data       The user data to be passed to the callback function
 922  * @param[out]  id              The focus state change watch callback id
 923  * @return @c 0 on success,
 924  *         otherwise a negative error value
 925  * @retval #SOUND_MANAGER_ERROR_NONE Success
 926  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 927  * @retval #SOUND_MANAGER_ERROR_INVALID_OPERATION Invalid operation
 928  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 929  * @see sound_manager_remove_focus_state_watch_cb()
 930  */
 931 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);
 932
 933 /**
 934  * @brief Unregisters the focus state change watch callback.
 935  * @since_tizen 3.0
 936  *
 937  * @remarks     Do not call this function within sound_stream_focus_state_changed_cb() or sound_stream_focus_state_watch_cb(),\n
 938  *      otherwise #SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned.
 939  *
 940  * @param[in]   id              The focus state change watch callback id
 941  * @return @c 0 on success,
 942  *         otherwise a negative error value
 943  * @retval #SOUND_MANAGER_ERROR_NONE Success
 944  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 945  * @retval #SOUND_MANAGER_ERROR_INVALID_OPERATION Invalid operation
 946  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 947  * @see sound_manager_add_focus_state_watch_cb()
 948  */
 949 int sound_manager_remove_focus_state_watch_cb(int id);
 950
 951 /**
 952  * @}
 953  */
 954
 955 /**
 956  * @addtogroup CAPI_MEDIA_SOUND_MANAGER_DEVICE_MODULE
 957  * @{
 958  */
 959
 960 /**
 961  * @brief Gets the list consisting of connected devices.
 962  * @since_tizen 3.0
 963  *
 964  * @remarks     @a device_list should be freed using sound_manager_free_device_list().\n
 965  *      Use sound_manager_get_next_device() to get the first node of the list.
 966  *
 967  * @param[in]   device_mask     The mask values of #sound_device_mask_e combined with bitwise 'or'
 968  * @param[out]  device_list     The list of connected devices
 969  * @return @c 0 on success,
 970  *         otherwise a negative error value
 971  * @retval #SOUND_MANAGER_ERROR_NONE Success
 972  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 973  * @retval #SOUND_MANAGER_ERROR_NO_DATA No data
 974  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
 975  * @see sound_manager_get_next_device()
 976  * @see sound_manager_get_prev_device()
 977  * @see sound_manager_get_device_type()
 978  * @see sound_manager_get_device_io_direction()
 979  * @see sound_manager_get_device_id()
 980  * @see sound_manager_get_device_name()
 981  * @see sound_manager_is_device_running()
 982  * @see sound_manager_free_device_list()
 983  */
 984 int sound_manager_get_device_list(int device_mask, sound_device_list_h *device_list);
 985
 986 /**
 987  * @brief Frees device list and each item of list.
 988  * @since_tizen 3.0
 989  *
 990  * @remarks     This function will deallocate not only device list itself but also each item.
 991  *
 992  * @param[in]   device_list     The device list got with sound_manager_get_device_list.
 993  * @return @c 0 on success,
 994  *         otherwise a negative error value
 995  * @retval #SOUND_MANAGER_ERROR_NONE Success
 996  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
 997  *
 998  *
 999  * @see sound_manager_get_device_list()
1000  * @see sound_manager_get_next_device()
1001  * @see sound_manager_get_prev_device()
1002  * @see sound_manager_get_device_type()
1003  * @see sound_manager_get_device_io_direction()
1004  * @see sound_manager_get_device_id()
1005  * @see sound_manager_get_device_name()
1006  * @see sound_manager_is_device_running()
1007  */
1008 int sound_manager_free_device_list(sound_device_list_h device_list);
1009
1010 /**
1011  * @brief Gets the next item of the device list.
1012  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1013  * @param[in]   device_list     The list of connected devices
1014  * @param[out]  device  The device item
1015  * @return @c 0 on success,
1016  *         otherwise a negative error value
1017  * @retval #SOUND_MANAGER_ERROR_NONE Success
1018  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1019  * @retval #SOUND_MANAGER_ERROR_NO_DATA No data
1020  * @see sound_manager_get_device_list()
1021  * @see sound_manager_get_prev_device()
1022  * @see sound_manager_get_device_type()
1023  * @see sound_manager_get_device_io_direction()
1024  * @see sound_manager_get_device_id()
1025  * @see sound_manager_get_device_name()
1026  * @see sound_manager_is_device_running()
1027  * @see sound_manager_free_device_list()
1028  */
1029 int sound_manager_get_next_device(sound_device_list_h device_list, sound_device_h *device);
1030
1031 /**
1032  * @brief Gets the previous item of the device list.
1033  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1034  * @param[in]   device_list     The list of connected devices
1035  * @param[out]  device  The device item
1036  * @return @c 0 on success,
1037  *         otherwise a negative error value
1038  * @retval #SOUND_MANAGER_ERROR_NONE Success
1039  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1040  * @retval #SOUND_MANAGER_ERROR_NO_DATA No data
1041  * @see sound_manager_get_device_list()
1042  * @see sound_manager_get_next_device()
1043  * @see sound_manager_get_device_type()
1044  * @see sound_manager_get_device_io_direction()
1045  * @see sound_manager_get_device_id()
1046  * @see sound_manager_get_device_name()
1047  * @see sound_manager_is_device_running()
1048  * @see sound_manager_free_device_list()
1049  */
1050 int sound_manager_get_prev_device(sound_device_list_h device_list, sound_device_h *device);
1051
1052 /**
1053  * @brief Gets the type of the device.
1054  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1055  * @param[in]   device  The device item
1056  * @param[out]  type    The type of the device
1057  * @return @c 0 on success,
1058  *         otherwise a negative error value
1059  * @retval #SOUND_MANAGER_ERROR_NONE Success
1060  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1061  * @see sound_manager_get_device_list()
1062  * @see sound_manager_get_next_device()
1063  * @see sound_manager_get_prev_device()
1064  * @see sound_manager_get_device_io_direction()
1065  * @see sound_manager_get_device_id()
1066  * @see sound_manager_get_device_name()
1067  * @see sound_manager_is_device_running()
1068  * @see sound_manager_free_device_list()
1069  */
1070 int sound_manager_get_device_type(sound_device_h device, sound_device_type_e *type);
1071
1072 /**
1073  * @brief Gets the io direction of the device.
1074  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1075  * @param[in]   device  The device item
1076  * @param[out]  io_direction    The io direction of the device
1077  * @return @c 0 on success,
1078  *         otherwise a negative error value
1079  * @retval #SOUND_MANAGER_ERROR_NONE Success
1080  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1081  * @see sound_manager_get_device_list()
1082  * @see sound_manager_get_next_device()
1083  * @see sound_manager_get_prev_device()
1084  * @see sound_manager_get_device_type()
1085  * @see sound_manager_get_device_id()
1086  * @see sound_manager_get_device_name()
1087  * @see sound_manager_is_device_running()
1088  * @see sound_manager_free_device_list()
1089  */
1090 int sound_manager_get_device_io_direction(sound_device_h device, sound_device_io_direction_e *io_direction);
1091
1092 /**
1093  * @brief Gets the id of the device.
1094  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1095  * @param[in]   device  The device item
1096  * @param[out]  id      The id of the device
1097  * @return @c 0 on success,
1098  *         otherwise a negative error value
1099  * @retval #SOUND_MANAGER_ERROR_NONE Success
1100  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1101  * @see sound_manager_get_device_list()
1102  * @see sound_manager_get_next_device()
1103  * @see sound_manager_get_prev_device()
1104  * @see sound_manager_get_device_type()
1105  * @see sound_manager_get_device_io_direction()
1106  * @see sound_manager_get_device_name()
1107  * @see sound_manager_is_device_running()
1108  * @see sound_manager_free_device_list()
1109  */
1110 int sound_manager_get_device_id(sound_device_h device, int *id);
1111
1112 /**
1113  * @brief Gets the name of the device.
1114  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1115  * @param[in]   device  The device item
1116  * @param[out]  name    The name of the device
1117  * @return @c 0 on success,
1118  *         otherwise a negative error value
1119  * @retval #SOUND_MANAGER_ERROR_NONE Success
1120  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1121  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
1122  * @see sound_manager_get_device_list()
1123  * @see sound_manager_get_next_device()
1124  * @see sound_manager_get_prev_device()
1125  * @see sound_manager_get_device_type()
1126  * @see sound_manager_get_device_io_direction()
1127  * @see sound_manager_get_device_id()
1128  * @see sound_manager_is_device_running()
1129  * @see sound_manager_free_device_list()
1130  */
1131 int sound_manager_get_device_name(sound_device_h device, char **name);
1132
1133 /**
1134  * @brief Checks if the device is running.
1135  * @since_tizen 5.0
1136  * @param[in]   device  The device item
1137  * @param[out]  is_running      Whether the device is running or not : (@c true = running, @c false = not running)
1138  * @return @c 0 on success,
1139  *         otherwise a negative error value
1140  * @retval #SOUND_MANAGER_ERROR_NONE Success
1141  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1142  * @see sound_manager_get_device_list()
1143  * @see sound_manager_get_next_device()
1144  * @see sound_manager_get_prev_device()
1145  * @see sound_manager_get_device_type()
1146  * @see sound_manager_get_device_io_direction()
1147  * @see sound_manager_get_device_id()
1148  * @see sound_manager_get_device_name()
1149  * @see sound_manager_free_device_list()
1150  */
1151 int sound_manager_is_device_running(sound_device_h device, bool *is_running);
1152
1153 /**
1154  * @deprecated Deprecated since 4.0. Use sound_manager_is_device_running() instead.
1155  * @brief Gets the state of the device.
1156  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1157  * @param[in]   device  The device item
1158  * @param[out]  state   The state of the device
1159  * @return @c 0 on success,
1160  *         otherwise a negative error value
1161  * @retval #SOUND_MANAGER_ERROR_NONE Success
1162  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1163  * @see sound_manager_get_device_list()
1164  * @see sound_manager_get_next_device()
1165  * @see sound_manager_get_prev_device()
1166  * @see sound_manager_get_device_type()
1167  * @see sound_manager_get_device_io_direction()
1168  * @see sound_manager_get_device_id()
1169  * @see sound_manager_get_device_name()
1170  * @see sound_manager_free_device_list()
1171  */
1172 int sound_manager_get_device_state(sound_device_h device, sound_device_state_e *state) TIZEN_DEPRECATED_API;
1173
1174 /**
1175  * @brief Adds a callback function to be invoked when the connection state of a sound device was changed.
1176  * @since_tizen 3.0
1177  *
1178  * @param[in]   device_mask     Devices for which changes should be tracked, values of #sound_device_mask_e combined with bitwise 'or'
1179  * @param[in]   callback        The device connection state changed callback function
1180  * @param[in]   user_data       The user data to be passed to the callback function
1181  * @param[out]  id      The callback id
1182  * @return @c 0 on success,
1183  *         otherwise a negative error value
1184  * @retval #SOUND_MANAGER_ERROR_NONE Success
1185  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1186  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
1187  * @post sound_device_connection_changed_cb() will be invoked.
1188  * @see sound_manager_remove_device_connection_changed_cb()
1189  * @see sound_device_connection_changed_cb()
1190  */
1191 int sound_manager_add_device_connection_changed_cb(int device_mask, sound_device_connection_changed_cb callback, void *user_data, int *id);
1192
1193 /**
1194  * @brief Removes a callback function invoked when the connection of a sound device was changed.
1195  * @since_tizen 3.0
1196  *
1197  * @param[in]   id      The id of the callback to remove
1198  * @return @c 0 on success,
1199  *         otherwise a negative error value
1200  * @retval #SOUND_MANAGER_ERROR_NONE Success
1201  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1202  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
1203  * @see sound_manager_add_device_connection_changed_cb()
1204  */
1205 int sound_manager_remove_device_connection_changed_cb(int id);
1206
1207 /**
1208  * @brief Adds a callback function to be invoked when the state of a sound device was changed.
1209  * @since_tizen 5.0
1210  *
1211  * @param[in]   device_mask     Devices for which changes should be tracked, values of #sound_device_mask_e combined with bitwise 'or'
1212  * @param[in]   callback        The device state changed callback function
1213  * @param[in]   user_data       The user data to be passed to the callback function
1214  * @param[out]  id      The callback id
1215  * @return @c 0 on success,
1216  *         otherwise a negative error value
1217  * @retval #SOUND_MANAGER_ERROR_NONE Success
1218  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1219  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
1220  * @post  sound_device_running_changed_cb() will be invoked.
1221  * @see sound_manager_remove_device_running_changed_cb()
1222  * @see sound_device_running_changed_cb()
1223  */
1224 int sound_manager_add_device_running_changed_cb(int device_mask, sound_device_running_changed_cb callback, void *user_data, int *id);
1225
1226 /**
1227  * @brief Removes a callback function invoked when the state of a sound device was changed.
1228  * @since_tizen 5.0
1229  *
1230  * @param[in]   id      The id of the callback to remove
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_INTERNAL Internal error inside the sound system
1236  * @see sound_manager_add_device_running_changed_cb()
1237  */
1238 int sound_manager_remove_device_running_changed_cb(int id);
1239
1240 /**
1241  * @deprecated Deprecated since 4.0. Use sound_manager_add_device_running_changed_cb() instead.
1242  * @brief Adds a callback function to be invoked when the state of a sound device was changed.
1243  * @since_tizen 3.0
1244  *
1245  * @param[in]   device_mask     Devices for which changes should be tracked, values of #sound_device_mask_e combined with bitwise 'or'
1246  * @param[in]   callback        The device state changed callback function
1247  * @param[in]   user_data       The user data to be passed to the callback function
1248  * @param[out]  id      The callback id
1249  * @return @c 0 on success,
1250  *         otherwise a negative error value
1251  * @retval #SOUND_MANAGER_ERROR_NONE Success
1252  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1253  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
1254  * @post  sound_device_state_changed_cb() will be invoked.
1255  * @see sound_manager_remove_device_state_changed_cb()
1256  * @see sound_device_state_connected_cb()
1257  */
1258 int sound_manager_add_device_state_changed_cb(int device_mask, sound_device_state_changed_cb callback, void *user_data, int *id) TIZEN_DEPRECATED_API;
1259
1260 /**
1261  * @deprecated Deprecated since 4.0. Use sound_manager_remove_device_running_changed_cb() instead.
1262  * @brief Removes a callback function invoked when the state of a sound device was changed.
1263  * @since_tizen 3.0
1264  *
1265  * @param[in]   id      The id of the callback to remove
1266  * @return @c 0 on success,
1267  *         otherwise a negative error value
1268  * @retval #SOUND_MANAGER_ERROR_NONE Success
1269  * @retval #SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
1270  * @retval #SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
1271  * @see sound_manager_add_device_state_changed_cb()
1272  */
1273 int sound_manager_remove_device_state_changed_cb(int id) TIZEN_DEPRECATED_API;
1274
1275 /**
1276  * @}
1277  */
1278
1279 /**
1280  * @}
1281  */
1282
1283 #ifdef __cplusplus
1284 }
1285 #endif
1286
1287 #endif /* __TIZEN_MEDIA_SOUND_MANAGER_H__ */