The Stream Policy API provides functions to control a sound stream.

Required Header

#include <sound_manager.h>

Overview

The Sound Manager Stream API allows you to:

determine/control a sound stream policy
handle the notification of a sound focus status change

The Sound Manager has predefined sound stream types (media, system, alarm, notification, emergency, voip, etc)

Functions
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)
	Creates a handle for stream information.
int	sound_manager_destroy_stream_information (sound_stream_info_h stream_info)
	Destroys the handle for stream information.
int	sound_manager_get_sound_type (sound_stream_info_h stream_info, sound_type_e *sound_type)
	Gets the sound type of the stream information.
int	sound_manager_add_device_for_stream_routing (sound_stream_info_h stream_info, sound_device_h device)
	Adds the device to the stream information for the stream routing.
int	sound_manager_remove_device_for_stream_routing (sound_stream_info_h stream_info, sound_device_h device)
	Removes the device from the stream information for the stream routing.
int	sound_manager_remove_all_devices_for_stream_routing (sound_stream_info_h stream_info)
	Removes all devices from the stream information for the stream routing.
int	sound_manager_apply_stream_routing (sound_stream_info_h stream_info)
	Applies the stream routing.
int	sound_manager_set_stream_preferred_device (sound_stream_info_h stream_info, sound_device_io_direction_e io_direction, sound_device_h device)
	Sets the preferred built-in device for the stream routing.
int	sound_manager_get_stream_preferred_device (sound_stream_info_h stream_info, int in_device_id, int out_device_id)
	Gets the preferred device id of the stream info handle.
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)
	Acquires the stream focus.
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)
	Releases the acquired stream focus.
int	sound_manager_acquire_focus_all (sound_stream_info_h stream_info, int sound_behavior, const char *extra_info)
	Acquires all the stream focuses.
int	sound_manager_release_focus_all (sound_stream_info_h stream_info, int sound_behavior, const char *extra_info)
	Releases all the acquired stream focuses.
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)
	Gets the state of focus.
int	sound_manager_set_focus_reacquisition (sound_stream_info_h stream_info, bool enable)
	Sets auto focus reacquisition property.
int	sound_manager_get_focus_reacquisition (sound_stream_info_h stream_info, bool *enabled)
	Gets auto focus reacquisition property.
int	sound_manager_deliver_focus (sound_stream_info_h source, sound_stream_info_h destination, sound_stream_focus_mask_e focus_mask)
	Delivers focuses to another stream information.
int	sound_manager_is_stream_on_device (sound_stream_info_h stream_info, sound_device_h device, bool *is_on)
	Checks if the stream information is using the device.
int	sound_manager_get_current_media_playback_device_type (sound_device_type_e *device_type)
	Gets the current device type for media playback stream.
int	sound_manager_get_current_playback_focus (sound_stream_focus_change_reason_e acquired_by, int sound_behavior, char **extra_info)
	Gets the reason for the current acquired playback focus.
int	sound_manager_get_current_recording_focus (sound_stream_focus_change_reason_e acquired_by, int sound_behavior, char **extra_info)
	Gets the reason for the current acquired recording focus.
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)
	Registers the watch callback function to be invoked when the focus state for each sound stream type is changed regardless of the process.
int	sound_manager_remove_focus_state_watch_cb (int id)
	Unregisters the focus state change watch callback.
Typedefs
typedef struct sound_stream_info_s *	sound_stream_info_h
	Sound stream information handle.
typedef void(*	sound_stream_focus_state_changed_cb )(sound_stream_info_h stream_info, sound_stream_focus_mask_e focus_mask, sound_stream_focus_state_e focus_state, sound_stream_focus_change_reason_e reason, int sound_behavior, const char extra_info, void user_data)
	Called when the state of focus that belongs to the stream_info is changed.
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)
	Called when the focus state for each sound stream type is changed regardless of the process.
Defines
#define	SOUND_MANAGER_STREAM_NO_PREFERRED_DEVICE 0
	Definition for the value indicating that the preferred device for the stream information was not set.

Define Documentation

#define SOUND_MANAGER_STREAM_NO_PREFERRED_DEVICE 0

Definition for the value indicating that the preferred device for the stream information was not set.

Since :: 5.5

See also:: sound_manager_get_stream_preferred_device()

Typedef Documentation

typedef void(* sound_stream_focus_state_changed_cb)(sound_stream_info_h stream_info, sound_stream_focus_mask_e focus_mask, sound_stream_focus_state_e focus_state, sound_stream_focus_change_reason_e reason, int sound_behavior, const char *extra_info, void *user_data)

Called when the state of focus that belongs to the stream_info is changed.

Since :: 3.0

Remarks:: This function is issued in the internal thread of the sound manager.
Therefore it is recommended not to call UI update function in this function.

Parameters:

[in]	stream_info	The handle of stream information
[in]	focus_mask	The changed focus mask
[in]	focus_state	The changed focus state
[in]	reason	The reason for state change of the focus
[in]	sound_behavior	The requested sound behavior that should be followed, values of sound_behavior_e combined with bitwise 'or'
[in]	extra_info	The extra information
[in]	user_data	The user data passed from the callback registration function

Precondition:: You should register this callback using sound_manager_create_stream_information().

See also:: sound_manager_create_stream_information(); sound_manager_destroy_stream_information(); sound_manager_get_focus_state()

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)

Called when the focus state for each sound stream type is changed regardless of the process.

Since :: 3.0

Remarks:: This function is invoked by the internal thread of the sound manager.
Therefore it is recommended not to call functions which update the UI from this callback.

Parameters:

[in]	id	The focus state change watch cb id
[in]	focus_mask	The changed focus mask
[in]	focus_state	The changed focus state
[in]	reason	The reason for state change of the focus
[in]	extra_info	The extra information
[in]	user_data	The user data passed from the callback registration function

Precondition:: You should register this callback using sound_manager_add_focus_state_watch_cb().

See also:: sound_manager_add_focus_state_watch_cb(); sound_manager_remove_focus_state_watch_cb()

typedef struct sound_stream_info_s* sound_stream_info_h

Sound stream information handle.

Since :: 3.0

Enumeration Type Documentation

enum sound_behavior_e

Enumeration for sound behavior.

Since :: 3.0

Remarks:: These values can be combined with bitwise 'or'.

See also:: sound_manager_get_current_playback_focus(); sound_manager_get_current_recording_focus()

Enumerator:

SOUND_BEHAVIOR_NONE	None (default)
SOUND_BEHAVIOR_NO_RESUME	No resumption
SOUND_BEHAVIOR_FADING	Fading effect

enum sound_stream_focus_change_reason_e

Enumeration for change reason of sound stream focus state.

Since :: 3.0

Enumerator:

SOUND_STREAM_FOCUS_CHANGED_BY_MEDIA	Changed by the stream type for media
SOUND_STREAM_FOCUS_CHANGED_BY_SYSTEM	Changed by the stream type for system
SOUND_STREAM_FOCUS_CHANGED_BY_ALARM	Changed by the stream type for alarm
SOUND_STREAM_FOCUS_CHANGED_BY_NOTIFICATION	Changed by the stream type for notification
SOUND_STREAM_FOCUS_CHANGED_BY_EMERGENCY	Changed by the stream type for emergency
SOUND_STREAM_FOCUS_CHANGED_BY_VOICE_INFORMATION	Changed by the stream type for voice information
SOUND_STREAM_FOCUS_CHANGED_BY_VOICE_RECOGNITION	Changed by the stream type for voice recognition
SOUND_STREAM_FOCUS_CHANGED_BY_RINGTONE	Changed by the stream type for ringtone
SOUND_STREAM_FOCUS_CHANGED_BY_VOIP	Changed by the stream type for VoIP
SOUND_STREAM_FOCUS_CHANGED_BY_CALL	Changed by the stream type for voice-call or video-call
SOUND_STREAM_FOCUS_CHANGED_BY_MEDIA_EXTERNAL_ONLY	Changed by the stream type for media only for external devices

enum sound_stream_focus_mask_e

Enumeration for sound stream focus mask.

Since :: 3.0

Enumerator:

SOUND_STREAM_FOCUS_FOR_PLAYBACK	Mask for playback focus
SOUND_STREAM_FOCUS_FOR_RECORDING	Mask for recording focus
SOUND_STREAM_FOCUS_FOR_BOTH	Mask for both playback and recording focus

enum sound_stream_focus_state_e

Enumeration for sound stream focus state.

Since :: 3.0

Enumerator:

SOUND_STREAM_FOCUS_STATE_RELEASED	Focus state for release
SOUND_STREAM_FOCUS_STATE_ACQUIRED	Focus state for acquisition

enum sound_stream_type_e

Enumeration for sound stream type.

Since :: 3.0

Enumerator:

SOUND_STREAM_TYPE_MEDIA	Sound stream type for media
SOUND_STREAM_TYPE_SYSTEM	Sound stream type for system
SOUND_STREAM_TYPE_ALARM	Sound stream type for alarm
SOUND_STREAM_TYPE_NOTIFICATION	Sound stream type for notification
SOUND_STREAM_TYPE_EMERGENCY	Sound stream type for emergency
SOUND_STREAM_TYPE_VOICE_INFORMATION	Sound stream type for voice information
SOUND_STREAM_TYPE_VOICE_RECOGNITION	Sound stream type for voice recognition
SOUND_STREAM_TYPE_RINGTONE_VOIP	Sound stream type for ringtone for VoIP
SOUND_STREAM_TYPE_VOIP	Sound stream type for VoIP
SOUND_STREAM_TYPE_MEDIA_EXTERNAL_ONLY	Sound stream type for media only for external devices

Function Documentation

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
	)

Acquires the stream focus.

Since :: 3.0

Remarks:: Do not call this function within sound_stream_focus_state_changed_cb() or sound_stream_focus_state_watch_cb(),
otherwise SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned. Since 4.0, it is allowed and does not return the error.

Parameters:

[in]	stream_info	The handle of stream information
[in]	focus_mask	The focus mask that user wants to acquire
[in]	sound_behavior	The requesting sound behavior, values of sound_behavior_e combined with bitwise 'or'
[in]	extra_info	The extra information for this request (optional, this can be NULL)

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_INVALID_STATE	Invalid state
SOUND_MANAGER_ERROR_POLICY	Noncompliance with the sound system policy
SOUND_MANAGER_ERROR_INTERNAL	Internal error inside the sound system

Precondition:: Call sound_manager_create_stream_information() with its parameter for sound_stream_focus_state_changed_cb()
before calling this function.

See also:: sound_manager_create_stream_information(); sound_manager_destroy_stream_information(); sound_manager_acquire_focus_all(); sound_manager_release_focus(); sound_manager_release_focus_all(); sound_manager_get_focus_state()

int sound_manager_acquire_focus_all	(	sound_stream_info_h	stream_info,
		int	sound_behavior,
		const char *	extra_info
	)

Acquires all the stream focuses.

Since :: 4.0

Remarks:: This function does not return error even though one or all of focuses have already been acquired.
Use sound_manager_get_focus_state() to get acquired focus state if it returns SOUND_MANAGER_ERROR_POLICY.

Parameters:

[in]	stream_info	The handle of stream information
[in]	sound_behavior	The requesting sound behavior, values of sound_behavior_e combined with bitwise 'or'
[in]	extra_info	The extra information for this request (optional, this can be NULL)

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

Precondition:: Call sound_manager_create_stream_information() with its parameter for sound_stream_focus_state_changed_cb()
before calling this function.

See also:: sound_manager_create_stream_information(); sound_manager_destroy_stream_information(); sound_manager_acquire_focus(); sound_manager_release_focus(); sound_manager_release_focus_all(); sound_manager_get_focus_state()

int sound_manager_add_device_for_stream_routing	(	sound_stream_info_h	stream_info,
		sound_device_h	device
	)

Adds the device to the stream information for the stream routing.

Since :: 3.0

Remarks:: Use sound_manager_get_device_list() and sound_manager_get_next_device() to get the device.
SOUND_MANAGER_ERROR_POLICY could be returned according to the stream type of the stream_info.
The available types of the stream_info for this function are SOUND_STREAM_TYPE_VOIP and SOUND_STREAM_TYPE_MEDIA_EXTERNAL_ONLY.

Parameters:

[in]	stream_info	The handle of stream information
[in]	device	The device item from sound_device_list_h

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

Precondition:: Call sound_manager_create_stream_information() before calling this function.

Postcondition:: You can apply this setting by calling sound_manager_apply_stream_routing().

See also:: sound_manager_create_stream_information(); sound_manager_destroy_stream_information(); sound_manager_remove_device_for_stream_routing(); sound_manager_remove_all_devices_for_stream_routing(); sound_manager_apply_stream_routing()

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
	)

Registers the watch callback function to be invoked when the focus state for each sound stream type is changed regardless of the process.

Since :: 3.0

Remarks:: The registered callback is invoked by the internal thread of the sound manager.
Do not call this function within sound_stream_focus_state_changed_cb() or sound_stream_focus_state_watch_cb(),
otherwise SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned.

Parameters:

[in]	focus_mask	The focus mask that user wants to watch
[in]	callback	The focus state change watch callback function
[in]	user_data	The user data to be passed to the callback function
[out]	id	The focus state change watch 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_INVALID_OPERATION	Invalid operation
SOUND_MANAGER_ERROR_INTERNAL	Internal error inside the sound system

See also:: sound_manager_remove_focus_state_watch_cb()

int sound_manager_apply_stream_routing ( sound_stream_info_h stream_info )

Applies the stream routing.

Since :: 3.0

Remarks:: If the stream has not been made yet, this setting will be applied when the stream starts to play.

Parameters:

[in] stream_info The handle of stream information

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_STATE	Invalid state
SOUND_MANAGER_ERROR_INTERNAL	Internal error inside the sound system

Precondition:: Call sound_manager_create_stream_information() and sound_manager_add_device_for_stream_routing() before calling this function.

See also:: sound_manager_create_stream_information(); sound_manager_destroy_stream_information(); sound_manager_add_device_for_stream_routing(); sound_manager_remove_device_for_stream_routing(); sound_manager_remove_all_devices_for_stream_routing()

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
	)

Creates a handle for stream information.

Since :: 3.0

Remarks:: The registered callback is issued in the internal thread of the sound manager.
Do not call this function within sound_stream_focus_state_changed_cb() or sound_stream_focus_state_watch_cb(),
otherwise SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned.
To apply the stream policy according to this stream information, this handle should be passed to other APIs
related to playback or recording.(e.g. player, wav-player, audio-io, etc.)

Parameters:

[in]	stream_type	The type of stream
[in]	callback	The focus state change callback function (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_info	The handle of stream information

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

See also:: sound_manager_destroy_stream_information(); sound_manager_add_device_for_stream_routing(); sound_manager_remove_device_for_stream_routing(); sound_manager_remove_all_devices_for_stream_routing(); sound_manager_apply_stream_routing(); sound_manager_acquire_focus(); sound_manager_release_focus(); sound_manager_get_focus_state()

int sound_manager_deliver_focus	(	sound_stream_info_h	source,
		sound_stream_info_h	destination,
		sound_stream_focus_mask_e	focus_mask
	)

Delivers focuses to another stream information.

Since :: 4.0

Remarks:: This function does not affect any invocation of sound_stream_focus_state_changed_cb() or
sound_stream_focus_state_watch_cb(). Do not call this function within sound_stream_focus_state_changed_cb() or
sound_stream_focus_state_watch_cb(), otherwise SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned.

Parameters:

[in]	source	The source handle of stream information which has focuses
[in]	destination	The destination handle of stream information which will receive focuses
[in]	focus_mask	The focus mask to deliver

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_INVALID_STATE	Invalid state
SOUND_MANAGER_ERROR_POLICY	Noncompliance with the sound system policy
SOUND_MANAGER_ERROR_INTERNAL	Internal error inside the sound system

Precondition:: Call sound_manager_create_stream_information(), sound_manager_acquire_focus() and sound_manager_acquire_focus_all()
before calling this function.

See also:: sound_manager_create_stream_information(); sound_manager_acquire_focus(); sound_manager_acquire_focus_all()

int sound_manager_destroy_stream_information ( sound_stream_info_h stream_info )

Destroys the handle for stream information.

Since :: 3.0

Remarks:: Do not call this function within sound_stream_focus_state_changed_cb() or sound_stream_focus_state_watch_cb(),
otherwise SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned.

Parameters:

[in] stream_info The handle of stream information

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_INTERNAL	Internal error inside the sound system

See also:: sound_manager_create_stream_information(); sound_manager_add_device_for_stream_routing(); sound_manager_remove_device_for_stream_routing(); sound_manager_remove_all_devices_for_stream_routing(); sound_manager_apply_stream_routing(); sound_manager_acquire_focus(); sound_manager_release_focus(); sound_manager_get_focus_state()

int sound_manager_get_current_media_playback_device_type ( sound_device_type_e * device_type )

Gets the current device type for media playback stream.

Since :: 3.0

Parameters:

[out] device_type The output device type that a media playback stream can go out

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_DATA	No data

See also:: sound_manager_get_device_type(); sound_manager_get_device_io_direction(); sound_manager_get_device_id(); sound_manager_get_device_name()

int sound_manager_get_current_playback_focus	(	sound_stream_focus_change_reason_e *	acquired_by,
		int *	sound_behavior,
		char **	extra_info
	)

Gets the reason for the current acquired playback focus.

Since :: 3.0

Remarks:: If there is no acquired playback focus in this system, it'll return SOUND_MANAGER_ERROR_NO_DATA.
Do not call this function within sound_stream_focus_state_changed_cb() or sound_stream_focus_state_watch_cb(),
otherwise SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned.
The extra_info should be released using free().

Parameters:

[out]	acquired_by	The reason for the current acquired playback focus
[out]	sound_behavior	The requested sound behavior that should be followed, values of sound_behavior_e combined with bitwise 'or'
[out]	extra_info	The extra information of the acquired playback focus (optional, this can be NULL)

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_NO_DATA	No data

See also:: sound_manager_get_current_recording_focus()

int sound_manager_get_current_recording_focus	(	sound_stream_focus_change_reason_e *	acquired_by,
		int *	sound_behavior,
		char **	extra_info
	)

Gets the reason for the current acquired recording focus.

Since :: 3.0

Remarks:: If there is no acquired recording focus in this system, it'll return SOUND_MANAGER_ERROR_NO_DATA.
Do not call this function within sound_stream_focus_state_changed_cb() or sound_stream_focus_state_watch_cb(),
otherwise SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned.
The extra_info should be released using free().

Parameters:

[out]	acquired_by	The reason for the current acquired recording focus
[out]	sound_behavior	The requested sound behavior that should be followed, values of sound_behavior_e combined with bitwise 'or'
[out]	extra_info	The extra information of the acquired recording focus (optional, this can be NULL)

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_NO_DATA	No data

See also:: sound_manager_get_current_playback_focus()

int sound_manager_get_focus_reacquisition	(	sound_stream_info_h	stream_info,
		bool *	enabled
	)

Gets auto focus reacquisition property.

Since :: 3.0

Remarks:: The default value is true.

Parameters:

[in]	stream_info	The handle of stream information
[out]	enabled	The value of focus auto reacquisition property: (`true` = enabled, `false` = disabled)

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

Return values:

SOUND_MANAGER_ERROR_NONE	Success
SOUND_MANAGER_ERROR_INVALID_PARAMETER	Invalid parameter

Precondition:: Call sound_manager_create_stream_information() before calling this function.

See also:: sound_manager_create_stream_information()

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
	)

Gets the state of focus.

Since :: 3.0

Parameters:

[in]	stream_info	The handle of stream information
[out]	state_for_playback	The state of playback focus
[out]	state_for_recording	The state of recording focus

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

Return values:

SOUND_MANAGER_ERROR_NONE	Success
SOUND_MANAGER_ERROR_INVALID_PARAMETER	Invalid parameter

Precondition:: Call sound_manager_create_stream_information() before calling this function.

See also:: sound_manager_create_stream_information(); sound_manager_destroy_stream_information(); sound_manager_acquire_focus(); sound_manager_release_focus()

int sound_manager_get_sound_type	(	sound_stream_info_h	stream_info,
		sound_type_e *	sound_type
	)

Gets the sound type of the stream information.

Since :: 3.0

Remarks:: In case of a stream_info made with SOUND_STREAM_TYPE_EMERGENCY, it'll return SOUND_MANAGER_ERROR_NO_DATA.
The reason is that there is no sound_type_e matched with this stream_info.

Parameters:

[in]	stream_info	The handle of stream information
[out]	sound_type	The 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_DATA	No data

Precondition:: Call sound_manager_create_stream_information() before calling this function.

See also:: sound_manager_create_stream_information(); sound_manager_set_volume(); sound_manager_get_max_volume(); sound_manager_get_volume()

int sound_manager_get_stream_preferred_device	(	sound_stream_info_h	stream_info,
		int *	in_device_id,
		int *	out_device_id
	)

Gets the preferred device id of the stream info handle.

Since :: 5.5

Remarks:: This function is to return the preferred device id per each direction if it has been set. If there is no preferred device for a given direction, the corresponding output value will be set to SOUND_MANAGER_STREAM_NO_PREFERRED_DEVICE. You can get a device handle of the id value by using sound_manager_get_device_list(), sound_manager_get_next_device() and sound_manager_get_device_id().

Parameters:

[in]	stream_info	The handle of stream information
[out]	in_device_id	The preferred input device id
[out]	out_device_id	The preferred output device 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

See also:: sound_manager_set_stream_preferred_device(); sound_manager_get_device_list(); sound_manager_get_next_device(); sound_manager_get_device_id(); sound_manager_free_device_list()

int sound_manager_is_stream_on_device	(	sound_stream_info_h	stream_info,
		sound_device_h	device,
		bool *	is_on
	)

Checks if the stream information is using the device.

Since :: 3.0

Parameters:

[in]	stream_info	The handle of stream information
[in]	device	The device item
[out]	is_on	Whether the stream info is using the device or not: (`true` = use, `false` = not use)

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

See also:: sound_manager_get_device_list(); sound_manager_get_next_device(); sound_manager_get_prev_device(); sound_manager_get_device_type(); sound_manager_get_device_io_direction(); sound_manager_get_device_id(); sound_manager_get_device_name(); sound_manager_free_device_list()

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
	)

Releases the acquired stream focus.

Since :: 3.0

Remarks:: Do not call this function within sound_stream_focus_state_changed_cb() or sound_stream_focus_state_watch_cb(),
otherwise SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned. Since 4.0, it is allowed and does not return the error.

Parameters:

[in]	stream_info	The handle of stream information
[in]	focus_mask	The focus mask that user wants to release
[in]	sound_behavior	The requesting sound behavior, values of sound_behavior_e combined with bitwise 'or'
[in]	extra_info	The extra information for this request (optional, this can be NULL)

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_INVALID_STATE	Invalid state
SOUND_MANAGER_ERROR_INTERNAL	Internal error inside the sound system

Precondition:: Call sound_manager_create_stream_information() and sound_manager_acquire_focus() before calling this function.

See also:: sound_manager_create_stream_information(); sound_manager_destroy_stream_information(); sound_manager_acquire_focus(); sound_manager_acquire_focus_all(); sound_manager_release_focus_all(); sound_manager_get_focus_state()

int sound_manager_release_focus_all	(	sound_stream_info_h	stream_info,
		int	sound_behavior,
		const char *	extra_info
	)

Releases all the acquired stream focuses.

Since :: 4.0

Remarks:: This function does not return error even though one or all of focuses have already been released.

Parameters:

[in]	stream_info	The handle of stream information
[in]	sound_behavior	The requesting sound behavior, values of sound_behavior_e combined with bitwise 'or'
[in]	extra_info	The extra information for this request (optional, this can be NULL)

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

Precondition:: Call sound_manager_create_stream_information(), sound_manager_acquire_focus() and sound_manager_acquire_focus_all()
before calling this function.

See also:: sound_manager_create_stream_information(); sound_manager_destroy_stream_information(); sound_manager_acquire_focus(); sound_manager_acquire_focus_all(); sound_manager_release_focus(); sound_manager_get_focus_state()

int sound_manager_remove_all_devices_for_stream_routing ( sound_stream_info_h stream_info )

Removes all devices from the stream information for the stream routing.

Since :: 4.0

Parameters:

[in] stream_info The handle of stream information

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

Precondition:: Call sound_manager_create_stream_information() before calling this function.

See also:: sound_manager_create_stream_information(); sound_manager_destroy_stream_information(); sound_manager_add_device_for_stream_routing(); sound_manager_remove_device_for_stream_routing(); sound_manager_apply_stream_routing()

int sound_manager_remove_device_for_stream_routing	(	sound_stream_info_h	stream_info,
		sound_device_h	device
	)

Removes the device from the stream information for the stream routing.

Since :: 3.0

Remarks:: Use sound_manager_get_device_list() and sound_manager_get_next_device() to get the device.

Parameters:

[in]	stream_info	The handle of stream information
[in]	device	The device item from sound_device_list_h

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

Return values:

SOUND_MANAGER_ERROR_NONE	Success
SOUND_MANAGER_ERROR_INVALID_PARAMETER	Invalid parameter

Precondition:: Call sound_manager_create_stream_information() and sound_manager_add_device_for_stream_routing() before calling this function.

Postcondition:: You can apply this setting by calling sound_manager_apply_stream_routing().

See also:: sound_manager_create_stream_information(); sound_manager_destroy_stream_information(); sound_manager_add_device_for_stream_routing(); sound_manager_remove_all_devices_for_stream_routing(); sound_manager_apply_stream_routing()

int sound_manager_remove_focus_state_watch_cb ( int id )

Unregisters the focus state change watch callback.

Since :: 3.0

Remarks:: Do not call this function within sound_stream_focus_state_changed_cb() or sound_stream_focus_state_watch_cb(),
otherwise SOUND_MANAGER_ERROR_INVALID_OPERATION will be returned.

Parameters:

[in] id The focus state change watch 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_INVALID_OPERATION	Invalid operation
SOUND_MANAGER_ERROR_INTERNAL	Internal error inside the sound system

See also:: sound_manager_add_focus_state_watch_cb()

int sound_manager_set_focus_reacquisition	(	sound_stream_info_h	stream_info,
		bool	enable
	)

Sets auto focus reacquisition property.

Since :: 3.0

Remarks:: The focus reacquisition is set as default. 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.

Parameters:

[in]	stream_info	The handle of stream information
[in]	enable	The auto focus reacquisition property value to set: (`true` = enable, `false` = disable)

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

Return values:

SOUND_MANAGER_ERROR_NONE	Success
SOUND_MANAGER_ERROR_INVALID_PARAMETER	Invalid parameter

Precondition:: Call sound_manager_create_stream_information() before calling this function.

See also:: sound_manager_create_stream_information()

int sound_manager_set_stream_preferred_device	(	sound_stream_info_h	stream_info,
		sound_device_io_direction_e	io_direction,
		sound_device_h	device
	)

Sets the preferred built-in device for the stream routing.

Since :: 5.5

Remarks:: This function is to set a specific built-in device when the system has multiple devices of the same built-in device type. When there's only one device for a built-in device type in the system, nothing will happen even if this function succeeds in operation. If device is not supported by stream_info, SOUND_MANAGER_ERROR_POLICY will be returned. After this function is called, device is not needed for the function's work. It's okay to destroy it by destroying the list from which it was obtained.

Parameters:

[in]	stream_info	The handle of stream information
[in]	io_direction	The IO direction of the device
[in]	device	The preferred device (this can be NULL to unset)

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

Precondition:: Call sound_manager_create_stream_information() before calling this function.; Get a device by calling sound_manager_get_device_list() and sound_manager_get_next_device().

Postcondition:: You can get preferred devices by calling sound_manager_get_stream_preferred_device().; Call sound_manager_free_device_list() to free the devices.

See also:: sound_manager_get_stream_preferred_device(); sound_manager_create_stream_information(); sound_manager_destroy_stream_information(); sound_manager_get_device_list(); sound_manager_get_next_device(); sound_manager_free_device_list()

Required Header

Overview

Functions

Typedefs

Defines

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation