maxfwd Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. OpenSIPS 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. Contributors

        2.1. By Commit Statistics
        2.2. By Commit Activity

   3. Documentation

        3.1. Contributors

   List of Tables

   2.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   2.2. Most recently active contributors^(1) to this module

   List of Examples

   1.1. Set max_limit parameter
   1.2. mx_process_maxfwd_header usage
   1.3. is_maxfwd_lt usage

Chapter 1. Admin 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. OpenSIPS Modules

   The following modules must be loaded before this module:
     * No dependencies on other OpenSIPS modules.

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSIPS 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
       successfully 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 (int) - 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
       strictly 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 (int) - 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. Contributors

2.1. By Commit Statistics

   Table 2.1. Top contributors by DevScore^(1), authored
   commits^(2) and lines added/removed^(3)
     Name DevScore Commits Lines ++ Lines --
   1. Bogdan-Andrei Iancu (@bogdan-iancu) 47 31 868 490
   2. Liviu Chircu (@liviuchircu) 12 10 17 44
   3. Jan Janak (@janakj) 11 9 58 38
   4. Daniel-Constantin Mierla (@miconda) 11 9 23 19
   5. Andrei Pelinescu-Onciul 10 8 31 26
   6. Jiri Kuthan (@jiriatipteldotorg) 9 7 93 7
   7. Razvan Crainea (@razvancrainea) 8 6 9 8
   8. Vlad Patrascu (@rvlad-patrascu) 6 4 34 43
   9. Henning Westerholt (@henningw) 4 2 3 3
   10. Maksym Sobolyev (@sobomax) 4 2 2 3

   All remaining contributors: Konstantin Bokarius, Andreas Heise,
   Peter Lemenkov (@lemenkov), Edson Gellert Schubert, Nils
   Ohlmeier, Elena-Ramona Modroiu, Klaus Darilion, Walter Doekes
   (@wdoekes).

   (1) DevScore = author_commits + author_lines_added /
   (project_lines_added / project_commits) + author_lines_deleted
   / (project_lines_deleted / project_commits)

   (2) including any documentation-related commits, excluding
   merge commits. Regarding imported patches/code, we do our best
   to count the work on behalf of the proper owner, as per the
   "fix_authors" and "mod_renames" arrays in
   opensips/doc/build-contrib.sh. If you identify any
   patches/commits which do not get properly attributed to you,
   please submit a pull request which extends "fix_authors" and/or
   "mod_renames".

   (3) ignoring whitespace edits, renamed files and auto-generated
   files

2.2. By Commit Activity

   Table 2.2. Most recently active contributors^(1) to this module
                      Name                   Commit Activity
   1.  Bogdan-Andrei Iancu (@bogdan-iancu) Jan 2002 - Dec 2024
   2.  Liviu Chircu (@liviuchircu)         Jan 2014 - May 2024
   3.  Maksym Sobolyev (@sobomax)          Feb 2023 - Feb 2023
   4.  Razvan Crainea (@razvancrainea)     Feb 2012 - Sep 2019
   5.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - Apr 2019
   6.  Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018
   7.  Walter Doekes (@wdoekes)            May 2014 - May 2014
   8.  Daniel-Constantin Mierla (@miconda) Nov 2006 - Mar 2008
   9.  Konstantin Bokarius                 Mar 2008 - Mar 2008
   10. Edson Gellert Schubert              Feb 2008 - Feb 2008

   All remaining contributors: Henning Westerholt (@henningw),
   Klaus Darilion, Andreas Heise, Elena-Ramona Modroiu, Jan Janak
   (@janakj), Andrei Pelinescu-Onciul, Nils Ohlmeier, Jiri Kuthan
   (@jiriatipteldotorg).

   (1) including any documentation-related commits, excluding
   merge commits

Chapter 3. Documentation

3.1. Contributors

   Last edited by: Vlad Patrascu (@rvlad-patrascu), Liviu Chircu
   (@liviuchircu), Peter Lemenkov (@lemenkov), Razvan Crainea
   (@razvancrainea), Bogdan-Andrei Iancu (@bogdan-iancu),
   Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson
   Gellert Schubert, Klaus Darilion, Elena-Ramona Modroiu.

   Documentation Copyrights:

   Copyright © 2003 FhG FOKUS
