freeswitch_scripting Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. OpenSIPS Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. db_url (string)
              1.3.2. db_table (string)
              1.3.3. db_col_username (string)
              1.3.4. db_col_password (string)
              1.3.5. db_col_ip (string)
              1.3.6. db_col_port (string)
              1.3.7. db_col_events (string)
              1.3.8. fs_subscribe (string)

        1.4. Exported Functions

              1.4.1. freeswitch_esl(command, freeswitch_url[,
                      response_var])

        1.5. Exported MI Commands

              1.5.1. fs_subscribe
              1.5.2. fs_unsubscribe
              1.5.3. fs_list
              1.5.4. fs_reload

        1.6. Exported Events

              1.6.1. E_FREESWITCH

   2. Contributors

        2.1. By Commit Statistics
        2.2. By Commit Activity

   3. Documentation

        3.1. Contributors

   List of Tables

   2.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   2.2. Most recently active contributors^(1) to this module

   List of Examples

   1.1. Setting the db_url parameter
   1.2. Setting the db_table parameter
   1.3. Setting the db_col_username parameter
   1.4. Setting the db_col_password parameter
   1.5. Setting the db_col_ip parameter
   1.6. Setting the db_col_port parameter
   1.7. Setting the db_col_events parameter
   1.8. Setting the fs_subscribe parameter
   1.9. freeswitch_esl() usage

Chapter 1. Admin Guide

1.1. Overview

   freeswitch_scripting is a helper module that exposes full
   control over the FreeSWITCH ESL interface to the OpenSIPS
   script.

   It allows the OpenSIPS script writer to subscribe to generic
   FreeSWITCH ESL events as well as to run arbitrary FreeSWITCH
   ESL commands and interpret their results. It makes use of the
   freeswitch module for the management of ESL connections and
   event subscriptions.

   Credits for the initial idea and working code samples providing
   both ESL events and commands go to Giovanni Maruzzelli
   <gmaruzz@opentelecom.it>.

1.2. Dependencies

1.2.1. OpenSIPS Modules

   The following modules must be loaded together with this module:
     * freeswitch
     * (optional) an SQL DB module

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSIPS with this module loaded:
     * None

1.3. Exported Parameters

1.3.1. db_url (string)

   An SQL database URL which the module will use in order to load
   a set of FreeSWITCH ESL sockets and their event subscriptions.

   Default value is “NULL” (DB support disabled).

   Example 1.1. Setting the db_url parameter
...
modparam("freeswitch_scripting", "db_url", "dbdriver://username:password
@dbhost/dbname")
...

1.3.2. db_table (string)

   The SQL table name for this module.

   Default value is “freeswitch”.

   Example 1.2. Setting the db_table parameter
...
modparam("freeswitch_scripting", "db_table", "freeswitch_sockets")
...

1.3.3. db_col_username (string)

   The SQL column name for the "username" ESL connect information.

   Default value is “username”.

   Example 1.3. Setting the db_col_username parameter
...
modparam("freeswitch_scripting", "db_col_username", "user")
...

1.3.4. db_col_password (string)

   The SQL column name for the "password" ESL connect information.

   Default value is “password”.

   Example 1.4. Setting the db_col_password parameter
...
modparam("freeswitch_scripting", "db_col_password", "pass")
...

1.3.5. db_col_ip (string)

   The SQL column name for the "ip" ESL connect information.

   Default value is “ip”.

   Example 1.5. Setting the db_col_ip parameter
...
modparam("freeswitch_scripting", "db_col_ip", "ip_addr")
...

1.3.6. db_col_port (string)

   The SQL column name for the "port" ESL connect information.

   Default value is “port”.

   Example 1.6. Setting the db_col_port parameter
...
modparam("freeswitch_scripting", "db_col_port", "tcp_port")
...

1.3.7. db_col_events (string)

   The SQL column name for the comma-separated, case-sensitive
   FreeSWITCH event names which OpenSIPS will subscribe to.

   Default value is “events_csv”.

   Example 1.7. Setting the db_col_events parameter
...
modparam("freeswitch_scripting", "db_col_events", "fs_events")
...

1.3.8. fs_subscribe (string)

   Add a FreeSWITCH ESL URL to which OpenSIPS will connect at
   startup. The URL syntax includes support for specifying a list
   of events to subscribe to and follows this pattern:
   [fs://][[username]:password@]host[:port][?event1[,event2]...]

   This parameter can be set multiple times.

   Example 1.8. Setting the fs_subscribe parameter
...
modparam("freeswitch_scripting", "fs_subscribe", ":ClueCon@10.0.0.10?CHA
NNEL_STATE")
modparam("freeswitch_scripting", "fs_subscribe", ":ClueCon@10.0.0.11:802
1?DTMF,BACKGROUND_JOB")
...

1.4. Exported Functions

1.4.1.  freeswitch_esl(command, freeswitch_url[, response_var])

   Run an arbitrary command on an arbitrary FreeSWITCH ESL socket.
   The socket need not necessarily be defined in the database or
   through fs_subscribe. However, if this is the case, then the
   "password" part of the URL becomes mandatory.

   The current OpenSIPS worker will block until an answer from
   FreeSWITCH arrives. The timeout for this operation can be
   controlled via the esl_cmd_timeout parameter of the freeswitch
   connection manager module.

   Meaning of the parameters is as follows:
     * command (string) - the ESL command string to execute.
     * freeswitch_url (string) - the ESL interface to connect to.
       The syntax is:
       [fs://][[username]:password@]host[:port][?event1[,event2]..
       .]. The "?events" part of the URL will be silently
       discarded.
     * response_var (var, optional) - a variable which will hold
       the text result of the ESL command.

   Return value
     * 1 (success) - the ESL command executed successfully and any
       output variables were successfully written to. Note that
       this does not say anything about the nature of the ESL
       answer (it may well be a "-ERR" type of response)
     * -1 (failure) - internal error or the ESL command failed to
       execute

   This function can be used from any route.

   Example 1.9.  freeswitch_esl() usage
...
        # ESL socket 10.0.0.10 is defined in the database (password "Clu
eCon")
        $var(rc) = freeswitch_esl("bgapi originate {origination_uuid=123
456789}user/1010 9386\njob-uuid: foobar", "10.0.0.10", "$var(response)")
;
        if ($var(rc) < 0) {
                xlog("failed to execute ESL command ($var(rc))\n");
                return -1;
        }
...
        # ESL socket 10.0.0.10 is new, we must specify a password
        $var(rc) = freeswitch_esl("bgapi originate {origination_uuid=123
456789}user/1010 9386\njob-uuid: foobar", ":ClueCon@10.0.0.10", $var(res
ponse));
        if ($var(rc) < 0) {
                xlog("failed to execute ESL command ($var(rc))\n");
                return -1;
        }
...

1.5. Exported MI Commands

1.5.1. fs_subscribe

   Ensures that the given FreeSWITCH ESL socket is subscribed to
   the given list of events. In case an event cannot be subscribed
   to, the freeswitch driver will periodically retry to subscribe
   to it until an fs_unsubscribe MI command for the respective
   event is issued.

   Parameters:
     * freeswitch_url - the ESL interface to connect to. The
       syntax is:
       [fs://][[username]:password@]host[:port][?event1[,event2]..
       .]. The "?events" part of the URL will be silently
       discarded.
     * event - the name of the event to subscribe to
     * ... - (other events)

1.5.2. fs_unsubscribe

   Ensures that the given FreeSWITCH ESL socket is unsubscribed
   from the given list of events.

   Parameters:
     * freeswitch_url - the ESL interface to search for. The
       syntax is:
       [fs://][[username]:password@]host[:port][?event1[,event2]..
       .]. The "?events" part of the URL will be silently
       discarded.
     * event - the name of the event to unsubscribe from
     * ... - (other events)

1.5.3. fs_list

   Displays the current set of FreeSWITCH ESL sockets and the list
   of events that the module is subscribed to for each socket.

1.5.4. fs_reload

   Replaces the current set* of FreeSWITCH ESL sockets along with
   their respective events with the current data (ESL sockets and
   their events) found in the "freeswitch" table.

   * this includes any sockets/events provisioned through
   fs_subscribe, MI fs_subscribe commands or previous DB data set.

1.6. Exported Events

1.6.1.  E_FREESWITCH

   This event is raised when OpenSIPS receives an ESL event
   notification from a socket that the "freeswitch_scripting"
   module is subscribed to.

   Parameters:
     * name - the name of the event
     * sender - the FreeSWITCH sender IP address
     * body - the full JSON-encoded body of the event, as sent by
       FreeSWITCH. Use the json module ($json variable) to easily
       interpret it.

Chapter 2. Contributors

2.1. By Commit Statistics

   Table 2.1. Top contributors by DevScore^(1), authored
   commits^(2) and lines added/removed^(3)
     Name DevScore Commits Lines ++ Lines --
   1. Liviu Chircu (@liviuchircu) 49 27 1935 277
   2. Vlad Patrascu (@rvlad-patrascu) 8 3 137 124
   3. Razvan Crainea (@razvancrainea) 5 3 3 1
   4. Bogdan-Andrei Iancu (@bogdan-iancu) 4 2 4 2
   5. Maksym Sobolyev (@sobomax) 3 1 4 4
   6. Peter Lemenkov (@lemenkov) 3 1 1 1

   (1) DevScore = author_commits + author_lines_added /
   (project_lines_added / project_commits) + author_lines_deleted
   / (project_lines_deleted / project_commits)

   (2) including any documentation-related commits, excluding
   merge commits. Regarding imported patches/code, we do our best
   to count the work on behalf of the proper owner, as per the
   "fix_authors" and "mod_renames" arrays in
   opensips/doc/build-contrib.sh. If you identify any
   patches/commits which do not get properly attributed to you,
   please submit a pull request which extends "fix_authors" and/or
   "mod_renames".

   (3) ignoring whitespace edits, renamed files and auto-generated
   files

2.2. By Commit Activity

   Table 2.2. Most recently active contributors^(1) to this module
                     Name                   Commit Activity
   1. Liviu Chircu (@liviuchircu)         Dec 2017 - Feb 2024
   2. Maksym Sobolyev (@sobomax)          Feb 2023 - Feb 2023
   3. Bogdan-Andrei Iancu (@bogdan-iancu) Apr 2019 - Mar 2020
   4. Razvan Crainea (@razvancrainea)     May 2019 - Sep 2019
   5. Vlad Patrascu (@rvlad-patrascu)     Jan 2019 - Apr 2019
   6. Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018

   (1) including any documentation-related commits, excluding
   merge commits

Chapter 3. Documentation

3.1. Contributors

   Last edited by: Liviu Chircu (@liviuchircu), Vlad Patrascu
   (@rvlad-patrascu), Peter Lemenkov (@lemenkov).

   Documentation Copyrights:

   Copyright © 2017 www.opensips-solutions.com
