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]	code	The interrupted code
[in]	user_data	The 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

enum sound_session_interrupted_code_e

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

enum sound_session_option_for_during_play_e

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

enum sound_session_option_for_resumption_e

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

enum sound_session_option_for_starting_e

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

enum sound_session_type_e

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

enum sound_session_voip_mode_e

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

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.

Since :: 2.3.1

Parameters:

[out]	s_option	The session option for starting
[out]	d_option	The session option for during play

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_INVALID_OPERATION	Invalid operation
SOUND_MANAGER_ERROR_POLICY	Noncompliance 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()

int sound_manager_get_media_session_resumption_option ( sound_session_option_for_resumption_e * option )

Gets the media sound session resumption option.

Since :: 2.3.1

Parameters:

[out] option The session resumption option

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_INVALID_OPERATION	Invalid operation
SOUND_MANAGER_ERROR_POLICY	Noncompliance 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()

int sound_manager_get_session_type ( sound_session_type_e * type )

Gets the application's sound session type.

Since :: 2.3.1

Parameters:

[in] type The session type

Returns:: 0 on success, otherwise a negative error value

Return values:

SOUND_MANAGER_ERROR_NONE	Success
SOUND_MANAGER_ERROR_INVALID_PARAMETER	Invalid parameter

See also:: sound_manager_set_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()

int sound_manager_get_voip_session_mode ( sound_session_voip_mode_e * mode )

Gets the mode of the voip sound session.

Since :: 2.3.1

Parameters:

[out] mode The voip session mode

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_NOT_SUPPORTED	Not supported
SOUND_MANAGER_ERROR_INTERNAL	Internal error inside the sound system
SOUND_MANAGER_ERROR_POLICY	Noncompliance 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()

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.

Since :: 2.3.1

Parameters:

[in]	s_option	The session option for starting
[in]	d_option	The session option for during play

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_INVALID_OPERATION	Invalid operation
SOUND_MANAGER_ERROR_POLICY	Noncompliance 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()

int sound_manager_set_media_session_resumption_option ( sound_session_option_for_resumption_e option )

Sets the media sound session resumption option.

Since :: 2.3.1

Parameters:

[in] option The session resumption option

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_INVALID_OPERATION	Invalid operation
SOUND_MANAGER_ERROR_POLICY	Noncompliance 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()

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.

Since :: 2.3.1

Parameters:

[in]	callback	The interrupted callback function
[in]	user_data	The user data to be passed to the callback function

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_POLICY	Noncompliance 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()

int sound_manager_set_session_type ( sound_session_type_e type )

Sets the application's sound session type.

Since :: 2.3.1

Parameters:

[in] type The session type to 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_NOT_SUPPORTED	Not supported
SOUND_MANAGER_ERROR_INTERNAL	Internal error inside the sound system
SOUND_MANAGER_ERROR_POLICY	Noncompliance 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()

int sound_manager_set_voip_session_mode ( sound_session_voip_mode_e mode )

Sets the mode of the voip sound session.

Since :: 2.3.1

Parameters:

[in] mode The voip session mode

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_NOT_SUPPORTED	Not supported
SOUND_MANAGER_ERROR_INTERNAL	Internal error inside the sound system
SOUND_MANAGER_ERROR_POLICY	Noncompliance 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()

int sound_manager_unset_session_interrupted_cb ( void )

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_NONE	Success
SOUND_MANAGER_ERROR_INTERNAL	Internal error inside the sound system

See also:: sound_manager_set_session_interrupted_cb()

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation