Chapter 9. Controlling FreeSWITCH Externally

The FreeSWITCH Event System is one of the most exciting components of FreeSWITCH. You have already learned how FreeSWITCH operates when it utilizes various static configuration files and scripting languages. The event system allows for tremendous real-time dynamic behavior and control of FreeSWITCH. Utilizing the event system is when FreeSWITCH really comes alive.

The event system allows external software programs to act as listeners regarding activity happening on the system. This allows for real-time interaction with telephony operations on the telephony softswitch in conjunction with externally running software or hardware. Almost everything that happens within the FreeSWITCH system causes some sort of event message to be generated. These events can be watched by external entities. This is similar to the publish/subscribe (or "pub-sub") system used by common message queuing software solutions, although it is specifically tailored for FreeSWITCH...

General overview

The event system is the nerve center of FreeSWITCH, allowing both internal and external software to subscribe to a stream of activity happening inside the switching system. In FreeSWITCH, almost everything that happens generates (or "fires") an event. Receiving a new phone call results in an event. Ending a call results in an event. Committing a log entry to disk results in an event. Even speaking or going silent can generate an event. Each event becomes part of an event stream, tagged with an event type, event category, and various other details about the event. Other pieces of software can then listen for these events and act on them in any way they wish, such as streaming them to you via a TCP socket connection in plain text.

Events provide yet another way to extend functionality within FreeSWITCH. Events are different from hooks or modules (which can affect the actual processing and handling of calls in real-time). Events provide an asynchronous (or non-blocking/queued...

Event system architecture

The event subsystem in FreeSWITCH was designed to maximize throughput and prioritize events depending on their type and the system load. There are two layers within event system itself of the FreeSWITCH. The first layer provides internal event handling routines and an interface for absorbing (or "consuming") events within FreeSWITCH itself. The second layer is provided by the modular architecture and provides the client-facing access to those events. By keeping these two pieces of functionality separate, the availability of a publish/subscribe style event system becomes apparent.

Within the internal event layer, FreeSWITCH provides core functionality that handles events occurring both on a system-level and a channel-level. Events can be published or broadcasted by any part of the system, including modules. Two core types of events generally exist—system events and logging events. System events are generated by the core subsystem components or by modules. They include...

Event-based modules

There are three different modules for handling events. They are as follows:

1. mod_event_socket

2. mod_event_multicast

3. mod_erlang_event

mod_event_socket is by far the most used of the event handler modules, so we will be discussing it in detail. The other two modules are designed for more specific use cases and we will discuss them briefly.

mod_event_socket

mod_event_socket is the most common module in FreeSWITCH for sending and receiving events via third-party programs. This module provides a TCP socket which you can connect to from external software programs. Once authenticated, you can send and receive plain-text event information that is easy to understand and parse. It allows for bi-directional communication for both consuming events from and sending events to FreeSWITCH.

Utilizing event sockets is generally easy. First, you connect from an external program to a preconfigured socket which is configured for mod_event_socket. You authenticate to the system, then you begin...

FreeSWITCH event system commands

The following is a list of commands available for use from any event-based utility you use to connect to FreeSWITCH. You can use these commands from ESL (the FreeSWITCH Event Socket Library), via mod_event_socket and via any other standard interface that FreeSWITCH provides for accessing the event system. The syntax is the same from one access method to the next, although there may be variations in formatting and encoding, introduced by individual modules.

auth <password>

When you first connect to the FreeSWITCH event system via the mod_event_socket module, you must authenticate. This command allows you to pass your authentication parameters.

auth ClueCon

api

The api command allows any command to be sent, that would otherwise be accessible via the FreeSWITCH command-line interface. This executes the corresponding command in blocking mode, which means that the control will not return to the open event socket and no other commands will be allowed to execute...

Event-based applications


Several applications exist that take advantage of the Event Socket system. The most commonly used application is the fs_cli. We will also go over a demo PHP and Perl script to get you familiar with utilizing the event system.

FreeSWITCH Console application

Most people do not realize it, but if they have used the FreeSWITCH Console application (fs_cli), then they have already used the FreeSWITCH event socket subsystem. fs_cli is a C application that connects to the FreeSWITCH event socket provided by mod_event_socket, as previously discussed. It consumes all system events, colorizes them and provides an interface for sending commands back in the form of event messages. The entire FreeSWITCH console has been completely recreated by this application. (You can view the source code for fs_cli in libs/esl/fs_cli.c under the FreeSWITCH source directory.)

PHP Socket connections

The FreePBX v3 project introduced a class that allows for connecting to the FreeSWITCH event socket...

Event Socket Library

The FreeSWITCH Event Socket Library (ESL) is a set of standard APIs made available as loadable modules for various programming languages. Generally speaking, the APIs, when loaded into a programming language of your choice, provide native function calls for accessing FreeSWITCH event functionality—without the need to set up a TCP or network socket or otherwise concern yourself with how FreeSWITCH is reached.

Supported libraries

FreeSWITCH utilizes SWIG (www.swig.org) to create a standardized set of APIs. SWIG takes a defined list of variable and function calls and automatically creates libraries that link the core FreeSWITCH code to the programming language's native loadable module interfaces. The following languages are supported by default:

• Perl

• PHP

• LUA

• Python

• Ruby

• C

• TCL

• .NET

The following objects and methods apply to any language that can build ESL extensions. Once you have loaded the corresponding module for your particular programming language, you can utilize any of the standard...

Events in practice

Let's look at a few specific examples that demonstrate the use of events.

Event Socket Library example: running a command

The following PHP example shows how you can write a simple script to take one-line commands and, using the FreeSWITCH Event Socket Library, send those commands to FreeSWITCH, and wait for the response.

// Include FreeSWITCH ESL Library. Note that ESL.php comes
// with the FreeSWITCH PHP ESL module.
require_once('ESL.php');

if ($argc <= 1) {
printf("ERROR: You Need To Pass A Command\nUsage:\n\t%s <command>",
$argv[0]);
exit();
}

// Strip off the executable's name ($argv[0])
array_shift($argv);
$command = sprintf('%s', implode(' ', $argv));
printf("Command to run is: %s\n", $command);

// Connect to FreeSWITCH
$sock = new ESLconnection('localhost', '8021', 'ClueCon');

// Send the Command
$res = $sock->api($command);

// Print the response
printf("%s\n", $res->getBody());

Examples of sending events to FreeSWITCH

The following examples are...

Summary

Once you understand how rich the event system in FreeSWITCH is and have tried it out yourself, you begin to realize that there are literally thousands of things you can do with the FreeSWITCH application. Unlike previous topics on making phone calls or configuring modules, this is one piece of FreeSWITCH that truly lets you and your users interact with FreeSWITCH in real time, in any way you can possibly imagine. The eventing engine is powerful and robust, and its applications are limitless.