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

<chapter>
    <chapterinfo>
	<revhistory>
	    <revision>
		<revnumber>$Revision: 1.1.10.1 $</revnumber>
		<date>$Date: 2005/06/22 23:12:06 $</date>
	    </revision>
	</revhistory>
    </chapterinfo>
    <title>User's Guide</title>
    
    <section>
	<title>Overview</title>
	<para>
	    The module implements all the operations regarding MaX-Forward header field, like adding
	    it (if not present) or decrementing and checking the value of the existent one.
	</para>
    </section>
    <section>
	<title>Dependencies</title>
	<section>
	    <title>&ser; Modules</title>
	    <para>
		The following modules must be loaded before this module:
	    	<itemizedlist>
		    <listitem>
			<para>
			    <emphasis>No dependencies on other &ser; 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
		&ser; with this module loaded:
	    	<itemizedlist>
		    <listitem>
			<para>
			    <emphasis>None</emphasis>.
			</para>
		    </listitem>
	    	</itemizedlist>
	    </para>
	</section>
    </section>

    <section>
	<title>Exported Parameters</title>
	<section>
	    <title><varname>max_limit</varname> (integer)</title>
	    <para>
		This parameters limits the maximum value of
		mf_process_maxfwd_header function parameter. Values bigger than
		the value of this parameter will be rejected and SER will
		refuse to start. The limit can be disabled by setting this
		parameter to 0.
	    </para>
	    <para>
		Default value is 16.
	    </para>
	</section>
    </section>

    <section>
	<title>Exported Functions</title>
	<section>
	    <title>
		<function moreinfo="none">mf_process_maxfwd_header(max_value)</function>
	    </title>
	    <para>
		If no Max-Forward header is present in the received request, a header will be added
		having the original value equal with <quote>max_value</quote>. An OK code is
		returned by the function.
	    </para>
	    <para>
		If a Max-Forward header is already present, its value will be decremented. If after
		this operation its value will be positive non-zero, an OK code will be
		returned. Otherwise (for a zero value) an error code will be returned.  Note that an
		error code will be also returned if the &sip; message couldn't be parsed or if the
		Max-Forward header's body invalid (non numerical string or negative numerical value).
	    </para>
	    <para>Meaning of the parameters is as follows:</para>
	    <itemizedlist>
		<listitem>
		    <para><emphasis>max_value</emphasis> - Value to be added if there is no
		    Max-Forwards header field in the message.
		    </para>
		</listitem>
	    </itemizedlist>
	    <example>
		<title><function>mx_process_maxfwd_header</function> usage</title>
		<programlisting format="linespecific">
...
# initial sanity checks -- messages with
# max_forwards==0, or excessively long requests
if (!mf_process_maxfwd_header("10")) {
    sl_send_reply("483","Too Many Hops");
    break;
};
...
</programlisting>
	    </example>
	</section>
    </section>
</chapter>

<!-- Keep this element at the end of the file
Local Variables:
sgml-parent-document: ("maxfwd.sgml" "Book" "chapter")
End:
-->
