Event Management

The Events module is used as means for any modue to register events of interest and allow other modules to listen for those events, all events from a source or any event. More...


Typedefs
typedef struct EventSource_s *	EventSource_t
	Event Source handle.
typedef struct Event_s *	Event_t
	Event handle.
typedef char (	EventToString_t )(Event_t event, void *payload)
	Pointer to a function that converts an event and its payload into a human readable string.
typedef void(*	EventListener_t )(void arg, Event_t event, void payload)
	Callback function that is to be executed when an event is fired.
Functions
int	EventsInit (void)
int	EventsDeInit (void)
void	EventsRegisterListener (EventListener_t listener, void *arg)
	Register a listener to receive ALL events.
void	EventsUnregisterListener (EventListener_t listener, void *arg)
	Unregister a listener from receiving all events.
EventSource_t	EventsRegisterSource (char *name)
	Register a new event source.
void	EventsUnregisterSource (EventSource_t source)
	Removes a previously registered source and all the sources associated events and listeners.
EventSource_t	EventsFindSource (char *name)
	Find an event source with the given name.
void	EventsRegisterSourceListener (EventSource_t source, EventListener_t listener, void *arg)
	Register a listener for a specific source.
void	EventsUnregisterSourceListener (EventSource_t source, EventListener_t listener, void *arg)
	Unregister a listener from receiving events from a source.
Event_t	EventsRegisterEvent (EventSource_t source, char *name, EventToString_t toString)
	Register a new event with an event source.
void	EventsUnregisterEvent (Event_t event)
	Unregisters an event.
Event_t	EventsFindEvent (char *name)
	Given a name in the form <Source>.
void	EventsFireEventListeners (Event_t event, void *payload)
	Calls all listeners that have register to receive events in the following order Global listeners Source listeners Event Listeners.
void	EventsRegisterEventListener (Event_t event, EventListener_t listener, void *arg)
	Register a listener for a specific event.
void	EventsUnregisterEventListener (Event_t event, EventListener_t listener, void *arg)
	Unregister a listener from receiving an event.
char *	EventsEventToString (Event_t event, void *payload)
	This function converts the event into a human readable form by combining the name of the event, with the output of the event specifc toString function (if supplied when the event was created).

Detailed Description

The Events module is used as means for any modue to register events of interest and allow other modules to listen for those events, all events from a source or any event.

Events are located based on the following naming convention: <EventSource>.<EventName> The '.' is used as the delimiter and should not appear in event source names. The source and event names should follow the Pascal or UpperCamelCase naming convention.

The Events module itself exports the single event "Events.Unregistered", with the event being destroyed as the payload, to inform interested parties when an event is destroyed.

Events Exported

Events.Unregistered Sent when an event is being unregistered.

Events.Unregistered

This event is fired just before the event is removed from the source.

: payload = The event being unregistered.

Typedef Documentation

typedef struct Event_s* Event_t

Event handle.

An event is associated with an event source (EventSource_t).

typedef void(* EventListener_t)(void *arg, Event_t event, void *payload)

Callback function that is to be executed when an event is fired.

Parameters:

	arg	A user defined argument to pass to the function.
	event	The event being fired.
	payload	The details of the event.

typedef struct EventSource_s* EventSource_t

Event Source handle.

An event source has a number of events (Event_t instances) associated with it.

Function Documentation

int EventsDeInit ( void )

For internal use only.

Deinitialises the Events subsystem.

Returns:: 0 on success.

char* EventsEventToString	(	Event_t	event,
		void *	payload
	)

This function converts the event into a human readable form by combining the name of the event, with the output of the event specifc toString function (if supplied when the event was created).

Parameters:

	event	The event to convert.
	payload	The payload of the event.

Returns:: A string containing "\<SourceName\>.\<EventName\>" if no toString function was supplied when the event was created, or "\<SourceName\>.\<EventName\> \<toString output\>" if a toString function was supplied.

Event_t EventsFindEvent ( char * name )

Given a name in the form <Source>.

<Event> find the Event_t object and return it.

Parameters:

name

The fully qualified name of the event to find.

Returns:: An Event_t object or NULL if the event could not be found.

EventSource_t EventsFindSource ( char * name )

Find an event source with the given name.

Parameters:

name

The name of the event source to find.

Returns:: An EventSource_t or NULL if no source matched the supplied name.

void EventsFireEventListeners	(	Event_t	event,
		void *	payload
	)

Calls all listeners that have register to receive events in the following order

Global listeners
Source listeners
Event Listeners.

Note:: All callbacks are called on the calling thread!

Parameters:

	event	The event to fire.
	payload	The private information associated with the event.

int EventsInit ( void )

For internal use only.

Initialises the Events subsystem.

Returns:: 0 on success.

Event_t EventsRegisterEvent	(	EventSource_t	source,
		char *	name,
		EventToString_t	toString
	)

Register a new event with an event source.

The toString function is used for debugging purposes and to allow the event to be translated into useful information for external applications that may receive event information over TCP for example.

Parameters:

	source	The source the event is linked to.
	name	The name of the event.
	toString	A function to return a textual representation of the event.

void EventsRegisterEventListener	(	Event_t	event,
		EventListener_t	listener,
		void *	arg
	)

Register a listener for a specific event.

Parameters:

	event	The event to register with.
	listener	The callback function to register.
	arg	The user defined argument to pass to the callback when an event is fired.

void EventsRegisterListener	(	EventListener_t	listener,
		void *	arg
	)

Register a listener to receive ALL events.

Parameters:

	listener	The callback function to register.
	arg	The user defined argument to pass to the callback when an event is fired.

EventSource_t EventsRegisterSource ( char * name )

Register a new event source.

The name of the source must not contain

Parameters:

name

The name of the source.

Returns:: An EventSource_t instance or NULL if the registration failed.

void EventsRegisterSourceListener	(	EventSource_t	source,
		EventListener_t	listener,
		void *	arg
	)

Register a listener for a specific source.

Parameters:

	source	The source to register with.
	listener	The callback function to register.
	arg	The user defined argument to pass to the callback when an event is fired.

void EventsUnregisterEvent ( Event_t event )

Unregisters an event.

Parameters:

event

The event to unregister from its assocated source.

void EventsUnregisterEventListener	(	Event_t	event,
		EventListener_t	listener,
		void *	arg
	)

Unregister a listener from receiving an event.

Parameters:

	event	The event to unregister with.
	listener	The callback function to unregister.
	arg	The user defined argument to pass to the callback when an event is fired.

void EventsUnregisterListener	(	EventListener_t	listener,
		void *	arg
	)

Unregister a listener from receiving all events.

Parameters:

	listener	The callback function to unregister.
	arg	The user defined argument to pass to the callback when an event is fired.

void EventsUnregisterSource ( EventSource_t source )

Removes a previously registered source and all the sources associated events and listeners.

Parameters:

source

The source to unregister.

void EventsUnregisterSourceListener	(	EventSource_t	source,
		EventListener_t	listener,
		void *	arg
	)

Unregister a listener from receiving events from a source.

Parameters:

	source	The source to unregister with.
	listener	The callback function to unregister.
	arg	The user defined argument to pass to the callback when an event is fired.

Event Management

Typedefs

Functions

Detailed Description

Events Exported

Events.Unregistered

Typedef Documentation

Function Documentation