Event Framework

---

Overview

For an introduction to the event framework used in the SDK please refer to the "SDK Users Guide".

Events are generated when accessing any SDK component in CALLBACK or SELECT access modes. It is also generated in one instance in DIRECT access mode - as a return from the esp_subscriber_get_next_event() function.

In CALLBACK access mode registered handlers get passed an EspEvent object which will be of the correct category. Users need to determine the type of the event and take action accordingly. In SELECT access mode events are returned from esp_selector_select() call. The list of returned events can be from multiple entities so users must determine the category of the events before processing them. The life cycle of these event objects are managed by the SDK.

NOTE: In the one case where an event is returned in DIRECT access mode, EspSubscriberEvent from esp_subscriber_get_next_event() users will need to free the resources held by that event using esp_subscriber_event_free().

Entities/Objects
typedef struct EspDispatcher	EspDispatcher
typedef struct EspUpdater	EspUpdater
typedef struct EspSelector	EspSelector

---

Enumeration Types

enum ESP_EVENT_CATEGORY_T

Event category - denotes the type of the entity that generated the event.

Enumerator:

ESP_EVENT_UNKNOWN	Unknown event - usually an error indication
ESP_EVENT_SERVER	Event relating to EspServer
ESP_EVENT_PROJECT	Event relating to EspProject
ESP_EVENT_PUBLISHER	Event retating to EspPublisher
ESP_EVENT_SUBSCRIBER	Event relating to EspSubscriber

Functions
ESPAPICALL EspDispatcher *	esp_dispatcher_create (const char *name, EspError *error)
ESPAPICALL EspDispatcher *	esp_dispatcher_get_default (EspError *error)
ESPAPICALL int32_t	esp_dispatcher_start (EspDispatcher *dispatcher, EspError *error)
ESPAPICALL int32_t	esp_dispatcher_dispatch (EspDispatcher *dispatcher, EspError *error)
ESPAPICALL int32_t	esp_dispatcher_stop (EspDispatcher *dispatcher, EspError *error)
ESPAPICALL int32_t	esp_dispatcher_free (EspDispatcher *dispatcher, EspError *error)
ESPAPICALL EspSelector *	esp_selector_create (const char *name, EspError *error)
ESPAPICALL int32_t	esp_selector_select (const EspSelector *selector, EspList *list, EspError *error)
ESPAPICALL int32_t	esp_selector_free (EspSelector *selector, EspError *error)

---

Function Documentation

ESPAPICALL EspDispatcher * esp_dispatcher_create	(	const char *	name,
		EspError *	error
	)

Creates a custom dispatcher.

Parameters:

name	specifies a name to assign the dispatcher for logging purposes.

Not implemented in R5.

Creates and returns a EspDispatcher object. This can be used to replace the default dispatcher for an entity.

Parameters:

name	name to assign the dispatcher for logging purposes

ESPAPICALL int32_t esp_dispatcher_dispatch	(	EspDispatcher *	dispatcher,
		EspError *	error
	)

Dispatches any queued events for all entities registered with this dispatcher. Returns when all pending events have been dispatched.

Not in R5. Dispatches any queued events for all entities registered with this dispatcher. Returns when all pending events have been dispatched.

Returns:

0 on success.

ESPAPICALL int32_t esp_dispatcher_free	(	EspDispatcher *	dispatcher,
		EspError *	error
	)

Deletes the dispatcher retrieved using esp_dispatcher_create().

Frees the dispatcher retrieved using the esp_dispatcher_create() function.

Returns:

0 on success.

ESPAPICALL EspDispatcher * esp_dispatcher_get_default

(

EspError *

error

)

Retrieves the SDK default dispatcher. This should never be freed by the user.

ESPAPICALL int32_t esp_dispatcher_start	(	EspDispatcher *	dispatcher,
		EspError *	error
	)

Starts an internal thread in the dispatcher.

Not in R5. Starts an internal thread in the dispatcher.

Returns:

0 on success.

ESPAPICALL int32_t esp_dispatcher_stop	(	EspDispatcher *	dispatcher,
		EspError *	error
	)

Stops the running internal thread in the dispatcher.

Stops the internal thread in the dispatcher.

Returns:

0 on success.

ESPAPICALL EspSelector* esp_selector_create	(	const char *	name,
		EspError *	error
	)

Not in R5. Creates and returns an EspSelector object.

ESPAPICALL int32_t esp_selector_free	(	EspSelector *	selector,
		EspError *	error
	)

Not in R5. Frees an EspSelector object and releases resources held by it.

Returns:

0 on success.

ESPAPICALL int32_t esp_selector_select	(	const EspSelector *	selector,
		EspList *	list,
		EspError *	error
	)

This call will block until there is an event in one of the entities registered with this EspSelector.

Returns:

0 on success.

Parameters:

selector	EspSelector to monitor
list	EspList to return the events in