<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
%docentities;

]>

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

<chapter>

    <title>&adminguide;</title>

    <section>
	<title>Overview</title>
	<para>
		This module exports the Lua module 'sr', the old API existing before the
		KEMI framework. The module requires 'app_lua' module.
	</para>
	<para>
		IMPORTANT: this module is kept to allow a smooth migration of the scripts
		using 'sr' module in Lua to KEMI framework and the 'KSR' module. It will
		be marked as obsolete in the near future and removed afterwards. If you
		find any function exported to Lua via 'sr' that has no alternative in
		Lua 'KSR' module, report it to sr-dev mailing list.
	</para>
	<para>
		Lua (http://www.lua.org) is a fast and easy to embed scripting
		language. Exported API from &kamailio; to Lua is documented in the
		dokuwiki.
	</para>
    </section>

    <section>
	<title>Dependencies</title>
	<section>
	    <title>&kamailio; Modules</title>
	    <para>
		The following modules must be loaded before this module:
	    	<itemizedlist>
		    <listitem>
			<para>
			    <emphasis>app_lua</emphasis> - the Lua interpreter module.
			</para>
		    </listitem>
		    <listitem>
			<para>
			    <emphasis>various</emphasis> - the modules specified by the
				'register' modparam.
			</para>
		    </listitem>
	    	</itemizedlist>
	    </para>
	</section>
	<section>
	    <title>External Libraries or Applications</title>
	    <para>
		The following libraries or applications must be installed before running
		&kamailio; with this module loaded:
	    	<itemizedlist>
		    <listitem>
			<para>
			    <emphasis>liblua5.1-dev</emphasis> - Lua devel library.
			</para>
		    </listitem>
	    	</itemizedlist>
			<para>
			    This module can be compiled against LuaJIT compiler (instead of
			    standard Lua). Then this library is needed:
			    <itemizedlist>
				    <listitem>
				    <emphasis>libluajit-5.1-dev</emphasis> - LuaJIT devel library.
				    </listitem>
				</itemizedlist>
				<para>
				    To enable that, LUAJIT variable has to be set.
					<example>
					    <title>Build against LuaJIT libraries</title>
					E.g: $ LUAJIT="yes" make modules modules=modules/app_lua_sr
					</example>
			    (Warning: LuaJIT version is 5.1, so scripts prepared for higher Lua versions
			    may not work with LuaJIT)
				</para>
			</para>
	    </para>
	</section>
    </section>

    <section>
	<title>Parameters</title>

	<section id="app_lua_sr.p.register">
	    <title><varname>register</varname> (string)</title>
	    <para>
	    NOTE: Since &kamailio; v5.0, KEMI exports are available in Lua script
		under KSR module exposed by 'app_lua'. These exports cover most of the modules,
		a lot more than those listed next. The KEMI exports are the recommended to
		be used, the old 'sr' module might be obsoleted soon. To read more about
		KEMI exports and available KSR submodules, see:
    	<itemizedlist>
		    <listitem>
			<para>
				<ulink url="https://kamailio.org/docs/tutorials/devel/kamailio-kemi-framework/">https://kamailio.org/docs/tutorials/devel/kamailio-kemi-framework/</ulink>
			</para>
		    </listitem>
    	</itemizedlist>
		</para>
	    <para>
			Use this parameter to register optional &kamailio; submodules
			to Lua. Available submodules are:
	    </para>
	    	<itemizedlist>
		    <listitem>
			<para>
				<emphasis>alias_db</emphasis> - register functions from
				alias_db module under 'sr.alias_db'.
			</para>
		    </listitem>
		    <listitem>
			<para>
				<emphasis>auth</emphasis> - register functions from auth module
				under 'sr.auth'.
			</para>
		    </listitem>
		    <listitem>
			<para>
				<emphasis>auth_db</emphasis> - register functions from auth_db
				module under 'sr.auth_db'.
			</para>
		    </listitem>
		    <listitem>
			<para>
				<emphasis>dispatcher</emphasis> - register functions from
				dispatcher module under 'sr.dispatcher'.
			</para>
		    </listitem>
		    <listitem>
			<para>
				<emphasis>maxfwd</emphasis> - register functions from maxfwd
				module under 'sr.maxfwd'.
			</para>
		    </listitem>
		    <listitem>
			<para>
				<emphasis>msilo</emphasis> - register functions from
				msilo module under 'sr.msilo'.
			</para>
		    </listitem>
		    <listitem>
			<para>
				<emphasis>presence</emphasis> - register functions from
				presence module under 'sr.presence'.
			</para>
		    </listitem>
		    <listitem>
			<para>
				<emphasis>presence_xml</emphasis> - register functions from
				presence_xml module under 'sr.presence_xml'.
			</para>
		    </listitem>
		    <listitem>
			<para>
				<emphasis>pua_usrloc</emphasis> - register functions from
				pua_usrloc module under 'sr.pua_usrloc'.
			</para>
		    </listitem>
		    <listitem>
			<para>
				<emphasis>registrar</emphasis> - register functions from
				registrar module under 'sr.registrar'.
			</para>
		    </listitem>
		    <listitem>
			<para>
				<emphasis>rls</emphasis> - register functions from
				rls module under 'sr.rls'.
			</para>
		    </listitem>
		    <listitem>
			<para>
				<emphasis>rr</emphasis> - register functions from rr module
				under 'sr.rr'.
			</para>
		    </listitem>
		    <listitem>
			<para>
				<emphasis>sanity</emphasis> - register functions from sanity
				module under 'sr.sanity'.
			</para>
		    </listitem>
		    <listitem>
			<para>
				<emphasis>sdpops</emphasis> - register functions from
				sdpops module under 'sr.sdpops'.
			</para>
		    </listitem>
		    <listitem>
			<para>
				<emphasis>siputils</emphasis> - register functions from
				siputils module under 'sr.siputils'.
			</para>
		    </listitem>
		    <listitem>
			<para>
				<emphasis>sl</emphasis> - register functions from sl module
				under 'sr.sl'.
			</para>
		    </listitem>
		    <listitem>
			<para>
				<emphasis>sqlops</emphasis> - register functions from sqlops
				module under 'sr.sqlops'.
			</para>
		    </listitem>
		    <listitem>
			<para>
				<emphasis>textops</emphasis> - register functions from
				textops module under 'sr.textops'.
			</para>
		    </listitem>
		    <listitem>
			<para>
				<emphasis>tm</emphasis> - register functions from tm module
				under 'sr.tm'.
			</para>
		    </listitem>
		    <listitem>
			<para>
				<emphasis>xhttp</emphasis> - register functions from xhttp
				module under 'sr.xhttp'.
			</para>
		    </listitem>
	    	</itemizedlist>
	    <para>
			Note that 'sr', 'sr.hdr' and 'sr.pv' modules are always registered
			to Lua.
	    </para>
	    <para>
		<emphasis>
		    Default value is <quote>null</quote>.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>register</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("app_lua_sr", "register", "sl")
...
</programlisting>
	    </example>
	</section>
	</section>

</chapter>

