FreeSWITCH Event System: Real-Time Call Notifications

/* From src/include/switch_event.h — event structure */
struct switch_event {
    switch_event_types_t    event_id;        /* the event type */
    switch_priority_t       priority;        /* event priority */
    char                   *owner;           /* who fired it */
    char                   *subclass_name;   /* subclass for CUSTOM events */
    switch_event_header_t  *headers;         /* linked list of key/value headers */
    switch_event_header_t  *last_header;     /* tail pointer for O(1) append */
    char                   *body;            /* optional free-form body */
    void                   *bind_user_data;  /* data from the subclass provider */
    void                   *event_user_data; /* data from the event sender */
    unsigned long           key;             /* unique key */
    struct switch_event    *next;
    int                     flags;
};

/* Each header is a name/value pair */
struct switch_event_header {
    char          *name;
    char          *value;
    char         **array;            /* array space for multi-value headers */
    int            idx;              /* array index */
    unsigned long  hash;
    struct switch_event_header *next;
};

Event-Name: CHANNEL_ANSWER
Core-UUID: e8e1b3c0-1a2b-4c3d-8e5f-6a7b8c9d0e1f
FreeSWITCH-Hostname: fs01.example.com
FreeSWITCH-Switchname: fs01
FreeSWITCH-IPv4: 192.168.1.10
FreeSWITCH-IPv6: ::1
Event-Date-Local: 2024-07-15 14:32:07
Event-Date-GMT: Mon, 15 Jul 2024 14:32:07 GMT
Event-Date-Timestamp: 1721054327093801
Event-Calling-File: switch_core_session.c
Event-Calling-Function: switch_core_session_run
Event-Calling-Line-Number: 835
Event-Sequence: 12345
Unique-ID: 3a8f1d2e-0c4b-4e7f-a19c-2b8d3e5f6a1c
Channel-State: CS_EXECUTE
Channel-Call-State: ACTIVE
Channel-State-Number: 4
Channel-Name: sofia/internal/1001@192.168.1.100
Caller-Direction: inbound
Caller-Logical-Direction: inbound
Caller-Username: 1001
Caller-Dialplan: XML
Caller-Caller-ID-Name: Alice
Caller-Caller-ID-Number: 1001
Caller-Orig-Caller-ID-Name: Alice
Caller-Orig-Caller-ID-Number: 1001
Caller-Callee-ID-Name: 
Caller-Callee-ID-Number: 1002
Caller-Destination-Number: 1002
Caller-Unique-ID: 3a8f1d2e-0c4b-4e7f-a19c-2b8d3e5f6a1c
Caller-Source: mod_sofia
Caller-Context: default
Caller-Channel-Name: sofia/internal/1001@192.168.1.100
Caller-Network-Addr: 192.168.1.100
Channel-Presence-ID: 1001@192.168.1.1
Answer-State: answered

switch_event_t *event;

/* Reserve the subclass name (done once at module load) */
switch_event_reserve_subclass("mymodule::my_event");

/* Fire the event */
if (switch_event_create_subclass(&event, SWITCH_EVENT_CUSTOM,
                                  "mymodule::my_event") == SWITCH_STATUS_SUCCESS) {
    switch_event_add_header_string(event, SWITCH_STACK_BOTTOM,
                                   "My-Header", "my-value");
    switch_event_add_body(event, "Optional body text");
    switch_event_fire(&event);
}

-- Fire a custom event from a Lua dialplan script
local event = freeswitch.Event("CUSTOM", "myapp::call_tagged")
event:addHeader("Tag-Name", "vip")
event:addHeader("Unique-ID", session:get_uuid())
event:fire()

sendevent CUSTOM
Event-Subclass: myapp::notify
My-Custom-Header: some-value

Optional body here

# Subscribe to all events (verbose — use with care in production)
events plain all

# Subscribe to a specific list of events
events plain CHANNEL_CREATE CHANNEL_ANSWER CHANNEL_HANGUP_COMPLETE DTMF BACKGROUND_JOB

# Subscribe to all events in JSON format
events json all

# Subscribe to a custom event subclass
events plain CUSTOM myapp::call_tagged

# Stop receiving a specific event type
nixevent CHANNEL_DATA

# Cancel all event subscriptions
noevents

/* Bind a C callback to CHANNEL_ANSWER events (from switch_event.h) */
SWITCH_DECLARE(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
);

/* Example callback signature */
static void my_event_handler(switch_event_t *event)
{
    const char *uuid = switch_event_get_header(event, "Unique-ID");
    switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_INFO,
                      "Call answered: %s\n", uuid);
}

/* Register it in SWITCH_MODULE_LOAD_FUNCTION */
switch_event_bind("mod_mymodule", SWITCH_EVENT_CHANNEL_ANSWER,
                  SWITCH_EVENT_SUBCLASS_ANY, my_event_handler, NULL);