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

<chapter>
	
	<title>&adminguide;</title>


	<section id="overview" xreflabel="Overview">
		<title>Overview</title>
		<para>
		UAC REDIRECT - User Agent Client redirection - module enhance &osips;
		with the functionality of being able to handle (interpret, filter,
		log and follow) redirect responses ( 3xx replies class).
		</para>
		<para>
		UAC REDIRECT module offer stateful processing, gathering the
		contacts from all 3xx branches of a call.
		</para>
		<para>
		The module provide a powerful mechanism for selecting and filtering 
		the contacts to be used for the new redirect:
		</para>
		<itemizedlist>
			<listitem>
			<para><emphasis>number based</emphasis> - limits like the 
			number of total contacts to be used or the maximum number of 
			contacts per branch to be selected.
			</para>
			</listitem>
			<listitem>
			<para><emphasis>Regular Expression based</emphasis> - combinations
			of deny and accept filters allow a strict control of the 
			contacts to be used for redirection.
			</para>
			</listitem>
		</itemizedlist>
		<para>
		When selecting from a 3xx branch the contacts to be used, the contacts
		will be ordered and prioritized based on the <quote>q</quote> value.
		</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>TM</emphasis> - Transaction Module, for accessing
				replies.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>ACC</emphasis> - Accounting Module, but only if the
				logging feature is used.
			</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_default_filter" xreflabel="default_filter">
			<title><varname>default_filter</varname> (string)</title>
			<para>
			The default behavior in filtering contacts. It may be 
			<quote>accept</quote> or <quote>deny</quote>.
			</para>
			<para>
				<emphasis>
					The default value is <quote>accept</quote>.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>default_filter</varname> 
					module parameter</title>
				<programlisting format="linespecific">
...
modparam("uac_redirect","default_filter","deny")
...
				</programlisting>
			</example>
		</section>
		<section id="param_deny_filter" xreflabel="deny_filter">
			<title><varname>deny_filter</varname> (string)</title>
			<para>
			The regular expression for default deny filtering. It make sens
			to be defined on only if the <varname>default_filter</varname>
			parameter is set to <quote>accept</quote>. All contacts matching
			the <varname>deny_filter</varname> will be rejected; the rest 
			of them will be accepted for redirection.
			</para>
			<para>
			The parameter may be defined only one - multiple definition will
			overwrite the previous definitions. If more regular expression 
			need to be defined, use the 
			<function moreinfo="none">set_deny_filter()</function> scripting
			function.
			</para>
			<para>
				<emphasis>
					This parameter is optional, it's default 
					value being NULL.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>deny_filter</varname> 
					module parameter</title>
				<programlisting format="linespecific">
...
modparam("uac_redirect","deny_filter",".*@siphub\.net")
...
				</programlisting>
			</example>
		</section>
		<section id="param_accept_filter" xreflabel="accept_filter">
			<title><varname>accept_filter</varname> (string)</title>
			<para>
			The regular expression for default accept filtering. It make sens
			to be defined on only if the <varname>default_filter</varname>
			parameter is set to <quote>deny</quote>. All contacts matching
			the <varname>accept_filter</varname> will be accepted; the rest 
			of them will be rejected for redirection.
			</para>
			<para>
			The parameter may be defined only one - multiple definition will
			overwrite the previous definitions. If more regular expression 
			need to be defined, use the 
			<function moreinfo="none">set_accept_filter()</function> scripting
			function.
			</para>
			<para>
				<emphasis>
					This parameter is optional, it's default 
					value being NULL.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>accept_filter</varname> 
					module parameter</title>
				<programlisting format="linespecific">
...
modparam("uac_redirect","accept_filter",".*@siphub\.net")
...
				</programlisting>
			</example>
		</section>
	</section>


	<section id="exported_functions" xreflabel="exported_functions">
		<title>Exported Functions</title>
		<section id="func_set_deny_filter" xreflabel="set_deny_filter()">
			<title>
				<function moreinfo="none">set_deny_filter(filter,flags)
					</function>
			</title>
			<para>
			Sets additional deny filters. Maximum 6 may be combined. This
			additional filter will apply only to the current message - it
			will not have a global effect.
			</para>
			<para>Parameters:</para>
			<itemizedlist>
				<listitem><para>
					<emphasis>filter</emphasis> (string) - regular expression
				</para></listitem>
				<listitem><para>
					<emphasis>flags</emphasis> (string)</para>
					<para>
					Default or previous added deny filter may be reset depending of
					the parameter value:
					</para>
					<itemizedlist>
						<listitem>
						<para><emphasis>reset_all</emphasis> - reset both default
						and previous added deny filters;
						</para>
						</listitem>
						<listitem>
						<para><emphasis>reset_default</emphasis> - reset only the
						default deny filter;
						</para>
						</listitem>
						<listitem>
						<para><emphasis>reset_added</emphasis> - reset only the 
						previous added deny filters;
						</para>
						</listitem>
						<listitem>
						<para><emphasis>empty</emphasis> - no reset, just add the
						filter.
						</para>
						</listitem>
					</itemizedlist>
				</listitem>
			</itemizedlist>
			<para>
			This function can be used from FAILURE_ROUTE.
			</para>
			<example>
				<title><function>set_deny_filter</function> usage</title>
				<programlisting format="linespecific">
...
set_deny_filter(".*@domain2.net","reset_all");
set_deny_filter(".*@domain1.net","");
...
				</programlisting>
			</example>
		</section>

		<section id="func_set_accept_filter" xreflabel="set_accept_filter()">
			<title>
				<function moreinfo="none">set_accept_filter(filter,flags)
					</function>
			</title>
			<para>
			Sets additional accept filters. Maximum 6 may be combined. This
			additional filter will apply only to the current message - it
			will not have a global effect.
			</para>
			<para>Parameters:</para>
			<itemizedlist>
				<listitem><para>
					<emphasis>filter</emphasis> (string) - regular expression
				</para></listitem>
				<listitem><para>
					<emphasis>flags</emphasis> (string)</para>
					<para>
					Default or previous added deny filter may be reset depending of
					the parameter value:
					</para>
					<itemizedlist>
						<listitem>
						<para><emphasis>reset_all</emphasis> - reset both default
						and previous added accept filters;
						</para>
						</listitem>
						<listitem>
						<para><emphasis>reset_default</emphasis> - reset only the
						default accept filter;
						</para>
						</listitem>
						<listitem>
						<para><emphasis>reset_added</emphasis> - reset only the 
						previous added accept filters;
						</para>
						</listitem>
						<listitem>
						<para><emphasis>empty</emphasis> - no reset, just add
						the filter.
						</para>
						</listitem>
					</itemizedlist>
				</listitem>
			</itemizedlist>
			<para>
			This function can be used from FAILURE_ROUTE.
			</para>
			<example>
				<title><function>set_accept_filter</function> usage</title>
				<programlisting format="linespecific">
...
set_accept_filter(".*@domain2.net","reset_added");
set_accept_filter(".*@domain1.net","");
...
				</programlisting>
			</example>
		</section>

		<section id="func_get_redirects" xreflabel="get_redirects()">
			<title>
				<function moreinfo="none">get_redirects([max_total], [max_branch])</function>
			</title>
			<para>
				The function may be called only from failure routes. It will
				extract the contacts from all 3xx branches and append them
				as new branches. Note that the function will not forward the
				new branches, this must be done explicitly from script.
			</para>
			<para>
				How many contacts (in total and per branch) are selected 
				depends on the <emphasis>max_total</emphasis> and
				<emphasis>max_branch</emphasis> parameters:
			</para>
			<itemizedlist>
				<listitem><para>
				max_total (int, optional) - max overall number of contacts to be selected
				</para></listitem>
				<listitem><para>
				max_branch (int, optional) - max number of contacts per branch to be selected
				</para></listitem>
			</itemizedlist>
			<para>
				Both <quote>max_total</quote> and <quote>max_branch</quote>
				default to 0 (unlimited).
			</para>
			<para>
				NOTE that during the selection process, each set of contacts 
				from a specific branch are ordered based on <quote>q</quote> 
				value.
			</para>
			<para>
				This function can be used from FAILURE_ROUTE.
			</para>
			<example>
				<title><function>get_redirects</function> usage</title>
				<programlisting format="linespecific">
...
# no restrictions
get_redirects();
...
# no limits per branch, but not more than 6 overall contacts
get_redirects(6);
...
# max 2 contacts per branch, but no overall limit
get_redirects(, 2);
...
				</programlisting>
			</example>
		</section>
	</section>

	<section>
		<title>Script Example</title>
		<example>
			<title>Redirection script example</title>
				<programlisting format="linespecific">
loadmodule "modules/sl/sl.so"
loadmodule "modules/usrloc/usrloc.so"
loadmodule "modules/registrar/registrar.so"
loadmodule "modules/tm/tm.so"
loadmodule "modules/acc/acc.so"
loadmodule "modules/uac_redirect/uac_redirect.so"

modparam("usrloc", "db_mode",   0)

route{
	if (is_myself("$rd")) {

		if ($rm=="REGISTER") {
			save("location");
			exit;
		};

		if (!lookup("location")) {
			sl_send_reply(404, "Not Found");
			exit;
		};
	}

	t_on_failure("do_redirect");

	if (!t_relay()) {
		sl_reply_error();
	};
}

failure_route[do_redirect] {
	if (get_redirects(3, 1))
		t_relay();
}

				</programlisting>
			</example>

	</section>



</chapter>

