FreeSWITCH API Documentation  1.7.0
Data Structures | Macros | Typedefs | Enumerations | Functions
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


#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 SWITCH_EVENT_CHANNEL_GLOBAL   "__global__"


typedef struct
typedef struct
typedef void(* switch_live_array_command_handler_t )(switch_live_array_t *la, const char *cmd, const char *sessid, cJSON *jla, void *user_data)


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


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_tswitch_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)
cJSONswitch_live_array_get (switch_live_array_t *la, const char *name)
cJSONswitch_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.