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

src/modules/uac_redirect/README

@@ -1,2 +1,405 @@
+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();
+}