mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
500 lines
12 KiB
500 lines
12 KiB
dialplan Module
|
|
|
|
Andreea-Ancuta Onofrei
|
|
|
|
Voice Sistem SRL
|
|
|
|
Edited by
|
|
|
|
Andreea-Ancuta Onofrei
|
|
|
|
Edited by
|
|
|
|
Juha Heinanen
|
|
|
|
Copyright © 2007-2008 Voice Sistem SRL
|
|
|
|
Copyright © 2008-2010 Juha Heinanen
|
|
__________________________________________________________________
|
|
|
|
Table of Contents
|
|
|
|
1. Admin Guide
|
|
|
|
1. Overview
|
|
2. How it works
|
|
3. Dialplan use cases
|
|
4. Dependencies
|
|
|
|
4.1. Kamailio Modules
|
|
4.2. External Libraries or Applications
|
|
|
|
5. Parameters
|
|
|
|
5.1. db_url (string)
|
|
5.2. table_name (string)
|
|
5.3. dpid_col (string)
|
|
5.4. pr_col (string)
|
|
5.5. match_op_col (string)
|
|
5.6. match_exp_col (string)
|
|
5.7. match_len_col (string)
|
|
5.8. subst_exp_col (string)
|
|
5.9. repl_exp_col (string)
|
|
5.10. attrs_col (string)
|
|
5.11. attrs_pvar (string)
|
|
5.12. fetch_rows (int)
|
|
|
|
6. Functions
|
|
|
|
6.1. dp_translate(id, [src[/dest]])
|
|
|
|
7. MI Commands
|
|
|
|
7.1. dp_reload
|
|
7.2. dp_translate
|
|
|
|
8. Exported RPC Commands
|
|
|
|
8.1. dialplan.reload
|
|
8.2. dialplan.translate
|
|
|
|
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
|
|
1.15. Example of rules
|
|
|
|
Chapter 1. Admin Guide
|
|
|
|
Table of Contents
|
|
|
|
1. Overview
|
|
2. How it works
|
|
3. Dialplan use cases
|
|
4. Dependencies
|
|
|
|
4.1. Kamailio Modules
|
|
4.2. External Libraries or Applications
|
|
|
|
5. Parameters
|
|
|
|
5.1. db_url (string)
|
|
5.2. table_name (string)
|
|
5.3. dpid_col (string)
|
|
5.4. pr_col (string)
|
|
5.5. match_op_col (string)
|
|
5.6. match_exp_col (string)
|
|
5.7. match_len_col (string)
|
|
5.8. subst_exp_col (string)
|
|
5.9. repl_exp_col (string)
|
|
5.10. attrs_col (string)
|
|
5.11. attrs_pvar (string)
|
|
5.12. fetch_rows (int)
|
|
|
|
6. Functions
|
|
|
|
6.1. dp_translate(id, [src[/dest]])
|
|
|
|
7. MI Commands
|
|
|
|
7.1. dp_reload
|
|
7.2. dp_translate
|
|
|
|
8. Exported RPC Commands
|
|
|
|
8.1. dialplan.reload
|
|
8.2. dialplan.translate
|
|
|
|
9. Installation
|
|
|
|
1. Overview
|
|
|
|
This module implements generic string translations based on matching
|
|
and replacement rules. It can be used to manipulate the request URI or
|
|
a PV and to translate to a new format/value.
|
|
|
|
2. How it works
|
|
|
|
At startup, the module will load a set of transformation rules from a
|
|
database. Rules are grouped into dialplans. Every database row will be
|
|
stored in memory as a translation rule. Each rule will describe how the
|
|
matching will be made, how the input value will be modified and which
|
|
attributes that will 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), string
|
|
or fnmatch (see 'man fnmatch') 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. This can be used to identify the used rule.
|
|
|
|
The first matching rule will be processed.
|
|
|
|
3. Dialplan use cases
|
|
|
|
The module can be used to implement multiple dialplans - do to
|
|
auto-completion of dialed numbers (like national to international), to
|
|
convert generic numbers to specific numbers (like for emergency
|
|
numbers).
|
|
|
|
The module can also be used for detecting a range or sets of numbers
|
|
mapped on a service/case - the attribute string can be used 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.
|
|
|
|
4. Dependencies
|
|
|
|
4.1. Kamailio Modules
|
|
4.2. External Libraries or Applications
|
|
|
|
4.1. Kamailio Modules
|
|
|
|
The following modules must be loaded before this module:
|
|
* A database module
|
|
|
|
4.2. External Libraries or Applications
|
|
|
|
The following libraries or applications must be installed before
|
|
running Kamailio with this module loaded:
|
|
* libpcre - the libraries of PCRE.
|
|
|
|
5. Parameters
|
|
|
|
5.1. db_url (string)
|
|
5.2. table_name (string)
|
|
5.3. dpid_col (string)
|
|
5.4. pr_col (string)
|
|
5.5. match_op_col (string)
|
|
5.6. match_exp_col (string)
|
|
5.7. match_len_col (string)
|
|
5.8. subst_exp_col (string)
|
|
5.9. repl_exp_col (string)
|
|
5.10. attrs_col (string)
|
|
5.11. attrs_pvar (string)
|
|
5.12. fetch_rows (int)
|
|
|
|
5.1. db_url (string)
|
|
|
|
The translation rules will be loaded using this database URL.
|
|
|
|
Default value is "mysql://kamailio:kamailiorw@localhost/kamailio".
|
|
|
|
Example 1.1. Set db_url parameter
|
|
...
|
|
modparam("dialplan", "db_url", "mysql://user:passwb@localhost/db")
|
|
...
|
|
|
|
5.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")
|
|
...
|
|
|
|
5.3. dpid_col (string)
|
|
|
|
The column name used to store the dialplan group ID.
|
|
|
|
Default value is "dpid".
|
|
|
|
Example 1.3. Set dpid_col parameter
|
|
...
|
|
modparam("dialplan", "dpid_col", "column_name")
|
|
...
|
|
|
|
5.4. pr_col (string)
|
|
|
|
The column name used to store the priority of the corresponding rule
|
|
from the database row.
|
|
|
|
Default value is "pr".
|
|
|
|
Example 1.4. Set pr_col parameter
|
|
...
|
|
modparam("dialplan", "pr_col", "column_name")
|
|
...
|
|
|
|
5.5. match_op_col (string)
|
|
|
|
The column name used 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")
|
|
...
|
|
|
|
5.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")
|
|
...
|
|
|
|
5.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")
|
|
...
|
|
|
|
5.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")
|
|
...
|
|
|
|
5.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")
|
|
...
|
|
|
|
5.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")
|
|
...
|
|
|
|
5.11. attrs_pvar (string)
|
|
|
|
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".
|
|
|
|
Example 1.11. Set attrs_pvar parameter
|
|
...
|
|
modparam("dialplan", "attrs_pvar", "$avp(s:dest)")
|
|
...
|
|
|
|
5.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)
|
|
...
|
|
|
|
6. Functions
|
|
|
|
6.1. dp_translate(id, [src[/dest]])
|
|
|
|
6.1. dp_translate(id, [src[/dest]])
|
|
|
|
Will try to translate src into dest according to the translation rules
|
|
with dialplan ID equal to id. If src/dest is missing the default
|
|
parameter "ruri.user/ruri.user" will be used, thus translating the
|
|
request uri user part. If only 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.
|
|
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 ANY_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");
|
|
...
|
|
|
|
7. MI Commands
|
|
|
|
7.1. dp_reload
|
|
7.2. dp_translate
|
|
|
|
7.1. dp_reload
|
|
|
|
Forces an update of the translation rules from the database.
|
|
|
|
Name: dp_reload
|
|
|
|
Parameters: none
|
|
|
|
MI DATAGRAM Command Format:
|
|
:dp_reload:
|
|
_empty_line_
|
|
|
|
7.2. dp_translate
|
|
|
|
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_
|
|
|
|
8. Exported RPC Commands
|
|
|
|
8.1. dialplan.reload
|
|
8.2. dialplan.translate
|
|
|
|
8.1. dialplan.reload
|
|
|
|
Forces an update of the translation rules from the database.
|
|
|
|
Name: dialplan.reload
|
|
|
|
Parameters: none
|
|
|
|
Example:
|
|
kamcmd dialplan.reload
|
|
|
|
8.2. dialplan.translate
|
|
|
|
Will apply a translation rule identified by a dialplan id and an input
|
|
string.
|
|
|
|
Name: dialplan.translate
|
|
|
|
Parameters: 2
|
|
* Dial plan ID
|
|
* Input String
|
|
|
|
Example:
|
|
# kamcmd dp_translate dpid "input"
|
|
kamcmd dp_translate 1 "abcdxyz"
|
|
|
|
9. Installation
|
|
|
|
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 from a 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: de
|
|
...
|
|
dpid: 1
|
|
pr: 2
|
|
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 dynamic name). References to SIP message,
|
|
private variables ($var(...)) and AVPs with static name are among those
|
|
that are safe to use in replacement expressions.
|
|
|
|
The match_op field specify matching operator, valid values: 0 - string
|
|
comparison; 1 - regular expression matching (pcre); 2 - fnmatch
|
|
(shell-like pattern) matching.
|
|
|
|
Chapter 2. Developer's Guide
|
|
|
|
The module does not provide any API to use in other Kamailio modules.
|