Events

Events are generated by

and the event system is responsible of controlling the distribution of events among (internal and external) subscribers.

For a comprehensive list of events, see Custom events.

An event message has two parts:

  • Header section
  • Body (optional)

1.1 Header section​

Headers are key/value pairs, and contain almost all of the information regarding an event. Most events only have a header section.

The Event headers page shows the list of available headers.

Some header values may contain multiple line breaks, but because FreeSWITCH URL-encodes all of them, these multi-line header values will still appear as 1 line.

Example of multi-line header values

# header BEFORE URL-encoding
variable_switch_r_sdp: v=0
o=UAC 6407 6867 IN IP4 192.168.27.72
s=SIP Media Capabilities
c=IN IP4 61.231.8.102
t=0 0
m=audio 12916 RTP/AVP 0 18 101
a=rtpmap:0 PCMU/8000
a=rtpmap:18 G729/8000
a=fmtp:18 annexb=no
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=maxptime:20

# header AFTER URL-encoding
variable_switch_r_sdp: v%3D0%0D%0Ao%3DUAC%206407%206867%20IN%20IP4%20192.168.27.72%0D%0As%3DSIP%20Media%20Capabilities%0D%0Ac%3DIN%20IP4%2061.231.8.102%0D%0At%3D0%200%0D%0Am%3Daudio%2012916%20RTP/AVP%200%2018%20101%0D%0Aa%3Drtpmap%3A0%20PCMU/8000%0D%0Aa%3Drtpmap%3A18%20G729/8000%0D%0Aa%3Dfmtp%3A18%20annexb%3Dno%0D%0Aa%3Drtpmap%3A101%20telephone-event/8000%0D%0Aa%3Dfmtp%3A101%200-15%0D%0Aa%3Dmaxptime%3A20%0D%0A

1.1.1 Common event headers​

Common headers

There is a minimum amount of information sent for every event (no matter what the type they are). See list below.

Headers common to all events:

TODO Would it be more prudent to call these «mandatory» fields?

Field/Header Type Description Example value
1 Core-UUID commonUnique ID of FreeSWITCH instance, changes on every reboot [1]. 11f751fa-47a7-11e2-9f24-bf76d9fc9ea3
2 Event-Calling-File commonSource file that triggered this event. mod_voicemail.c
3 Event-Calling-Function commonSource function that triggered this event. sofia_reg_parse_auth
4 Event-Calling-Line-NumbercommonSource file line that triggered this event. 710
5 Event-Date-GMT commonDate/time including timezone from FreeSWITCH instance at the point the event was triggered. Fri, 28 Dec 2012 19:08:39 GMT
6 Event-Date-Local commonLocal date/time from FreeSWITCH instance at the point the event was triggered. 2012-12-28 19:08:39
7 Event-Date-Timestamp commonUnix epoch time from FreeSWITCH instance at the point the event was triggered. (in microseconds, divide by 1000 to get milliseconds). 1356721719352143
8 Event-Name commonName of the event. See Classes section. RE_SCHEDULE
9 Event-Sequence commonSequential ID of event on the FreeSWITCH instance.This resets to zero after every reboot, and is not unique to each instance. 1]9274
10FreeSWITCH-IPv4 commonIPv4 address of FreeSWITCH instance. 192.168.0.2
11FreeSWITCH-IPv6 commonIPv6 address of FreeSWITCH instance. ::1
12FreeSWITCH-Hostname commonHost name of machine that FreeSWITCH instance is running on. server123.example.comserver123
13FreeSWITCH-Switchname commonSwitch name of FreeSWITCH instance. This is normally the same as FreeSWITCH-Hostname unless you have a complex configuration (for example, fail over, multi-homing etc). server123.example.comserver123

The example below is in the format of mod_event_socket's event plain command.

Example

Event-Name: RE_SCHEDULE
Core-UUID: 6d2375b0-5183-11e1-b24c-f527b57af954
FreeSWITCH-Hostname: freeswitch.local
FreeSWITCH-Switchname: freeswitch.local
FreeSWITCH-IPv4: 127.0.0.1
FreeSWITCH-IPv6: ::1
Event-Date-Local: 2012-02-07 19:36:31
Event-Date-GMT: Tue, 07 Feb 2012 18:36:31 GMT
Event-Date-Timestamp: 1328639791116026
Event-Calling-File: switch_scheduler.c
Event-Calling-Function: switch_scheduler_execute
Event-Calling-Line-Number: 65
Event-Sequence: 3349

1.2 Event body​

Events may have a body, carrying additional content generated with the event. It is usually not in the key/value form of headers, and may contain its own native formatting.

If the event does have a body, then

  • Content-Length header will be included in the header section, and
  • it will contain the size of the payload in bytes (analogous to the HTTP header of the same name).

Events with bodies include MESSAGE, MESSAGE_WAITING, DETECTED_SPEECH, BACKGROUND_JOB, and so on (see Event List). For parsing instructions, see How to parse events section.

The example below is in the format of mod_event_socket's event plain command.

TODO Update example because (1) not sure how old this example is (and thus whether it's still relevant), (2) does not contain all common fields, and (3) there are 3 line feeds before the event body, instead of 2 (is this valid?).

Example taken from «Event List» page

Speech-Type: detected-speech
Event-Name: DETECTED_SPEECH
Core-UUID: aac0f73e-b822-e54c-a02a-06a839ca3e5a
FreeSWITCH-Hostname: AMONROY
FreeSWITCH-IPv4: 192.168.1.220
FreeSWITCH-IPv6: ::1
Event-Date-Local: 2009-01-26 16:07:24
Event-Date-GMT: Mon, 26 Jan 2009 22:07:24 GMT
Event-Date-Timestamp: 1233007644906250
Event-Calling-File: switch_ivr_async.c
Event-Calling-Function: speech_thread
Event-Calling-Line-Number: 1758
Content-Length: 435


<result grammar="<request1@form-level.store>#nombres">
    <interpretation grammar="<request1@form-level.store>#nombres" confidence="0.494643">
        <instance confidence="0.494643">
            arturo monroy
        </instance>
        <input mode="speech" confidence="0.494643">
            <input confidence="0.313102">
                arturo
            </input>
            <input confidence="0.618854">
                monroy
            </input>
        </input>
    </interpretation>
</result>

2.1 Classes​

The below events (i.e., Event-Name header values) ar defined by the core of FreeSWITCH, and thus they are the main class of events.

See Event List for their descriptions with examples.

  • ADD_SCHEDULE
  • API
  • BACKGROUND_JOB
  • CALL_DETAIL
  • CALL_SECURE
  • CALL_SETUP_REQ
  • CALL_UPDATE
  • CDR
  • CHANNEL_ANSWER
  • CHANNEL_APPLICATION
  • CHANNEL_BRIDGE
  • CHANNEL_CALLSTATE
  • CHANNEL_CREATE
  • CHANNEL_DATA
  • CHANNEL_DESTROY
  • CHANNEL_EXECUTE
  • CHANNEL_EXECUTE_COMPLETE
  • CHANNEL_GLOBAL
  • CHANNEL_HANGUP
  • CHANNEL_HANGUP_COMPLETE
  • CHANNEL_HOLD
  • CHANNEL_ORIGINATE
  • CHANNEL_OUTGOING
  • CHANNEL_PARK
  • CHANNEL_PROGRESS
  • CHANNEL_PROGRESS_MEDIA
  • CHANNEL_STATE
  • CHANNEL_UNBRIDGE
  • CHANNEL_UNHOLD
  • CHANNEL_UNPARK
  • CHANNEL_UUID
  • CLONE
  • CODEC
  • COMMAND
  • CONFERENCE_DATA
  • CONFERENCE_DATA_QUERY
  • CUSTOM
  • DEL_SCHEDULE
  • DETECTED_SPEECH
  • DETECTED_TONE
  • DEVICE_STATE
  • DTMF
  • EXE_SCHEDULE
  • FAILURE
  • GENERAL
  • HEARTBEAT
  • LOG
  • MEDIA_BUG_START
  • MEDIA_BUG_STOP
  • MESSAGE
  • MESSAGE_QUERY
  • MESSAGE_WAITING
  • MODULE_LOAD
  • MODULE_UNLOAD
  • NAT
  • NOTALK
  • NOTIFY
  • NOTIFY_IN
  • PHONE_FEATURE
  • PHONE_FEATURE_SUBSCRIBE
  • PLAYBACK_START
  • PLAYBACK_STOP
  • PRESENCE_IN
  • PRESENCE_OUT
  • PRESENCE_PROBE
  • PRIVATE_COMMAND
  • PUBLISH
  • QUEUE_LEN
  • RECORD_START
  • RECORD_STOP
  • RECV_INFO
  • RECV_MESSAGE
  • RECV_RTCP_MESSAGE
  • RECYCLE
  • RELOADXML
  • REQUEST_PARAMS
  • RE_SCHEDULE
  • ROSTER
  • SEND_INFO
  • SEND_MESSAGE
  • SESSION_HEARTBEAT
  • SHUTDOWN
  • STARTUP
  • SUBCLASS_ANY
  • TALK
  • TRAP
  • UNPUBLISH

2.2 Subclasses (or CUSTOM events)​

A CUSTOM event (i.e., where the **Event-Name** header's value is CUSTOM) is a generic class to define events that is specific to a module, a feature, or to a service.

CUSTOM events are used with the Event-Subclass header denoting the event's role and meaning.

CUSTOM events are employed by

for example, when a user logs into Verto, or a SIP phone tries to register

such as the conference, voicemail, and call center applications, the fax management in mod_spandsp, and so on. The ivr application also generates CUSTOM events, and subclasses describe entering and exiting of menus (see «Events» section in mod_dptools: IVR Menu).

See List of CUSTOM Events for a complete list of subclasses.

Modules with CUSTOM events

The steps depend on what method is used to tap into the event system.

For example, in case of using

the values are returned as Erlang terms.

the event building blocks are parsed by the programming language used, and the ESLevent object has a getBody() method.

one has to parse TCP packets. (See parsing instructions there under 3.5 event.)

  • TODO What else?

Edit this page

Event-headers_32178341 Previous

Event headers

List-of-CUSTOM-Events_15139388 Next

List of CUSTOM Events

  • freeswitch/event_system/events.txt
  • Последние изменения: 2023/06/02