%docentities; ]>

The time needed when writing a new &kamailio; module unfortunately is quite high, while the options provided by the configuration file are limited to the features implemented in the modules. With this Perl module, you can easily implement your own &kamailio; extensions in Perl. This allows for simple access to the full world of CPAN modules. SIP URI rewriting could be implemented based on regular expressions; accessing arbitrary data backends, e.g. LDAP or Berkeley DB files, is now extremely simple.

This Perl module is loaded in &kamailioconfig; (just like all the other modules) with loadmodule("/path/to/perl.so");. For the Perl module to compile, you need a reasonably recent version of perl (tested with 5.8.8) linked dynamically. It is strongly advised to use a threaded version. The default binary packages from your favorite Linux distribution should work fine. Cross compilation is supported by the Makefile. You need to set the environment variables PERLLDOPTS, PERLCCOPTS and TYPEMAP to values similar to the output of PERLLDOPTS: perl -MExtUtils::Embed -e ldopts PERLCCOPTS: perl -MExtUtils::Embed -e ccopts TYPEMAP: echo "`perl -MConfig -e 'print $Config{installprivlib}'`/ExtUtils/typemap" The exact position of your (precompiled!) perl libraries depends on the setup of your environment.

The Perl module has two interfaces: The perl side, and the &kamailio; side. Once a Perl function is defined and loaded via the module parameters (see below), it may be called in &kamailio;'s configuration at an arbitary point. E.g., you could write a function "ldap_alias" in Perl, and then execute ... if (perl_exec("ldap_alias")) { ... } ... just as you would have done with the current alias_db module. The functions you can use are listed in the "Exported Functions" section below. On the Perl side, there are a number of functions that let you read and modify the current SIP message, such as the RURI or the message flags. An introduction to the Perl interface and the full reference documentation can be found below.

The following modules must be loaded before this module: The "sl" module is needed for sending replies uppon fatal errors. All other modules can be accessed from the Perl module, though.

The following libraries or applications must be installed before running &kamailio; with this module loaded: Perl 5.8.x or later Additionally, a number of perl modules should be installed. The &kamailio;::LDAPUtils package relies on Net::LDAP to be installed. One of the sample scripts needs IPC::Shareable This module has been developed and tested with Perl 5.8.8, but should work with any 5.8.x release. Compilation is possible with 5.6.x, but its behavior is unsupported. Earlier versions do not work. On current Debian systems, at least the following packages should be installed: perl perl-base perl-modules libperl5.8 libperl-dev libnet-ldap-perl libipc-shareable-perl It was reported that other Debian-style distributions (such as Ubuntu) need the same packages. On SuSE systems, at least the following packages should be installed: perl perl-ldap IPC::Shareable perl module from CPAN Although SuSE delivers a lot of perl modules, others may have to be fetched from CPAN. Consider using the program cpan2rpm - which, in turn, is available on CPAN. It creates RPM files from CPAN.

This is the file name of your script. This may be set once only, but it may include an arbitary number of functions and use as many Perl module as necessary. Must not be empty! ... modparam("app_perl", "filename", "/home/test/kamailio/myperl.pl") ...

The path to the Perl modules included (Kamailio.pm et.al). It is not absolutely crucial to set this path, as you may install the Modules in Perl's standard path, or update the %INC variable from within your script. Using this module parameter is the standard behavior, though. Multiple paths may be specified by separating them with a : character. The maximum is 10 paths. ... modparam("app_perl", "modpath", "/usr/local/lib/kamailio/perl/") ...

The number of execution cycles after which the embedded perl interpreter is reset. Sometimes is hard to track the scope of variables in all used perl modules and that can result in leaks of system memory. Resetting the interpreter cleans the memory space. When the interpreter is reset, the perl script is loaded again. Note that not all &kamailio; processes will reset the interpreter at the same time. Each will do it when it has executed the script for the number of reset_cycles. Also, be aware that the reset of the interpreter is taking a bit of time (in the order of tens of mili-seconds). Default value is 0 - never reset the interpreter. ... modparam("app_perl", "reset_cycles", 100000) ...

The name of Perl function to be executed before the interpreter is re-initialized (reset -- see reset_cycles parameter) at runtime. This could be useful to clean global variables or file descriptors from the Perl script. ... modparam("app_perl", "perl_destroy_func", "my_perl_destroy") ...

Calls a perl function without passing it the current SIP message. May be used for very simple simple requests that do not have to fiddle with the message themselves, but rather return information values about the environment. The first parameter is the function to be called. An arbitrary string may optionally be passed as a parameter. This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE and BRANCH_ROUTE. ... if (method=="INVITE") { perl_exec_simple("dosomething", "on invite messages"); }; ...

Calls a perl function with passing it the current SIP message. The SIP message is reflected by a Perl module that gives you access to the information in the current SIP message (Kamailio::Message). The first parameter is the function to be called. An arbitrary string may be passed as a parameter. This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE and BRANCH_ROUTE. ... if (perl_exec("ldapalias")) { ... }; ...

Set the value of the reset_cycle. The command has one integer parameter. ... kamcmd app_perl.set_reset_cycles 20000 ...

Return the value of the reset_cycle. ... kamcmd app_perl.get_reset_cycles ...