Events

0. About

Events are generated by

• commands
• changes in status or configuration
• the core and modules of FreeSWITCH
• external applications

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

For a comprehensive list of events, see Event List.

1. Event structure

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 | common | Unique ID of FreeSWITCH instance, changes on every reboot [1]. | 11f751fa-47a7-11e2-9f24-bf76d9fc9ea3 | | 2 | Event-Calling-File | common | Source file that triggered this event. | mod_voicemail.c | | 3 | Event-Calling-Function | common | Source function that triggered this event. | sofia_reg_parse_auth | | 4 | Event-Calling-Line-Number | common | Source file line that triggered this event. | 710 | | 5 | Event-Date-GMT | common | Date/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 | common | Local date/time from FreeSWITCH instance at the point the event was triggered. | 2012-12-28 19:08:39 | | 7 | Event-Date-Timestamp | common | Unix epoch time from FreeSWITCH instance at the point the event was triggered. (in microseconds, divide by 1000 to get milliseconds). | 1356721719352143 | | 8 | Event-Name | common | Name of the event. See Classes section. | RE_SCHEDULE | | 9 | Event-Sequence | common | Sequential ID of event on the FreeSWITCH instance.This resets to zero after every reboot, and is not unique to each instance. [1] | 9274 | | 10 | FreeSWITCH-IPv4 | common | IPv4 address of FreeSWITCH instance. | 192.168.0.2 | | 11 | FreeSWITCH-IPv6 | common | IPv6 address of FreeSWITCH instance. | ::1 | | 12 | FreeSWITCH-Hostname | common | Host name of machine that FreeSWITCH instance is running on. | server123.example.comserver123 | | 13 | FreeSWITCH-Switchname | common | Switch 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. Event hierarchy

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

• most endpoint modules (see Creating a New Endpoint: Lifecycle of a Session), for example, when a user logs into Verto, or a SIP phone tries to register
• many dialplan applications, 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

• mod_sofia - Sofia-SIP module.
• mod_dingaling - Jabber/GoogleTalk Talk integration module.
• mod_portaudio - Host machine sound card.
• mod_conference - Conference module.
• mod_event_multicast
• mod_skinny - Skinny (aka SCCP) module.
• mod_callcenter - Call queuing application for call center needs.
• mod_spandsp - SpanDSP module including T.38 fax support.
• IVR Menu - Built IVR Engine events since FreeSWITCH 1.6

3. How to process events

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

For example, in case of using

• mod_erlang_event or mod_kazoo, the values are returned as Erlang terms.

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

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

• TODO What else?