modules: readme files regenerated - uac_redirect ... [skip ci]

src/modules/uac_redirect/README

@@ -1,405 +1,2 @@
-UAC_REDIRECT Module
 
-Bogdan-Andrei Iancu
 
-   Voice System
-
-Edited by
-
-Bogdan-Andrei Iancu
-
-   Copyright © 2005 Voice Sistem
-     __________________________________________________________________
-
-   Table of Contents
-
-   1. Admin Guide
-
-        1. Overview
-        2. Accounting
-        3. Dependencies
-
-              3.1. Kamailio Modules
-              3.2. External Libraries or Applications
-
-        4. Parameters
-
-              4.1. default_filter (string)
-              4.2. deny_filter (string)
-              4.3. accept_filter (string)
-              4.4. acc_function (string)
-              4.5. acc_db_table (string)
-              4.6. bflags (int)
-
-        5. Functions
-
-              5.1. set_deny_filter(filter,flags)
-              5.2. set_accept_filter(filter,flags)
-              5.3. get_redirects(max)
-              5.4. get_redirects(max,reason)
-
-        6. Script Example
-
-   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 acc_function parameter
-   1.5. Set acc_db_table parameter
-   1.6. Set bflags module parameter
-   1.7. set_deny_filter usage
-   1.8. set_accept_filter usage
-   1.9. get_redirects usage
-   1.10. get_redirects usage
-   1.11. Redirection script example
-
-Chapter 1. Admin Guide
-
-   Table of Contents
-
-   1. Overview
-   2. Accounting
-   3. Dependencies
-
-        3.1. Kamailio Modules
-        3.2. External Libraries or Applications
-
-   4. Parameters
-
-        4.1. default_filter (string)
-        4.2. deny_filter (string)
-        4.3. accept_filter (string)
-        4.4. acc_function (string)
-        4.5. acc_db_table (string)
-        4.6. bflags (int)
-
-   5. Functions
-
-        5.1. set_deny_filter(filter,flags)
-        5.2. set_accept_filter(filter,flags)
-        5.3. get_redirects(max)
-        5.4. get_redirects(max,reason)
-
-   6. Script Example
-
-1. Overview
-
-   UAC REDIRECT - User Agent Client redirection - module enhance Kamailio
-   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.
-
-2. Accounting
-
-   UAC REDIRECT module allows to log all the redirection (to be later used
-   for CDR aggregation). This functionality may be dynamically enabled for
-   each redirection situation.
-
-   The logging will be done via the accounting module functions (all are
-   supported). The information to be logged will be the same as the normal
-   logged information directly via ACC module, but with following
-   differences:
-     * reason phrase - which will be dynamically set by the redirection
-       function;
-     * outgoing URI - which will be the redirect URI.
-
-   For each redirect contact, a separate record will be logged. For
-   example, if a call is redirected to three new contacts, the module will
-   log three additional records corresponding to each redirect URI.
-
-3. Dependencies
-
-   3.1. Kamailio Modules
-   3.2. External Libraries or Applications
-
-3.1. Kamailio 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.
-
-3.2. External Libraries or Applications
-
-   The following libraries or applications must be installed before
-   running Kamailio with this module loaded:
-     * None
-
-4. Parameters
-
-   4.1. default_filter (string)
-   4.2. deny_filter (string)
-   4.3. accept_filter (string)
-   4.4. acc_function (string)
-   4.5. acc_db_table (string)
-   4.6. bflags (int)
-
-4.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")
-...
-
-4.2. deny_filter (string)
-
-   The regular expression for default deny filtering. It makes sense to be
-   defined 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")
-...
-
-4.3. accept_filter (string)
-
-   The regular expression for default accept filtering. It makes sense to
-   be defined 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")
-...
-
-4.4. acc_function (string)
-
-   Specifies the accounting function to be used. Just by defining this
-   parameter, the accounting support will not be enabled. Accounting may
-   only be enabled via two parameters set_accept_filter() scripting
-   function.
-
-   Its values may be:
-     * acc_log_request
-     * acc_db_request
-     * acc_rad_request
-     * acc_diam_request
-
-   The default value is “acc_log_request”.
-
-   Example 1.4. Set acc_function parameter
-...
-modparam("uac_redirect","acc_function","acc_db_request")
-...
-
-4.5. acc_db_table (string)
-
-   Specifies the accounting table to be used if DB accounting was chosen
-   (acc_function was set to “acc_db_request”). Just by defining this
-   parameter, the accounting support will not be enabled. Accounting may
-   only be enabled via two parameters set_accept_filter() scripting
-   function.
-
-   The default value is “acc”.
-
-   Example 1.5. Set acc_db_table parameter
-...
-modparam("uac_redirect","acc_db_table","acc_redirect")
-...
-
-4.6. bflags (int)
-
-   This parameter defines the branch-flags to be set for new, added
-   branch.
-
-   This parameter is optional, it's default value being 0.
-
-   Example 1.6. Set bflags module parameter
-...
-modparam("uac_redirect","bflags", 1)
-...
-
-branch_route[1] {
-        if (isbflagset(1)) {
-                log(1, "This branch comes from a 302 Forward Request.\n");
-        } else {
-                log(1, "This is a regular branch.\n");
-        }
-}
-
-5. Functions
-
-   5.1. set_deny_filter(filter,flags)
-   5.2. set_accept_filter(filter,flags)
-   5.3. get_redirects(max)
-   5.4. get_redirects(max,reason)
-
-5.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.
-
-   Default or previous added deny filter may be reset depending of the
-   flag 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.7. set_deny_filter usage
-...
-set_deny_filter(".*@domain2.net","reset_all");
-set_deny_filter(".*@domain1.net","");
-...
-
-5.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.
-
-   Default or previous added deny filter may be reset depending of the
-   flag 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.8. set_accept_filter usage
-...
-set_accept_filter(".*@domain2.net","reset_added");
-set_accept_filter(".*@domain1.net","");
-...
-
-5.3.  get_redirects(max)
-
-   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 of the
-   max parameter values. Its syntax is:
-     * max = max_total [":" max_branch]
-     * max_total = number of total contacts to be selected
-     * max_branch = number of contacts per branch to be selected
-
-   Both “max_total” and “max_branch” are positive integer. To specify
-   unlimited values, use 0 value or "*" character.
-
-   NOTE that during the selection process, each set of contacts from a
-   specific branch are ordered based on “q” value.
-
-   This function will produce no accounting records.
-
-   This function can be used from FAILURE_ROUTE.
-
-   Example 1.9. get_redirects usage
-...
-# max 2 contacts per branch, but no overall limit
-get_redirects("*:2");
-...
-# no limits per branch, but not more than 6 overall contacts
-get_redirects("6:*");
-...
-# no restrictions
-get_redirects("*");
-...
-
-5.4.  get_redirects(max,reason)
-
-   The function has same functionality as get_redirects(max) function, but
-   it will produce accounting records.
-
-   The accounting records will be mark by the reason phrase.
-
-   If this function appears in the script, at startup, the module will
-   import the accounting function. Otherwise not.
-
-   This function can be used from FAILURE_ROUTE.
-
-   Example 1.10. get_redirects usage
-...
-get_redirects("4:1","Redirected");
-...
-
-6. Script Example
-
-   Example 1.11. 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)
-
-request_route{
-        if (uri==myself) {
-
-                if (method=="REGISTER") {
-                        save("location");
-                        exit;
-                }
-
-                if (!lookup("location")) {
-                        sl_send_reply("404", "Not Found");
-                        exit;
-                }
-                # do redirect with accounting
-                t_on_failure("REDIRECT_ACC");
-        } else {
-                # just do redirect
-                t_on_failure("REDIRECT_NOACC");
-        }
-
-        if (!t_relay()) {
-                sl_reply_error();
-        }
-}
-
-# redirect without storing acc record
-failure_route[REDIRECT_NOACC] {
-        if(!t_check_status("3[0-9][0-9]")) {
-                exit;
-        }
-        get_redirects("3:1");
-        t_relay();
-}
-
-# redirect with storing acc record
-failure_route[REDIRECT_ACC] {
-        if(!t_check_status("3[0-9][0-9]")) {
-                exit;
-        }
-        get_redirects("6:2", "redirect");
-        t_relay();
-}