Kamailio-开源SIP软交换平台

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

用户工具

站点工具


textopsx_extra_text_operations_released

差别

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

到此差别页面的链接

textopsx_extra_text_operations_released [2017/09/11 17:24] (当前版本)
james_zhu 创建
行 1: 行 1:
 +====== Textopsx Module ======
  
 +==== Andrei Pelinescu-Onciul ====
 +
 +FhG FOKUS\\ ​
 +
 +==== Daniel-Constantin Mierla ====
 +
 +asipto.com\\ ​
 +
 +''<​[[miconda@gmail.com|miconda@gmail.com]]>''​
 +
 +Copyright © 2003 FhG FOKUS
 +
 +----
 +
 +**Table of Contents**
 +
 +  * **1. Admin Guide** ​
 +    * **1. Overview** ​
 +    * **2. Functions** ​
 +      * **2.1. msg_apply_changes()** ​
 +      * **2.2. change_reply_status(code,​ reason)** ​
 +      * **2.3. remove_body()** ​
 +      * **2.4. keep_hf%%([%%regexp])** ​
 +      * **2.5. fnmatch(value,​ expr [, flags])** ​
 +      * **2.6. append_hf_value(hf,​ hvalue)** ​
 +      * **2.7. insert_hf_value(hf,​ hvalue)** ​
 +      * **2.8. remove_hf_value(hf_par)** ​
 +      * **2.9. remove_hf_value2(hf_par)** ​
 +      * **2.10. assign_hf_value(hf,​ hvalue)** ​
 +      * **2.11. assign_hf_value2(hf,​ hvalue)** ​
 +      * **2.12. include_hf_value(hf,​ hvalue)** ​
 +      * **2.13. exclude_hf_value(hf,​ hvalue)** ​
 +      * **2.14. hf_value_exists(hf,​ hvalue)** ​
 +    * **3. Selects** ​
 +      * **3.1. @hf_value** ​
 +      * **3.2. @hf_value2** ​
 +      * **3.3. @hf_value_exists** ​
 +
 +**List of Examples**
 +
 +  * **1.1. msg_apply_changes() usage** ​
 +  * **1.2. change_reply_status usage** ​
 +  * **1.3. remove_body() usage** ​
 +  * **1.4. keep_hf() usage** ​
 +  * **1.5. fnmatch() usage** ​
 +  * **1.6. append_hf_value usage** ​
 +  * **1.7. insert_hf_value usage** ​
 +  * **1.8. remove_hf_value usage** ​
 +  * **1.9. remove_hf_value2 usage** ​
 +  * **1.10. assign_hf_value usage** ​
 +  * **1.11. assign_hf_value2 usage** ​
 +  * **1.12. include_hf_value usage** ​
 +  * **1.13. exclude_hf_value usage** ​
 +  * **1.14. hf_value_exists usage** ​
 +  * **1.15. @hf_value select usage** ​
 +
 +====== Chapter 1. Admin Guide ======
 +
 +**Table of Contents**
 +
 +  * **1. Overview** ​
 +  * **2. Functions** ​
 +    * **2.1. msg_apply_changes()** ​
 +    * **2.2. change_reply_status(code,​ reason)** ​
 +    * **2.3. remove_body()** ​
 +    * **2.4. keep_hf%%([%%regexp])** ​
 +    * **2.5. fnmatch(value,​ expr [, flags])** ​
 +    * **2.6. append_hf_value(hf,​ hvalue)** ​
 +    * **2.7. insert_hf_value(hf,​ hvalue)** ​
 +    * **2.8. remove_hf_value(hf_par)** ​
 +    * **2.9. remove_hf_value2(hf_par)** ​
 +    * **2.10. assign_hf_value(hf,​ hvalue)** ​
 +    * **2.11. assign_hf_value2(hf,​ hvalue)** ​
 +    * **2.12. include_hf_value(hf,​ hvalue)** ​
 +    * **2.13. exclude_hf_value(hf,​ hvalue)** ​
 +    * **2.14. hf_value_exists(hf,​ hvalue)** ​
 +  * **3. Selects** ​
 +    * **3.1. @hf_value** ​
 +    * **3.2. @hf_value2** ​
 +    * **3.3. @hf_value_exists** ​
 +
 +===== 1. Overview =====
 +
 +This module implements functions for SIP message text operations in routing block configurations. It adds new features similar to the textops module (textops eXtentions).
 +
 +===== 2. Functions =====
 +
 +==== 2.1. msg_apply_changes() ====
 +
 +Use this function to apply changes performed on SIP message content. Be careful when using this function; due to special handling of changes to the SIP message buffer so far, using this function might change the behaviour of your config. Do test your config properly!
 +
 +The function returns true (1) on success. If it is failure before the new content is build, the function returns false (-1), the old content is still in place. If parsing of the new content is failing, the function stops executions of the config file (the internal structure is no longer valid for config processing, like it happens when a broken message is received from network).
 +
 +This function can be used from REQUEST_ROUTE or core REPLY_ROUTE.
 +
 +Note: It must be used before the transaction is created in request_route and not inside the onreply_route[name] executed by tm module. Also, do not used after resuming a suspended request or reply, at that moment the transaction is already created.
 +
 +**Example 1.1. ''​msg_apply_changes()''​ usage**
 +
 +<​code>​
 +...
 +append_hf("​My-Header:​ yes\r\n"​);​
 +if(msg_apply_changes())
 +{
 +    # msg buffer has a new content
 +    if(is_present_hf("​My-Header"​))
 +    {
 +        # will get here always
 +    }
 +}
 +...
 +</​code>​
 +
 +\\ ==== 2.2. change_reply_status(code,​ reason) ====
 +
 +Intercept a SIP reply (in an onreply_route) and change its status code and reason phrase prior to forwarding it.
 +
 +Meaning of the parameters is as follows:
 +
 +  * code - Status code. 
 +  * reason - Reason phrase. ​
 +
 +This function can be used from ONREPLY_ROUTE.
 +
 +**Example 1.2. ''​change_reply_status''​ usage**
 +
 +<​code>​
 +...
 +onreply_route {
 +    if (@status == "​603"​) {
 +        change_reply_status(404,​ "Not Found"​);​
 +        exit;
 +    }
 +}
 +...
 +</​code>​
 +
 +\\ ==== 2.3. remove_body() ====
 +
 +Use this function to remove the body of SIP requests or replies.
 +
 +This function can be used from ANY_ROUTE.
 +
 +**Example 1.3. ''​remove_body()''​ usage**
 +
 +<​code>​
 +...
 +remove_body();​
 +...
 +</​code>​
 +
 +\\ ==== 2.4. keep_hf%%([%%regexp]) ====
 +
 +Remove headers that don't match the regular expression regexp. Several header are ignored always (thus not removed): Via, From, To, Call-ID, CSeq, Content-Length,​ Content-Type,​ Max-Forwards,​ Contact, Route, Record-Route -- these can be removed one by one with remove_hf(). If regexp is missing, then only the headers listed above are kept, the rest are removed.
 +
 +This function can be used from ANY_ROUTE.
 +
 +**Example 1.4. ''​keep_hf()''​ usage**
 +
 +<​code>​
 +...
 +keep_hf("​User-Agent"​);​
 +...
 +</​code>​
 +
 +\\ ==== 2.5. fnmatch(value,​ expr [, flags]) ====
 +
 +Match the value against the expr using shell-style pattern for file name matching (see man page for C function fnmatch()). It is known to be faster and use less-memory than regular expressions.
 +
 +Parameter '​flags'​ is optional and can be '​i'​ to do case insensitive matching.
 +
 +This function can be used from ANY_ROUTE.
 +
 +**Example 1.5. ''​fnmatch()''​ usage**
 +
 +<​code>​
 +...
 +if(fnmatch("​$rU",​ "​123*"​))
 +{
 +    ...
 +}
 +...
 +</​code>​
 +
 +\\ ==== 2.6. append_hf_value(hf,​ hvalue) ====
 +
 +Append new header value after an existing header, if no index acquired append at the end of list. Note that a header may consist of comma delimited list of values.
 +
 +Meaning of the parameters is as follows:
 +
 +  * hf - Header field to be appended. Format: HFNAME [ [IDX] ]. If index is not specified new header is inserted at the end of message. ​
 +  * hvalue - Value to be added, config var formatting supported. ​
 +
 +**Example 1.6. ''​append_hf_value''​ usage**
 +
 +<​code>​
 +...
 +append_hf_value("​foo",​ "​gogo;​stamp=$Ts"​) ​  # add new header
 +append_hf_value("​foo[1]",​ "​gogo"​) ​ # add new value behind first value
 +append_hf_value("​foo[-1]",​ "​$var(Bar)"​) # try add value to the last header, if not exists add new header
 +...
 +</​code>​
 +
 +\\ ==== 2.7. insert_hf_value(hf,​ hvalue) ====
 +
 +Insert new header value before an existing header, if no index acquired insert before first hf header. Note that a header may consist of comma delimited list of values. To insert value behing last value use ''​appenf_hf_value''​.
 +
 +Meaning of the parameters is as follows:
 +
 +  * hf - Header field to be appended. Format: HFNAME [ [IDX] ]. If index is not specified new header is inserted at the top of message. ​
 +  * hvalue - Value to be added, config var formatting supported. ​
 +
 +**Example 1.7. ''​insert_hf_value''​ usage**
 +
 +<​code>​
 +...
 +insert_hf_value("​foo[2]",​ "​gogo"​)
 +insert_hf_value("​foo",​ "​$avp(foo)"​) ​  # add new header at the top of list
 +insert_hf_value("​foo[1]",​ "​gogo"​) # try add to the first header
 +...
 +</​code>​
 +
 +\\ ==== 2.8. remove_hf_value(hf_par) ====
 +
 +Remove the header value from existing header, Note that a header may consist of comma delimited list of values.
 +
 +Meaning of the parameters is as follows:
 +
 +  * hf_par - Header field/param to be removed. Format: HFNAME [ [IDX] ] [. PARAM ] If asterisk is specified as index then all values are affected. ​
 +
 +**Example 1.8. ''​remove_hf_value''​ usage**
 +
 +<​code>​
 +...
 +remove_hf_value("​foo"​) ​ # remove foo[1]
 +remove_hf_value("​foo[*]"​) ​ # remove all foo's headers
 +remove_hf_value("​foo[-1]"​) # last foo
 +remove_hf_value("​foo.bar"​) ​ # delete parameter
 +remove_hf_value("​foo[*].bar"​) # for each foo delete bar parameters
 +...
 +</​code>​
 +
 +\\ ==== 2.9. remove_hf_value2(hf_par) ====
 +
 +Remove specified header or parameter. It is expected header in Authorization format (comma delimiters are not treated as multi-value delimiters).
 +
 +Meaning of the parameters is as follows:
 +
 +  * hf_par - Header/​param to be removed. Format: HFNAME [ [IDX] ] [. PARAM ] If asterisk is specified as index then all values are affected. ​
 +
 +**Example 1.9. ''​remove_hf_value2''​ usage**
 +
 +<​code>​
 +...
 +remove_hf_value2("​foo"​) ​ # remove foo[1]
 +remove_hf_value2("​foo[*]"​) ​ # remove all foo's headers, the same as remove_hf_header("​foo[*]"​);​
 +remove_hf_value2("​foo[-1]"​) # last foo
 +remove_hf_value2("​foo.bar"​) ​ # delete parameter
 +remove_hf_value2("​foo[*].bar"​) # for each foo delete bar parameters
 +...
 +</​code>​
 +
 +\\ ==== 2.10. assign_hf_value(hf,​ hvalue) ====
 +
 +Assign value to specified header value / param.
 +
 +Meaning of the parameters is as follows:
 +
 +  * hf_para - Header field value / param to be appended. Format: HFNAME [ [IDX] ] [. PARAM] If asterisk is specified as index then all values are affected. ​
 +  * hvalue - Value to be assigned, config var formatting supported. If value is empty then no equal sign apears in param. ​
 +
 +**Example 1.10. ''​assign_hf_value''​ usage**
 +
 +<​code>​
 +...
 +assign_hf_value("​foo",​ "​gogo"​) ​ # foo[1]
 +assign_hf_value("​foo[-1]",​ "​gogo"​) ​ # foo[last_foo]
 +
 +assign_hf_value("​foo.bar",​ ""​)
 +assign_hf_value("​foo[3].bar",​ ""​)
 +assign_hf_value("​foo[*]",​ ""​) ​ # remove all foo's, empty value remains
 +assign_hf_value("​foo[*].bar",​ ""​) ​ # set empty value (ex. lr)
 +...
 +</​code>​
 +
 +\\ ==== 2.11. assign_hf_value2(hf,​ hvalue) ====
 +
 +Assign value to specified header. It is expected header in Authorization format (comma delimiters are not treated as multi-value delimiters).
 +
 +Meaning of the parameters is as follows:
 +
 +  * hf_para - Header field value / param to be appended. Format: HFNAME [ [IDX] ] [. PARAM] If asterisk is specified as index then all values are affected. ​
 +  * hvalue - Value to be assigned, config var formatting supported. If value is empty then no equal sign apears in param. ​
 +
 +**Example 1.11. ''​assign_hf_value2''​ usage**
 +
 +<​code>​
 +...
 +assign_hf_value2("​Authorization.integrity-protected",​ "​\"​yes\""​)
 +assign_hf_value2("​foo[-1]",​ "​gogo"​) ​ # foo[last_foo]
 +assign_hf_value2("​foo[*].bar",​ ""​) ​ # set empty value (ex. lr)
 +...
 +</​code>​
 +
 +\\ ==== 2.12. include_hf_value(hf,​ hvalue) ====
 +
 +Add value in set if not exists, eg. "​Supported:​ path,​100rel"​.
 +
 +Meaning of the parameters is as follows:
 +
 +  * hf - Header field name to be affected. ​
 +  * hvalue - config var formatting supported. ​
 +
 +**Example 1.12. ''​include_hf_value''​ usage**
 +
 +<​code>​
 +...
 +include_hf_value("​Supported",​ "​path"​);​
 +...
 +</​code>​
 +
 +\\ ==== 2.13. exclude_hf_value(hf,​ hvalue) ====
 +
 +Remove value from set if exists, eg. "​Supported:​ path,​100rel"​.
 +
 +Meaning of the parameters is as follows:
 +
 +  * hf - Header field name to be affected. ​
 +  * hvalue - config formatting supported. ​
 +
 +**Example 1.13. ''​exclude_hf_value''​ usage**
 +
 +<​code>​
 +...
 +exclude_hf_value("​Supported",​ "​100rel"​);​
 +...
 +</​code>​
 +
 +\\ ==== 2.14. hf_value_exists(hf,​ hvalue) ====
 +
 +Check if value exists in set. Alternate select @hf_value_exists.HF.VALUE may be used. It returns one or zero.
 +
 +Meaning of the parameters is as follows:
 +
 +  * hf - Header field name to be affected. Underscores are treated as dashes. ​
 +  * hvalue - config var formatting supported. ​
 +
 +**Example 1.14. ''​hf_value_exists''​ usage**
 +
 +<​code>​
 +...
 +if (hf_value_exists("​Supported",​ "​100rel"​)) {
 +
 +}
 +
 +if (@hf_value_exists.supported.path == "​1"​) {
 +
 +}
 +...
 +</​code>​
 +
 +\\ ===== 3. Selects =====
 +
 +==== 3.1. @hf_value ====
 +
 +Get value of required header-value or param. Note that functions called '​value2'​ works with Authorization-like headers where comma is not treated as value delimiter. Formats: @hf_value.HFNAME[IDX] # idx value, negative value counts from bottom @hf_value.HFNAME.PARAM_NAME @hf_value.HFNAME[IDX].PARAM_NAME @hf_value.HFNAME.p.PARAM_NAME # or .param., useful if requred called "​uri",​ "​p",​ "​param"​ @hf_value.HFNAME[IDX].p.PARAM_NAME # dtto @hf_value.HFNAME[IDX].uri # (< & > excluded) @hf_value.HFNAME%%[*%%] # return comma delimited list of all values (combines headers) @hf_value.HFNAME # the same as above %%[*%%] but may be parsed by cfg.y @hf_value.HFNAME%%[*%%].uri # return comma delimited list of uris (< & > excluded) @hf_value.HFNAME.uri # the same as above %%[*%%] but may be parsed by cfg.y @hf_value.HFNAME[IDX].name # returns name part, quotes excluded @hf_value.HFNAME.name # returns name part of the first value @hf_value2.HFNAME # returns value of first header @hf_value2.HFNAME[IDX] # returns value of idx's header @hf_value2.HFNAME.PARAM_NAME @hf_value2.HFNAME[IDX].PARAM_NAME @hf_value.HFNAME[IDX].uri # return URI, quotes excluded @hf_value.HFNAME.p.uri # returns param named uri, not URI itself @hf_value.HFNAME.p.name # returns param named name, not name itself @hf_value.HFNAME[IDX].uri.name # any sel_any_uri nested features may be used @hf_value.HFNAME[IDX].nameaddr.name # select_any_nameaddr
 +
 +Meaning of the parameters is as follows:
 +
 +  * HFNAME - Header field name. Underscores are treated as dashes. ​
 +  * IDX - Value index, negative value counts from bottom ​
 +  * PARAM_NAME - name of parameter ​
 +
 +**Example 1.15. ''​@hf_value select''​ usage**
 +
 +<​code>​
 +...
 +$a = @hf_value.my_header[1].my_param;​
 +xplog("​L_ERR",​ "​$sel(@hf_value.via[-1]),​ $sel(@hf_value.from.tag)\n"​);​
 +$b = @hf_value.p_associated_uri;​
 +
 +xplog("​L_ERR",​ "Route uris: '​$sel(@hf_value.route[*].uri)'​\n"​);​
 +$rr = @hf_value.route.uri;​
 +
 +$prt = @hf_value2.authorization.integrity_protected;​
 +...
 +</​code>​
 +
 +\\ ==== 3.2. @hf_value2 ====
 +
 +TBA.
 +
 +==== 3.3. @hf_value_exists ====
 +
 +TBA.
textopsx_extra_text_operations_released.txt · 最后更改: 2017/09/11 17:24 由 james_zhu