Kamailio-开源SIP软交换平台

中国第一个专注Kamailio SIP 软交换技术分享平台

用户工具

站点工具


dialplan_dialplan_translation_module_released

差别

这里会显示出您选择的修订版和当前版本之间的差别。

到此差别页面的链接

dialplan_dialplan_translation_module_released [2017/09/11 11:17] (当前版本)
james_zhu 创建
行 1: 行 1:
 +====== dialplan Module ======
  
 +==== Andreea-Ancuta Onofrei ====
 +
 +Voice Sistem SRL\\ 
 +
 +=== Edited by ===
 +
 +==== Andreea-Ancuta Onofrei ====
 +
 +=== Edited by ===
 +
 +==== Juha Heinanen ====
 +
 +=== Edited by ===
 +
 +==== Olle E. Johansson ====
 +
 +=== Edited by ===
 +
 +==== Luis Martin ====
 +
 +Copyright © 2007-2008 Voice Sistem SRL
 +
 +Copyright © 2008-2010 Juha Heinanen
 +
 +Copyright © 2014 Olle E. Johansson, Edvina AB
 +
 +----
 +
 +**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)** ​
 +      * **5.13. match_dynamic (int)** ​
 +    * **6. Functions** ​
 +      * **6.1. dp_translate(id,​ [src%%[/​%%dest]])** ​
 +      * **6.2. dp_reload()** ​
 +    * **7. RPC Commands** ​
 +      * **7.1. dialplan.dump** ​
 +      * **7.2. dialplan.reload** ​
 +      * **7.3. dialplan.translate** ​
 +    * **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. Set match_dynamic parameter** ​
 +  * **1.14. dp_translate usage** ​
 +  * **1.15. dp_translate usage** ​
 +  * **1.16. 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)** ​
 +    * **5.13. match_dynamic (int)** ​
 +  * **6. Functions** ​
 +    * **6.1. dp_translate(id,​ [src%%[/​%%dest]])** ​
 +    * **6.2. dp_reload()** ​
 +  * **7. RPC Commands** ​
 +    * **7.1. dialplan.dump** ​
 +    * **7.2. dialplan.reload** ​
 +    * **7.3. dialplan.translate** ​
 +  * **8. 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 it to a new format/​value. Dialplan can also be used to match a given URI and retrieve a set of attributes based on the match. It is a very flexible module that can be used to handle call routing, prefix rewrites and much more.
 +
 +===== 2. How it works =====
 +
 +At startup the module will load a set of matching and transformation rules from a database. Rules are grouped into dialplans. Every database row will be stored in memory as a dialplan 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. One priority can have multiple dialplan entries. Priorities need not be numbered with consecutive numbers. The next higher priority will be used after trying to match all entries in one priority.
 +
 +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 - to do 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 ====
 +
 +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 [[http://​www.pcre.org/​|PCRE]]. ​
 +
 +===== 5. Parameters =====
 +
 +==== 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**
 +
 +<​code>​
 +...
 +modparam("​dialplan",​ "​db_url",​ "​mysql://​user:​passwb@localhost/​db"​)
 +...
 +</​code>​
 +
 +\\ ==== 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**
 +
 +<​code>​
 +...
 +modparam("​dialplan",​ "​table_name",​ "​my_table"​)
 +...
 +</​code>​
 +
 +\\ ==== 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**
 +
 +<​code>​
 +...
 +modparam("​dialplan",​ "​dpid_col",​ "​column_name"​)
 +...
 +</​code>​
 +
 +\\ ==== 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**
 +
 +<​code>​
 +...
 +modparam("​dialplan",​ "​pr_col",​ "​column_name"​)
 +...
 +</​code>​
 +
 +\\ ==== 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**
 +
 +<​code>​
 +...
 +modparam("​dialplan",​ "​match_op_col",​ "​column_name"​)
 +...
 +</​code>​
 +
 +\\ ==== 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**
 +
 +<​code>​
 +...
 +modparam("​dialplan",​ "​match_exp_col",​ "​column_name"​)
 +...
 +</​code>​
 +
 +\\ ==== 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**
 +
 +<​code>​
 +...
 +modparam("​dialplan",​ "​match_len_col",​ "​column_name"​)
 +...
 +</​code>​
 +
 +\\ ==== 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**
 +
 +<​code>​
 +...
 +modparam("​dialplan",​ "​subst_exp_col",​ "​column_name"​)
 +...
 +</​code>​
 +
 +\\ ==== 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**
 +
 +<​code>​
 +...
 +modparam("​dialplan",​ "​repl_exp_col",​ "​column_name"​)
 +...
 +</​code>​
 +
 +\\ ==== 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**
 +
 +<​code>​
 +...
 +modparam("​dialplan",​ "​attrs_col",​ "​column_name"​)
 +...
 +</​code>​
 +
 +\\ ==== 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**
 +
 +<​code>​
 +...
 +modparam("​dialplan",​ "​attrs_pvar",​ "​$avp(s:​dest)"​)
 +...
 +</​code>​
 +
 +\\ ==== 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**
 +
 +<​code>​
 +...
 +modparam("​dialplan",​ "​fetch_rows",​ 4000)
 +...
 +</​code>​
 +
 +\\ ==== 5.13. match_dynamic (int) ====
 +
 +If set to 1, the match and substitution expressions can include script variables and their values are evaluated at runtime.
 +
 +During the loading process, the values that contain variables are no longer pre-compiled to PCRE structure in memory, because the values change at runtime, thus expect slightly slower performances. Values without script variables are pre-compiled even if this parameter is enabled.
 +
 +Default value is “0” (disabled).
 +
 +**Example 1.13. Set ''​match_dynamic''​ parameter**
 +
 +<​code>​
 +...
 +modparam("​dialplan",​ "​match_dynamic",​ 1)
 +...
 +</​code>​
 +
 +\\ ===== 6. Functions =====
 +
 +==== 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.14. ''​dp_translate''​ usage**
 +
 +<​code>​
 +...
 +dp_translate("​240",​ "​$ruri.user/​$avp(s:​dest)"​);​
 +xlog("​translated to var $avp(s:​dest) \n");
 +...
 +</​code>​
 +
 +\\ **Example 1.15. ''​dp_translate''​ usage**
 +
 +<​code>​
 +...
 +$avp(s:src) = $ruri.user;
 +dp_translate("​$var(x)",​ "​$avp(s:​src)/​$var(y)"​);​
 +xlog("​translated to var $var(y) \n");
 +...
 +</​code>​
 +
 +\\ ==== 6.2. dp_reload() ====
 +
 +Forces an update of the translation rules from the database.
 +
 +Name: dp_reload
 +
 +Parameters: none
 +
 +This function can be used from ANY_ROUTE.
 +
 +===== 7. RPC Commands =====
 +
 +==== 7.1. dialplan.dump ====
 +
 +Dumps the content of one dialplan ID
 +
 +Name: dialplan.dump
 +
 +Parameters: Dialplan ID
 +
 +Example:
 +
 +<​code>​
 +                kamcmd dialplan.dump 100
 +</​code>​
 +
 +==== 7.2. dialplan.reload ====
 +
 +Forces an update of the translation rules from the database.
 +
 +Name: dialplan.reload
 +
 +Parameters: none
 +
 +Example:
 +
 +<​code>​
 +                kamcmd dialplan.reload
 +</​code>​
 +
 +==== 7.3. 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:
 +
 +<​code>​
 +                kamcmd dialplan.translate 1 "​abcdxyz"​
 +</​code>​
 +
 +===== 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, [[https://​www.kamailio.org/​docs/​db-tables/​kamailio-db-devel.html|https://​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.16. Example of rules**
 +
 +<​code>​
 +...
 +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
 +...
 +</​code>​
 +
 +\\ 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.
dialplan_dialplan_translation_module_released.txt · 最后更改: 2017/09/11 11:17 由 james_zhu