switch_event.h File Reference

Event System. More...

#include <switch.h>

Include dependency graph for switch_event.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	switch_event_header
	An event Header. More...
struct	switch_event
	Representation of an event. More...
struct	switch_serial_event_s
struct	switch_serial_event_header_s

Macros
#define	SWITCH_EVENT_SUBCLASS_ANY   NULL
#define	switch_event_create_subclass(_e, _eid, _sn)   switch_event_create_subclass_detailed(__FILE__, (const char * )__SWITCH_FUNC__, __LINE__, _e, _eid, _sn)
#define	switch_event_get_header(_e, _h)   switch_event_get_header_idx(_e, _h, -1)
#define	switch_event_get_header_nil(e, h)   switch_str_nil(switch_event_get_header(e,h))
#define	switch_event_del_header(_e, _h)   switch_event_del_header_val(_e, _h, NULL)
#define	switch_event_safe_destroy(_event)   if (_event) switch_event_destroy(_event)
#define	switch_event_prep_for_delivery(_event)   switch_event_prep_for_delivery_detailed(__FILE__, (const char * )__SWITCH_FUNC__, __LINE__, _event)
#define	switch_event_expand_headers(_event, _in)   switch_event_expand_headers_check(_event, _in, NULL, NULL, 0)
#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. More...
#define	switch_event_free_subclass(subclass_name)   switch_event_free_subclass_detailed(__FILE__, subclass_name)
#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. More...
#define	switch_event_fire(event)   switch_event_fire_detailed(__FILE__, (const char * )__SWITCH_FUNC__, __LINE__, event, NULL)
	Fire an event filling in most of the arguements with obvious values. More...
#define	switch_event_fire_data(event, data)   switch_event_fire_detailed(__FILE__, (const 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. More...
#define	NO_EVENT_CHANNEL_ID   0
#define	SWITCH_EVENT_CHANNEL_GLOBAL   "__global__"

Typedefs
typedef struct switch_serial_event_s	switch_serial_event_t
typedef struct switch_serial_event_header_s	switch_serial_event_header_t
typedef void(*	switch_live_array_command_handler_t )(switch_live_array_t *la, const char *cmd, const char *sessid, cJSON *jla, void *user_data)

Enumerations
enum	switch_event_flag_t { EF_UNIQ_HEADERS = (1 << 0), EF_NO_CHAT_EXEC = (1 << 1), EF_DEFAULT_ALLOW = (1 << 2) }

Functions
switch_status_t	switch_event_init (switch_memory_pool_t *pool)
	Start the eventing system. More...
switch_status_t	switch_event_shutdown (void)
	Stop the eventing system. More...
switch_status_t	switch_event_create_subclass_detailed (const char *file, const char *func, int line, switch_event_t **event, switch_event_types_t event_id, const char *subclass_name)
	Create an event. More...
switch_status_t	switch_event_set_priority (switch_event_t *event, switch_priority_t priority)
	Set the priority of an event. More...
switch_event_header_t *	switch_event_get_header_ptr (switch_event_t *event, const char *header_name)
	Retrieve a header value from an event. More...
_Ret_opt_z_ char *	switch_event_get_header_idx (switch_event_t *event, const char *header_name, int idx)
switch_status_t	switch_event_rename_header (switch_event_t *event, const char *header_name, const char *new_header_name)
char *	switch_event_get_body (switch_event_t *event)
	Retrieve the body value from an event. More...
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. More...
switch_status_t switch_status_t	switch_event_set_subclass_name (switch_event_t *event, const char *subclass_name)
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. More...
switch_status_t	switch_event_del_header_val (switch_event_t *event, const char *header_name, const char *val)
int	switch_event_add_array (switch_event_t *event, const char *var, const char *val)
void	switch_event_destroy (switch_event_t **event)
	Destroy an event. More...
switch_status_t	switch_event_dup (switch_event_t **event, switch_event_t *todup)
	Duplicate an event. More...
void	switch_event_merge (switch_event_t *event, switch_event_t *tomerge)
switch_status_t	switch_event_dup_reply (switch_event_t **event, switch_event_t *todup)
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. More...
void	switch_event_prep_for_delivery_detailed (const char *file, const char *func, int line, switch_event_t *event)
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. More...
switch_status_t	switch_event_get_custom_events (switch_console_callback_match_t **matches)
switch_status_t	switch_event_bind_removable (const char *id, switch_event_types_t event, const char *subclass_name, switch_event_callback_t callback, void *user_data, switch_event_node_t **node)
	Bind an event callback to a specific event. More...
switch_status_t	switch_event_unbind (switch_event_node_t **node)
	Unbind a bound event consumer. More...
switch_status_t	switch_event_unbind_callback (switch_event_callback_t callback)
const char *	switch_event_name (switch_event_types_t event)
	Render the name of an event id enumeration. More...
switch_status_t	switch_name_event (const char *name, switch_event_types_t *type)
	return the event id that matches a given event name More...
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. More...
switch_status_t	switch_event_free_subclass_detailed (const char *owner, const char *subclass_name)
switch_status_t	switch_event_binary_deserialize (switch_event_t **eventp, void **data, switch_size_t len, switch_bool_t duplicate)
	Render a string representation of an event suitable for printing or network transport. More...
switch_status_t	switch_event_binary_serialize (switch_event_t *event, void **data, switch_size_t *len)
switch_status_t	switch_event_serialize (switch_event_t *event, char **str, switch_bool_t encode)
switch_status_t	switch_event_serialize_json (switch_event_t *event, char **str)
switch_status_t	switch_event_serialize_json_obj (switch_event_t *event, cJSON **json)
switch_status_t	switch_event_create_json (switch_event_t **event, const char *json)
switch_status_t	switch_event_create_brackets (char *data, char a, char b, char c, switch_event_t **event, char **new_data, switch_bool_t dup)
switch_status_t	switch_event_create_array_pair (switch_event_t **event, char **names, char **vals, int len)
switch_xml_t	switch_event_xmlize (switch_event_t *event, const char *fmt,...) PRINTF_FUNCTION(2
	Render a XML representation of an event suitable for printing or network transport. More...
switch_xml_t switch_status_t	switch_event_running (void)
	Determine if the event system has been initialized. More...
switch_status_t	switch_event_add_body (switch_event_t *event, const char *fmt,...) PRINTF_FUNCTION(2
	Add a body to an event. More...
switch_status_t switch_status_t	switch_event_set_body (switch_event_t *event, const char *body)
char *	switch_event_expand_headers_check (switch_event_t *event, const char *in, switch_event_t *var_list, switch_event_t *api_list, uint32_t recur)
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)
static switch_status_t	switch_event_create_plain (switch_event_t **event, switch_event_types_t event_id)
void	switch_event_deliver (switch_event_t **event)
	Deliver an event to all of the registered event listeners. More...
char *	switch_event_build_param_string (switch_event_t *event, const char *prefix, switch_hash_t *vars_map)
int	switch_event_check_permission_list (switch_event_t *list, const char *name)
void	switch_event_add_presence_data_cols (switch_channel_t *channel, switch_event_t *event, const char *prefix)
void	switch_json_add_presence_data_cols (switch_event_t *event, cJSON *json, const char *prefix)
void	switch_event_launch_dispatch_threads (uint32_t max)
switch_status_t	switch_event_channel_broadcast (const char *event_channel, cJSON **json, const char *key, switch_event_channel_id_t id)
uint32_t	switch_event_channel_unbind (const char *event_channel, switch_event_channel_func_t func)
switch_status_t	switch_event_channel_bind (const char *event_channel, switch_event_channel_func_t func, switch_event_channel_id_t *id)
switch_status_t	switch_live_array_clear (switch_live_array_t *la)
switch_status_t	switch_live_array_bootstrap (switch_live_array_t *la, const char *sessid, switch_event_channel_id_t channel_id)
switch_status_t	switch_live_array_destroy (switch_live_array_t **live_arrayP)
switch_status_t	switch_live_array_create (const char *event_channel, const char *name, switch_event_channel_id_t channel_id, switch_live_array_t **live_arrayP)
cJSON *	switch_live_array_get (switch_live_array_t *la, const char *name)
cJSON *	switch_live_array_get_idx (switch_live_array_t *la, int idx)
switch_status_t	switch_live_array_del (switch_live_array_t *la, const char *name)
switch_status_t	switch_live_array_add (switch_live_array_t *la, const char *name, int index, cJSON **obj, switch_bool_t destroy)
switch_status_t	switch_live_array_visible (switch_live_array_t *la, switch_bool_t visible, switch_bool_t force)
switch_bool_t	switch_live_array_isnew (switch_live_array_t *la)
void	switch_live_array_lock (switch_live_array_t *la)
void	switch_live_array_unlock (switch_live_array_t *la)
void	switch_live_array_set_user_data (switch_live_array_t *la, void *user_data)
void	switch_live_array_set_command_handler (switch_live_array_t *la, switch_live_array_command_handler_t command_handler)
void	switch_live_array_parse_json (cJSON *json, switch_event_channel_id_t channel_id)
switch_bool_t	switch_live_array_add_alias (switch_live_array_t *la, const char *event_channel, const char *name)
switch_bool_t	switch_live_array_clear_alias (switch_live_array_t *la, const char *event_channel, const char *name)
switch_bool_t	switch_event_channel_permission_verify (const char *cookie, const char *event_channel)
void	switch_event_channel_permission_modify (const char *cookie, const char *event_channel, switch_bool_t set)
void	switch_event_channel_permission_clear (const char *cookie)

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 recommended that you implement your own handler thread and FIFO queue so you can accept the events in the callback and queue them into your own thread rather than tie up the delivery agent. It is in the opinion of the author that such a necessity should be judged on a per-use basis and therefore it does not fall within the scope of this system to provide that functionality at a core level.

Definition in file switch_event.h.