Tizen Native API

The Session API provides functions to control a session.

Required Header

#include <sound_manager.h>

Overview

The Sound Manager Session API allows you to:

  • determine a sound session policy
  • handle the notification of a sound session interruption

The Sound Manager has predefined sound sessions (media, alarm, notification, emergency, voip)

Related Features

APIs for voip sound session are related with the following features:

It is recommended to design feature related codes in your application for reliability.

You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.

To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.

More details on featuring your application can be found from Feature Element.

Functions

int sound_manager_set_session_type (sound_session_type_e type)
 Sets the application's sound session type.
int sound_manager_get_session_type (sound_session_type_e *type)
 Gets the application's sound session type.
int sound_manager_set_media_session_option (sound_session_option_for_starting_e s_option, sound_session_option_for_during_play_e d_option)
 Sets the media sound session option.
int sound_manager_get_media_session_option (sound_session_option_for_starting_e *s_option, sound_session_option_for_during_play_e *d_option)
 Gets the media sound session option.
int sound_manager_set_media_session_resumption_option (sound_session_option_for_resumption_e option)
 Sets the media sound session resumption option.
int sound_manager_get_media_session_resumption_option (sound_session_option_for_resumption_e *option)
 Gets the media sound session resumption option.
int sound_manager_set_voip_session_mode (sound_session_voip_mode_e mode)
 Sets the mode of the voip sound session.
int sound_manager_get_voip_session_mode (sound_session_voip_mode_e *mode)
 Gets the mode of the voip sound session.
int sound_manager_set_session_interrupted_cb (sound_session_interrupted_cb callback, void *user_data)
 Registers a callback function to be invoked when the sound session being played was interrupted.
int sound_manager_unset_session_interrupted_cb (void)
 Unregisters the callback function which is called when the sound session being played is interrupted.

Typedefs

typedef void(* sound_session_interrupted_cb )(sound_session_interrupted_code_e code, void *user_data)
 Called when the playing sound session is interrupted.

Typedef Documentation

typedef void(* sound_session_interrupted_cb)(sound_session_interrupted_code_e code, void *user_data)

Called when the playing sound session is interrupted.

Since :
2.3.1
Parameters:
[in]codeThe interrupted code
[in]user_dataThe user data passed from the callback registration function
Precondition:
You should register this callback using sound_manager_set_session_interrupted_cb().
See also:
sound_manager_set_session_interrupted_cb()
sound_manager_unset_session_interrupted_cb()

Enumeration Type Documentation

Enumeration for sound session interrupted type.

Since :
2.3.1
Enumerator:
SOUND_SESSION_INTERRUPTED_COMPLETED 

Interrupt completed

SOUND_SESSION_INTERRUPTED_BY_MEDIA 

Interrupted by media application

SOUND_SESSION_INTERRUPTED_BY_CALL 

Interrupted by an incoming call

SOUND_SESSION_INTERRUPTED_BY_EARJACK_UNPLUG 

Interrupted by unplugging headphones

SOUND_SESSION_INTERRUPTED_BY_RESOURCE_CONFLICT 

Interrupted by a resource conflict

SOUND_SESSION_INTERRUPTED_BY_ALARM 

Interrupted by an alarm

SOUND_SESSION_INTERRUPTED_BY_EMERGENCY 

Interrupted by an emergency

SOUND_SESSION_INTERRUPTED_BY_NOTIFICATION 

Interrupted by a notification

Enumeration for session option during play.

Since :
2.3.1
Enumerator:
SOUND_SESSION_OPTION_INTERRUPTIBLE_DURING_PLAY 

This session will be interrupted by other sessions during play (default)

SOUND_SESSION_OPTION_UNINTERRUPTIBLE_DURING_PLAY 

This session will not be interrupted by other media sessions

Enumeration for session option for resumption.

Since :
2.3.1
Enumerator:
SOUND_SESSION_OPTION_RESUMPTION_BY_SYSTEM 

This session will be resumed according to system policy (default)

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

Enumeration for session option for starting.

Since :
2.3.1
Enumerator:
SOUND_SESSION_OPTION_MIX_WITH_OTHERS_WHEN_START 

This session will be mixed with others when starting (default)

SOUND_SESSION_OPTION_PAUSE_OTHERS_WHEN_START 

This session will interrupt other sessions when starting

Enumeration for session type.

Since :
2.3.1
Enumerator:
SOUND_SESSION_TYPE_MEDIA 

Media type

SOUND_SESSION_TYPE_ALARM 

Alarm type

SOUND_SESSION_TYPE_NOTIFICATION 

Notification type

SOUND_SESSION_TYPE_EMERGENCY 

Emergency type

SOUND_SESSION_TYPE_VOIP 

VOIP type

Enumeration for voip session mode.

Since :
2.3.1
Enumerator:
SOUND_SESSION_VOIP_MODE_RINGTONE 

voip mode for ringtone

SOUND_SESSION_VOIP_MODE_VOICE_WITH_BUILTIN_RECEIVER 

voip mode for during call with built-in receiver

SOUND_SESSION_VOIP_MODE_VOICE_WITH_BUILTIN_SPEAKER 

voip mode for during call with built-in speaker

SOUND_SESSION_VOIP_MODE_VOICE_WITH_AUDIO_JACK 

voip mode for during call with audio jack

SOUND_SESSION_VOIP_MODE_VOICE_WITH_BLUETOOTH 

voip mode for during call with bluetooth


Function Documentation

Gets the media sound session option.

Since :
2.3.1
Parameters:
[out]s_optionThe session option for starting
[out]d_optionThe session option for during play
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_MANAGER_ERROR_NONESuccess
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
SOUND_MANAGER_ERROR_INVALID_OPERATIONInvalid operation
SOUND_MANAGER_ERROR_POLICYNoncompliance with the sound system policy
See also:
sound_manager_set_session_type()
sound_manager_get_session_type()
sound_manager_set_media_session_option()
sound_manager_set_media_session_resumption_option()
sound_manager_get_media_session_resumption_option()

Gets the media sound session resumption option.

Since :
2.3.1
Parameters:
[out]optionThe session resumption option
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_MANAGER_ERROR_NONESuccess
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
SOUND_MANAGER_ERROR_INVALID_OPERATIONInvalid operation
SOUND_MANAGER_ERROR_POLICYNoncompliance with the sound system policy
See also:
sound_manager_set_session_type()
sound_manager_get_session_type()
sound_manager_set_media_session_option()
sound_manager_get_media_session_option()
sound_manager_set_media_session_resumption_option()

Gets the mode of the voip sound session.

Since :
2.3.1
Parameters:
[out]modeThe voip session mode
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_MANAGER_ERROR_NONESuccess
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
SOUND_MANAGER_ERROR_NOT_SUPPORTEDNot supported
SOUND_MANAGER_ERROR_INTERNALInternal error inside the sound system
SOUND_MANAGER_ERROR_POLICYNoncompliance with the sound system policy
Precondition:
Call sound_manager_set_session_type(SOUND_SESSION_TYPE_VOIP) before calling this function.
See also:
sound_manager_set_session_type()
sound_manager_get_session_type()
sound_manager_set_voip_session_mode()

Sets the media sound session option.

Since :
2.3.1
Parameters:
[in]s_optionThe session option for starting
[in]d_optionThe session option for during play
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_MANAGER_ERROR_NONESuccess
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
SOUND_MANAGER_ERROR_INVALID_OPERATIONInvalid operation
SOUND_MANAGER_ERROR_POLICYNoncompliance with the sound system policy
Precondition:
Call sound_manager_set_session_type(SOUND_SESSION_TYPE_MEDIA) before calling this function.
See also:
sound_manager_set_session_type()
sound_manager_get_session_type()
sound_manager_get_media_session_option()
sound_manager_set_media_session_resumption_option()
sound_manager_get_media_session_resumption_option()

Sets the media sound session resumption option.

Since :
2.3.1
Parameters:
[in]optionThe session resumption option
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_MANAGER_ERROR_NONESuccess
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
SOUND_MANAGER_ERROR_INVALID_OPERATIONInvalid operation
SOUND_MANAGER_ERROR_POLICYNoncompliance with the sound system policy
Precondition:
Call sound_manager_set_session_type(SOUND_SESSION_TYPE_MEDIA) before calling this function.
See also:
sound_manager_set_session_type()
sound_manager_get_session_type()
sound_manager_set_media_session_option()
sound_manager_get_media_session_option()
sound_manager_get_media_session_resumption_option()

Registers a callback function to be invoked when the sound session being played was interrupted.

Since :
2.3.1
Parameters:
[in]callbackThe interrupted callback function
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_MANAGER_ERROR_NONESuccess
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
SOUND_MANAGER_ERROR_POLICYNoncompliance with the sound system policy
Postcondition:
sound_session_interrupted_cb() will be invoked.
See also:
sound_manager_unset_session_interrupted_cb()
sound_session_interrupted_cb()

Sets the application's sound session type.

Since :
2.3.1
Parameters:
[in]typeThe session type to set
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_MANAGER_ERROR_NONESuccess
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
SOUND_MANAGER_ERROR_NOT_SUPPORTEDNot supported
SOUND_MANAGER_ERROR_INTERNALInternal error inside the sound system
SOUND_MANAGER_ERROR_POLICYNoncompliance with the sound system policy
See also:
sound_manager_get_session_type()
sound_manager_set_media_session_option()
sound_manager_get_media_session_option()
sound_manager_set_media_session_resumption_option()
sound_manager_get_media_session_resumption_option()
sound_manager_set_voip_session_mode()
sound_manager_get_voip_session_mode()

Sets the mode of the voip sound session.

Since :
2.3.1
Parameters:
[in]modeThe voip session mode
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_MANAGER_ERROR_NONESuccess
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
SOUND_MANAGER_ERROR_NOT_SUPPORTEDNot supported
SOUND_MANAGER_ERROR_INTERNALInternal error inside the sound system
SOUND_MANAGER_ERROR_POLICYNoncompliance with the sound system policy
Precondition:
Call sound_manager_set_session_type(SOUND_SESSION_TYPE_VOIP) before calling this function.
See also:
sound_manager_set_session_type()
sound_manager_get_session_type()
sound_manager_get_voip_session_mode()

Unregisters the callback function which is called when the sound session being played is interrupted.

Since :
2.3.1
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_MANAGER_ERROR_NONESuccess
SOUND_MANAGER_ERROR_INTERNALInternal error inside the sound system
See also:
sound_manager_set_session_interrupted_cb()