dialplan Module
Andreea-Ancuta Onofrei
Voice Sistem SRL
Edited by
Andreea-Ancuta Onofrei
Copyright © 2007-2008 voice-system.ro
Revision History
Revision $Revision: 5895 $ $Date: 2009-07-20 17:11:05 +0300
(Mon, 20 Jul 2009) $
__________________________________________________________
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. db_url (string)
1.6.2. table_name (string)
1.6.3. dpid_col (string)
1.6.4. pr_col (string)
1.6.5. match_op_col (string)
1.6.6. match_exp_col (string)
1.6.7. match_len_col (string)
1.6.8. subst_exp_col (string)
1.6.9. repl_exp_col (string)
1.6.10. attrs_col (string)
1.6.11. attrs_pvar (string)
1.6.12. fetch_rows (int)
1.7. Exported Functions
1.7.1. dp_translate(id, src/dest)
1.8. Exported MI Functions
1.8.1. dp_reload
1.8.2. dp_translate
1.9. Installation
2. Developer's Guide
List of Examples
1.1. Set db_url parameter
1.2. Set table_name parameter
1.3. Set dpid_col parameter
1.4. Set pr_col parameter
1.5. Set match_op_col parameter
1.6. Set match_exp_col parameter
1.7. Set pr_col parameter
1.8. Set pr_col parameter
1.9. Set repl_exp_col parameter
1.10. Set attrs_col parameter
1.11. Set attrs_pvar parameter
1.12. Set fetch_rows parameter
1.13. dp_translate usage
1.14. 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 a set of transformation rules
from a database. Every database raw 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 rules via regexp 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.
1.3. Usage cases
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).
Also the module can be used for detecting range or sets of
numbers mapped on a service/case - attributes 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.
1.4. Database structure and usage
Depending what kind of operation (translation, matching, etc)
you want to do with the module, you need to appropriate
populate the 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 expresion
that will be used to match with this rule (if the rule
should be applied for the input string)
* match_len = 0 (not used for regexp op)
* subst_exp = "^(0040|\+40|0|40)(.+)" ; regular expresion
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 fix value
* match-op = 1 (regexp)
* match_exp = "^((Germany)|(Germania)|(Deutschland)|(DE))" ;
regular expresion that will be used to match with this rule
(if the rule should be applied for the input string)
* match_len = 0 (not used for regexp op)
* 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 expresion that will
be used to match with this rule (if the rule should be
applied for the input string)
* match_len = 0 (not used for regexp op)
* 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 fix string/number and replace it with something
fix.
* match-op = 0 (equal)
* match_exp = "SIP server" ; string to be matched
* match_len = 10
* 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. db_url (string)
The translation rules will be loaded using this database url.
Default value is
"mysql://opensips:opensipsrw@localhost/opensips".
Example 1.1. Set db_url parameter
...
modparam("dialplan", "db_url", "mysql://user:passwb@localhost/db")
...
1.6.2. table_name (string)
The table's name from which to load the translation rules.
Default value is "dialplan".
Example 1.2. Set table_name parameter
...
modparam("dialplan", "table_name", "my_table")
...
1.6.3. dpid_col (string)
The column name to store the dialplan ID group.
Default value is "dpid".
Example 1.3. Set dpid_col parameter
...
modparam("dialplan", "dpid_col", "column_name")
...
1.6.4. pr_col (string)
The column name to store the priority of the corresponding rule
from the database raw.
Default value is "pr".
Example 1.4. Set pr_col parameter
...
modparam("dialplan", "pr_col", "column_name")
...
1.6.5. match_op_col (string)
The column name to store the type of matching of the rule.
Default value is "match_op".
Example 1.5. Set match_op_col parameter
...
modparam("dialplan", "match_op_col", "column_name")
...
1.6.6. match_exp_col (string)
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")
...
1.6.7. match_len_col (string)
The column name to store the length of a string matching the
match expression.
Default value is "match_len".
Example 1.7. Set pr_col parameter
...
modparam("dialplan", "match_len_col", "column_name")
...
1.6.8. subst_exp_col (string)
The column name to store the rule's substitution expression.
Default value is "subst_exp".
Example 1.8. Set pr_col parameter
...
modparam("dialplan", "subst_exp_col", "column_name")
...
1.6.9. repl_exp_col (string)
The column name to store the rule's replacement expression.
Default value is "repl_exp".
Example 1.9. Set repl_exp_col parameter
...
modparam("dialplan", "repl_exp_col", "column_name")
...
1.6.10. attrs_col (string)
The column name to store the rule's attributes to be set to the
message.
Default value is "attrs".
Example 1.10. Set attrs_col parameter
...
modparam("dialplan", "attrs_col", "column_name")
...
1.6.11. attrs_pvar (string)
The pvar to store the rule's attributes, after translation
(dp_translate() succeeds). This parameter can be any PVAR that
can be written.
Default value is "NULL".
Example 1.11. Set attrs_pvar parameter
...
modparam("dialplan", "attrs_pvar", "$avp(s:dest)")
...
1.6.12. fetch_rows (int)
The number of rows to be fetched at once from database/
Default value is "1000".
Example 1.12. Set fetch_rows parameter
...
modparam("dialplan", "fetch_rows", 4000)
...
1.7. Exported Functions
1.7.1. dp_translate(id, src/dest)
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 the possible matching rules. This
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 interger 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 writtable one.
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");
...
1.8. Exported MI Functions
1.8.1. dp_reload
It will update the translation rules, loading the database
info.
Name: dp_reload
Parameters: none
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
* Dial plan ID
* Input String
MI DATAGRAM Command Format:
:dp_translate:
dpid
input
_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: 2009-07-20 17:11:05 +0300
(Mon, 20 Jul 2009) $
The module does not provide any API to use in other OpenSIPS
modules.
