kamailio/modules_s/nathelper/doc/functions.xml

<?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="nathelper.functions" xmlns:xi="http://www.w3.org/2001/XInclude">
    <sectioninfo>
    </sectioninfo>

    <title>Functions</title>

    <section id="fix_nated_contact">
	<title>
	    <function>fix_nated_contact()</function>
	</title>
	<para>
	    Rewrites Contact <acronym>HF</acronym> to contain request's source address:port.
	</para>
	<example>
	    <title><function>fix_nated_contact</function> usage</title>
	    <programlisting>
...
if (search("User-Agent: Cisco ATA.*") {fix_nated_contact();};
...
	    </programlisting>
	</example>
    </section>

    <section id="fix_nated_sdp">
	<title>
	    <function>fix_nated_sdp(mode)</function>
	</title>
	<para>
	    Rewrites Contact <acronym>HF</acronym> to contain request's source address:port.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para>
		    <emphasis>mode</emphasis> - 0x01 (add direction=active),
		    0x02 (rewrite media IP address with source address of the
		    message).
		</para>
	    </listitem>
	</itemizedlist>
	<example>
	    <title><function>fix_nated_sdp</function> usage</title>
	    <programlisting>
...
if (search("User-Agent: Cisco ATA.*") {fix_nated_sdp("3");};
...
	    </programlisting>
	</example>
    </section>

    <section id="add_rcv_param">
	<title>
	    <function>add_rcv_param()</function>
	</title>
	<para>
	    Add received parameter to Contact header fields. The parameter will
	    contain URI created from the source IP, port, and protocol of the
	    packet containing the SIP message. The parameter can be then
	    processed by another registrar, this is useful, for example, when
	    replicating register messages using t_replicate function to another
	    registrar.
	</para>
	<example>
	    <title><function>add_rcv_paramer</function> usage</title>
	    <programlisting>
...
add_rcv_param();
...
	    </programlisting>
	</example>
    </section>

    <section id="fix_nated_register">
	<title>
	    <function>fix_nated_register()</function>
	</title>
	<para>
	    The function creates a URI consisting of the source IP, port, and
	    protocol and stores the URI in an Attribute-Value-Pair. The URI
	    will be appended as "received" parameter to Contact in 200 OK and
	    registrar will store it in the user location database.
	</para>
	<example>
	    <title><function>fix_nated_register</function> usage</title>
	    <programlisting>
...
fix_nated_register();
...
	    </programlisting>
	</example>
    </section>

    <section id="nat_uac_test">
	<title>
	    <function>nat_uac_test(mode)</function>
	</title>
	<para>
	    Tries to guess if client's request originated behind a nat.  The
	    mode parameter determines what heuristics is used. If mode contains:
	</para>
	<itemizedlist>
	<listitem>
		<para>
			<emphasis>01</emphasis> - the Contact URI host contains a private IP address (from RFC1981).
		</para>
	</listitem>
	<listitem>
		<para>
			<emphasis>02</emphasis> - the address in the topmost Via header differs from the source IP address of the request.
		</para>
	</listitem>
	<listitem>
		<para>
			<emphasis>04</emphasis> - the address in the topmost Via contains a private IP address (RFC1918).
		</para>
	</listitem>
	<listitem>
		<para>
			<emphasis>08</emphasis> - the SDP body of the request contains a private IP address (RFC1918).
		</para>
	</listitem>
	<listitem>
		<para>
			<emphasis>16</emphasis> - the port in the topmost Via differs from the source port of the request.
		</para>
	</listitem>
	<listitem>
		<para>
			<emphasis>32</emphasis> - the Contact URI port differs from the source port of the request (Warning: this is might be legal or even intended combination in non natted scenarios).
		</para>
	</listitem>
	</itemizedlist>
	<para>
	All of them might be bitwise combined (which is equal to the sum of the 
	values from the list above). If one of the test matched the function
	returns true.
	</para>
    </section>

    <section id="ping_contact">
	<title>
	    <function>ping_contact(contact)</function>
	</title>
	<para>
	    Ping contact specified by parameter. It enables pinging independently
	    on <emphasis>usrloc</emphasis>. It may be processed e.g. via timer
	    module.
	</para>
	<example>
	    <title><function>ping_contact</function> usage</title>
	    <programlisting>
...
$c = @get_a_contact;
ping_contact($c);
...
	    </programlisting>
	</example>
    </section>

    <section id="nathelper.rewrite_contact">
	<title>
	    <function>@nathelper.rewrite_contact[n]</function>
	</title>
	<para>
	    Get n-th Contact value with IP:Port rewritten to source ip:port. N is counted from 1.
	    Only IP:port is rewritten, remaining part are left unchanged. Full nameaddr is supported.
	</para>
	<example>
	    <title><function>@nathelper.rewrite_contact</function> usage</title>
	    <programlisting>
...
$c = @nathelper.rewrite_contact[1];
...
$c2 = @nathelper.rewrite_contact[1].nameaddr.uri;
	    </programlisting>
	</example>
    </section>

</section>