Tizen Native API  6.5

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

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_infoThe handle of stream information
[in]focus_maskThe changed focus mask
[in]focus_stateThe changed focus state
[in]reasonThe reason for state change of the focus
[in]sound_behaviorThe requested sound behavior that should be followed, values of sound_behavior_e combined with bitwise 'or'
[in]extra_infoThe extra information
[in]user_dataThe 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]idThe focus state change watch cb id
[in]focus_maskThe changed focus mask
[in]focus_stateThe changed focus state
[in]reasonThe reason for state change of the focus
[in]extra_infoThe extra information
[in]user_dataThe 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

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

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

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

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

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_infoThe handle of stream information
[in]focus_maskThe focus mask that user wants to acquire
[in]sound_behaviorThe requesting sound behavior, values of sound_behavior_e combined with bitwise 'or'
[in]extra_infoThe extra information for this request (optional, this can be NULL)
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_INVALID_STATEInvalid state
SOUND_MANAGER_ERROR_POLICYNoncompliance with the sound system policy
SOUND_MANAGER_ERROR_INTERNALInternal 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_infoThe handle of stream information
[in]sound_behaviorThe requesting sound behavior, values of sound_behavior_e combined with bitwise 'or'
[in]extra_infoThe extra information for this request (optional, this can be NULL)
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
SOUND_MANAGER_ERROR_INTERNALInternal 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()

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_infoThe handle of stream information
[in]deviceThe device item from sound_device_list_h
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
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_maskThe focus mask that user wants to watch
[in]callbackThe focus state change watch callback function
[in]user_dataThe user data to be passed to the callback function
[out]idThe focus state change watch callback id
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_INTERNALInternal error inside the sound system
See also:
sound_manager_remove_focus_state_watch_cb()

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_infoThe handle of stream information
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_STATEInvalid state
SOUND_MANAGER_ERROR_INTERNALInternal 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_typeThe type of stream
[in]callbackThe focus state change callback function (optional, this can be NULL)
[in]user_dataThe user data to be passed to the callback function (optional, this can be NULL)
[out]stream_infoThe handle of stream information
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_NOT_SUPPORTEDNot supported
SOUND_MANAGER_ERROR_INTERNALInternal 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()

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]sourceThe source handle of stream information which has focuses
[in]destinationThe destination handle of stream information which will receive focuses
[in]focus_maskThe focus mask to deliver
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_INVALID_STATEInvalid state
SOUND_MANAGER_ERROR_POLICYNoncompliance with the sound system policy
SOUND_MANAGER_ERROR_INTERNALInternal 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()

Gets the current device type for media playback stream.

Since :
3.0
Parameters:
[out]device_typeThe 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_NONESuccess
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
SOUND_MANAGER_ERROR_NO_DATANo 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_byThe reason for the current acquired playback focus
[out]sound_behaviorThe requested sound behavior that should be followed, values of sound_behavior_e combined with bitwise 'or'
[out]extra_infoThe 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_NONESuccess
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
SOUND_MANAGER_ERROR_INVALID_OPERATIONInvalid operation
SOUND_MANAGER_ERROR_NO_DATANo 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_byThe reason for the current acquired recording focus
[out]sound_behaviorThe requested sound behavior that should be followed, values of sound_behavior_e combined with bitwise 'or'
[out]extra_infoThe 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_NONESuccess
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
SOUND_MANAGER_ERROR_INVALID_OPERATIONInvalid operation
SOUND_MANAGER_ERROR_NO_DATANo 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_infoThe handle of stream information
[out]enabledThe value of focus auto reacquisition property: (true = enabled, false = disabled)
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_MANAGER_ERROR_NONESuccess
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid 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_infoThe handle of stream information
[out]state_for_playbackThe state of playback focus
[out]state_for_recordingThe state of recording focus
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_MANAGER_ERROR_NONESuccess
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid 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_infoThe handle of stream information
[out]sound_typeThe sound type
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_MANAGER_ERROR_NONESuccess
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
SOUND_MANAGER_ERROR_NO_DATANo 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_infoThe handle of stream information
[out]in_device_idThe preferred input device id
[out]out_device_idThe preferred output device id
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_MANAGER_ERROR_NONESuccess
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
SOUND_MANAGER_ERROR_INTERNALInternal 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_infoThe handle of stream information
[in]deviceThe device item
[out]is_onWhether 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_NONESuccess
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
SOUND_MANAGER_ERROR_INTERNALInternal 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_infoThe handle of stream information
[in]focus_maskThe focus mask that user wants to release
[in]sound_behaviorThe requesting sound behavior, values of sound_behavior_e combined with bitwise 'or'
[in]extra_infoThe extra information for this request (optional, this can be NULL)
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_INVALID_STATEInvalid state
SOUND_MANAGER_ERROR_INTERNALInternal 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_infoThe handle of stream information
[in]sound_behaviorThe requesting sound behavior, values of sound_behavior_e combined with bitwise 'or'
[in]extra_infoThe extra information for this request (optional, this can be NULL)
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
SOUND_MANAGER_ERROR_INTERNALInternal 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()

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

Since :
4.0
Parameters:
[in]stream_infoThe handle of stream information
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
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()

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_infoThe handle of stream information
[in]deviceThe device item from sound_device_list_h
Returns:
0 on success, otherwise a negative error value
Return values:
SOUND_MANAGER_ERROR_NONESuccess
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid 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()

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]idThe focus state change watch callback id
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_INTERNALInternal 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_infoThe handle of stream information
[in]enableThe 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_NONESuccess
SOUND_MANAGER_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
Call sound_manager_create_stream_information() before calling this function.
See also:
sound_manager_create_stream_information()

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_infoThe handle of stream information
[in]io_directionThe IO direction of the device
[in]deviceThe preferred device (this can be NULL to unset)
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
SOUND_MANAGER_ERROR_INTERNALInternal 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()