Skip to main content
Header: inc/PalApi.h

Functions

pal_get_version

Get PAL version in the form of Major and Minor number seperated by period.
Returns the version string in the form of Major and Minor e.g ‘1.0’

pal_init

Initialize PAL. Increases ref count.
Returns 0 on success, error code on failure.

pal_deinit

De-Initialize PAL. Decreases the ref count.

pal_stream_open

Open the stream with specified configuration.
Parameters
struct pal_stream_attributes *
  • Valid stream attributes obtained from pal_stream_open
uint32_t
  • no of audio devices that the stream should be initially started with.
  • an array of pal_devices. The size of the array is based on the no_of_devices specified by the client. If pal_media_config in pal_device is specified as NULL, PAL uses the default device configuration or appropriate configuration based on the usecases running. Clients can query the device configuration by using pal_get_device().
uint32_t
  • no of modifiers.
struct modifier_kv *
  • an array of modifiers. Modifiers are used to add additional key-value pairs. e.g to identify the topology of usecase from default set.
pal_stream_callback
  • callback function associated with stream. Any event will notified through this callback function.
uint64_t
  • client data associated with the stream. This cookie will be returned back in the callback function.
pal_stream_handle_t **
  • Updated with valid stream handle if the operation is successful.
Returns 0 on success, error code otherwise

pal_stream_close

Close the stream.
Parameters
pal_stream_handle_t *
  • Valid stream handle obtained from pal_stream_open
Returns 0 on success, error code otherwise

pal_stream_start

Register for specific event on a given stream. Events will be notified via the callback function registered in pal_stream_open cmd.
Parameters
pal_stream_handle_t *
  • Valid stream handle obtained from pal_stream_open
  • Valid event id that the client would like notificaiton.
  • Event configuration data.
pal_stream_handle_t *
  • Valid stream handle obtained from pal_stream_open
Returns 0 on success, error code otherwise

pal_stream_stop

Stop the stream. Stream must be in started/paused state before stoping.
Parameters
pal_stream_handle_t *
  • Valid stream handle obtained from pal_stream_open
Returns 0 on success, error code otherwise

pal_stream_pause

Pause the stream. Stream must be in started state before resuming.
Parameters
pal_stream_handle_t *
  • Valid stream handle obtained from pal_stream_open
Returns 0 on success, error code otherwise

pal_stream_resume

Resume the stream. Stream must be in paused state before resuming.
Parameters
pal_stream_handle_t *
  • Valid stream handle obtained from pal_stream_open
Returns 0 on success, error code otherwise

pal_stream_flush

Flush accumlated data from the stream. Stream must be in paused state before flushing.
Parameters
pal_stream_handle_t *
  • Valid stream handle obtained from pal_stream_open
Returns 0 on success, error code otherwise

pal_stream_drain

Drain audio data buffered by the driver/hardware has been played depending on the drain type specified. If stream is opened with AUDIO_STREAM_FLAG_NON_BLOCKING and callback function is set in pal_open_stream(), drain complete notificaiton will be sent via the callback function otherwise will block until drain is completed. Drain will return immediately on stop() and flush() call.
Parameters
pal_stream_handle_t *
  • Valid stream handle obtained from pal_stream_open
pal_drain_type_t
  • drain type, DRAIN or DRAIN_PARTIAL.
Returns 0 on success, error code otherwise

pal_stream_suspend

Suspend graph and stop processing data from the stream. Stream must be in started state before suspending.
Parameters
pal_stream_handle_t *
  • Valid stream handle obtained from pal_stream_open
Returns 0 on success, error code otherwise

pal_stream_get_buffer_size

Get audio buffer size based on the direction of the stream.
Parameters
pal_stream_handle_t *
  • Valid stream handle obtained from pal_stream_open.
size_t *
  • filled if stream was opened with PAL_AUDIO_INPUT direction.
size_t *
  • filled if stream was opened with PAL_AUDIO_OUTPUT direction.
buffer and out_buffer - filled if stream was opened with PAL_AUDIO_OUTPUT|PAL_AUDIO_INPUT direction.
Returns
  • 0 on success, error code otherwise.

pal_stream_set_buffer_size

Set audio buffer size based on the direction of the stream. This overwrites the default buffer size configured for certain stream types.
Parameters
pal_stream_handle_t *
  • Valid stream handle obtained from pal_stream_open.
pal_buffer_config_t *
  • input buffers configuratoin when stream is opened with PAL_AUDIO_INPUT or PAL_AUDIO_INPUT_OUTPUT direction.
  • output buffers configuratoin when stream is opened with PAL_AUDIO_OUTPUT or PAL_AUDIO_INPUT_OUTPUT direction.
Returns
  • 0 on success, error code otherwise.

pal_stream_read

Read audio buffer captured from in the audio stream. an error code. Capture timestamps will be populated if session was opened with timetamp flag.
Parameters
pal_stream_handle_t *
  • Valid stream handle obtained from pal_stream_open
struct pal_buffer *
  • pointer to pal_buffer containing audio samples and metadata.
Returns
  • number of bytes read or error code on failure

pal_stream_write

Write audio buffer of a stream for rendering.If at least one frame was written successfully prior to the error, PAL will return number of bytes returned. Timestamp is honored if the stream was opened with timestamp flag otherwise it is ignored. If the stream was opened with non-blocking mode, the write() will operate in non-blocking mode. PAL will write only the number of bytes that currently fit in the driver/hardware buffer. If the callback function is set during pal_stream_open, the callback function will be called when more space is available in the driver/hardware buffer.
Parameters
pal_stream_handle_t *
  • Valid stream handle obtained from pal_stream_open
struct pal_buffer *
  • pointer to pal_buffer containing audio samples and metadata.
Returns number of bytes written or error code.

pal_stream_get_device

get current device on stream.
Parameters
pal_stream_handle_t *
  • Valid stream handle obtained from pal_stream_open
uint32_t
  • no of audio devices allocated for below pal_device array.
  • Pointer to an array of pal_device. The size of the array is sent via the above no_of_devices param.
Returns number of devices on success, error code otherwise.

pal_stream_set_device

set new device on stream. This api will disable the existing device and set the new device. If the new device is a combo device and includes previously set device, it will retain the old device to avoid setting the same device again unless device configuration chagnes.
Parameters
pal_stream_handle_t *
  • Valid stream handle obtained from pal_stream_open
uint32_t
  • no of audio devices that the stream should be initially started with.
  • an array of pal_device. The size of the array is based on the no_of_devices specified by the client.
Returns 0 on success, error code otherwise

pal_stream_get_param

Get audio parameters specific to a stream.
Parameters
pal_stream_handle_t *
  • Valid stream handle obtained from pal_stream_open
uint32_t
  • param id whose parameters are retrieved.
pal_param_payload **
  • param data applicable to the param_id
Returns 0 on success, error code otherwise

pal_stream_set_param

Set audio parameters specific to a stream.
Parameters
pal_stream_handle_t *
  • Valid stream handle obtained from pal_stream_open
uint32_t
  • param id whose parameters are to be set.
pal_param_payload *
  • param data applicable to the param_id
Returns 0 on success, error code otherwise

pal_stream_get_volume

Get audio volume specific to a stream.
Parameters
pal_stream_handle_t *
  • Valid stream handle obtained from pal_stream_open
struct pal_volume_data *
  • volume data to be set on a stream.
Returns 0 on success, error code otherwise

pal_stream_set_volume

Set audio volume specific to a stream.
Parameters
pal_stream_handle_t *
  • Valid stream handle obtained from pal_stream_open
struct pal_volume_data *
  • volume data to be retrieved from the stream.
Returns 0 on success, error code otherwise

pal_stream_get_mute

Get current audio audio mute state to a stream.
Parameters
pal_stream_handle_t *
  • Valid stream handle obtained from pal_stream_open
  • mute state to be retrieved from the stream.
Returns 0 on success, error code otherwise

pal_stream_set_mute

Set mute specific to a stream.
Parameters
  • Valid stream handle obtained from pal_stream_open
  • mute state to be set to the stream.
Returns 0 on success, error code otherwise

pal_get_mic_mute

Get microphone mute state.
Parameters
  • global mic mute flag to be retrieved.
Returns 0 on success, error code otherwise

pal_set_mic_mute

Set global mic mute state.
Parameters
  • global mic mute state
Returns 0 on success, error code otherwise

pal_get_timestamp

Get time stamp.
Parameters
pal_stream_handle_t *
  • Valid stream handle obtained from pal_stream_open
struct pal_session_time *
  • time stamp data to be retrieved from the stream.
Returns 0 on success, error code otherwise

pal_add_remove_effect

Add remove effects for Voip TX path.
Parameters
pal_stream_handle_t *
  • Valid stream handle obtained from pal_stream_open
pal_audio_effect_t
  • effect to be enabled or disable
bool
  • enable/disable
Returns 0 on success, error code otherwise

pal_set_param

Set pal parameters.
Parameters
uint32_t
  • param id whose parameters are to be set.
void *
  • param data applicable to the param_id
size_t
  • size of payload
Returns 0 on success, error code otherwise

pal_get_param

Get pal parameters.
Parameters
uint32_t
  • param id whose parameters are retrieved.
void **
  • param data applicable to the param_id
size_t *
  • size of payload
Returns 0 on success, error code otherwise

pal_stream_create_mmap_buffer

Set audio volume specific to a stream.
Parameters
pal_stream_handle_t *
  • Valid stream handle obtained from pal_stream_open
int32_t
  • minimum frame size required.
struct pal_mmap_buffer *
  • map buffer descriptor returned by stream.
Returns 0 on success, error code otherwise

pal_stream_get_mmap_position

Set audio volume specific to a stream.
Parameters
pal_stream_handle_t *
  • Valid stream handle obtained from pal_stream_open
struct pal_mmap_position *
  • Mmap buffer read/write position returned.
Returns 0 on success, error code otherwise

pal_register_global_callback

Register global callback to pal. This can be used to inform client about any information needed even before stream is created.
Parameters
pal_global_callback
  • Valid callback.
uint64_t
  • client data. This cookie will be returned back in the callback function.
Returns 0 on success, error code otherwise

pal_cshm_alloc

Request for shared memory allocation.
Parameters
uint32_t
  • Size of the shared memeory required
  • Info regarding the allocated shared memory
Returns 0 on success, error code otherwise

pal_cshm_dealloc

Request for deallocate the shared memory allocated via pal_cshm_alloc.
Parameters
  • mem_id of the shared memory block to be deallocated
Returns 0 on success, error code otherwise

pal_stream_set_custom_param

Stream set parameters for generic/custom param.
Parameters
pal_stream_handle_t *
  • stream handle to which the param is set/get.
char
  • param str that mention the type of setparam.
param_payload - param data applicable to the param_str
size_t
  • size of payload passed in
Returns 0 on success, error code otherwise

pal_stream_get_custom_param

Stream set parameters for generic/custom param.
Parameters
pal_stream_handle_t *
  • stream handle to which the param is set/get.
char
  • param str that mention the type of getparam.
param_payload - param data applicable to the param_str
payload_size - as input max size of the allocated/memory passed by the client. If it is not enough to copy the get_param payload - a error is returned with the size set to the expected size of the memory to be passed. If the memory is more/enough - api will return actual size copied for the response as a ouput.
Returns 0 on success, error code otherwise

pal_set_custom_param

Stream get parameters for generic/custom param.
Parameters
char
  • param str that mention the type of getparam.
param_payload - param data applicable to the param_str
size_t
  • size of the payload passed by the client.
Returns 0 on success, error code otherwise

pal_register_for_events

registers a callback function to get notification for audio events.
Parameters
pal_audio_event_callback
  • Callback function to be called
Returns 0 on success, error code otherwise

pal_get_custom_param

Get pal parameters for generic/custom param.
Parameters
custom_payload_uc_info_t *
  • info of the usecase to which custom/param need to get/set.
char
  • param str that mention the type of getparam.
param_payload - param data applicable to the param_str
payload_size - as input max size of the allocated/memory passed by the client. If it is not enough to copy the get_param payload - a error is returned with the size set to the expected size of the memory to be passed. If the memory is more/enough - api will return actual size copied for the response as a ouput.
Returns 0 on success, error code otherwise