src/modules/mtree/doc/mtree_admin.xml
bd8b01b9
 <?xml version="1.0" encoding="iso-8859-1"?>
c9ba911f
 <!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 -->
6deb5fcf
 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
c9ba911f
 %docentities;
 
 ]>
 
 <!-- Module User's Guide -->
 
 <chapter>
b16d00ff
 
c9ba911f
     <title>&adminguide;</title>
b16d00ff
 
c9ba911f
     <section>
 	<title>Overview</title>
 	<para>
74fadc54
 		This module loads (prefix, value) records from database and indexes
 		them in a named memory tree. Name of the tree is specified for each
 		record or as module parameter.
 	</para>
b16d00ff
 	<para>
74fadc54
 		It exports to configuration file functions to match against in-memory
 		trees and return the values (raw or precompiled) associated with
 		matched prefixes.
 	</para>
b16d00ff
 	<para>
74fadc54
 		The maximum size of the prefix is limited internally to 63, database
 		table definition may enforce lower maximum size.
c9ba911f
 	</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>A &kamailio; database module (e.g., mysql)</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>None</emphasis>.
 			</para>
 		    </listitem>
 	    	</itemizedlist>
 	    </para>
 	</section>
     </section>
     <section>
9114eebc
 	<title>Parameters</title>
0e806316
 	<section id="mtree.p.db_url">
c9ba911f
 	    <title><varname>db_url</varname> (string)</title>
 	    <para>
 		URL of the database server to be used.
 	    </para>
 	    <para>
 		<emphasis>
 		    Default value is <quote>&defaultdb;</quote>.
 		</emphasis>
 	    </para>
 	    <example>
 		<title>Set <varname>db_url</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("mtree", "db_url", "&exampledb;")
 ...
 </programlisting>
 	    </example>
 	</section>
 
0e806316
 	<section id="mtree.p.db_table">
1e115fd9
 	    <title><varname>db_table</varname> (string)</title>
 	    <para>
1c1e5138
 		Name of database table where data for many trees is stored. It is ignored
 		if a 'mtree' parameter is defined. The SQL scripts creates a table named
 		'mtrees' that can be used for this parameter.
1e115fd9
 	    </para>
 	    <para>
 		<emphasis>
1c1e5138
 		    Default value is <quote></quote> (no table name).
1e115fd9
 		</emphasis>
 	    </para>
 	    <example>
 		<title>Set <varname>db_table</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
1c1e5138
 modparam("mtree", "db_table", "mtrees")
1e115fd9
 ...
 </programlisting>
 	    </example>
 	</section>
 
0e806316
 	<section id="mtree.p.mtree">
c9ba911f
 	    <title><varname>mtree</varname> (string)</title>
 	    <para>
e6a30626
 			Definition of memory tree with using a parameters format string.
ebdf05f5
 			The parameter names can be:
 		<itemizedlist>
 		<listitem>
 			<para>
 				name - the name of the tree to be used for referencing
 				inside configuration file.
 			</para>
 		</listitem>
 		<listitem>
 			<para>
 				dbtable - the name of the database table from where to
 				load the records stored in the tree.
 			</para>
 		</listitem>
 		<listitem>
 			<para>
 				cols - the column names of the database table. They must
 				be enclosed in quotes in order to form a valid SIP parameter
 				value and be separated by comma. The first column corresponds
 				to tprefix. When specified, there must be at least two columns.
 				If this attribute is not specified, then the global module
 				parameters for tprefix and tvalue are used. If more than one
 				value columns are specified, the tree will pack the column
 				values in a comma separated string, which will be associated
 				with the prefix (string transformation {s.select,...) can be
 				used in configuration file to extract a specific column value).
 			</para>
 		</listitem>
 		<listitem>
 			<para>
07643b70
 				type - the  type of tree elements (0 = string, 1 = d:w, 2 = integer).
 				None-zero is valid only when the (tprefix, tvalue) pairs are loaded
dee1dc34
 				(not for multi-column values).
ebdf05f5
 			</para>
07643b70
 			<para>
 				When the type is 1, the value in database has to be two integers
 				separated by colon, the first one (d - dstid) will be stored in
 				pv_dstid AVP and the second (w - weight) will be stored in
 				pv_weight AVP. If in the matching records are many with the same
 				dstid, it will keep only the one with the longest prefix. Then
 				the records are ordered by the weight and stored in the specified
 				AVPs. The number of stored records is saved in pv_count variable.
 			</para>
ebdf05f5
 		</listitem>
 		<listitem>
 			<para>
 				multi - tells if dbtable can contain more than one tree
 				(0 = one tree, 1 = more than one tree identified by tname
 				column). It is valid only when the (tprefix, tvalue) pairs
dee1dc34
 				are loaded (not for multi-column values).
ebdf05f5
 			</para>
 		</listitem>
 		</itemizedlist>
 		</para>
0b122416
 	    <para>
 	    This parameter can be set many times to add more trees in
 	    memory.
 	    </para>
c9ba911f
 	    <para>
 		<emphasis>
 		    Default value is <quote>none</quote>.
 		</emphasis>
 	    </para>
 	    <example>
 		<title>Set <varname>mtree</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
0b122416
 modparam("mtree", "mtree", "name=mytree1;dbtable=routes1;type=0")
 modparam("mtree", "mtree", "name=mytree2;dbtable=routes2;type=0;multi=1")
ebdf05f5
 modparam("mtree", "mtree",
     "name=mytree1;dbtable=routes1;cols='key1,val1,val2,val3'")
c9ba911f
 ...
 </programlisting>
 	    </example>
 	</section>
 
0e806316
 	<section id="mtree.p.tname_column">
1e115fd9
 	    <title><varname>tname_column</varname> (string)</title>
 	    <para>
 		Name of 'tname' column.
 	    </para>
 	    <para>
 		<emphasis>
 		    Default value is <quote>tname</quote>.
 		</emphasis>
 	    </para>
 	    <example>
 		<title>Set <varname>tname_column</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("mtree", "tname_column", "name")
 ...
 </programlisting>
 	    </example>
 	</section>
 
0e806316
 	<section id="mtree.p.tprefix_column">
c9ba911f
 	    <title><varname>tprefix_column</varname> (string)</title>
 	    <para>
 		Name of 'tprefix' column.
 	    </para>
 	    <para>
 		<emphasis>
 		    Default value is <quote>tprefix</quote>.
 		</emphasis>
 	    </para>
 	    <example>
1e115fd9
 		<title>Set <varname>tprefix_column</varname> parameter</title>
c9ba911f
 		<programlisting format="linespecific">
 ...
 modparam("mtree", "tprefix_column", "prefix")
 ...
 </programlisting>
 	    </example>
 	</section>
 
0e806316
 	<section id="mtree.p.tvalue_column">
c9ba911f
 	    <title><varname>tvalue_column</varname> (string)</title>
 	    <para>
 		Name of 'tvalue' column.
 	    </para>
 	    <para>
 		<emphasis>
 		    Default value is <quote>tvalue</quote>.
 		</emphasis>
 	    </para>
 	    <example>
 		<title>Set <varname>tvalue_column</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("mtree", "tvalue_column", "ipaddr")
 ...
 </programlisting>
 	    </example>
 	</section>
 
0e806316
 	<section id="mtree.p.fetch_rows">
c9ba911f
 	    <title><varname>fetch_rows</varname> (integer)</title>
 	    <para>
 		Number of rows to be loaded in one step from database.
 	    </para>
 	    <para>
 		<emphasis>
 		    Default value is 1000.
 		</emphasis>
 	    </para>
 	    <example>
 		<title>Set <varname>fetch_rows</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("mtree", "fetch_rows", 4000)
 ...
 </programlisting>
 	    </example>
 	</section>
 
0e806316
 	<section id="mtree.p.char_list">
c9ba911f
 	    <title><varname>char_list</varname> (string)</title>
 	    <para>
 		The list with characters allowed in prefix.
 		</para>
 	    <para>
 		<emphasis>
 		    Default value is <quote>0123456789</quote>.
 		</emphasis>
 	    </para>
 	    <example>
 		<title>Set <varname>char_list</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("mtree", "char_list", "0123456789*+")
 ...
 </programlisting>
 	    </example>
 	</section>
 
0e806316
 	<section id="mtree.p.pv_value">
c9ba911f
 	    <title><varname>pv_value</varname> (string)</title>
 	    <para>
 		The PV spec where to store the matched value. It can be any
c4b3b04e
 		writable PV.
c9ba911f
 		</para>
 	    <para>
 		<emphasis>
 		    Default value is <quote>$avp(s:tvalue)</quote>.
 		</emphasis>
 	    </para>
 	    <example>
 		<title>Set <varname>pv_value</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("mtree", "pv_value", "$var(mtval)")
 ...
 </programlisting>
 	    </example>
 	</section>
 
0e806316
 	<section id="mtree.p.pv_values">
bd8b01b9
 	    <title><varname>pv_values</varname> (string)</title>
 	    <para>
af69a307
 		The AVP where to store the matched values when mtree is of type
 		0 or 2 and mode of mt_match() call has value 2.
bd8b01b9
 		</para>
 	    <para>
 		<emphasis>
 		    Default value is <quote>$avp(s:tvalues)</quote>.
 		</emphasis>
 	    </para>
 	    <example>
 		<title>Set <varname>pv_values</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("mtree", "pv_values", "$avp(mtvals)")
 ...
 </programlisting>
 	    </example>
 	</section>
 
0e806316
 	<section id="mtree.p.pv_dstid">
07643b70
 	    <title><varname>pv_dstid</varname> (string)</title>
 	    <para>
 		The AVP name where to store the first integer value when tree type is 1.
 		</para>
 	    <para>
 		<emphasis>
 		    Default value is <quote>$avp(tdstid)</quote>.
 		</emphasis>
 	    </para>
 	    <example>
 		<title>Set <varname>pv_dstid</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("mtree", "pv_dstid", "$var(dstid)")
 ...
 </programlisting>
 	    </example>
 	</section>
 
0e806316
 	<section id="mtree.p.pv_weight">
07643b70
 	    <title><varname>pv_weight</varname> (string)</title>
 	    <para>
 		The AVP name where to store the second integer value when tree type is 1.
 		</para>
 	    <para>
 		<emphasis>
 		    Default value is <quote>$avp(tweight)</quote>.
 		</emphasis>
 	    </para>
 	    <example>
 		<title>Set <varname>pv_weight</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("mtree", "pv_dstid", "$var(weight)")
 ...
 </programlisting>
 	    </example>
 	</section>
 
0e806316
 	<section id="mtree.p.pv_count">
07643b70
 	    <title><varname>pv_count</varname> (string)</title>
 	    <para>
 		The PV spec where to store the count of matched values when tree type
 		is 1. It can be any writable PV.
 		</para>
 	    <para>
 		<emphasis>
 		    Default value is <quote>$avp(tcount)</quote>.
 		</emphasis>
 	    </para>
 	    <example>
 		<title>Set <varname>pv_count</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("mtree", "pv_count", "$var(count)")
 ...
 </programlisting>
 	    </example>
 	</section>
 
0e806316
 	<section id="mtree.p.mt_tree_type">
1e115fd9
 	    <title><varname>mt_tree_type</varname> (integer)</title>
 	    <para>
c4b3b04e
 		Default payload type for trees data stored in 'db_table'. Documented
 		values are 0 for string payloads and 2 for integer payloads.
1e115fd9
 	    </para>
 	    <para>
 		<emphasis>
 		    Default value is 0.
 		</emphasis>
 	    </para>
 	    <example>
 		<title>Set <varname>mt_tree_type</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
1d593737
 modparam("mtree", "mt_tree_type", 2)
1e115fd9
 ...
 </programlisting>
 	    </example>
 	</section>
 
0e806316
 	<section id="mtree.p.mt_ignore_duplicates">
427e4c0f
 	    <title><varname>mt_ignore_duplicates</varname> (integer)</title>
 	    <para>
 		Ignore duplicated prefixes when loading data.
 	    </para>
 	    <para>
 		<emphasis>
 		    Default value is 0.
 		</emphasis>
 	    </para>
 	    <example>
 		<title>Set <varname>mt_ignore_duplicates</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("mtree", "mt_ignore_duplicates", 1)
 ...
 </programlisting>
 	    </example>
 	</section>
 
0e806316
 	<section id="mtree.p.mt_allow_duplicates">
1d593737
 	    <title><varname>mt_allow_duplicates</varname> (integer)</title>
 	    <para>
 		Allow duplicate prefixes when loading data.
 	    </para>
 	    <para>
 		<emphasis>
 		    Default value is 0.
 		</emphasis>
 	    </para>
 	    <example>
 		<title>Set <varname>mt_allow_duplicates</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("mtree", "mt_allow_duplicates", 1)
 ...
 </programlisting>
 	    </example>
 	</section>
 
c9ba911f
 	</section>
b16d00ff
 
c9ba911f
     <section>
9114eebc
 	<title>Functions</title>
c9ba911f
  	<section>
7747872f
 	    <title id="mtree.f.mt_match">
c9ba911f
 		<function moreinfo="none">mt_match(mtree, pv, mode)</function>
 	    </title>
 	    <para>
c4b3b04e
 		Match 'pv' value against 'mtree'. If 'mtree' type is 0 or 2 and value
07643b70
 		of 'mode' is NOT 2, sets associated value of the longest matching prefix
 		to pseudo variable specified by pv_value parameter. If 'mtree' type is
c4b3b04e
 		0 or 2 and value of 'mode' is 2, sets values of all matching prefixes
 		to avp specified by pv_values parameter so that a value of longest
 		matching prefix is in avp index 0.  Parameter 'mode' can be an integer
 		constant or a pseudo variable with integer value.
af69a307
 	    </para>
 	    <para>
 	      Returns 1 if match succeeded and -1 otherwise.
c9ba911f
 	    </para>
 		<example>
 		<title><function>mt_match</function> usage</title>
 		<programlisting format="linespecific">
 ...
 mt_match("mytree", "$rU", "0");
 ...
 </programlisting>
 	    </example>
 	</section>
 
     </section>
 
 	<section>
b16d00ff
 	<title>RPC Commands</title>
 	<section id="mtree.rpc.list">
c9ba911f
 		<title>
b16d00ff
 		<function moreinfo="none">mtree.list</function>
c9ba911f
 		</title>
 		<para>
b16d00ff
 		List content of one or all trees.
c9ba911f
 		</para>
 		<para>
b16d00ff
 		Name: <emphasis>mtree.list</emphasis>
c9ba911f
 		</para>
 		<para>Parameters:</para>
 		<itemizedlist>
b16d00ff
 			<listitem><para>_mtree_ : name of tree to list (optional). </para></listitem>
c9ba911f
 		</itemizedlist>
b16d00ff
 		<example>
 		<title><function>mtree.list</function> rpc usage</title>
 		<programlisting format="linespecific">
 ...
 &kamcmd; mtree.list
 &kamcmd; mtree.list mytree
 ...
 </programlisting>
 	    </example>
0620105b
     </section>
b16d00ff
 	<section id="mtree.rpc.summary">
6d34982c
 		<title>
 		<function moreinfo="none">mtree.summary</function>
 		</title>
 		<para>
910224d3
 			List usage summary for all trees or for the tree whose name is
 			given as parameter.
6d34982c
 		</para>
910224d3
 		<para>Parameters:</para>
 		<itemizedlist>
 			<listitem><para>_mtree_ - (optional) the name of the tree.</para></listitem>
 		</itemizedlist>
b16d00ff
     </section>
 	<section id="mtree.rpc.reload">
0ff087e9
 		<title>
 		<function moreinfo="none">mtree.reload</function>
 		</title>
 		<para>
 		Reload mtree from database to memory.
 		</para>
 		<para>Parameters:</para>
 		<itemizedlist>
910224d3
 			<listitem><para>_mtree_</para> - name of mtree or empty string meaning all mtrees</listitem>
0ff087e9
 		</itemizedlist>
b16d00ff
     </section>
     <section id="mtree.rpc.match">
0620105b
 		<title>
 		<function moreinfo="none">mtree.match</function>
 		</title>
 		<para>
 		Match prefix value against mtree
 		</para>
 		<para>Parameters:</para>
 		<itemizedlist>
 			<listitem><para>_mtree_</para> - name of mtree</listitem>
 			<listitem><para>_prefix_</para> - match prefix</listitem>
 			<listitem><para>_mode_</para> - matching mode</listitem>
 		</itemizedlist>
b16d00ff
     </section>
     </section><!-- RPC commands -->
c9ba911f
 
 </chapter>