maxfwd Module

Bogdan-Andrei Iancu

   voice-system.ro

Edited by

Bogdan-Andrei Iancu

   Copyright  2003 FhG FOKUS
     __________________________________________________________

   Table of Contents
   1. User's Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. OpenSER Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. max_limit (integer)

        1.4. Exported Functions

              1.4.1. mf_process_maxfwd_header(max_value)
              1.4.2. is_maxfwd_lt(max_value)

   2. Developer's Guide
   3. Frequently Asked Questions

   List of Examples
   1-1. Set max_limit parameter
   1-2. mx_process_maxfwd_header usage
   1-3. is_maxfwd_lt usage
     __________________________________________________________

Chapter 1. User's Guide

1.1. Overview

   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.
     __________________________________________________________

1.2. Dependencies

1.2.1. OpenSER Modules

   The following modules must be loaded before this module:

     * No dependencies on other OpenSER modules.
     __________________________________________________________

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSER with this module loaded:

     * None.
     __________________________________________________________

1.3. Exported Parameters

1.3.1. max_limit (integer)

   Set an upper limit for the max-forward value in the outgoing
   requests. If the header is present, the decremented value is
   not allowed to exceed this max_limits - if it does, the header
   value will by decreased to "max_limit".

   Note: This check is done when calling the
   mf_process_maxfwd_header() header.

   The range of values stretches from 1 to 256, which is the
   maximum MAX-FORWARDS value allowed by RFC 3261.

   Default value is "256".

   Example 1-1. Set max_limit parameter
...
modparam("maxfwd", "max_limit", 32)
...
     __________________________________________________________

1.4. Exported Functions

1.4.1. mf_process_maxfwd_header(max_value)

   If no Max-Forward header is present in the received request, a
   header will be added having the original value equal with
   "max_value". If a Max-Forward header is already present, its
   value will be decremented (if not 0).

   Retuning codes:

     * 2 (true) - header was not found and a new header was
       succesfully added.
     * 1 (true) - header was found and its value was successfully
       decremented (had a non-0 value).
     * -1 (false) - the header was found and its value is 0
       (cannot be decremented).
     * -2 (false) - error during processing.

   The return code may be extensivly tested via script variable
   "retcode" (or "$?").

   Meaning of the parameters is as follows:

     * max_value - Value to be added if there is no Max-Forwards
       header field in the message.

   This function can be used from REQUEST_ROUTE.

   Example 1-2. mx_process_maxfwd_header usage
...
# initial sanity checks -- messages with
# max_forwards==0, or excessively long requests
if (!mf_process_maxfwd_header("10") && retcode==-1) {
        sl_send_reply("483","Too Many Hops");
        exit;
};
...
     __________________________________________________________

1.4.2. is_maxfwd_lt(max_value)

   Checks if the Max-Forward header value is less then the
   "max_value" parameter value. It considers also the value of the
   new inserted header (if locally added).

   Retuning codes:

     * 1 (true) - header was found or set and its value is stricly
       less than "max_value".
     * -1 (false) - the header was found or set and its value is
       greater or equal to "max_value".
     * -2 (false) - header was not found or not set.
     * -3 (false) - error during processing.

   The return code may be extensivly tested via script variable
   "retcode" (or "$?").

   Meaning of the parameters is as follows:

     * max_value - value to check the Max-Forward.value against
       (as less than).

   Example 1-3. is_maxfwd_lt usage
...
# next hope is a gateway, so make no sens to
# forward if MF is 0 (after decrement)
if ( is_maxfwd_lt("1") ) {
        sl_send_reply("483","Too Many Hops");
        exit;
};
...
     __________________________________________________________

Chapter 2. Developer's Guide

   The module does not provide any API to use in other OpenSER
   modules.
     __________________________________________________________

Chapter 3. Frequently Asked Questions

   3.1. Where can I find more about OpenSER?
   3.2. Where can I post a question about this module?
   3.3. How can I report a bug?

   3.1. Where can I find more about OpenSER?

   Take a look at http://openser.org/.

   3.2. Where can I post a question about this module?

   First at all check if your question was already answered on one
   of our mailing lists:

     * User Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/users
     * Developer Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/devel

   E-mails regarding any stable OpenSER release should be sent to
   <users@openser.org> and e-mails regarding development versions
   should be sent to <devel@openser.org>.

   If you want to keep the mail private, send it to
   <team@openser.org>.

   3.3. How can I report a bug?

   Please follow the guidelines provided at:
   http://sourceforge.net/tracker/?group_id=139143.
