%docentities; ]>

There are a number of example scripts in the samples/. They are documented well. Read them, it will explain a lot to you :) If you want to use any of these scripts directly in your implementation, you can use Perl's require mechanism to import them (just remember that you need to use quotes when require'ing .pl files).

The included sample scripts are described below:

The minimal function in branches.pl demonstrates that you can access the "append_branch" function from within perl, just as you would have done from your normal configuration file. You'll find documentation on the concepts of branching in the Kamailio documentation.

Message's first_line structure may be evaluated. Message can be either of SIP_REQUEST or SIP_REPLY. Depending on that, different information can be received. This script demonstrates these functions.

The perl module provides access to Kamailio's flagging mechanism. The flag names available for Kamailio modules are made available through the Kamailio::Constants package, so you can flag messages as "green", "magenta" etc. The first function, setflag, demonstrates how the "green" flag is set. In the second function, readflag, the "green" and "magenta" flags are evaluated.

This sample script demonstrates different things related to calling functions from within perl, and the different types of functions you can offer for Kamailio access. exportedfuncs simply demonstrates that you can use the moduleFunction method to call functions offered by other modules. The results are equivalent to calling these functions from your config file. In the demonstrated case, telephone calls with a destination number beginning with 555... are rejected with an internal server error. Other destination addresses are passed to the alias_db module. Please note that the moduleFunction method is not fully available in Kamailio 1.2. See the method's documentation for details. paramfunc shows that you can pass arbitrary strings to perl functions. Do with them whatever you want :) autotest demonstrates that unknown functions in Kamailio::Message objects are automatically transformed into calls to module functions. The diefuncs show that dying perl scripts - by "manual" dying, or because of script errors - are handled by the Kamailio package. The error message is logged through Kamailio's logging mechanism. Please note that this only works correctly if you do NOT overwrite the default die handler. Oh, yes, that works for warnings, too.

Header extraction is among the most crucial functionalities while processing SIP messages. This sample script demonstrates access to header names and values within two sample functions. headernames extracts all header names and logs their names. someheaders logs the contents of the two headers, To and WWW-Contact. As you can see, headers that occur more than once are retrieved as an array, which may be accessed by Perl's array accessing methods.

For debugging purposes, you probably want to write messages to the syslog. The logdemo shows three ways to access the Kamailio log function: it is available through the Kamailio class as well as through the Kamailio::Message class. Remember that you can use exported functions from other modules. You may thus as well use the xlog module and it's xlog function. The L_INFO, L_DBG, L_ERR, L_CRIT... constants are available through the Kamailio::Constants package.

This script demonstrates how to access the whole message header of the current message. Please note that modifications on the message made by earlier function calls in your configuration script may NOT be reflected in this dump.

When processing SIP messages, you may want to use persistent data across multiple calls to your Perl functions. Your first option is to use global variables in your script. Unfortunately, these globals are not visible from the mulitple instances of Kamailio. You may want to use a mechanism such as the IPC::Shareable shared memory access package to correct this.

The Kamailio::Utils::PhoneNumbers package provides two methods for the transformation of local to canonical telephone numbers, and vice versa. This script demonstrates it's use.

This script demonstrates the Perl module's pseudoVar method. It may be used to retrieve the values of current pseudo variables. You might notice that there is no particular function for setting pseudo variables; you may use the exported functions from the avpops module, though.