Tizen Native API
7.0
|
The Volume API provides functions to check and control volumes.
Required Header
#include <sound_manager.h>
Overview
The Sound Manager Volume API allows you to:
- check/control output volumes
- handle a volume changed notification
The Sound Manager has predefined types of sounds.(system, notification, alarm, ringtone, media, call, voip, voice).
Current volume level of each type can be checked with sound_manager_get_volume(). To get the maximum supported volume level of each type, call sound_manager_get_max_volume(). The volume level of each type can be adjusted with sound_manager_set_volume().
The type of currently playing sound may be obtained by calling sound_manager_get_current_sound_type().
Functions | |
int | sound_manager_get_max_volume (sound_type_e type, int *max) |
Gets the maximum volume level supported for a particular sound type. | |
int | sound_manager_set_volume (sound_type_e type, int volume) |
Sets the volume level specified for a particular sound type. | |
int | sound_manager_get_volume (sound_type_e type, int *volume) |
Gets the volume level specified for a particular sound type. | |
int | sound_manager_get_current_sound_type (sound_type_e *type) |
Gets the type of the sound being currently played. | |
int | sound_manager_add_volume_changed_cb (sound_manager_volume_changed_cb callback, void *user_data, int *id) |
Adds a callback function to be invoked when the volume level is changed. | |
int | sound_manager_remove_volume_changed_cb (int id) |
Removes the volume change callback. | |
int | sound_manager_create_stream_ducking (sound_stream_type_e target_stream, sound_stream_ducking_state_changed_cb callback, void *user_data, sound_stream_ducking_h *stream_ducking) |
Creates a handle for stream ducking. | |
int | sound_manager_is_ducked (sound_stream_ducking_h stream_ducking, bool *is_ducked) |
Checks if the stream is ducked. | |
int | sound_manager_activate_ducking (sound_stream_ducking_h stream_ducking, unsigned int duration, double ratio) |
Activates ducking, asynchronously. | |
int | sound_manager_deactivate_ducking (sound_stream_ducking_h stream_ducking) |
Deactivates ducking, asynchronously. | |
int | sound_manager_destroy_stream_ducking (sound_stream_ducking_h stream_ducking) |
Destroys the handle for stream ducking. | |
Typedefs | |
typedef struct sound_stream_ducking_s * | sound_stream_ducking_h |
Sound stream ducking handle. | |
typedef void(* | sound_manager_volume_changed_cb )(sound_type_e type, unsigned int volume, void *user_data) |
Called when the system volume has changed. | |
typedef void(* | sound_stream_ducking_state_changed_cb )(sound_stream_ducking_h stream_ducking, bool is_ducked, void *user_data) |
Called when the ducking activation or deactivation is finished. |
Typedef Documentation
typedef void(* sound_manager_volume_changed_cb)(sound_type_e type, unsigned int volume, void *user_data) |
Called when the system volume has changed.
- Since :
- 2.3
- Parameters:
-
[in] type The sound type of the changed volume [in] volume The new volume value [in] user_data The user data passed from the callback registration function
- Precondition:
- sound_manager_set_volume() will invoke this callback if you register it using sound_manager_add_volume_changed_cb().
typedef struct sound_stream_ducking_s* sound_stream_ducking_h |
Sound stream ducking handle.
- Since :
- 5.5
typedef void(* sound_stream_ducking_state_changed_cb)(sound_stream_ducking_h stream_ducking, bool is_ducked, void *user_data) |
Called when the ducking activation or deactivation is finished.
- Since :
- 5.5
- Remarks:
- This function is invoked by the internal thread of the sound manager. Therefore it is recommended not to call functions which update UI in this callback.
- stream_ducking is the same handle as the parameter in sound_manager_create_stream_ducking() that registers this callback, so the handle should not be released in this callback.
- Parameters:
-
[in] stream_ducking The stream ducking handle [in] is_ducked The flag whether it's ducked or not [in] user_data The user data passed from the callback registration function
- Precondition:
- You should register this callback when sound_manager_create_stream_ducking() is called.
Enumeration Type Documentation
enum sound_type_e |
Enumeration for sound type.
- Since :
- 2.3
- Enumerator:
Function Documentation
int sound_manager_activate_ducking | ( | sound_stream_ducking_h | stream_ducking, |
unsigned int | duration, | ||
double | ratio | ||
) |
Activates ducking, asynchronously.
- Since :
- 5.5
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/volume.set
- Remarks:
- If ducking is activated successfully, the volume of all sound streams matched with the target_stream that set in sound_manager_create_stream_ducking() is decreased by ratio for duration. The change applies system-wide.
- Parameters:
-
[in] stream_ducking The handle of stream ducking [in] duration The duration for ducking (msec, 0 <= duration <= 3000) [in] ratio The volume ratio when ducked (0.0 <= ratio < 1.0)
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
SOUND_MANAGER_ERROR_NONE Success SOUND_MANAGER_ERROR_PERMISSION_DENIED Permission denied SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter SOUND_MANAGER_ERROR_INVALID_STATE Invalid state SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
- Precondition:
- The stream should be unducked before calling this function, otherwise, SOUND_MANAGER_ERROR_INVALID_STATE is returned.
- Postcondition:
- sound_stream_ducking_state_changed_cb() will be invoked.
int sound_manager_add_volume_changed_cb | ( | sound_manager_volume_changed_cb | callback, |
void * | user_data, | ||
int * | id | ||
) |
Adds a callback function to be invoked when the volume level is changed.
- Since :
- 3.0
- Parameters:
-
[in] callback Callback function to indicate change in volume [in] user_data The user data to be passed to the callback function [out] id The callback id
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
SOUND_MANAGER_ERROR_NONE Success SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
- Postcondition:
- sound_manager_volume_changed_cb() will be invoked.
int sound_manager_create_stream_ducking | ( | sound_stream_type_e | target_stream, |
sound_stream_ducking_state_changed_cb | callback, | ||
void * | user_data, | ||
sound_stream_ducking_h * | stream_ducking | ||
) |
Creates a handle for stream ducking.
- Since :
- 5.5
- Remarks:
- stream_ducking should be released using sound_manager_destroy_stream_ducking().
- Parameters:
-
[in] target_stream The type of target stream [in] callback The callback function called when ducking state is changed (optional, this can be NULL) [in] user_data The user data to be passed to the callback function (optional, this can be NULL) [out] stream_ducking The handle of stream ducking
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
SOUND_MANAGER_ERROR_NONE Success SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
int sound_manager_deactivate_ducking | ( | sound_stream_ducking_h | stream_ducking | ) |
Deactivates ducking, asynchronously.
- Since :
- 5.5
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/volume.set
- Parameters:
-
[in] stream_ducking The handle of stream ducking
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
SOUND_MANAGER_ERROR_NONE Success SOUND_MANAGER_ERROR_PERMISSION_DENIED Permission denied SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter SOUND_MANAGER_ERROR_INVALID_STATE Invalid state SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
- Precondition:
- The stream should be ducked before calling this function, otherwise, SOUND_MANAGER_ERROR_INVALID_STATE is returned.
- Postcondition:
- sound_stream_ducking_state_changed_cb() will be invoked.
int sound_manager_destroy_stream_ducking | ( | sound_stream_ducking_h | stream_ducking | ) |
Destroys the handle for stream ducking.
- Since :
- 5.5
- Parameters:
-
[in] stream_ducking The handle of stream ducking
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
SOUND_MANAGER_ERROR_NONE Success SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system SOUND_MANAGER_ERROR_INVALID_STATE Invalid state
- Precondition:
- The stream should be unducked before calling this function, otherwise, SOUND_MANAGER_ERROR_INVALID_STATE is returned.
int sound_manager_get_current_sound_type | ( | sound_type_e * | type | ) |
Gets the type of the sound being currently played.
- Since :
- 2.3
- Parameters:
-
[out] type The current sound type
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
SOUND_MANAGER_ERROR_NONE Success SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter SOUND_MANAGER_ERROR_NO_PLAYING_SOUND No playing sound SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
int sound_manager_get_max_volume | ( | sound_type_e | type, |
int * | max | ||
) |
Gets the maximum volume level supported for a particular sound type.
- Since :
- 2.3
- Parameters:
-
[in] type The sound type [out] max The maximum volume level
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
SOUND_MANAGER_ERROR_NONE Success SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter
int sound_manager_get_volume | ( | sound_type_e | type, |
int * | volume | ||
) |
Gets the volume level specified for a particular sound type.
- Since :
- 2.3
- Parameters:
-
[in] type The sound type [out] volume The current volume level
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
SOUND_MANAGER_ERROR_NONE Success SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
int sound_manager_is_ducked | ( | sound_stream_ducking_h | stream_ducking, |
bool * | is_ducked | ||
) |
Checks if the stream is ducked.
- Since :
- 5.5
- Parameters:
-
[in] stream_ducking The handle of stream ducking [out] is_ducked Whether the stream is ducked or not. true
if ducked,false
otherwise.
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
SOUND_MANAGER_ERROR_NONE Success SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system SOUND_MANAGER_ERROR_INVALID_STATE Invalid state
int sound_manager_remove_volume_changed_cb | ( | int | id | ) |
Removes the volume change callback.
- Since :
- 3.0
- Parameters:
-
[in] id The id of the callback to remove
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
SOUND_MANAGER_ERROR_NONE Success SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system
int sound_manager_set_volume | ( | sound_type_e | type, |
int | volume | ||
) |
Sets the volume level specified for a particular sound type.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/volume.set
- Parameters:
-
[in] type The sound type [in] volume The volume level to be set
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
SOUND_MANAGER_ERROR_NONE Success SOUND_MANAGER_ERROR_INVALID_PARAMETER Invalid parameter SOUND_MANAGER_ERROR_PERMISSION_DENIED Permission denied SOUND_MANAGER_ERROR_INTERNAL Internal error inside the sound system