<!-- Module User's Guide -->

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
		<title>Overview</title>
		<para>
		The time needed when writing a new OpenSIPS module unfortunately is quite high, while the
		options provided by the configuration file are limited to the features implemented in the
		modules.
		</para>
		<para>
		With this Perl module, you can easily implement your own OpenSIPS 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.
		</para>
	</section>
	<section>
		<title>Installing the module</title>
		<para>
		This Perl module is loaded in opensips.cfg (just like all the other modules) with
		loadmodule("/path/to/perl.so");.
		</para>

		<para>
		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.
		</para>

		<para>
		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
		</para>
		<programlisting format="linespecific">
PERLLDOPTS: perl -MExtUtils::Embed -e ldopts
PERLCCOPTS: perl -MExtUtils::Embed -e ccopts
TYPEMAP:    echo "`perl -MConfig -e 'print $Config{installprivlib}'`/ExtUtils/typemap"
</programlisting>
		<para>
		The exact position of your (precompiled!) perl libraries depends on the setup of your
		environment.
		</para>
	</section>

	<section>
		<title>Using the module</title>
		<para>
		The Perl module has two interfaces: The perl side, and the OpenSIPS side. Once a Perl
		function is defined and loaded via the module parameters (see below), it may be
		called in OpenSIPS's configuration at an arbitary point. E.g., you could write
		a function "ldap_alias" in Perl, and then execute <programlisting format="linespecific">
...
if (perl_exec("ldap_alias")) {
	...
}	
...
</programlisting>
		just as you would have done with the current alias_db module.
		</para>

		<para>
		The functions you can use are listed in the
		<xref linkend="exported_functions"/> section below.
		</para>
		<para>
		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.
		</para>
	</section>
			

	<section id="dependencies" xreflabel="Dependencies">
	<title>Dependencies</title>
	<section>
		<title>&osips; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				The "sl" module is needed for sending replies uppon fatal errors. All other modules
				can be accessed from the Perl module, though.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before 
		running &osips; with this module loaded:
		<itemizedlist>
			<listitem>
			<para>
				<emphasis>Perl 5.8.x or later</emphasis>
			</para>
			</listitem>
		</itemizedlist>
		Additionally, a number of perl modules should be installed. The OpenSIPS::LDAPUtils package
		relies on Net::LDAP to be installed. One of the sample scripts needs IPC::Shareable
		</para>
		<para>
		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.
		</para>
		<para>
		On current Debian systems, at least the following packages should be installed:
		</para>
		<itemizedlist>
			<listitem><para>perl</para></listitem>
			<listitem><para>perl-base</para></listitem>
			<listitem><para>perl-modules</para></listitem>
			<listitem><para>libperl5.8</para></listitem>
			<listitem><para>libperl-dev</para></listitem>
			<listitem><para>libnet-ldap-perl</para></listitem>
			<listitem><para>libipc-shareable-perl</para></listitem>
		</itemizedlist>
		<para>
		It was reported that other Debian-style distributions (such as Ubuntu) need the
		same packages.
		</para>
		<para>
		On SuSE systems, at least the following packages should be installed:
		</para>
		<itemizedlist>
			<listitem><para>perl</para></listitem>
			<listitem><para>perl-ldap</para></listitem>
			<listitem><para>IPC::Shareable perl module from CPAN</para></listitem>
		</itemizedlist>
		<para>
		Although SuSE delivers a lot of perl modules, others may have to be fetched
		from CPAN. Consider using the program <quote>cpan2rpm</quote> - which, in turn,
		is available on CPAN. It creates RPM files from CPAN.
		</para>
	</section>
	</section>

	<section id="exported_parameters" xreflabel="Exported Parameters">
		<title>Exported Parameters</title>
		<section id="param_filename" xreflabel="filename">
			<title><varname>filename</varname> (string)</title>
			<para>
			This is the file name of your script. This may be set once only, but it may include an arbitary
			number of functions and <quote>use</quote> as many Perl module as necessary.
			</para>
			<para>
			<emphasis>
				May not be empty!
			</emphasis>
			</para>
			<example>
			<title>Set <varname>filename</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("perl", "filename", "/home/john/opensips/myperl.pl")
...
</programlisting>
			</example>
		</section>

		<section id="param_modpath" xreflabel="modpath">
			<title><varname>modpath</varname> (string)</title>
			<para>
			The path to the Perl modules included (OpenSIPS.pm et.al). It is not absolutely
			crucial to set this path,
			as you <emphasis>may</emphasis> install the Modules in Perl's standard path, or update
			the <quote>%INC</quote> variable from within your script. Using this module parameter
			is the standard behavior, though.
			</para>
			<example>
			<title>Set <varname>modpath</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("perl", "modpath", "/usr/local/lib/opensips/perl/")
...
</programlisting>
			</example>
		</section>
	</section>

	<section id="exported_functions" xreflabel="exported_functions">
		<title>Exported Functions</title>
		<section id="func_perl_exec_simple" xreflabel="perl_exec_simple()">
			<title>
			<function moreinfo="none">perl_exec_simple(func, [param])</function>
			</title>
			<para>
			Calls a perl function <emphasis>without</emphasis> 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.
			</para>
			<para>
			The first parameter is the function to be called.
			An arbitrary string may optionally be passed as a parameter.
			</para>
			<para>
			The function returns <emphasis>1</emphasis> if the perl function was successfully called
			or <emphasis>-1</emphasis> if an internal error occured. Note that it does not propagate
			the return value of the perl function.
			</para>
			<para>
			This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE and BRANCH_ROUTE.
			</para>
			<example>
			<title><function>perl_exec_simple()</function> usage</title>
			<programlisting format="linespecific">
...
if ($rm=="INVITE") {
	perl_exec_simple("dosomething", "on invite messages");
};
...
</programlisting>
			</example>
		</section>

		<section id="func_perl_exec" xreflabel="perl_exec()">
			<title>
			<function moreinfo="none">perl_exec(func, [param])</function>
			</title>
			<para>
			Calls a perl function <emphasis>with</emphasis> 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 (OpenSIPS::Message).
			</para>
			<para>
			The first parameter is the function to be called.
			An arbitrary string may be passed as a parameter.
			</para>
			<para>
			The function returns back to the OpenSIPS script the value returned by the perl function.
			Note that if this value is <emphasis>0</emphasis> the script execution
			will be stoped, similarly to calling <emphasis>exit</emphasis>.
			</para>
			<para>
			This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE and BRANCH_ROUTE.
			</para>
			<example>
			<title><function>perl_exec()</function> usage</title>
			<programlisting format="linespecific">
...
if (perl_exec("ldapalias")) {
	...
};
...
</programlisting>
			</example>
		</section>
	</section>

</chapter>

