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

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
		This is a module to help with &sdp; mangling.
		Note: This module is obselete and will be removed for the 1.5.0 release.
	</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>No dependencies on other &osips; modules</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_contact_flds_separator" xreflabel="contact_flds_separator">
		<title><varname>contact_flds_separator</varname> (string)</title>
		<para>
		First char of this parameter is used as separator for encoding/decoding 
		Contact header.
		</para>
		<warning>
		<para>
			First char of this field must be set to a value which is not used 
			inside username,password or other fields of contact. Otherwise it 
			is possible for the decoding step to fail/produce wrong results.
		</para>
		</warning>
		<para>
		<emphasis>
			Default value is <quote>*</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>db_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("mangler", "contact_flds_separator", "-")
...
</programlisting>
		</example>
		<para>
		then an encoded uri might look 
		sip:user-password-ip-port-protocol@PublicIP
		</para>
	</section>

	</section>
	<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
	<section id="func_sdp_mangle_ip" xreflabel="sdp_mangle_ip()">
		<title>
		<function moreinfo="none">sdp_mangle_ip(pattern, newip)</function>
		</title>
		<para>
		Changes &ip; addresses inside &sdp; package in lines describing 
		connections like c=IN IP4 Currently in only changes IP4 addresses 
		since IP6 probably will not need to traverse NAT :)
		</para>
		<para>
		The function returns negative on error, or number of replacements + 1.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>pattern</emphasis> (string) - A pair ip/mask used to match 
			&ip;'s located inside &sdp; package in lines c=IN IP4 ip. This 
			lines will only be mangled if located &ip; is in the network 
			described by this pattern. Examples of
			valid patterns are <quote>10.0.0.0/255.0.0.0</quote> or
			<quote>10.0.0.0/8</quote> etc.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>newip</emphasis> (string) - the new 
			&ip; to be put inside &sdp; package if old &ip; address matches 
			pattern.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE.
		</para>
		<example>
		<title><function>sdp_mangle_ip</function> usage</title>
		<programlisting format="linespecific">
...
sdp_mangle_ip("10.0.0.0/8","193.175.135.38");
...
</programlisting>
		</example>
	</section>

	<section id="func_sdp_mangle_port" xreflabel="sdp_mangle_port()">
		<title>
		<function moreinfo="none">sdp_mangle_port(offset)</function>
		</title>
		<para>
		Changes ports inside &sdp; package in lines describing media like 
		m=audio 13451.
		</para>
		<para>
		The function returns negative on error, or number of replacements + 1.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>offset</emphasis> (int) - an integer which will
			be added/subtracted from the located port.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE.
		</para>
		<example>
		<title><function>sdp_mangle_port</function> usage</title>
		<programlisting format="linespecific">
...
sdp_mangle_port(-12000);
...
</programlisting>
		</example>
	</section>

	<section id="func_encode_contact" xreflabel="encode_contact()">
		<title>
		<function moreinfo="none">encode_contact(encoding_prefix, public_ip)</function>
		</title>
		<para>
		This function will encode uri-s inside Contact header in the following 
		manner
		sip:username:password@ip:port;transport=protocol goes
		sip:enc_pref*username*ip*port*protocol@public_ip * is the default 
		separator.
		</para>
		<para>
		The function returns negative on error, 1 on success.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>encoding_prefix</emphasis> (string) - Something to allow us 
			to determine that a contact is encoded publicip--a routable &ip;, 
			most probably you should
			put your external &ip; of your &nat; box.
			</para>
			<para><emphasis>public_ip</emphasis> (string) - The public IP which will be
			used in the encoded contact, as described by the example above.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE.
		</para>
		<example>
		<title><function>encode_contact</function> usage</title>
		<programlisting format="linespecific">
...
if ($si == 10.0.0.0/8) encode_contact("enc_prefix","193.175.135.38"); 
...
</programlisting>
		</example>
	</section>

	<section id="func_decode_contact" xreflabel="decode_contact()">
		<title>
		<function moreinfo="none">decode_contact()</function>
		</title>
		<para>
		This function will decode the &uri; in first line in packets which 
		come with encoded &uri; in the following manner 
		sip:enc_pref*username*ip*port*protocol@public_ip goes to
		sip:username:password@ip:port;transport=protocol It uses the default 
		set parameter for contact encoding separator.
		</para>
		<para>
		The function returns negative on error, 1 on success.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>decode_contact</function> usage</title>
		<programlisting format="linespecific">
...
if ($ru =~ "^enc*") { decode_contact(); }
...
</programlisting>
		</example>
	</section>

	<section id="func_decode_contact_header" xreflabel="decode_contact_header()">
		<title>
		<function moreinfo="none">decode_contact_header()</function>
		</title>
		<para>
		This function will decode &uri;s inside Contact header in the 
		following manner sip:enc_pref*username*ip*port*protocol@public_ip goes 
		to sip:username:password@ip:port;transport=protocol. It uses the 
		default set parameter for contact encoding separator.
		</para>
		<para>
		The function returns negative on error, 1 on success.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE.
		</para>
		<example>
		<title><function>decode_contact_header</function> usage</title>
		<programlisting format="linespecific">
...
if ($ru =~ "^enc*") { decode_contact_header(); }
...
</programlisting>
		</example>
	</section>
	</section>
</chapter>

