Event Interface

The ADF provides the Event Interface API to establish communication between Audio Elements in a pipeline. The API is built around FreeRTOS queue. It implements ‘listeners’ to watch for incoming messages and inform about them with a callback function.

Application Examples

Implementation of this API is demonstrated in couple of examples including get-started/play_mp3_control.

API Reference

Header File

Functions

audio_event_iface_handle_t audio_event_iface_init(audio_event_iface_cfg_t *config)

Initialize audio event.

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • config: The configurations

esp_err_t audio_event_iface_destroy(audio_event_iface_handle_t evt)

Cleanup event, it doesn’t free evt pointer.

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • evt: The event

esp_err_t audio_event_iface_set_listener(audio_event_iface_handle_t evt, audio_event_iface_handle_t listener)

Add audio event evt to the listener, then we can listen evt event from listen

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • listener: The event can listen another event

  • evt: The event to be added to

esp_err_t audio_event_iface_remove_listener(audio_event_iface_handle_t listener, audio_event_iface_handle_t evt)

Remove audio event evt from the listener.

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • listener: The event listener

  • evt: The event to be removed from

esp_err_t audio_event_iface_set_cmd_waiting_timeout(audio_event_iface_handle_t evt, TickType_t wait_time)

Set current queue wait time for the event.

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • evt: The event

  • [in] wait_time: The wait time

esp_err_t audio_event_iface_waiting_cmd_msg(audio_event_iface_handle_t evt)

Waiting internal queue message.

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • evt: The event

esp_err_t audio_event_iface_cmd(audio_event_iface_handle_t evt, audio_event_iface_msg_t *msg)

Trigger an event for internal queue with a message.

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • evt: The event

  • msg: The message

esp_err_t audio_event_iface_cmd_from_isr(audio_event_iface_handle_t evt, audio_event_iface_msg_t *msg)

It’s same with audio_event_iface_cmd, but can send a message from ISR.

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • [in] evt: The event

  • msg: The message

esp_err_t audio_event_iface_sendout(audio_event_iface_handle_t evt, audio_event_iface_msg_t *msg)

Trigger and event out with a message.

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • evt: The event

  • msg: The message

esp_err_t audio_event_iface_discard(audio_event_iface_handle_t evt)

Discard all ongoing event message.

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • evt: The event

esp_err_t audio_event_iface_listen(audio_event_iface_handle_t evt, audio_event_iface_msg_t *msg, TickType_t wait_time)

Listening and invoke callback function if there are any event are comming.

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • evt: The event

  • msg: The message

  • wait_time: The wait time

QueueHandle_t audio_event_iface_get_queue_handle(audio_event_iface_handle_t evt)

Get External queue handle of Emmitter.

Return

External QueueHandle_t

Parameters

  • [in] evt: The external queue

esp_err_t audio_event_iface_read(audio_event_iface_handle_t evt, audio_event_iface_msg_t *msg, TickType_t wait_time)

Read the event from all the registered event emitters in the queue set of the interface.

Return

  • ESP_OK On successful receiving of event

  • ESP_FAIL In case of a timeout or invalid parameter passed

Parameters

  • [in] evt: The event interface

  • [out] msg: The pointer to structure in which event is to be received

  • [in] wait_time: Timeout for receiving event

QueueHandle_t audio_event_iface_get_msg_queue_handle(audio_event_iface_handle_t evt)

Get Internal queue handle of Emmitter.

Return

Internal QueueHandle_t

Parameters

  • [in] evt: The Internal queue

esp_err_t audio_event_iface_set_msg_listener(audio_event_iface_handle_t evt, audio_event_iface_handle_t listener)

Add audio internal event evt to the listener, then we can listen evt event from listen

Return

  • ESP_OK

  • ESP_FAIL

Parameters

  • listener: The event can listen another event

  • evt: The event to be added to

Structures

struct audio_event_iface_msg_t

Event message

Public Members

int cmd

Command id

void *data

Data pointer

int data_len

Data length

void *source

Source event

int source_type

Source type (To know where it came from)

bool need_free_data

Need to free data pointer after the event has been processed

struct audio_event_iface_cfg_t

Event interface configurations

Public Members

int internal_queue_size

It’s optional, Queue size for event internal_queue

int external_queue_size

It’s optional, Queue size for event external_queue

int queue_set_size

It’s optional, QueueSet size for event queue_set

on_event_iface_func on_cmd

Function callback for listener when any event arrived

void *context

Context will pass to callback function

TickType_t wait_time

Timeout to check for event queue

int type

it will pass to audio_event_iface_msg_t source_type (To know where it came from)

Macros

DEFAULT_AUDIO_EVENT_IFACE_SIZE
AUDIO_EVENT_IFACE_DEFAULT_CFG()

Type Definitions

typedef esp_err_t (*on_event_iface_func)(audio_event_iface_msg_t *, void *)
typedef struct audio_event_iface *audio_event_iface_handle_t

Provide feedback about this document