Table of Contents
db_url (string)
table_name (string)
dpid_col (string)
pr_col (string)
match_op_col (string)
match_exp_col (string)
match_len_col (string)
subst_exp_col (string)
repl_exp_col (string)
attrs_col (string)
attrs_pvar (string)
fetch_rows (int)
List of Examples
db_url parametertable_name parameterdpid_col parameterpr_col parametermatch_op_col parametermatch_exp_col parameterpr_col parameterpr_col parameterrepl_exp_col parameterattrs_col parameterattrs_pvar parameterfetch_rows parameterdp_translate usagedp_translate usageTable of Contents
db_url (string)
table_name (string)
dpid_col (string)
pr_col (string)
match_op_col (string)
match_exp_col (string)
match_len_col (string)
subst_exp_col (string)
repl_exp_col (string)
attrs_col (string)
attrs_pvar (string)
fetch_rows (int)
This module implements generic string translations based on matching and replacement rules. It can be used to manipulate Request URI or a PV and to translated to a new format/value.
At startup, the module will load a set of transformation rules from a database. Every database 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.
The module expects an input value which will be matched against a rule by using regular expressions (see 'man pcresyntax' for syntax) or string matching. Overlapping matching expressions can be controlled via priorities. Once a rule is matched, 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.
The first matching rule will be processed.
The module can be used to implement dialplans - do to auto completion of the dial numbers (like national to international), to convert generic numbers to specific numbers (like for emergency numbers).
The module can also be used for detecting range or sets of numbers mapped on a service/case - attribute string can be used here to store extra information about the service/case.
Non-SIP string translation can be implemented - like converting country names from all possible formats to a canonical format: (UK, England, United Kingdom) -> GB.
Any other string-base translation or detection for whatever other purposes.
The following libraries or applications must be installed before running Kamailio with this module loaded:
libpcre - the libraries of PCRE.
The translation rules will be loaded using this database URL.
Default value is “mysql://openser:openserrw@localhost/openser”.
Example 1.1. Set db_url parameter
...
modparam("dialplan", "db_url", "mysql://user:passwb@localhost/db")
...
The table's name from which to load the translation rules.
Default value is “dialplan”.
The column name used to store the dialplan ID group.
Default value is “dpid”.
The column name used to store the priority of the corresponding rule from the database row.
Default value is “pr”.
The column name used to store the type of matching of the rule.
Default value is “match_op”.
The column name to store the rule match expression.
Default value is “match_exp”.
Example 1.6. Set match_exp_col parameter
...
modparam("dialplan", "match_exp_col", "column_name")
...
The column name to store the length of a string matching the match expression.
Default value is “match_len”.
The column name to store the rule's substitution expression.
Default value is “subst_exp”.
The column name to store the rule's replacement expression.
Default value is “repl_exp”.
The column name to store the rule's attributes to be set to the message.
Default value is “attrs”.
The pvar to store the rule's attributes, after translation (dp_translate() succeeds). This parameter can be an AVP or a SCRIPT VAR.
Default value is “NULL”.
Will try to translate src into dest according to the translation rules with dialplan ID equal to id. If dest is missing, only matching and storing of matching rule's attributes is done.
Returns 1, if translation succeeded, -1 in case of some error occurred, and -2 if dialplan with ID equal to id does not exist.
Meaning of the parameters is as follows:
id -the dialplan id of the possible matching rules. This parameter can have the following types:
integer- the dialplan id is statically assigned
avp var - the dialplan id is the value of an existing avp variable
script var - the dialplan id is the value of an existing script variable.
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 user part.
Input parameter src can be any pseudo variable. Output parameter dest can be:
R-URI
- the string is the r-uri or r-uri user part
avp var
- At input the function will get the input string from an existing avp variable. At output the function will add an avp with the value of the output string.
script var
- At input the function will get the input string from an existing script variable. At output the function will set an script variable with the value of the output string.
This function can be used from REQUEST_ROUTE, BRANCH_ROUTE.
Example 1.13. dp_translate usage
...
dp_translate("240", "$ruri.user/$avp(s:dest)");
xlog("translated to var $avp(s:dest) \n");
...
Example 1.14. dp_translate usage
...
$avp(s:src) = $ruri.user;
dp_translate("$var(x)", "$avp(s:src)/$var(y)");
xlog("translated to var $var(y) \n");
...
Forces an update of the translation rules from the database.
Name: dp_reload
Parameters: none
MI DATAGRAM Command Format:
:dp_reload: _empty_line_
Forces an update of the translation rules from the database.
Name: dialplan.reload
Parameters: none
Example:
sercmd dialplan.reload
The modules requires one table in Kamailio database: dialplan. The SQL syntax to create them can be found in dialplan-create.sql script in the database directories in the kamailio/scripts folder. You can also find the complete database documentation on the project webpage, http://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.
Some sample records fromd dialplan table are presented in the next figure.
Example 1.15. Example of rules
... dpid: 1 pr: 1 match_op: 1 match_exp: ^0([1-9][0-9]+)$ match_len: 0 subst_exp: ^0([1-9][0-9]+)$ repl_exp: 0049\1 attrs: xyz ... dpid: 1 pr: 1 match_op: 1 match_exp: ^0([1-9][0-9]+)$ match_len: 0 subst_exp: ^0(.+)$ repl_exp: $var(prefix)\1 attrs: xyz ...
Note that you can use config variables in the replacement expression (repl_exp) field. However, not all of config variables are safe to use there - specifically the variables that have in their name other variables (variables with dinamic name). References to sip message, private variables ($var(...)) and AVPs with static name are among those that are safe to use in replacement expressions.