Mod perl

From FreeSWITCH Wiki
Jump to: navigation, search

mod_perl is supported as of RC4.

Keep in mind that if you just want to execute perl scripts (or talk to FreeSWITCH using sockets through perl) you do not need mod_perl. Generally the only time you will need mod_perl support is if you want to interact with a live session from a script executed by FreeSWITCH (see examples below). For more details on using Perl without mod_perl see the Perl page.

Contents

Suse Issue

FreeSWITCH will compile mod_perl on Suse 10.3, 11.0, and 11.1 however it appears that it will coredump. I resolved this by recompiling perl 5, (and upgrading to 5.10.0 in the process) which seems to have gotten this bug resolved. If you're not sufficiently skilled to re-compile perl yourself, contact your Distribution vendor and ask them to stop fixing things that aren't broken.

I have not tried FreeSWITCH on earlier Suse distributions, your mileage may vary...

Installing

First beware that for mod_perl support you must have perl compiled with threads/multiplicity (generally once you compile for threads this is enabled). If you are not sure if you have perl compiled with multiplicity (the FreeSWITCH install will _not_ check this for you) or if you are looking for tips on recompiling perl with this support please see the section on the perl multiplicity requirement at the end of this page.

Once you have multiplicity support working you can continue:

  • Uncomment the mod_perl line in modules.conf in the build root of FreeSWITCH
  • (re)compile freeswitch
  • issue "make mod_perl-install" from the shell
  • Uncomment the mod_perl load line in modules.conf.xml
  • Mod perl will now load and work correctly

On RHEL / CentOS, gdbm-devel and db4-devel packages must be installed.

Configuring

Once you have enabled mod_perl in the modules config, you are ready to start using it. If you want to call it as part of a dial plan you just have to call your script using:

<action application="perl" data="/path/to/your/script.pl" />

You can pass arguments to the script by just placing them at the end of the data string (separated by spaces).

If you want to use mod_perl to call a perl script to generate XML for a dialplan however you want to do a few additional things:

The file conf/autoload_configs/perl.conf.xml is used in the default FreeSWITCH™ setup.

Here is a minimum configuration file, it will fetch a dialplan from perl script.

<configuration name="perl.conf" description="PERL Configuration">
  <settings>
    <param name="xml-handler-script" value="/tmp/xml.pl"/>
    <param name="xml-handler-bindings" value="dialplan"/>

    <!--
	The following options identifies a perl script that is launched	
	at startup and may live forever in the background.
	You can define multiple lines, one for each script you 
	need to run.
    -->
    <!--param name="startup-script" value="startup_script_1.pl"/-->
    <!--param name="startup-script" value="startup_script_2.pl"/-->

  </settings>
</configuration>

The xml-handler-bindings value can assume the following values:

  • configuration
  • dialplan
  • directory

(See Mod xml curl for more informations. Mod_perl behaves the same identical way.

The startup-script values represent perl scripts (located inside the scripts/ directory) that are launched when FreeSWITCH is started. The scripts live in their own thread. You can use them to run simple tasks (and then let them finish) or looping forever, watching (for example) for events, generating calls or whatever you like.

Programming with mod_perl

Given there are two different ways for programming with mod_perl, generating xml, and standard plan execution. There are a few separate pages covering programming with mod_perl:

Some tips for programming with mod_perl

Most instance functions have 'this' as the first parameter, you don't actually pass 'this', it is automatically passed when you call a function, for example:

$session->answer();

will pass $session as the this automatically.

It is important to know that the perl->c++ conversion is not always perfect. Passing functions is done by passing the function name as a string, rather than the standard dereferencing:

$session->setHangupHook( 'on_hangup' ); # GOOD

NOT

$session->setHangupHook( \&on_hangup ); # BAD

In addition a function that takes a string argument you should not pass it a number, so:

$session->execute("sleep","1500"); # GOOD

NOT

$session->execute("sleep",1500); #BAD

Generally if you pass an invalid argument it will give you an error when you run it, with an error of "No matching function for overloaded".

Also, some differences exist in the function names. For example, where in JavaScript you might do:

var hangup_cause = session.cause

In Perl, you would do:

$hangup_cause = $session->hangupCause();

Finally functions can behave a little bit different than expected, for example consoleLog does not append a newline at the end of the log message automatically, and may not flush it to the console until a new line is printed.

Executing an API from within mod_perl

Sometimes you need to execute an API (like 'show channels' or 'fifo list') while processing in your script. You need to create an API object:

my $api = new freeswitch::API;

Then use the execute or executeString method and capture the return value:

my $res = $api->executeString("show channels");

Here's a very simple example that calls version and prints the value in the debug log.

# api_example.pl
#
my $api = new freeswitch::API;
my $res = $api->executeString("version");
chomp($res);
freeswitch::consoleLog("INFO","Version information is '$res'\n");
$session->hangup;

1; ## Always end with a TRUE value    

Perl Multiplicity Requirement

As FreeSWITCH is multithreaded it requires mod_perl to be multithreaded this can be a bit of a task to get working if it is not already compiled with this support.

While there is a check in the makefile for this it doesn't actually execute currently so it is best to verify this yourself. At a command line run:

perl -V | grep -oP "usemultiplicity=[a-z]+"

you should get back something like: usemultiplicity=define however if you get back usemultiplicity=undef you are in bad shape. If this happens to you you will need to recompile perl to make mod_perl for FreeSWITCH load correctly. Keep in mind that in addition to recompiling some (many) of your perl modules may need to be reinstalled to work correctly along with some apps that may require in with perl/libperl. You should test this on a non-production system before trying to convert a production system.

For gentoo do the following:

Add ithreads to the perl and libperl use flags
recompile perl and libperl
perl-cleaner reallyall

That should help to ensure everything that could be effected is recompiled but it may not get everything (specifically manually compiled apps or cpan installed modules).

A script to help ensure all modules are reinstalled for your new version of perl can be found at: http://mitchcapper.com/missing_modules.pl.txt

See Also

Examples