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

<chapter>
    <chapterinfo>
	<revhistory>
	    <revision>
		<revnumber>$Revision: 1827 $</revnumber>
		<date>$Date: 2007-03-12 17:22:53 +0200 (Mon, 12 Mar 2007) $</date>
	    </revision>
	</revhistory>
    </chapterinfo>
    <title>User's Guide</title>
    
    <section>
	<title>Overview</title>
	<para>
	    This module translates a numerical prefix into a domain and updates
		accordingly the request &uri;.
	</para>
	<para>
	    The module looks up at the R-&uri; part of a message and if the user
		part begins with an established prefix it will update the &uri;.
		Updating the uri consists of: remove the prefix from the user part of
		the uri and keep the rest as the user part of the new uri. The host
		and port are changed with the domain matched for the leading prefix and
		the domain in From URI.
	</para>
	<para>
	    &lt;prefix&gt;&lt;userid&gt;&lt;:password&gt;@&lt;mydomain.com&gt; ...
	</para>
	<para>
	    and the result will be:
	</para>
	<para>
	    &lt;userid&gt;&lt;:password&gt;@&lt;domain[:port]&gt;...
	</para>
	<example>
	    <title>prefix-domain translation</title>
	    <programlisting format="linespecific">
prefix=123, domain(FROM)=siphub.org

entry in database:
 sdomain=siphub.org
    domain[123]=alpha.org
    domain[124]=beta.org
    domain[125]=gamma.org
	
The RURI will be updated in the following way"
sip:12391001@mydomain.com  => sip:91001@alpha.org    
</programlisting>
	</example>
	<para>
	    The prefix could be prefixed by other digits. These digits
	    will not be used to look up the domain (the classic example, 00 used
		for international calls, then follows the country prefix). For more
		information on this, see 'prefix' parameter.
	</para>
	<itemizedlist>
	    <listitem>
		<para>
		    A sample config file and the <acronym>MySQL</acronym> script to
			create the database needed by PDT are located in './doc/'.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    Sample shell scripts to manage prefix-domain pairs are also located
			in './doc/' (pdt_fifo_add.sh, pdt_fifo_delete.sh, pdt_fifo_list.sh).
		</para>
	    </listitem>
	</itemizedlist>
    </section>
    <section>
	<title>Dependencies</title>
	<section>
	    <title>&ser; Modules</title>
	    <para>
		The following modules must be loaded before this module:
	    	<itemizedlist>
		    <listitem>
			<para>
			    <emphasis>A &ser; database module (e.g., mysql,
				dbtext)</emphasis>.
			</para>
		    </listitem>
	    	</itemizedlist>
	    </para>
	</section>
	<section>
	    <title>External Libraries or Applications</title>
	    <para>
		The following libraries or applications must be installed before running
		&ser; with this module loaded:
	    	<itemizedlist>
		    <listitem>
			<para>
			    <emphasis>None</emphasis>.
			</para>
		    </listitem>
	    	</itemizedlist>
	    </para>
	</section>
    </section>
    <section>
	<title>Exported Parameters</title>
	<section>
	    <title><varname>db_url</varname> (string)</title>
	    <para>
		<acronym>SQL</acronym> &url; of database--username, password, host,
		port and database (ex: mysql://username:password@hostname.com/database)
	    </para>
	    <para>
		<emphasis>
		    Default value is <quote>mysql://root@127.0.0.1/pdt</quote>.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>db_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("pdt", "db_url", "mysql://user:xxx@127.0.0.1/ser")
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>db_table</varname> (string)</title>
	    <para>
		Table name.
	    </para>
	    <para>
		<emphasis>
		    Default value is <quote>pdt</quote>.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>db_table</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("pdt", "db_table", "pdt")
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>sdomain_column</varname> (string)</title>
	    <para>
		Name of 'sdomain' column.
	    </para>
	    <para>
		<emphasis>
		    Default value is <quote>sdomain</quote>.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>sdomain_column</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("pdt", "domain_column", "source_domain")
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>prefix_column</varname> (string)</title>
	    <para>
		Name of 'prefix' column.
	    </para>
	    <para>
		<emphasis>
		    Default value is <quote>prefix</quote>.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>prefix_column</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("pdt", "prefix_column", "prefix")
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>domain_column</varname> (string)</title>
	    <para>
		Name of 'domain' column.
	    </para>
	    <para>
		<emphasis>
		    Default value is <quote>domain</quote>.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>domain_column</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("pdt", "domain_column", "hostname")
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>prefix</varname> (string)</title>
	    <para>
		Default leading prefix who denotes what &uri; needs to be translated
		- if it is NULL the module will not check the R-&uri; against it and
		the PDT prefix is considered starting from the first digit. Otherwise,
		the module will check first if the R-&uri; starts with it and will
		skip it to look up the domain.
	    </para>
	    <para>
		<emphasis>
		    Default value is NULL.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>prefix</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("pdt", "prefix", "00")
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>hsize_2pow</varname> (integer)</title>
	    <para>
		Number of the hash entries = 2^hash_size.
	    </para>
	    <para>
		<emphasis>
		    Default value is 4.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>hsize_2pow</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("pdt", "hsize_2pow", 4)
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>sync_time</varname> (integer)</title>
	    <para>
		Time in seconds to synchronize the cache of each process with the
		changes made through FIFO. Any prefix-domain change made through FIFO
		is guaranteed to have efect after this period of time past.
		</para>
	    <para>
		<emphasis>
		    Default value is 600.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>sync_time</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("pdt", "sync_time", 300)
...
</programlisting>
	    </example>
	</section>

	<section>
	    <title><varname>clean_time</varname> (integer)</title>
	    <para>
		Time in seconds to clean the changes inserted via FIFO. The changes
		will be removed from FIFO diff list only when all &ser; processes
		applied these changes.
		</para>
	    <para>
		<emphasis>
		    Default value is 900.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>clean_time</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("pdt", "clean_time", 600)
...
</programlisting>
	    </example>
	</section>

    </section>
	
    <section>
	<title>Exported Functions</title>
 	<section>
	    <title>
		<function moreinfo="none">prefix2domain(rewrite_mode, multidomain_mode)</function>
	    </title>
	    <para>
		Build a new &uri; if it is necessary. Returns 1 when the translation
		was made or there was nothing to translate (user part of the &uri; is
		empty, it does not match the prefix parameter or there is no domain
		associated with a possible prefix from user part).
		Returns -1 in error cases.
	    </para>
		<para>
		The translation is done based on lookup up for a entry in the database
		where the sdomain equals the domain in FROM uri, and the prefix matches
		the beginning of the user part of the RURI. If such an entry is found,
		then the domain in RURI is updated with the domain of this entry
		(sdomain, prefix, domain).
		</para>
		<para>
		There is also the possibility to have the translation of &uri; regardless of
		source domain. This can be achieved inserting in the database entries where
		sdomain has the value "*".
		</para>
		<para>
		The <quote>rewrite_mode</quote> parameter specifies whether to strip or not
		the prefix from user part. If the parameter is missing or it has the
		value <quote>0</quote>, then the prefix is removed along with the 
		leading prefix. If the value is <quote>1</quote>, only the leading
		prefix is removed. If the values is <quote>2</quote> the user part
		of the URI is not changed.
		</para>
		<para>
		The  <quote>multidomain_mode</quote> parameter specifies the kind of multidomain
		support to use. There are three possible values:
		<itemizedlist>
			<listitem><para>0 : Translation of &uri; regardless of source domain.</para>
			</listitem>	  
			<listitem><para>1 :  Translation of &uri; using as source domain the domain
			in From-URI.</para></listitem>			
			<listitem><para>2 :  Translation of &uri; using as source domain the domain
			in From-URI. In case there is no entry for the required sdomain, it tries 
			the translation using "*" as sdomain.</para></listitem>
		</itemizedlist>		
		</para>
	    <para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>prefix2domain</function> usage</title>
		<programlisting format="linespecific">
...
prefix2domain("2", "2");
...
</programlisting>
	    </example>
	</section>
	<section>
	    <title>
		<function moreinfo="none">prefix2domain(rewrite_mode)</function>
	    </title>
		<para>The same as prefix2domain(rewrite_mode, "0"), that is without 
		multidomain support, translation of  &uri; being done regardless of 
		the source domain.
		</para>
		<programlisting format="linespecific">
...
prefix2domain("2");
...
</programlisting>
    </section>
	
	<section>
	    <title>
		<function moreinfo="none">prefix2domain()</function>
	    </title>
		<para>The same as prefix2domain("0", "0").</para>
		<programlisting format="linespecific">
...
prefix2domain();
...
</programlisting>
    </section>
	
    </section>
	
		<section>
		<title>Exported MI Functions</title>
		<para>
		The modules uses only the cache to look up domains. If you want to
		add or delete a new prefix-domain pair you have to use MI FIFO commands.
		All changes made via these commands are applied to database, while the database
		is loaded only at &ser; start up time.
		</para>

	<section>
		<title>
		<function moreinfo="none">pdt_add</function>
		</title>
		<para>
		Adds a new sdomain-prefix-domain entry.
		</para>
		<para>
		Name: <emphasis>pdt_add</emphasis>
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>_sdomain_ : source domain</para></listitem>	  
			<listitem><para>_prefix_: prefix</para></listitem>			
			<listitem><para>_domain_: domain corresponding to a pair of source domain and prefix</para></listitem>
		</itemizedlist>
		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		:pdt_add:_reply_fifo_file_
		_sdomain_
		_prefix_
		_domain_
		_empty_line_
		</programlisting>
    </section>

	<section>
		<title>
		<function moreinfo="none">pdt_delete</function>
		</title>
		<para>
		Removes a sdomain-prefix-domain entry.
		</para>
		<para>
		Name: <emphasis>pdt_delete</emphasis>
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>_sdomain_ : a source domain</para></listitem>	  
			<listitem><para>_domain_: a domain associated via a prefix with the source domain</para></listitem>
		</itemizedlist>
		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		:pdt_delete:_reply_fifo_file_
		_sdomain_
		_domain_
		_empty_line_
		</programlisting>
    </section>

	<section>
		<title>
		<function moreinfo="none">pdt_list</function>
		</title>
		<para>
		Produces a listing of the entries prefixes/domains/sdomains.
		</para>
		<para>
		Name: <emphasis>pdt_list</emphasis>
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>_sdomain_ : a source domain value. </para></listitem>	  
			<listitem><para>_prefix_ : a prefix value</para></listitem>	 
            <listitem><para>_domain_: a domain value </para></listitem>
		</itemizedlist>
		<para>
		"." (dot) means NULL value
		</para> 
		<para>
		The comparison operation is 'START WITH' -- if domain is 'a' then all domains 
		starting with 'a' are listed.
		</para>
		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		:pdt_list:_reply_fifo_file_
		_sdomain_
		_prefix_
		_domain_
		_empty_line_
		</programlisting>
		<para>
		 Examples:
		 <itemizedlist>
			<listitem><para><quote>pdt_list siph 2 .</quote>  : Lists the entries where sdomain is 
			starting with 'siph', prefix is starting with '2' and domain is anything
			</para></listitem>	

			<listitem><para><quote>pdt_list siph 2</quote>  : Lists the entries where sdomain is 
			starting with 'siph', prefix is starting with '2' and domain is anything
			</para></listitem>	
	 
			 <listitem><para><quote>pdt_list . 2 open</quote>  : Lists the entries where sdomain 
			 is anything, prefix starts with '2' and domain starts with 'open'.
			</para></listitem>	
		</itemizedlist>
		<para>
    </section>
    </section>

    <section>
	<title>Installation & Running</title>
	<para>Make sure you have created the table needed by this module.</para>
    <para>
	Example shell scripts for MI FIFO commands are placed in './doc/'
	(pdt_fifo_add.sh, pdt_fifo_delete.sh, pdt_fifo_list.sh). 
	</para>
    </section>
</chapter>

<!-- Keep this element at the end of the file
Local Variables:
sgml-parent-document: ("pdt.sgml" "Book" "chapter")
End:
-->
