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

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
		This module provides on-server speed dial facilities. An user can store
		records consisting of pairs short numbers (2 digits) and SIP addresses
		into a table of OpenSIPS. Then it can dial the two digits whenever it
		wants to call the SIP address associated with them.
	</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>
				<emphasis>database module (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
		&osips; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>
	<section id="exported_parameters" xreflabel="Exported Parameters">
	<title>Exported Parameters</title>
	<section id="param_db_url" xreflabel="db_url">
		<title><varname>db_url</varname> (string)</title>
		<para>
		The URL of database where the table containing speed dial records.
		</para>
		<para>
		<emphasis>
			Default value is &defaultrodb;.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>db_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("speeddial", "db_url", "mysql://user:xxx@localhost/db_name")
...
</programlisting>
		</example>
	</section>
	<section id="param_user_column" xreflabel="user_column">
		<title><varname>user_column</varname> (string)</title>
		<para>
		The name of column storing the user name of the owner of the speed dial
		record.
		</para>
		<para>
		<emphasis>
			Default value is <quote>username</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>user_column</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("speeddial", "user_column", "userid")
...
</programlisting>
		</example>
	</section>
	<section id="param_domain_column" xreflabel="domain_column">
		<title><varname>domain_column</varname> (string)</title>
		<para>
		The name of column storing the domain of the owner of the speed dial
		record.
		</para>
		<para>
		<emphasis>
			Default value is  <quote>domain</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>domain_column</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("speeddial", "domain_column", "userdomain")
...
</programlisting>
		</example>
	</section>
	<section id="param_sd_user_column" xreflabel="sd_user_column">
		<title><varname>sd_user_column</varname> (string)</title>
		<para>
		The name of the column storing the user part of the short dial address.
		</para>
		<para>
		<emphasis>
			Default value is  <quote>sd_username</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>sd_user_column</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("speeddial", "sd_user_column", "short_user")
...
</programlisting>
		</example>
	</section>
	<section id="param_sd_domain_column" xreflabel="sd_domain_column">
		<title><varname>sd_domain_column</varname> (string)</title>
		<para>
		The name of the column storing the domain of the short dial address.
		</para>
		<para>
		<emphasis>
			Default value is  <quote>sd_domain</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>sd_domain_column</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("speeddial", "sd_domain_column", "short_domain")
...
</programlisting>
		</example>
	</section>
	<section id="param_new_uri_column" xreflabel="new_uri_column">
		<title><varname>new_uri_column</varname> (string)</title>
		<para>
		The name of the column containing the URI that will be use to replace
		the short dial URI.
		</para>
		<para>
		<emphasis>
			Default value is <quote>new_uri</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>new_uri_column</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("speeddial", "new_uri_column", "real_uri")
...
</programlisting>
		</example>
	</section>
	<section id="param_domain_prefix" xreflabel="domain_prefix">
		<title><varname>domain_prefix</varname> (string)</title>
		<para>
		If the domain of the owner (From URI) starts with the value of this parameter, then
		it is stripped before performing the lookup of the short number.
		</para>
		<para>
		<emphasis>
			Default value is NULL.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>domain_prefix</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("speeddial", "domain_prefix", "tel.")
...
</programlisting>
		</example>
	</section>
	<section id="param_use_domain" xreflabel="use_domain">
		<title><varname>use_domain</varname> (int)</title>
		<para>
		The parameter specifies wheter or not to use the domain when searching a
		speed dial record (0 - no domain, 1 - use domain from From URI,
		2 - use both domains, from From URI and from request URI).
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>use_domain</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("speeddial", "use_domain", 1)
...
</programlisting>
		</example>
	</section>
	</section>
	<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
	<section id="func_sd_lookup" xreflabel="sd_lookup()">
		<title>
		<function moreinfo="none">sd_lookup(table [, owner])</function>
		</title>
		<para>
		The function lookups the short dial number from R-URI in 'table' and replaces the R-URI with associated address.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>table</emphasis> (string) - The name of the table storing the
			speed dial records.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>owner</emphasis> (string) - The SIP URI of the owner of
			short dialing codes. If not pressent, URI of From header is used.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>sd_lookup</function> usage</title>
		<programlisting format="linespecific">
...
# 'speed_dial' is the default table name created by opensips db script
if($ru=~"sip:[0-9]{2}@.*")
	sd_lookup("speed_dial");
# use auth username
if($ru=~"sip:[0-9]{2}@.*")
	sd_lookup("speed_dial", "sip:$au@$fd");
...
</programlisting>
		</example>
	</section>
	</section>
	<section>
	<title>Installation and Running</title>
		<section>
		<title>&osips; config file</title>
		<para>
		Next picture displays a sample usage of speeddial.
		</para>
		<example>
		<title>&osips; config script - sample speeddial usage</title>
		<programlisting format="linespecific">
...
&speeddialcfg;
...
		</programlisting>
		</example>
	</section>
	</section>
</chapter>

