UAC_REDIRECT 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. default_filter (string)
              1.3.2. deny_filter (string)
              1.3.3. accept_filter (string)

        1.4. Exported Functions

              1.4.1. set_deny_filter(filter,flags)
              1.4.2. set_accept_filter(filter,flags)
              1.4.3. get_redirects([max_total], [max_branch])

        1.5. Script Example

   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 default_filter module parameter
   1.2. Set deny_filter module parameter
   1.3. Set accept_filter module parameter
   1.4. set_deny_filter usage
   1.5. set_accept_filter usage
   1.6. get_redirects usage
   1.7. Redirection script example

Chapter 1. Admin Guide

1.1. Overview

   UAC REDIRECT - User Agent Client redirection - module enhance
   OpenSIPS with the functionality of being able to handle
   (interpret, filter, log and follow) redirect responses ( 3xx
   replies class).

   UAC REDIRECT module offer stateful processing, gathering the
   contacts from all 3xx branches of a call.

   The module provide a powerful mechanism for selecting and
   filtering the contacts to be used for the new redirect:
     * number based - limits like the number of total contacts to
       be used or the maximum number of contacts per branch to be
       selected.
     * Regular Expression based - combinations of deny and accept
       filters allow a strict control of the contacts to be used
       for redirection.

   When selecting from a 3xx branch the contacts to be used, the
   contacts will be ordered and prioritized based on the “q”
   value.

1.2. Dependencies

1.2.1. OpenSIPS Modules

   The following modules must be loaded before this module:
     * TM - Transaction Module, for accessing replies.
     * ACC - Accounting Module, but only if the logging feature is
       used.

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. default_filter (string)

   The default behavior in filtering contacts. It may be “accept”
   or “deny”.

   The default value is “accept”.

   Example 1.1. Set default_filter module parameter
...
modparam("uac_redirect","default_filter","deny")
...

1.3.2. deny_filter (string)

   The regular expression for default deny filtering. It make sens
   to be defined on only if the default_filter parameter is set to
   “accept”. All contacts matching the deny_filter will be
   rejected; the rest of them will be accepted for redirection.

   The parameter may be defined only one - multiple definition
   will overwrite the previous definitions. If more regular
   expression need to be defined, use the set_deny_filter()
   scripting function.

   This parameter is optional, it's default value being NULL.

   Example 1.2. Set deny_filter module parameter
...
modparam("uac_redirect","deny_filter",".*@siphub\.net")
...

1.3.3. accept_filter (string)

   The regular expression for default accept filtering. It make
   sens to be defined on only if the default_filter parameter is
   set to “deny”. All contacts matching the accept_filter will be
   accepted; the rest of them will be rejected for redirection.

   The parameter may be defined only one - multiple definition
   will overwrite the previous definitions. If more regular
   expression need to be defined, use the set_accept_filter()
   scripting function.

   This parameter is optional, it's default value being NULL.

   Example 1.3. Set accept_filter module parameter
...
modparam("uac_redirect","accept_filter",".*@siphub\.net")
...

1.4. Exported Functions

1.4.1.  set_deny_filter(filter,flags)

   Sets additional deny filters. Maximum 6 may be combined. This
   additional filter will apply only to the current message - it
   will not have a global effect.

   Parameters:
     * filter (string) - regular expression
     * flags (string)
       Default or previous added deny filter may be reset
       depending of the parameter value:
          + reset_all - reset both default and previous added deny
            filters;
          + reset_default - reset only the default deny filter;
          + reset_added - reset only the previous added deny
            filters;
          + empty - no reset, just add the filter.

   This function can be used from FAILURE_ROUTE.

   Example 1.4. set_deny_filter usage
...
set_deny_filter(".*@domain2.net","reset_all");
set_deny_filter(".*@domain1.net","");
...

1.4.2.  set_accept_filter(filter,flags)

   Sets additional accept filters. Maximum 6 may be combined. This
   additional filter will apply only to the current message - it
   will not have a global effect.

   Parameters:
     * filter (string) - regular expression
     * flags (string)
       Default or previous added deny filter may be reset
       depending of the parameter value:
          + reset_all - reset both default and previous added
            accept filters;
          + reset_default - reset only the default accept filter;
          + reset_added - reset only the previous added accept
            filters;
          + empty - no reset, just add the filter.

   This function can be used from FAILURE_ROUTE.

   Example 1.5. set_accept_filter usage
...
set_accept_filter(".*@domain2.net","reset_added");
set_accept_filter(".*@domain1.net","");
...

1.4.3.  get_redirects([max_total], [max_branch])

   The function may be called only from failure routes. It will
   extract the contacts from all 3xx branches and append them as
   new branches. Note that the function will not forward the new
   branches, this must be done explicitly from script.

   How many contacts (in total and per branch) are selected
   depends on the max_total and max_branch parameters:
     * max_total (int, optional) - max overall number of contacts
       to be selected
     * max_branch (int, optional) - max number of contacts per
       branch to be selected

   Both “max_total” and “max_branch” default to 0 (unlimited).

   NOTE that during the selection process, each set of contacts
   from a specific branch are ordered based on “q” value.

   This function can be used from FAILURE_ROUTE.

   Example 1.6. get_redirects usage
...
# no restrictions
get_redirects();
...
# no limits per branch, but not more than 6 overall contacts
get_redirects(6);
...
# max 2 contacts per branch, but no overall limit
get_redirects(, 2);
...

1.5. Script Example

   Example 1.7. Redirection script example
loadmodule "modules/sl/sl.so"
loadmodule "modules/usrloc/usrloc.so"
loadmodule "modules/registrar/registrar.so"
loadmodule "modules/tm/tm.so"
loadmodule "modules/acc/acc.so"
loadmodule "modules/uac_redirect/uac_redirect.so"

modparam("usrloc", "db_mode",   0)

route{
        if (is_myself("$rd")) {

                if ($rm=="REGISTER") {
                        save("location");
                        exit;
                };

                if (!lookup("location")) {
                        sl_send_reply(404, "Not Found");
                        exit;
                };
        }

        t_on_failure("do_redirect");

        if (!t_relay()) {
                sl_reply_error();
        };
}

failure_route[do_redirect] {
        if (get_redirects(3, 1))
                t_relay();
}


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 29 1711 143
   2. Liviu Chircu (@liviuchircu) 18 10 106 372
   3. Daniel-Constantin Mierla (@miconda) 12 10 24 20
   4. Rob Gagnon (@rgagnon24) 8 6 50 48
   5. Razvan Crainea (@razvancrainea) 8 6 11 10
   6. Henning Westerholt (@henningw) 7 5 12 11
   7. Vlad Patrascu (@rvlad-patrascu) 5 3 25 6
   8. Maksym Sobolyev (@sobomax) 4 2 3 4
   9. Anca Vamanu 3 1 30 55
   10. Konstantin Bokarius 3 1 2 5

   All remaining contributors: Andreas Granig, Peter Lemenkov
   (@lemenkov), Edson Gellert Schubert, Elena-Ramona Modroiu,
   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.  Maksym Sobolyev (@sobomax)          Feb 2023 - Feb 2023
   2.  Bogdan-Andrei Iancu (@bogdan-iancu) Jun 2005 - Feb 2022
   3.  Razvan Crainea (@razvancrainea)     Feb 2012 - Sep 2019
   4.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - Apr 2019
   5.  Liviu Chircu (@liviuchircu)         Mar 2014 - Apr 2019
   6.  Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018
   7.  Rob Gagnon (@rgagnon24)             Mar 2015 - Mar 2015
   8.  Walter Doekes (@wdoekes)            May 2014 - May 2014
   9.  Daniel-Constantin Mierla (@miconda) Nov 2006 - Mar 2008
   10. Konstantin Bokarius                 Mar 2008 - Mar 2008

   All remaining contributors: Edson Gellert Schubert, Henning
   Westerholt (@henningw), Anca Vamanu, Andreas Granig,
   Elena-Ramona Modroiu.

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

Chapter 3. Documentation

3.1. Contributors

   Last edited by: Bogdan-Andrei Iancu (@bogdan-iancu), Vlad
   Patrascu (@rvlad-patrascu), Liviu Chircu (@liviuchircu), Peter
   Lemenkov (@lemenkov), Rob Gagnon (@rgagnon24), Razvan Crainea
   (@razvancrainea), Daniel-Constantin Mierla (@miconda),
   Konstantin Bokarius, Edson Gellert Schubert, Henning Westerholt
   (@henningw).

   Documentation Copyrights:

   Copyright © 2005 Voice Sistem SRL
