dialplan Module

Andreea-Ancuta Onofrei

   Voice Sistem SRL

Edited by

Andreea-Ancuta Onofrei

Edited by

Juha Heinanen

   Copyright © 2007-2008 voice-system.ro

   Copyright © 2008 Juha Heinanen
   Revision History
   Revision $Revision: 1.1 $ $Date: 2007/08/30 13:16:22 $
   Revision $Revision: 1.2 $ $Date: 2008/10/9 15:57 $
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. How it works
        1.3. Usage cases
        1.4. Dependencies

              1.4.1. Kamailio Modules
              1.4.2. External Libraries or Applications

        1.5. Exported Parameters

              1.5.1. db_url (string)
              1.5.2. table_name (string)
              1.5.3. dpid_col (string)
              1.5.4. pr_col (string)
              1.5.5. match_op_col (string)
              1.5.6. match_exp_col (string)
              1.5.7. match_len_col (string)
              1.5.8. subst_exp_col (string)
              1.5.9. repl_exp_col (string)
              1.5.10. attrs_col (string)
              1.5.11. attrs_pvar (string)
              1.5.12. fetch_rows (int)

        1.6. Exported Functions

              1.6.1. dp_translate(id, src/dest)

        1.7. Exported MI Functions

              1.7.1. dp_reload
              1.7.2. dp_translate

        1.8. 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 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 rules via regexp (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.

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. Dependencies

1.4.1. Kamailio Modules

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

1.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.

1.5. Exported Parameters

1.5.1. db_url (string)

   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")
...

1.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")
...

1.5.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.5.4. pr_col (string)

   The column name 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")
...

1.5.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.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")
...

1.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")
...

1.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")
...

1.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")
...

1.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")
...

1.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)")
...

1.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)
...

1.6. Exported Functions

1.6.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
          + 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.
       Input parameter src can be any pseudo variable. Output
       parameter dest can be:
          + R-URI
            - the string is the r-uri or r-uri username
          + 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");
...

1.7. Exported MI Functions

1.7.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.7.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.8. 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.

Chapter 2. Developer's Guide

   Revision History
   Revision $Revision: 1.1 $ $Date: 2007/08/30 13:16:22 $

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