<?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 "../../../docbook/entities.xml">
%docentities;

]>

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

<chapter>
    <title>&adminguide;</title>
	
	<section>
	<title>Overview</title>
	<para>
	This module implements generic string translations based on matching and
	replacement rules. It can be used to manipulate R-URI or a PV and to 
	translated to a new format/value.
	</para>
	</section>

	<section>
	<title>How it works</title>
	<para>
	At startup, the module will load a set of transformation rules from a 
	database. Every database row will be stored in memory as a translation 
	rule. Each rule will describe how the matching should be made, how the 
	input value should be modified and which attributes should be set for 
	the matching transformation.
	</para>
	<para>
	The module expects an input value which will be matched against a rules
	via regexp (see 'man pcresyntax' for syntax) or string
	matching. Overlapping matching expressions can be 
	controlled via priorities. Once a rule is matched, the defined 
	transformation (if any) is applied and the result is returned as output 
	value. Also, if any string attribute is associated to the rule, this will 
	be returned to the script along with the output value.
	</para>
	<para>
	<emphasis> The first matching rule will be processed.</emphasis>
	</para>
	</section>

	<section>
	<title>Usage cases</title>
	<para>
	The module can be used to implement dialplans - do to auto completion of 
	the dial numbers (like national to international), to convert generic 
	numbers to specific numbers (like for emergency numbers).
	</para>
	<para>
	Also the module can be used for detecting range or sets of numbers mapped 
	on a service/case - attributes string can be used here to store extra 
	information about the service/case.
	</para>
	<para>
	Non-SIP string translation can be implemented - like converting country 
	names from all possible formats to a canonical format:
	(UK, England, United Kingdom) -> GB.
	</para>
	<para>
	Any other string-base translation or detection for whatever other purposes.
	</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>None</emphasis>
			</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>libpcre - the libraries of <ulink url="http://www.pcre.org/">PCRE</ulink></emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>


	<section>
	<title>Exported Parameters</title>
	<section>
		<title><varname>db_url</varname> (string)</title>
		<para>
		The translation rules will be loaded using this database url.
		</para>
		<para>
		<emphasis>
			Default value is 
				<quote>mysql://openser:openserrw@localhost/openser</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>db_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialplan", "db_url", "mysql://user:passwb@localhost/db")
...
		</programlisting>
		</example>
	</section>

	<section>
		<title><varname>table_name</varname> (string)</title>
		<para>
		The table's name from which to load the translation rules.
		</para>
		<para>
		<emphasis>
			Default value is <quote>dialplan</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>table_name</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialplan", "table_name", "my_table")
...
		</programlisting>
		</example>
	</section>

	<section>
		<title><varname>dpid_col</varname> (string)</title>
		<para>
		The column name to store the dialplan ID group.
		</para>
		<para>
		<emphasis>
			Default value is <quote>dpid</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>dpid_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialplan", "dpid_col", "column_name")
...
		</programlisting>
		</example>
	</section>

	<section>
		<title><varname>pr_col</varname> (string)</title>
		<para>
		The column name to store the priority of the corresponding rule from the database
		row.
		</para>
		<para>
		<emphasis>
			Default value is <quote>pr</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>pr_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialplan", "pr_col", "column_name")
...
		</programlisting>
		</example>
	</section>

	<section>
		<title><varname>match_op_col</varname> (string)</title>
		<para>
		The column name to store the type of matching of the rule.
		</para>
		<para>
		<emphasis>
			Default value is <quote>match_op</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>match_op_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialplan", "match_op_col", "column_name")
...
		</programlisting>
		</example>
	</section>

	<section>
		<title><varname>match_exp_col</varname> (string)</title>
		<para>
		The column name to store the rule match expression.
		</para>
		<para>
		<emphasis>
			Default value is <quote>match_exp</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>match_exp_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialplan", "match_exp_col", "column_name")
...
		</programlisting>
		</example>
	</section>

	<section>
		<title><varname>match_len_col</varname> (string)</title>
		<para>
		The column name to store the length of a string matching the 
		match expression.
		</para>
		<para>
		<emphasis>
			Default value is <quote>match_len</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>pr_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialplan", "match_len_col", "column_name")
...
		</programlisting>
		</example>
	</section>

	<section>
		<title><varname>subst_exp_col</varname> (string)</title>
		<para>
		The column name to store the rule's substitution expression.
		</para>
		<para>
		<emphasis>
			Default value is <quote>subst_exp</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>pr_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialplan", "subst_exp_col", "column_name")
...
		</programlisting>
		</example>
	</section>

		<section>
		<title><varname>repl_exp_col</varname> (string)</title>
		<para>
		The column name to store the rule's replacement expression.
		</para>
		<para>
		<emphasis>
			Default value is <quote>repl_exp</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>repl_exp_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialplan", "repl_exp_col", "column_name")
...
		</programlisting>
		</example>
	</section>

	<section>
		<title><varname>attrs_col</varname> (string)</title>
		<para>
		The column name to store the rule's attributes to be set to the message.
		</para>
		<para>
		<emphasis>
			Default value is <quote>attrs</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>attrs_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialplan", "attrs_col", "column_name")
...
		</programlisting>
		</example>
	</section>

	<section>
		<title><varname>attrs_pvar</varname> (string)</title>
		<para>
		The pvar to store the rule's attributes, after translation (dp_translate() succeeds).
		This parameter can be an AVP or a SCRIPT VAR.
		</para>
		<para>
		<emphasis>
			Default value is <quote>NULL</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>attrs_pvar</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialplan", "attrs_pvar", "$avp(s:dest)")
...
		</programlisting>
		</example>
	</section>

	<section>
		<title><varname>fetch_rows</varname> (int)</title>
		<para>
		The number of rows to be fetched at once from database/
		</para>
		<para>
		<emphasis>
			Default value is <quote>1000</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>fetch_rows</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("dialplan", "fetch_rows", 4000)
...
		</programlisting>
		</example>
	</section>


	</section>


	<section>
	<title>Exported Functions</title>
	
	<section>
	<title>
		<function moreinfo="none">dp_translate(id, src/dest)</function>
	</title>
	<para>
	Will try to translate the src string into dest string according to 
	the translation rules with dialplan ID equal to id.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	<listitem>
		<para>
		<emphasis>id</emphasis> -the dialplan id of the possible matching rules.
		This parameter can have the following types:
		</para>
		<itemizedlist>
			<listitem>
			<para><emphasis>integer</emphasis>- the dialplan id is statically 
			assigned </para>
			</listitem>
			
			<listitem>
			<para><emphasis>avp var</emphasis> 
			-the dialplan id is the value of an existing avp variable
			</para>
			</listitem>

			<listitem>
			<para><emphasis>script var</emphasis> 
			-the dialplan id is the value of an existing script variable.</para>
			</listitem>
		</itemizedlist>
  	</listitem>

	<listitem>
		<para>
 		<emphasis>src/dest</emphasis> - input and output of the function.
		If this parameter is missing the default parameter 
		<quote>ruri.user/ruri.user</quote> will be used, thus translating 
		the request uri. 
 		</para>
		<para>Input parameter src can be any pseudo variable.
		Output parameter dest can be:
		</para>
		<itemizedlist>
			<listitem>
			<para><emphasis>R-URI</emphasis></para>
			<para>
			- the string is the r-uri or r-uri username
			</para>
			</listitem>
			
			<listitem>
			<para><emphasis>avp var</emphasis> </para>
			<para>
			-At input the function will get the input string from an existing 
			avp variable. At output the function will add an avp with the 
			value of the output string.
			</para>
			</listitem>

			<listitem>
			<para><emphasis>script var</emphasis> </para>
			<para>
			-At input the function will get the input string from an existing 
			script variable. At output the function will set an script variable
			with the value of the output string.
			</para>
			</listitem>
        </itemizedlist>
        </listitem>
	</itemizedlist>
	<para>
	This function can be used from REQUEST_ROUTE, BRANCH_ROUTE.
	</para>
	<example>
	<title><function>dp_translate</function> usage</title>
	<programlisting format="linespecific">
...
dp_translate("240", "$ruri.user/$avp(s:dest)");
xlog("translated to var $avp(s:dest) \n");
...
	</programlisting>
	</example>
	<example>
	<title><function>dp_translate</function> usage</title>
	<programlisting format="linespecific">
...
$avp(s:src) = $ruri.user;
dp_translate("$var(x)", "$avp(s:src)/$var(y)");
xlog("translated to var $var(y) \n");
...
	</programlisting>
	</example>

	</section>

	</section>


	<section>
	<title>Exported MI Functions</title>

		<section>
			<title><varname>dp_reload</varname></title>
			<para>
			It will update the translation rules, loading the database info.
			</para>
		<para>
		Name: <emphasis>dp_reload</emphasis>
		</para>
		<para>Parameters: <emphasis>none</emphasis></para>
 		<para>
		MI DATAGRAM Command Format:
		</para>
        <programlisting  format="linespecific">
		:dp_reload:
		_empty_line_
		</programlisting>
		</section>
    
    <section>
			<title><varname>dp_translate</varname></title>
			<para>
                It will apply a translation rule identified by a dialplan
                id and an input string.
			</para>
		<para>
		Name: <emphasis>dp_translate</emphasis>
		</para>
        <para>Parameters: <emphasis>2</emphasis></para>
        	<itemizedlist>
                <listitem>
                <para><emphasis>Dial plan ID</emphasis></para>
                </listitem>
                <listitem>
                <para><emphasis>Input String</emphasis></para>
                </listitem>
            </itemizedlist>
 		<para>
		MI DATAGRAM Command Format:
		</para>
        <programlisting  format="linespecific">
            :dp_translate:
            dpid
            input
		_empty_line_
		</programlisting>
		</section>
	</section>
    
    <section>
	    <title>Installation</title>
	    <para>
        The modules requires one table in Kamailio database: dialplan.The SQL 
        syntax to create them can be found in dialplan-create.sql     
        script in the database directories in the kamailio/scripts folder.
        You can also find the complete database documentation on the
        project webpage, &kamailiodbdocslink;.
        </para>
    </section>



</chapter>