switch_event.h File Reference

---

Detailed Description

Event System.

The event system uses a backend thread and an APR threadsafe FIFO queue to accept event objects from various threads and allow the backend to take control and deliver the events to registered callbacks.

The typical usage would be to bind to one or all of the events and use a callback function to react in various ways (see the more_xmpp_event_handler or mod_event_test modules for examples).

Builtin events are fired by the core at various points in the execution of the application and custom events can be reserved and registered so events from an external module can be rendered and handled by an another even handler module.

If the work time to process an event in a callback is anticipated to grow beyond a very small amount of time it is reccommended that you impelment your own handler thread and FIFO queue so you can accept the events int the callback and queue them into your own thread rather than tie up the delivery agent. It is in to opinion of the author that such a necessity should be judged on a per-use basis and therefore does not fall within the scope of this system to provide that functionality at a core level.

Data Structures
struct	switch_event_header
	An event Header. More...
struct	switch_event_subclass
	A registered custom event subclass. More...
struct	switch_event
	Representation of an event. More...
struct	switch_event_node
	A node to store binded events. More...
Defines
#define	SWITCH_EVENT_SUBCLASS_ANY   NULL
#define	switch_event_get_header_nil(e, h)   switch_str_nil(switch_event_get_header(e,h))
#define	switch_event_create_pres_in(event)
#define	switch_event_reserve_subclass(subclass_name)   switch_event_reserve_subclass_detailed(__FILE__, subclass_name)
	Reserve a subclass assuming the owner string is the current filename.
#define	switch_event_create(event, id)   switch_event_create_subclass(event, id, SWITCH_EVENT_SUBCLASS_ANY)
	Create a new event assuming it will not be custom event and therefore hiding the unused parameters.
#define	switch_event_fire(event)   switch_event_fire_detailed(__FILE__, (char * )__SWITCH_FUNC__, __LINE__, event, NULL)
	Fire an event filling in most of the arguements with obvious values.
#define	switch_event_fire_data(event, data)   switch_event_fire_detailed(__FILE__, (char * )__SWITCH_FUNC__, __LINE__, event, data)
	Fire an event filling in most of the arguements with obvious values and allowing user_data to be sent.
Functions
switch_status_t	switch_event_init (switch_memory_pool_t *pool)
	Start the eventing system.
switch_status_t	switch_event_shutdown (void)
	Stop the eventing system.
switch_status_t	switch_event_create_subclass (switch_event_t **event, switch_event_types_t event_id, const char *subclass_name)
	Create an event.
switch_status_t	switch_event_set_priority (switch_event_t *event, switch_priority_t priority)
	Set the priority of an event.
_Ret_opt_z_ char *	switch_event_get_header (switch_event_t *event, char *header_name)
	Retrieve a header value from an event.
char *	switch_event_get_body (switch_event_t *event)
	Retrieve the body value from an event.
switch_status_t	switch_event_add_header (switch_event_t *event, switch_stack_t stack, const char *header_name, const char *fmt,...) PRINTF_FUNCTION(4
	Add a header to an event.
switch_status_t	switch_event_add_header_string (switch_event_t *event, switch_stack_t stack, const char *header_name, const char *data)
	Add a string header to an event.
switch_status_t	switch_event_del_header (switch_event_t *event, const char *header_name)
void	switch_event_destroy (switch_event_t **event)
	Destroy an event.
switch_status_t	switch_event_dup (switch_event_t **event, switch_event_t *todup)
	Duplicate an event.
switch_status_t	switch_event_fire_detailed (const char *file, const char *func, int line, switch_event_t **event, void *user_data)
	Fire an event with full arguement list.
switch_status_t	switch_event_bind (const char *id, switch_event_types_t event, const char *subclass_name, switch_event_callback_t callback, void *user_data)
	Bind an event callback to a specific event.
const char *	switch_event_name (switch_event_types_t event)
	Render the name of an event id enumeration.
switch_status_t	switch_name_event (const char *name, switch_event_types_t *type)
	return the event id that matches a given event name
switch_status_t	switch_event_reserve_subclass_detailed (const char *owner, const char *subclass_name)
	Reserve a subclass name for private use with a custom event.
switch_status_t	switch_event_serialize (switch_event_t *event, char **str, switch_bool_t encode)
	Render a string representation of an event sutable for printing or network transport.
switch_xml_t	switch_event_xmlize (switch_event_t *event, const char *fmt,...) PRINTF_FUNCTION(2
	Render a XML representation of an event sutable for printing or network transport.
switch_status_t	switch_event_running (void)
	Determine if the event system has been initilized.
switch_status_t	switch_event_add_body (switch_event_t *event, const char *fmt,...) PRINTF_FUNCTION(2
	Add a body to an event.
char *	switch_event_expand_headers (switch_event_t *event, const char *in)
switch_status_t	switch_event_create_pres_in_detailed (_In_z_ char *file, _In_z_ char *func, _In_ int line, _In_z_ const char *proto, _In_z_ const char *login, _In_z_ const char *from, _In_z_ const char *from_domain, _In_z_ const char *status, _In_z_ const char *event_type, _In_z_ const char *alt_event_type, _In_ int event_count, _In_z_ const char *unique_id, _In_z_ const char *channel_state, _In_z_ const char *answer_state, _In_z_ const char *call_direction)
void	switch_event_deliver (switch_event_t **event)
	Deliver an event to all of the registered event listeners.
char *	switch_event_build_param_string (switch_event_t *event, const char *prefix, switch_hash_t *vars_map)

---