<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<section id="mangler.functions" xmlns:xi="http://www.w3.org/2001/XInclude">
    <sectioninfo>
    </sectioninfo>

    <title>Functions</title>

    <section id="mangler.f.sdp_mangle_ip">
	<title>
	    <function>sdp_mangle_ip(pattern, newip)</function>
	</title>
	<para>
	    Changes IP addresses inside SDP document in lines describing
	    connections like c=IN IP4 . Currently this function 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> - An IP address/mask pair used to match
		    IP's located inside SDP package in lines c=IN IP4 ip. This
		    line will only be changed if located IP is in the network
		    described by this pattern. Examples of valid patterns are
		    "10.0.0.0/255.0.0.0" or "10.0.0.0/8" etc.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    <emphasis>newip</emphasis> - A string representing the new
		    IP to be put inside SDP package if old IP address
		    matches pattern.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>sdp_mangle_ip</function> usage</title>
	    <programlisting>
...
sdp_mangle_ip("10.0.0.0/8","193.175.135.38");
...
	    </programlisting>
	    </example>
    </section>
    
    <section id="mangler.f.sdp_mangle_port">
	<title>
	    <function>sdp_mangle_port(offset)</function>
	</title>
	<para>
	    Changes ports in SDP document in lines starting a media section 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> - A string representing an
		    integer which will be added/subtracted from the located
		    port.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>sdp_mangle_port</function> usage</title>
	    <programlisting>
...
sdp_mangle_port("-12000");
...
	    </programlisting>
	</example>
    </section>
    
    <section id="mangler.f.encode_contact">
	<title>
	    <function>encode_contact(encoding_prefix)</function>
	</title>
	<para>
	    This function will encode URIs inside the "Contact" header in the
	    following manner "sip:username:password@ip:port;transport=protocol"
	    goes <emphasis>sip:enc_pref*username*ip*port*protocol@public_ip</emphasis>.
	    "*" (asterisk) 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> - Something to allow
		    us to determine that a contact is encoded public IP--a
		    routable IP, most probably you should put your external IP
		    of your NAT box.
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>encode_contact</function> usage</title>
	    <programlisting>
...
if (src_ip == 10.0.0.0/8) encode_contact("enc_prefix","193.175.135.38"); 
...
	    </programlisting>
	</example>
    </section>
    
    <section id="mangler.f.decode_contact">
	<title>
	    <function>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
	    <emphasis>
	    sip:enc_pref*username*ip*port*protocol*src_ip*src_port*src_proto@public_ip;parameters
	    </emphasis>
	   is converted to
	    <emphasis>
	    sip:username:password@ip:port;parameters
	    </emphasis>
	    and will set destination URI to 
	    <emphasis>
	    sip:src_ip:src_port;transport=src_proto
	    </emphasis>
		(so that the next forward() or
		t_relay() will send the message back to src_ip:src_port using 
		src_proto). It uses the default set parameter for contact encoding 
		separator.
	</para>
	<para>
	    The function returns negative on error, 1 on success.
	</para>
	<example>
	    <title><function>decode_contact</function> usage</title>
	    <programlisting>
...
if (uri =~ "^enc*") { decode_contact(); }
...
	    </programlisting>
	</example>
    </section>
    
    <section id="mangler.f.decode_contact_header">
	<title>
	    <function>decode_contact_header()</function>
	</title>
	<para>
	    This function will decode URIs inside the "Contact" header in the
	    same manner as decode_contact(). The difference is that no dst_uri is set
		 (src_ip, src_port and src_proto are ignored) and instead of changing
		 the request URI, the Contact header URI is modified.
		 It uses the default set parameter for contact encoding separator.
	</para>
	<para>
	    The function returns negative on error, 1 on success.
	</para>
	<example>
	    <title><function>decode_contact_header</function> usage</title>
	    <programlisting>
...
if (uri =~ "^enc*") { decode_contact_header(); }
...
	    </programlisting>
	</example>
    </section>
</section>
