kamailio/modules/dialplan

dialplan Module

Andreea-Ancuta Onofrei

Voice Sistem SRL

Edited by

Andreea-Ancuta Onofrei

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 name of the database table used 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 after match
(see attrs_pvar )

Default value is "attrs".

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

5.11. attrs_pvar (string)

The pseudovariable used to store the rule's attributes, after
translation (when dp_translate() succeeds). This parameter can be an
"AVP" or a script variable ("$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 in the dialplan identified by "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 the 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.