dialplan Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. How it works
        1.3. Usage cases
        1.4. Database structure and usage

              1.4.1. What to place in table

        1.5. Dependencies

              1.5.1. OpenSIPS Modules
              1.5.2. External Libraries or Applications

        1.6. Exported Parameters

              1.6.1. partition (string)
              1.6.2. db_url (string)
              1.6.3. table_name (string)
              1.6.4. dpid_col (string)
              1.6.5. pr_col (string)
              1.6.6. match_op_col (string)
              1.6.7. match_exp_col (string)
              1.6.8. match_flags_col (string)
              1.6.9. subst_exp_col (string)
              1.6.10. repl_exp_col (string)
              1.6.11. timerec_col (integer)
              1.6.12. disabled_col (integer)
              1.6.13. attrs_col (string)

        1.7. Exported Functions

              1.7.1. dp_translate([partition:]id, src/dest[,
                      attrs_pvar])

        1.8. Exported MI Functions

              1.8.1. dp_reload
              1.8.2. dp_translate
              1.8.3. dp_show_partiton

        1.9. Installation

   2. Developer's Guide
   3. Contributors

        3.1. By Commit Statistics
        3.2. By Commit Activity

   4. Documentation

        4.1. Contributors

   List of Tables

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

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

   List of Examples

   1.1. Set partition parameter
   1.2. Set default partition with partition parameter
   1.3. Set db_url parameter
   1.4. Set table_name parameter
   1.5. Set dpid_col parameter
   1.6. Set pr_col parameter
   1.7. Set match_op_col parameter
   1.8. Set match_exp_col parameter
   1.9. Set match_flags_col parameter
   1.10. Set subs_exp_col parameter
   1.11. Set repl_exp_col parameter
   1.12. Set timerec_col parameter
   1.13. Set disabled_col parameter
   1.14. Set attrs_col parameter
   1.15. dp_translate usage
   1.16. dp_translate usage
   1.17. dp_translate usage
   1.18. dp_translate usage

Chapter 1. Admin Guide

1.1. Overview

   This module implements generic string translations based on
   matching and replacement rules. It can be used to manipulate
   R-URI or a PV and to translated to a new format/value.

1.2. How it works

   At startup, the module will load all transformation rules from
   one or more dialplan-compatible tables. The data of each table
   will be stored in a partition which is defined by the "db_url"
   and "table_name" parameters. Every table row will be stored in
   memory as a translation rule. Each rule will describe how the
   matching should be made, how the input value should be modified
   and which attributes should be set for the matching
   transformation.

   A dialplan rule can be of two types:
     * "String matching" rule - performs a string equality test
       against the input string. The case of the characters can be
       ignored by enabling bit 1 of the rule's "match_flags"
       bitmask column (i.e. set the column value to 1 or 0, for
       insensitive or sensitive)
     * "Regex matching" rule - uses Perl Compatible Regular
       Expressions, and will attempt to match the rule's
       expression against an input string. The regex maching can
       be done in a caseless manner by enabling bit 1 of the
       rule's "match_flags" bitmask column (i.e. set the column
       value to 1 or 0, for insensitive or sensitive)

   The module provides the dp_translate() script function, which
   expects an input string value that will be matched, at worst,
   against all rules of a partition.

   Internally, the module groups a partition's rules into two
   sets, "string" and "regex". The matching logic will attempt to
   find the first match within each of these two sets of rules.
   Each set will be iterated in ascending order of priority. If an
   input string happens to match a rule in each of the two sets,
   the rule with the smallest priority will be chosen.
   Furthermore, should these two matching rules also have equal
   priorities, the one with the smallest "id" field (the unique
   key) will be chosen.

   Once a single rule is decided upon, the defined transformation
   (if any) is applied and the result is returned as output value.
   Also, if any string attribute is associated to the rule, this
   will be returned to the script along with the output value.

1.3. Usage cases

   The module can be used to implement dialplans - to do auto
   completion of the dialed numbers (e.g. national to
   international), to convert generic numbers to specific numbers
   (e.g. for emergency numbers).

   Also the module can be used for detecting ranges or sets of
   numbers mapped on a service/case - the "attributes" string
   column can be used here to store extra information about the
   service/case.

   Non-SIP string translation can also be implemented - like
   converting country names from all possible formats to a
   canonical format: (UK, England, United Kingdom) -> GB.

   Any other string-based translation or detection for whatever
   other purposes.

1.4. Database structure and usage

   Depending what kind of operation (translation, matching, etc)
   you want to do with the module, you need to populate the
   appropriate DB records.

   The definition of the tables used by the dialplan module can be
   found at
   http://www.opensips.org/html/docs/db/db-schema-devel.html#AEN15
   01

1.4.1. What to place in table

1.4.1.1. String translation (regexp detection, subst translation)

   Recognize a number block in all forms (international, national)
   and convert it to a canonical format (E.164)
     * match_op = 1 (regexp)
     * match_exp = "^(0040|\+40|0|40)21[0-9]+" ; regular
       expression that will be used to match with this rule (if
       the rule should be applied for the input string)
     * match_flags = 0 (0 - case sensitive, 1 - case insensitive
       matching)
     * subst_exp = "^(0040|\+40|0|40)(.+)" ; regular expression
       used to do the transformation (first part of the subst
       operation)
     * repl_exp = "40\2" ; second part of the subst (output) -
       linked to the subst_exp field; when both defined, they work
       as a subst()

1.4.1.2. String translation (regexp detection, replacement)

   Recognize the name of a country (multiple languages) and
   convert it to a single, fixed value
     * match_op = 1 (regexp)
     * match_exp = "^((Germany)|(Germania)|(Deutschland)|(DE))" ;
       regular expression that will be used to match with this
       rule (if the rule should be applied for the input string)
     * match_flags = 0 (0 - case sensitive, 1 - case insensitive
       matching)
     * subst_exp = NULL ; when translation is actually a
       replacement, this field must be NULL.
     * repl_exp = "DE" ; static string to replace the input -
       whenever this rule will match, it will return this string
       as output.

1.4.1.3. Number detection (regexp detection, no replacement)

   Recognize a block of numbers as belong to a single service and
   signalize this via an attribute.
     * match_op = 1 (regexp)
     * match_exp = "^021456[0-9]{5}" ; regular expression that
       will be used to match with this rule (if the rule should be
       applied for the input string)
     * match_flags = 0 (0 - case sensitive, 1 - case insensitive
       matching)
     * subst_exp = NULL ; no translation
     * repl_exp = NULL ; no translation
     * attrs = "serviceX" ; whatever string you will get into
       OpenSIPS script and it will provide you more information
       (totally custom)

1.4.1.4. String conversion (equal detection, replacement)

   Recognize a fixed string/number and replace it with something
   fixed.
     * match_op = 0 (equal)
     * match_exp = "SIP server" ; string to be matched
     * match_flags = 0 (0 - case sensitive, 1 - case insensitive
       matching)
     * subst_exp = NULL ; no subst translation
     * repl_exp = "OpenSIPS" ; output string

1.5. Dependencies

1.5.1. OpenSIPS Modules

   The following modules must be loaded before this module:
     * None

1.5.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSIPS with this module loaded:
     * libpcre-dev - the development libraries of PCRE.

1.6. Exported Parameters

1.6.1. partition (string)

   This can be used to define new db_url and table_name parameters
   from which to load the translation rules. These parameters will
   be held in partitions. The db_url parameter is mandatory. The
   order of the parameters does not matter. Multiple partitions
   can be defined and you can also define the default partition
   here. The name of this partition is "default". In order to be
   able to use a table from a partition, its name must be found in
   the "version" table belonging to the database defined in the
   partition's db_url.

   Example 1.1.  Set partition parameter
...
modparam("dialplan", "partition",
  "part2:table_name=dialplan;db_url=mysql://user:pw@localhost/db;")
...

   Example 1.2.  Set default partition with partition parameter
...
modparam("dialplan", "partition",
  "default:table_name=dialplan;db_url=mysql://user:pw@localhost/db;")
...

1.6.2. db_url (string)

   The translation rules will be loaded using this database
   url.This will be the db_url parameter value for the default
   partition.

   NOTE: if you intend to use the default partition you have to
   explicity set this default db_url, otherwise OpenSIPS will not
   start (he value of global default db_url is not inherited here!
   ).

   Example 1.3. Set db_url parameter
...
modparam("dialplan", "db_url", "mysql://user:passwb@localhost/db")
...

1.6.3. table_name (string)

   The table's name from which to load the translation rules.This
   will be the table_name parameter value for the default
   partition. The db_url must be defined for the default partition
   in order to be able to define it's table name.

   Default value is “dialplan”.

   Example 1.4. Set table_name parameter
...
modparam("dialplan", "table_name", "my_table")
...

1.6.4. dpid_col (string)

   The column name to store the dialplan ID group.

   Default value is “dpid”.

   Example 1.5. Set dpid_col parameter
...
modparam("dialplan", "dpid_col", "column_name")
...

1.6.5. pr_col (string)

   The column name to store the priority of the corresponding rule
   from the table row. Smaller priority values have higher
   precedence.

   Default value is “pr”.

   Example 1.6. Set pr_col parameter
...
modparam("dialplan", "pr_col", "column_name")
...

1.6.6. match_op_col (string)

   The column name to store the type of matching of the rule.

   Default value is “match_op”.

   Example 1.7. Set match_op_col parameter
...
modparam("dialplan", "match_op_col", "column_name")
...

1.6.7. match_exp_col (string)

   The column name to store the rule match expression.

   Default value is “match_exp”.

   Example 1.8. Set match_exp_col parameter
...
modparam("dialplan", "match_exp_col", "column_name")
...

1.6.8. match_flags_col (string)

   The column name to store various matching flags. Currently 0 -
   case sensitive matching, 1 - case insensitive matching.

   Default value is “match_flags”.

   Example 1.9. Set match_flags_col parameter
...
modparam("dialplan", "match_flags_col", "column_name")
...

1.6.9. subst_exp_col (string)

   The column name to store the rule's substitution expression.

   Default value is “subst_exp”.

   Example 1.10. Set subs_exp_col parameter
...
modparam("dialplan", "subst_exp_col", "column_name")
...

1.6.10. repl_exp_col (string)

   The column name to store the rule's replacement expression.

   Default value is “repl_exp”.

   Example 1.11. Set repl_exp_col parameter
...
modparam("dialplan", "repl_exp_col", "column_name")
...

1.6.11. timerec_col (integer)

   The column name that indicates an additional time recurrence
   check within the rule. (column values are RFC 2445-compatible
   strings)

   Default value is “timerec”.

   Example 1.12. Set timerec_col parameter
...
modparam("dialplan", "timerec_col", "month_match")
...

1.6.12. disabled_col (integer)

   The column name that indicates if the dialplan rule is
   disabled.

   Default value is “disabled”.

   Example 1.13. Set disabled_col parameter
...
modparam("dialplan", "disabled_col", "disabled_column")
...

1.6.13. attrs_col (string)

   The column name to store rule-specific attributes.

   Default value is “attrs”.

   Example 1.14. Set attrs_col parameter
...
modparam("dialplan", "attrs_col", "column_name")
...

1.7. Exported Functions

1.7.1.  dp_translate([partition:]id, src/dest[, attrs_pvar])

   Will try to translate the src string into dest string according
   to the translation rules with dialplan ID equal to id.

   Meaning of the parameters is as follows:
     * id - the dialplan id of possible matching rules. The id
       parameter can have the following types:
          + integer - the dialplan id is statically assigned
          + pvar - the dialplan id is the value of an existing
            pseudo-variable (as integer value)
     * partition - Specifies the partition where the search will
       take place. This parameter can be ommited. If the parameter
       is omitted the default partition will be used if exists.
       The partition parameter can have the following types:
          + string - the table name is statically assigned
          + pvar - the partition name is the value of an existing
            pseudo-variable (as string value)
     * src/dest - input and output of the function. If this
       parameter is missing the default parameter
       “ruri.user/ruri.user” will be used, thus translating the
       request uri.
       The “src” variable can be any type of pseudo-variable.
       The “dest” variable can be also any type of
       pseudo-variable, but it must be a writable one.
     * attrs_pvar (output, optional) - a pseudo-variable which
       will hold the attributes of the matched translation rule.

   This function can be used from REQUEST_ROUTE, BRANCH_ROUTE.

   Example 1.15. dp_translate usage
...
dp_translate("240", "$ruri.user/$avp(dest)");
xlog("translated to var $avp(dest) \n");
...

   Example 1.16. dp_translate usage
...
$avp(src) = $ruri.user;
dp_translate("$var(x)", "$avp(src)/$var(y)", "$var(attrs)");
xlog("translated to var $var(y) with attributes: '$var(attrs)'\n");
...

   Example 1.17. dp_translate usage
...
$avp(src) = $uri.user;
dp_translate("example_partition:$var(x)", "$avp(src)/$var(y)", "$avp(att
rs)");
xlog("translated to var $var(y) with attributes: '$avp(attrs)'\n");
...

   Example 1.18. dp_translate usage
...
$var(partition) = "default";
$var(id)        = 10;
dp_translate("$var(partition):$var(id)", "$avp(src)/$var(y)");
xlog("translate to var $var(y) partition $var(partition)")
...

1.8. Exported MI Functions

1.8.1. dp_reload

   It will update the translation rules, loading the database
   info.

   Name: dp_reload

   Parameters: 1
     * table_name - Partition to be reloaded. If no table is
       specified, the table specified in the "partition" parameter
       (default "default") will be reloaded.

   MI DATAGRAM Command Format:
                :dp_reload:
                _empty_line_

1.8.2. dp_translate

   It will apply a translation rule identified by a dialplan id
   and an input string.

   Name: dp_translate

   Parameters: 2
     * [Partition Name:]Dialplan ID - The dpid of the rules used
       to match the input string. The table name can be ommited.
       The default table is dialplan.
     * Input String

   MI DATAGRAM Command Format:
        :dp_translate:
        dpid
        input
        _empty_line_

1.8.3. dp_show_partiton

   Display partition(s) details.

   Name: dp_show_partiton

   Parameters: 2
     * Partition Name - The partition name. If no partition is
       specified, all known partitions will be listed.

   MI DATAGRAM Command Format:
        :dp_translate:
        default
        _empty_line_

1.9. Installation

   The modules requires one table in OpenSIPS database:
   dialplan.The SQL syntax to create them can be found in
   dialplan-create.sql script in the database directories in the
   opensips/scripts folder. You can also find the complete
   database documentation on the project webpage,
   http://www.opensips.org/html/docs/db/db-schema-devel.html.

Chapter 2. Developer's Guide

   Revision History
   Revision $Revision: 5895 $ $Date$

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

Chapter 3. Contributors

3.1. By Commit Statistics

   Table 3.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) 50 38 491 413
   2. Liviu Chircu (@liviuchircu) 44 28 725 509
   3. Ionut Ionita (@ionutrazvanionita) 41 20 1149 579
   4. Anca Vamanu 32 5 3263 19
   5. Andrei Dragus 25 3 382 1029
   6. Ovidiu Sas (@ovidiusas) 16 13 144 37
   7. Razvan Crainea (@razvancrainea) 16 12 81 128
   8. Eseanu Marius Cristian (@eseanucristian) 5 3 114 47
   9. Henning Westerholt (@henningw) 5 3 5 14
   10. Parantido Julius De Rica (@Parantido) 5 2 203 23

   All remaining contributors: Paul Wise, Sergio Gutierrez, Vlad
   Paiu (@vladpaiu), Rudy Pedraza, Juha Heinanen (@juha-h),
   UnixDev, David Sanders, Vlad Patrascu (@rvlad-patrascu).

   (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

3.2. By Commit Activity

   Table 3.2. Most recently active contributors^(1) to this module
                         Name                     Commit Activity
   1.  Liviu Chircu (@liviuchircu)              Jul 2012 - Nov 2018
   2.  Bogdan-Andrei Iancu (@bogdan-iancu)      Jun 2008 - Jun 2018
   3.  Razvan Crainea (@razvancrainea)          Dec 2010 - Jun 2017
   4.  Vlad Patrascu (@rvlad-patrascu)          May 2017 - May 2017
   5.  Ovidiu Sas (@ovidiusas)                  Sep 2008 - Nov 2015
   6.  Ionut Ionita (@ionutrazvanionita)        Jul 2014 - Nov 2015
   7.  David Sanders                            Sep 2015 - Sep 2015
   8.  Eseanu Marius Cristian (@eseanucristian) Jul 2015 - Jul 2015
   9.  Parantido Julius De Rica (@Parantido)    Sep 2014 - Sep 2014
   10. Vlad Paiu (@vladpaiu)                    Dec 2013 - Dec 2013

   All remaining contributors: Rudy Pedraza, Sergio Gutierrez,
   Paul Wise, Anca Vamanu, Andrei Dragus, UnixDev, Juha Heinanen
   (@juha-h), Henning Westerholt (@henningw).

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

Chapter 4. Documentation

4.1. Contributors

   Last edited by: Bogdan-Andrei Iancu (@bogdan-iancu), Liviu
   Chircu (@liviuchircu), Razvan Crainea (@razvancrainea), Ovidiu
   Sas (@ovidiusas), Ionut Ionita (@ionutrazvanionita), Andrei
   Dragus, Anca Vamanu.

   doc copyrights:

   Copyright © 2007-2008 Voice Sistem SRL
