APIs
[Audio Manager]

Functions

alp_status_t alp_snd_callback_register (void *handle, void *data, AlpSndCallBack cb)

Register a callback function to process message from audio manager.

alp_status_t alp_snd_close (void *handle)

Close ALP sound handle object.

alp_status_t alp_snd_dev_get_present (char *name, uint8_t *status)

This funtion is used to check whether a sound device is present or not.

alp_status_t alp_snd_get_current_routepath (char *streamtype, char **routepath)

Get the current route path(device name) of the specified stream type.

alp_status_t alp_snd_get_silent_mode (bool *silent_mode)

Get mute status .

alp_status_t alp_snd_get_stream_status (char *stream_type, int *num_app, stream_status_t **arrary)

Get status of streams of type "stream_type".

alp_status_t alp_snd_get_stream_type_status (char *streamtype, bool *status)

Get active stream type status.

alp_status_t alp_snd_get_stream_volume (char *stream_type, int *volume)

Get stream type volume.

alp_status_t alp_snd_ioctl (void *handle, AlpSndCmd cmd, void *data)

I/O control function for both middleware components and application.

alp_status_t alp_snd_notify (AlpSndNotifyStru *notify, AlpSndNotifyType type, int num)

This function is used to send notification message to audio manager.

alp_status_t alp_snd_open (void **handle, char *srcid, AlpSndAppMode mode)

Opens an audio handle object for playback or recording.

alp_status_t alp_snd_play_tone (unsigned short amplitude, unsigned short duration, unsigned short freq)

This function is used to play tone.

alp_status_t alp_snd_read (void *handle, void *pbuf, int buflen, int *preadlen)

Read audio PCM data(from audio manager) into a buffer which is malloced from an open audio handle.

alp_status_t alp_snd_syssnd_async_fini (int id)

This function is used to do finish work for asynchronous play.

alp_status_t alp_snd_syssnd_async_init (const char *sound, int *id)

This function is used to do initial work for async play.

alp_status_t alp_snd_syssnd_async_play (int id, char *streamtype, int volume)

This function is used to asynchronous play system sound(uncompressed wav file).

alp_status_t alp_snd_syssnd_async_play_file (char *filename, char *streamtype, int volume)

This function is used to asychnronous play PCM(.wav) file.

alp_status_t alp_snd_syssnd_play (const char *sound, char *streamtype, int volume)

This function is used to play system sound(uncompressed wav file) file.

alp_status_t alp_snd_syssnd_play_file (char *filename, char *streamtype, int volume)

This function is used to play PCM(.wav) file.

alp_status_t alp_snd_write (void *handle, void *pbuf, int buflen)

Write audio PCM data to audio manager from the specified audio object.

Function Documentation

alp_status_t alp_snd_callback_register ( void * handle,

void * data,

AlpSndCallBack cb

)

Register a callback function to process message from audio manager.

Parameters:

[in] handle ALP sound handle object

[in] data Pointer to user self-defined data.

[in] cb Callback of your application to handle, which type is AlpSndCallBack.

Returns:
ALP_STATUS_SND_OK Function succeeds.
ALP_STATUS_SND_ERROR Function failed with unknown reason.
ALP_STATUS_SND_PARAM_ERROR Function failed because of parameter illegal.
ALP_STATUS_SND_CALLBACK_ERROR Create/Register callback failed.

alp_status_t alp_snd_close ( void * handle )

Close ALP sound handle object.

Parameters:

[in] handle ALP sound handle object

Returns:
ALP_STATUS_SND_OK If the function succeeds, the return value is ALP_STATUS_SND_OK.
ALP_STATUS_SND_ERROR If the function failed, the return value is ALP_STATUS_SND_ERROR.

Remarks:
Also see alp_snd_open(), alp_snd_write(), alp_snd_read().

alp_status_t alp_snd_dev_get_present ( char * name,

uint8_t * status

)

This funtion is used to check whether a sound device is present or not.

Parameters:

[in] name the device's name

[out] status the device's status

Returns:
ALP_STATUS_SND_OK Function succeeds.
ALP_STATUS_SND_ERROR Function failed.

alp_status_t alp_snd_get_current_routepath ( char * streamtype,

char ** routepath

)

Get the current route path(device name) of the specified stream type.

Parameters:

[in] streamtype Sound stream type. Detailed information refer to alp_snd_open()

[out] routepath Pointer to Router path string pointer.

Returns:
ALP_STATUS_SND_OK Function succeeds.
ALP_STATUS_SND_ERROR Function failed.

Remarks:
When function returns ALP_STATUS_SND_ERROR, comments of parameter '*routepath' has no meaning! When function returns ALP_SND_STATUS_OK, if comments of *routepath is '', No route path for the stream type, else route path(device name) will saved in parameter '*routepath' with comma-separated, such as 'speaker', 'speaker, headphone'. It can get more than one device name in the parameter 'routepath', the 3rd application need to decide the counts of route path(device name). If *routepath is not NULL, you should free the memory(For example, free(*routepath)).

alp_status_t alp_snd_get_silent_mode ( bool * silent_mode )

Get mute status .

Parameters:

[out] silent_mode Sound stream type volume.

Returns:
ALP_STATUS_SND_OK Function succeeds.
ALP_STATUS_SND_ERROR Function failed.

Remarks:
This function return the status:mute or not

alp_status_t alp_snd_get_stream_status ( char * stream_type,

int * num_app,

stream_status_t ** arrary

)

Get status of streams of type "stream_type".

Parameters:

[in] streamtype Sound stream type. Detailed information refer to alp_snd_open()

[out] num_app the number of states.

[out] arrary the pointer to the status array.

Returns:
ALP_STATUS_SND_OK Function succeeds.
ALP_STATUS_SND_ERROR Function failed.

Remarks:
This function return the status of stream;

alp_status_t alp_snd_get_stream_type_status ( char * streamtype,

bool * status

)

Get active stream type status.

Parameters:

[in] streamtype Sound stream type. Detailed information refer to alp_snd_open()

[out] status Sound stream type status.

Returns:
ALP_STATUS_SND_OK Function succeeds.
ALP_STATUS_SND_ERROR Function failed.

Remarks:
This function is used to decide whether there have a stream in running status which stream type is defined by parameter 'streamtype'. If *status is TRUE, there have stream in running status ,else there have no stream in running status with specific stream type.

alp_status_t alp_snd_get_stream_volume ( char * stream_type,

int * volume

)

Get stream type volume.

Parameters:

[in] streamtype Sound stream type. Detailed information refer to alp_snd_open()

[out] volume Sound stream type volume.

Returns:
ALP_STATUS_SND_OK Function succeeds.
ALP_STATUS_SND_ERROR Function failed.

Remarks:
This function get current volume of stream typed "stream_type", in case of temp_volume is increased or decreased,the currnet temp volume is returned

alp_status_t alp_snd_ioctl ( void * handle,

AlpSndCmd cmd,

void * data

)

I/O control function for both middleware components and application.

Parameters:

[in] handle ALP sound handle object

[in] cmd snd control command,please refer to AlpSndCmd.

[in] data parameters for cmd. For details, see AlpSndCmd.

Returns:
ALP_STATUS_SND_OK Function succeeds.
ALP_STATUS_SND_ERROR Function failed with unknown reason.
ALP_STATUS_SND_PARAM_ERROR Function failed because of parameter illegal.
ALP_STATUS_SND_SEND_MSG_ERROR Send msg failed.
ALP_STATUS_SND_SYSTEM_ERROR Create share memory/semaphore failed.
ALP_STATUS_SND_FORMAT_ERROR Set format failed.

Remarks:
For application, When an application want to play music, it should use alp_snd_open function to open an handle, and then after it use alp_snd_ioctl which cmd is ALP_SND_CTL_PLAY to send message to audio manager and audio manager processes this message, audio manager starts to send pcm data to device; when application want to pause playing, it should use alp_snd_ioctl to send pause message to telling audio manager(audio manager can not know when an application want to pause). For middleware, these steps are packaged and works automatically.
The volume control of alp_snd_ioctl is different from the one triggered by alp_snd_notify. The former only set one stream volume, while the latter will only be used to notify audio manager daemon when the volume level of each sound type was changed in volume pref panel or master volume level was changed in volume status gadget.

alp_status_t alp_snd_notify ( AlpSndNotifyStru * notify,

AlpSndNotifyType type,

int num

)

This function is used to send notification message to audio manager.

Parameters:

[in] notify pointer to AlpSndNotifyStru array. AlpSndNotifyStru has two members: keyid and val. When the type is volume, the keyid of voulme can be got from router.xml, the val is from to 100; When the type is condition, the keyid of conditions can be got from router.xml, the val is 0 or 1; When the type is device status, the keyid of device can be got from router.xml, the val is 0 or 1. The keyid and val must be paired and if the keyid is not correct, the alp_snd_notify() has no influence.

[in] type please refer to AlpSndNotifyType.

[in] num size of notify array.

Returns:
ALP_STATUS_SND_OK Function succeeds.
ALP_STATUS_SND_ERROR Function failed with unknown reason.
ALP_STATUS_SND_PARAM_ERROR Function failed because of parameter illegal.
ALP_STATUS_SND_CONNECT_ERROR Connect to audio manager failed.
ALP_STATUS_SND_NOTIFY_KEY_ERROR Notify key name is illegal.
ALP_STATUS_SND_SEND_MSG_ERROR Send msg failed.

Remarks:
This function is used for both 3rd developers (which does not need connect to audio manager firstly) and application(need communication to audio manager) to send notification message to audio manager. You can send multiple messages to audio manager in one call which type must be same, and in this situation the value of num is the size of messages.
Using alp_snd_notify, you only can send three type message to audio manager: ALP_SND_NOTIFY_VOLUME (volume), ALP_SND_NOTIFY_CONDITION(condition), ALP_SND_NOTIFY_DEVPRESENT (device-status). For example, when you press the key to add/reduce volume of handset, system(3rd application) can call alp_snd_notify(type is ALP_SND_NOTIFY_VOLUME) to send message to audio manager to add/reduce volume of handset; when the device of headphone is plugged and the system is detected this information, so system can call alp_snd_notify(type is ALP_SND_NOTIFY_DEVPRESENT) to telling audio manager and you maybe listen music from headphone.

alp_status_t alp_snd_open ( void ** handle,

char * srcid,

AlpSndAppMode mode

)

Opens an audio handle object for playback or recording.

Parameters:

[out] handle ALP sound handle object

[in] srcid sound stream type. All stream type is defined in a XML file named router.xml. You can not define stream type randomly, you can get the list of stream type from router.xml. Each kind of playback/record has corresponding stream type. For example, when playing music, the stream type is audio_out; when playing ringtone,stream type is phone_call. If stream type has not be set properly, the playback/record maybe not carry on normally.

[in] mode please refer to AlpSndAppMode

Returns:
ALP_STATUS_SND_OK Function succeeds.
ALP_STATUS_SND_ERROR Function failed with unknown reason.
ALP_STATUS_SND_PARAM_ERROR Function failed because of parameter illegal.
ALP_STATUS_SND_MALLOC_ERROR Function failed because of malloc failed.
ALP_STATUS_SND_CONNECT_ERROR Connect to audio manager failed.
ALP_STATUS_SND_STREAM_TYPE_ERROR Stream type is illegal or set stream type failed.

Remarks:
The purpose of this function is that it connects to audio manager and does some initial work. The functions alp_snd_open(), alp_snd_read(), alp_snd_write(), alp_snd_close() provide basic low-level APIs to send audio data to the audio manager or to record audio data from the audio manager. The audio object can be controlled using alp_snd_ioctl() function (e.g. play, stop, volume, etc.) .

alp_status_t alp_snd_play_tone ( unsigned short amplitude,

unsigned short duration,

unsigned short freq

)

This function is used to play tone.

Parameters:

[in] amplitude tone's amplitude in the range (0, 100].

[in] duration tone's duration[80, 2000] in milliseconds.

[in] freq tone's frequency[21, 19912] in Hertz.

Returns:
ALP_STATUS_SND_OK Function succeeds.
ALP_STATUS_SND_ERROR Function failed with unknown reason.
ALP_STATUS_SND_PARAM_ERROR Function failed because of parameter illegal.
ALP_STATUS_SND_CONNECT_ERROR Connect to audio manager failed.
ALP_STATUS_SND_SYSTEM_ERROR Create share memory/semaphore failed.

alp_status_t alp_snd_read ( void * handle,

void * pbuf,

int buflen,

int * preadlen

)

Read audio PCM data(from audio manager) into a buffer which is malloced from an open audio handle.

Parameters:

[in] handle ALP sound handle object

[in] pbuf buffer to store PCM data.

[in] buflen length of PCM data buffer.

[in] preadlen bytes have been read.

Returns:
ALP_STATUS_SND_OK Function succeeds.
ALP_STATUS_SND_ERROR Function failed with unknown reason.
ALP_STATUS_SND_PARAM_ERROR Function failed because of parameter illegal.
ALP_STATUS_SND_STATE_ERROR Write failed because of state is not AUDIO_RUNNING or format is not set correctly.
ALP_STATUS_SND_SYSTEM_ERROR Function failed because of access semaphore failed.

Remarks:
This function is used to record audio from input devices (e.g. microphone). Also see alp_snd_open(), alp_snd_write(), alp_snd_close().

alp_status_t alp_snd_syssnd_async_fini ( int id )

This function is used to do finish work for asynchronous play.

Parameters:

[in] id The identify of play, it is generated by initial function.

Returns:
ALP_STATUS_SND_OK Function succeeds.
ALP_STATUS_SND_ERROR Function failed .

alp_status_t alp_snd_syssnd_async_init ( const char * sound,

int * id

)

This function is used to do initial work for async play.

Parameters:

[in] sound Sound key name,for example: ALP_SND_KEY; or sound file name with absoulte path,for example : /usr/share/sounds/system/startup.wav.

in/out] id The unique identity for initial of sound.

Returns:
ALP_STATUS_SND_OK Function succeeds.
ALP_STATUS_SND_ERROR Function failed with unknown reason.
ALP_STATUS_SND_PARAM_ERROR Function failed because of parameter illegal.
ALP_STATUS_SND_NO_FILE_ERROR Parameter 'sound' is illegal or no find sound file.
ALP_STATUS_SND_OPEN_FILE_ERROR Open sound file failed.
ALP_STATUS_SND_FORMAT_ERROR File format is illegal or set format failed.
ALP_STATUS_SND_CONNECT_ERROR Connect to audio manager failed.
ALP_STATUS_SND_SYSTEM_ERROR Create share memory/semaphore failed.

Remarks:
This function is used to do initial work for play system sounds asynchronously. Not only sound key but also file name can be initialed. When you want to asynchronous play system sounds(such as call alp_snd_syssnd_async_play()), you should do initial first. After initial, you can play it randomly and when you want to close the asynchronous play you should fini it(call alp_snd_syssnd_async_fini() to do this). You can initial more than one asynchronous play, and the max num that you can initial is TWENTY; when the num of initial is greater than TWENTY, the former initial will be fini in order to save system resources.

alp_status_t alp_snd_syssnd_async_play ( int id,

char * streamtype,

int volume

)

This function is used to asynchronous play system sound(uncompressed wav file).

Parameters:

[in] id The identify of play, it is generated by initial function.

[in] streamtype Sound stream type. Detailed information referrered to alp_snd_open().

[in] volume Sound volume in the range (0, 100].

Returns:
ALP_STATUS_SND_OK Function succeeds.
ALP_STATUS_SND_ERROR Function failed with unknown reason.
ALP_STATUS_SND_PARAM_ERROR Function failed because of parameter illegal.

Remarks:
This function is used to asynchronous play system sounds that require low latency like UI feedback (keytone, button sounds, etc).And it only can play PCM data(uncompressed wav files). This function is used to play sounds asychnorous ly, it only allows one sound to ayshnronous play, that means the later play will stop the former play regardless of whether the former has finished. When there have more stream to play, you should set streamtype according to sound key. If streamtype is improperly, it maybe influence other audio stream output, Please take care. If the id does not initial, this function can not play that is to say when you play, the id must be initialed.

alp_status_t alp_snd_syssnd_async_play_file ( char * filename,

char * streamtype,

int volume

)

This function is used to asychnronous play PCM(.wav) file.

Parameters:

[in] filename wav file name.

[in] streamtype Sound stream type. Detailed information referrered to alp_snd_open().

[in] volume Sound volume in the range (0, 100].

Returns:
ALP_STATUS_SND_OK Function succeeds.
ALP_STATUS_SND_ERROR Function failed with unknown reason.
ALP_STATUS_SND_PARAM_ERROR Function failed because of parameter illegal.
ALP_STATUS_SND_NO_FILE_ERROR Parameter 'filename' is illegal or no find sound file.
ALP_STATUS_SND_OPEN_FILE_ERROR Open sound file failed.
ALP_STATUS_SND_FORMAT_ERROR File format is illegal or set format failed.
ALP_STATUS_SND_CONNECT_ERROR Connect to audio manager failed.
ALP_STATUS_SND_SYSTEM_ERROR Create share memory/semaphore failed.

Remarks:
This function is also used to asychnronous play system sounds, the ayschnronous strategy is same as alp_snd_syssnd_async_play()(the later play will stop the former play). When you use this function to asychnronous play, you do not need to do intial and finish work for play.

alp_status_t alp_snd_syssnd_play ( const char * sound,

char * streamtype,

int volume

)

This function is used to play system sound(uncompressed wav file) file.

Parameters:

[in] sound Sound type. For example: ALP_SND_KEY, ALP_SND_ATTENTION,....

[in] streamtype Sound stream type. Detailed information referrered to alp_snd_open().

[in] volume Sound volume in the range (0, 100].

Returns:
ALP_STATUS_SND_OK Function succeeds.
ALP_STATUS_SND_ERROR Function failed with unknown reason.
ALP_STATUS_SND_PARAM_ERROR Function failed because of parameter illegal.
ALP_STATUS_SND_NO_FILE_ERROR Parameter 'sound' is illegal or no find sound file.
ALP_STATUS_SND_OPEN_FILE_ERROR Open sound file failed.
ALP_STATUS_SND_FORMAT_ERROR File format is illegal or set format failed.
ALP_STATUS_SND_CONNECT_ERROR Connect to audio manager failed.
ALP_STATUS_SND_SYSTEM_ERROR Create share memory/semaphore failed.

Remarks:
This function is used to play sounds that require low latency like UI feedback (keytone, warning sounds, camera shutter/zoom sounds, etc).And it only can play PCM data(uncompressed wav files). The parameter 'sound' and 'streamtype' should be paired. For example, when 'sound' is ALP_SND_KEY, streamtype should be 'button_sounds'; when 'sound' is ALP_SND_ATTENTION, ALP_SND_SAVED, ALP_SND_DELETED or ALP_SND_ERROR, streamtype should be 'system_sounds'; when 'sound' is ALP_SND_CAMERA_SHUTTER, streamtype should be 'camera_sound'; when 'sound' is ALP_SND_CAMERA_ZOOM, streamtype should be 'zoom_sound', when 'sound' is ALP_SND_WARNING, streamtype should be 'alarm'. If streamtype is improperly, it maybe influence other audio stream output, Please take care. If sound is illegal, function can not get wav file.

alp_status_t alp_snd_syssnd_play_file ( char * filename,

char * streamtype,

int volume

)

This function is used to play PCM(.wav) file.

Parameters:

[in] filename wav file name.

[in] streamtype Sound stream type. Detailed information referrered to alp_snd_open().

[in] volume Sound volume in the range (0, 100].

Returns:
ALP_STATUS_SND_OK Function succeeds.
ALP_STATUS_SND_ERROR Function failed with unknown reason.
ALP_STATUS_SND_PARAM_ERROR Function failed because of parameter illegal.
ALP_STATUS_SND_NO_FILE_ERROR Parameter 'sound' is illegal or no find sound file.
ALP_STATUS_SND_OPEN_FILE_ERROR Open sound file failed.
ALP_STATUS_SND_FORMAT_ERROR File format is illegal or set format failed.
ALP_STATUS_SND_CONNECT_ERROR Connect to audio manager failed.
ALP_STATUS_SND_SYSTEM_ERROR Create share memory/semaphore failed.

alp_status_t alp_snd_write ( void * handle,

void * pbuf,

int buflen

)

Write audio PCM data to audio manager from the specified audio object.

Parameters:

[in] handle ALP sound handle object

[in] pbuf audio PCM data buffer.

[in] buflen length of PCM data buffer.

Returns:
ALP_STATUS_SND_OK Function succeeds.
ALP_STATUS_SND_ERROR Function failed with unknown reason.
ALP_STATUS_SND_PARAM_ERROR Function failed because of parameter illegal.
ALP_STATUS_SND_STATE_ERROR Write failed because of state is not AUDIO_RUNNING or format is not set correctly.
ALP_STATUS_SND_SYSTEM_ERROR Function failed because of access semaphore failed.

Remarks:
Also see alp_snd_open(), alp_snd_read(), alp_snd_close().

Generated on Wed Jul 30 07:06:41 2008 by Doxygen 1.4.6 for ALP SDK + Hiker Documentation


Functions
alp_status_t	alp_snd_callback_register (void handle, void data, AlpSndCallBack cb)
	Register a callback function to process message from audio manager.
alp_status_t	alp_snd_close (void *handle)
	Close ALP sound handle object.
alp_status_t	alp_snd_dev_get_present (char name, uint8_t status)
	This funtion is used to check whether a sound device is present or not.
alp_status_t	alp_snd_get_current_routepath (char streamtype, char *routepath)
	Get the current route path(device name) of the specified stream type.
alp_status_t	alp_snd_get_silent_mode (bool *silent_mode)
	Get mute status .
alp_status_t	alp_snd_get_stream_status (char stream_type, int num_app, stream_status_t **arrary)
	Get status of streams of type "stream_type".
alp_status_t	alp_snd_get_stream_type_status (char streamtype, bool status)
	Get active stream type status.
alp_status_t	alp_snd_get_stream_volume (char stream_type, int volume)
	Get stream type volume.
alp_status_t	alp_snd_ioctl (void handle, AlpSndCmd cmd, void data)
	I/O control function for both middleware components and application.
alp_status_t	alp_snd_notify (AlpSndNotifyStru *notify, AlpSndNotifyType type, int num)
	This function is used to send notification message to audio manager.
alp_status_t	alp_snd_open (void *handle, char srcid, AlpSndAppMode mode)
	Opens an audio handle object for playback or recording.
alp_status_t	alp_snd_play_tone (unsigned short amplitude, unsigned short duration, unsigned short freq)
	This function is used to play tone.
alp_status_t	alp_snd_read (void handle, void pbuf, int buflen, int *preadlen)
	Read audio PCM data(from audio manager) into a buffer which is malloced from an open audio handle.
alp_status_t	alp_snd_syssnd_async_fini (int id)
	This function is used to do finish work for asynchronous play.
alp_status_t	alp_snd_syssnd_async_init (const char sound, int id)
	This function is used to do initial work for async play.
alp_status_t	alp_snd_syssnd_async_play (int id, char *streamtype, int volume)
	This function is used to asynchronous play system sound(uncompressed wav file).
alp_status_t	alp_snd_syssnd_async_play_file (char filename, char streamtype, int volume)
	This function is used to asychnronous play PCM(.wav) file.
alp_status_t	alp_snd_syssnd_play (const char sound, char streamtype, int volume)
	This function is used to play system sound(uncompressed wav file) file.
alp_status_t	alp_snd_syssnd_play_file (char filename, char streamtype, int volume)
	This function is used to play PCM(.wav) file.
alp_status_t	alp_snd_write (void handle, void pbuf, int buflen)
	Write audio PCM data to audio manager from the specified audio object.

APIs [Audio Manager]

Functions

Function Documentation

APIs
[Audio Manager]