Kamailio SIP Server Wiki

User Tools

Site Tools

Trace: • transformations
cookbooks:devel:transformations

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
cookbooks:devel:transformations [2011/12/16 22:41] – [{s.ftime,format}] micondacookbooks:devel:transformations [2022/04/08 16:08] (current) – [URI Alias Transformations] miconda
Line 1: Line 1:
-====== Kamailio SIP Server and SER v3.2.x (devel): Transformations ======+====== Transformations ====== 
 + 
 +Version: Kamailio SIP Server v5.6.x (devel)
  
 <code> <code>
 Main author: Main author:
-   Daniel-Constantin Mierla <miconda (at) asipto.com>+   Daniel-Constantin Mierla <miconda (at) gmail.com>
 </code> </code>
  
-**Transformation** is basically a function that is applied to a pseudo-variable (PV) to get a special value from it. The value of PV is not affected at all.+**Transformation** is basically a function that is applied to a pseudo-variable (PV) to get a property of it. The value of PV is not affected at all.
  
 Transformations are implemented by various modules, most of them being in **pv** module. Transformations are implemented by various modules, most of them being in **pv** module.
Line 66: Line 68:
 <code> <code>
 xlog("md5 over From username: $(fU{s.md5})"); xlog("md5 over From username: $(fU{s.md5})");
 +</code>
 +
 +==== {s.sha256} ====
 +
 +Return sha 256 over PV value
 +
 +<code>
 +xlog("sha 256 over From username: $(fU{s.sha256})");
 +</code>
 +
 +==== {s.sha384} ====
 +
 +Return sha 384 over PV value
 +
 +<code>
 +xlog("sha 384 over From username: $(fU{s.sha384})");
 +</code>
 +
 +==== {s.sha512} ====
 +
 +Return sha 512 over PV value
 +
 +<code>
 +xlog("sha 512 over From username: $(fU{s.sha512})");
 </code> </code>
  
Line 90: Line 116:
 $(var(x){s.select,-2,,}) => "34" $(var(x){s.select,-2,,}) => "34"
 </code> </code>
 +
 +
 +==== {s.encode.7bit} ====
 +
 +Return encoding in 7Bit of PV value
 +
 +==== {s.decode.7bit} ====
 +
 +Return decoding of PV value in 7Bit
  
 ==== {s.encode.hexa} ==== ==== {s.encode.hexa} ====
Line 99: Line 134:
 Return decoding from hexa of PV value Return decoding from hexa of PV value
  
 +==== {s.encode.base58} ====
 +
 +Return base58 encoding of PV value.
 +
 +The set of base58 digits is:
 +
 +<code>
 +123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz
 +</code>
 +
 +==== {s.decode.base58} ====
 +
 +Return base58 decoding of PV value.
 +
 +==== {s.encode.base64} ====
 +
 +Return base64 encoding of PV value
 +==== {s.decode.base64} ====
 +
 +Decode base64 encoded PV and return value
 +
 +==== {s.encode.base64t} ====
 +
 +Return base64 encoding of PV value without trailing padding characters('=').
 +
 +
 +==== {s.decode.base64t} ====
 +
 +Decode base64 encoded PV, handling missing trailing padding characters, and return value.
 +
 +==== {s.encode.base64url} ====
 +
 +Return base64-url encoding of PV value
 +
 +==== {s.decode.base64url} ====
 +
 +Decode base64-url encoded PV and return value
 +
 +==== {s.encode.base64urlt} ====
 +
 +Return base64-url encoding of PV value without trailing padding characters('=').
 +
 +
 +==== {s.decode.base64urlt} ====
 +
 +Decode base64-url encoded PV, handling missing trailing padding characters, and return value.
  
  
Line 129: Line 210:
  
 Return unescaped string of PV value, changing '%hexa' to character code. Reverse of above transformation. Return unescaped string of PV value, changing '%hexa' to character code. Reverse of above transformation.
 +
 +
 +==== {s.escape.csv} ====
 +
 +Escapes a string to use as a CSV field, as specified in RFC4180:
 +   * enclose string in double quotes
 +   * escape double quotes with a second double quote
 +
 +Example:
 +<code c>
 +$var(x) = 'foo,bar"baz';
 +$(var(x){s.escape.csv}); # contains '"foo,bar""baz"'
 +</code>
 +
 +==== {s.numeric} ====
 +
 +Removes all non-numeric parts of string.
 +
 +Example:
 +<code>
 +$var(x) = "(040)1234/567-89";
 +$(var(x){s.numeric}) => "040123456789" ;
 +</code>
  
 ==== {s.tolower} ==== ==== {s.tolower} ====
Line 222: Line 326:
 $(var(x){s.ltrim}) $(var(x){s.ltrim})
 </code> </code>
 +
 +==== {s.rm,match} ====
 +
 +Remove occurrences of 'match' from PV. 'match' can be static string or variable.
 +
 +<code c>
 +$(var(x){s.rm,test})
 +</code>
 +
 +==== {s.rmws} ====
 +
 +Remove occurrences of whitespace characters (' ', '\t, '\r', '\n').
 +
 +<code c>
 +$(var(x){s.rmws})
 +</code>
 +==== {s.corehash,n} ====
 +
 +Return the hash id computed with Kamailio's core hashing function. The parameter n is optional, it has to be a number of a pv holding a number. If n is provided, the value returned is **(hashid)&(n-1)**. If n is power of two, the result is the modulo operation between hashid and n (hash id % n).
 +
 +Note: the value is returned as string.
 +
 +<code c>
 +$(var(x){s.corehash})
 +</code>
 +
 +==== {s.unquote} ====
 +
 +Return the value without surrounding single (') or double quotes (").
 +
 +<code c>
 +$var(x) = "\"alice\"";
 +$var(alice) = $(var(x){s.unquote});
 +</code>
 +
 +==== {s.unbracket} ====
 +
 +Return the value without surrounding (), [], {} or <>.
 +
 +<code c>
 +$var(x) = "<sip:alice@test.sip>";
 +$var(uri) = $(var(x){s.unbracket});
 +</code>
 +
 +==== {s.count,c} ====
 +
 +Count how many times c appears in the pv value.
 +
 +<code c>
 +"abababa"{s.count,a}
 +# will return 4
 +</code>
 +
 +==== {s.after,x} ====
 +
 +Return the part of the string after the character **x** searched from the start of the value. If the character **x** is not found, it returns empty string.
 +
 +<code c>
 +"abcdef"{s.after,c}
 +# will return "def"
 +</code>
 +
 +==== {s.rafter,x} ====
 +
 +Return the part of the string after the character **x** searched from the end of the value. If the character **x** is not found, it returns empty string.
 +
 +<code c>
 +"abcdefcgh"{s.rafter,c}
 +# will return "gh"
 +</code>
 +==== {s.before,x} ====
 +
 +Return the part of the string before the character **x** searched from the start of the value. If the character **x** is not found, it returns the entire input string.
 +
 +<code c>
 +"abcdef"{s.before,c}
 +# will return "ab"
 +</code>
 +
 +==== {s.rbefore,x} ====
 +
 +Return the part of the string before the character **x** searched from the end of the value. If the character **x** is not found, it returns the entire input string.
 +
 +<code c>
 +"abcdefcgh"{s.rbefore,c}
 +# will return "abcdef"
 +</code>
 +
 +==== {s.fmtlines,n,m} ====
 +
 +Format the value in lines of n characters, adding m spaces to the start of each new line (not to first line). Each line is ended with "\r\n" apart of last line.
 +
 +<code c>
 +"abcdefgh"{s.fmtlines,4,2}
 +</code>
 +
 +==== {s.fmtlinet,n,m} ====
 +
 +Format the value in lines of n characters, adding m tabs to the start of each new line (not to first line). Each line is ended with "\r\n" apart of last line.
 +
 +<code c>
 +"abcdefgh"{s.fmtlinet,4,2}
 +</code>
 +==== {s.urlencode.param} ====
 +
 +Encode the value for URL param format.
 +
 +==== {s.urldecode.param} ====
 +
 +Decode the value from URL param format.
 +
 ===== URI Transformations ===== ===== URI Transformations =====
  
Line 286: Line 501:
 Return the value of r2 parameter Return the value of r2 parameter
  
 +==== {uri.scheme} ====
 +
 +Return the string value of URI scheme.
 +
 +==== {uri.tosocket} ====
 +
 +Return the string value corresponding to socket address matching proto, address and port from the URI. In other words, converts from a format like **sip:address:port;transport=proto** to **proto:address:port**.
 +
 +Example:
 +
 +<code>
 +"sip:test@127.0.0.1:5060;transport=udp"{uri.tosocket} => "udp:127.0.0.1:5060"
 +</code>
 +
 +==== {uri.duri} ====
 +
 +Return the destination URI for routing, keeping only schema, host, port and transport parameter. If port and transport are not in the original value, they are also not in the returned value.
 +
 +Example:
 +
 +<code c>
 +$var(ouri) = "sip:alice@server.com:5060;nat=yes;transport=tcp;line=xyz";
 +$var(duri) = $(var(ouri){uri.duri}); # => "sip:server.com:5060;transport=tcp"
 +</code>
 +
 +==== {uri.saor} ====
 +
 +Return the SIP AoR, keeping only schema, user and host. If user is not in the original value, it is also not in the returned value.
 +
 +Example:
 +
 +<code c>
 +$var(ouri) = "sip:alice@server.com:5060;nat=yes;transport=tcp;line=xyz";
 +$var(suri) = $(var(ouri){uri.saor}); # => "sip:alice@server.com"
 +</code>
 +
 +==== {uri.suri} ====
 +
 +Return the simple URI for routing, keeping only schema, user, host, port and transport parameter. If user, port and transport are not in the original value, they are also not in the returned value.
 +
 +Example:
 +
 +<code c>
 +$var(ouri) = "sip:alice@server.com:5060;nat=yes;transport=tcp;line=xyz";
 +$var(suri) = $(var(ouri){uri.suri}); # => "sip:alice@server.com:5060;transport=tcp"
 +</code>
 ===== Parameters List Transformations ===== ===== Parameters List Transformations =====
  
 The name of the transformation starts with 'param.'. The PV value is considered to be a string like name1=value1;name2=value2;...". The transformations returns the value for a specific parameter, or the name of a parameter at a specific index. The name of the transformation starts with 'param.'. The PV value is considered to be a string like name1=value1;name2=value2;...". The transformations returns the value for a specific parameter, or the name of a parameter at a specific index.
  
-Available transformations in this class:+Available transformations in this class are presented in the next sections. 
 + 
 +**Important Note:** the delimiter cannot be comma (,), because this transformation is using SIP header/URI parameters parser and the comma is a delimiter between serialized SIP header/URI bodies. The workaround is to use the subst transformation to replace the comma with another character that is used then as separator.
  
  
-==== {param.value,name} ====+==== {param.value,name[, delimiter]} ====
  
 Return the value of parameter 'name' Return the value of parameter 'name'
Line 304: Line 567:
 'name' can be a pseudo-variable 'name' can be a pseudo-variable
  
-==== {param.valueat,index} ====+'delimiter' allows you to specify a single character to use as the parameter delimiter. For example, when parsing HTTP URL query strings use '&'. 
 + 
 +==== {param.in,name[,delimiter]} ==== 
 + 
 +Return 1 if the parameter 'name' is found in parameters list, 0 if not found. 
 + 
 +Example: 
 +<code> 
 +"a=1;b=2;c=3"{param.in,c} = 1 
 +</code> 
 + 
 +'name' can be a pseudo-variable 
 + 
 +'delimiter' allows you to specify a single character to use as the parameter delimiter. For example, when parsing HTTP URL query strings use '&'. 
 + 
 +==== {param.valueat,index[, delimiter]} ====
  
 Return the value of parameter at position give by 'index' (0-based index) Return the value of parameter at position give by 'index' (0-based index)
Line 315: Line 593:
 'index' can be a pseudo-variable 'index' can be a pseudo-variable
  
-==== {param.name,index} ====+'delimiter' allows you to specify a single character to use as the parameter delimiter. For example, when parsing HTTP URL query strings use '&'. 
 + 
 +==== {param.name,index[, delimiter]} ====
  
 Return the name of parameter at position 'index'. Return the name of parameter at position 'index'.
Line 324: Line 604:
 </code> </code>
  
 +'delimiter' allows you to specify a single character to use as the parameter delimiter. For example, when parsing HTTP URL query strings use '&'.
  
-==== {param.count} ====+==== {param.count[, delimiter]} ====
  
 Return the number of parameters in the list. Return the number of parameters in the list.
Line 333: Line 614:
 "a=1;b=2;c=3"{param.count} = 3 "a=1;b=2;c=3"{param.count} = 3
 </code> </code>
 +
 +'delimiter' allows you to specify a single character to use as the parameter delimiter. For example, when parsing HTTP URL query strings use '&'.
  
 ===== Name-address Transformations ===== ===== Name-address Transformations =====
Line 395: Line 678:
 * return parameters part from To body * return parameters part from To body
  
 +===== Line Transformations =====
 +
 +Line-based operations on text values.
 +
 +==== {line.count} ====
 +
 +Return the number of lines.
 +
 +Example:
 +
 +<code c>
 +$(var(x){line.count})
 +</code>
 +
 +==== {line.at,pos} ====
 +
 +Return the line at position 'pos'. The index start from 0. Negative position can be used to count from last line (which is -1). The pos can be also a variable holding the index value.
 +
 +Example:
 +
 +<code c>
 +$(var(x){line.at,2})
 +</code>
 +
 +==== {line.sw,match} ====
 +
 +Return the line starting with **match**.
 +
 +Example:
 +
 +<code c>
 +$(var(x){line.sw,mytext})
 +</code>
 +
 +===== MSRP Transformations =====
 +
 +<fc #0000ff>This transformation class is exported by **msrp** module.</fc>
 +
 +==== {msrpuri.user} ====
 +
 +User part of a MSRP URI.
 +
 +==== {msrpuri.host} ====
 +
 +Host part of a MSRP URI.
 +
 +==== {msrpuri.port} ====
 +
 +Port part of a MSRP URI.
 +
 +==== {msrpuri.session} ====
 +
 +Session ID part of a MSRP URI.
 +
 +==== {msrpuri.proto} ====
 +
 +Transport layer part of a MSRP URI.
 +
 +==== {msrpuri.params} ====
 +
 +Parameters part of a MSRP URI.
 +
 +==== {msrpuri.userinfo} ====
 +
 +User-Info part of a MSRP URI. This is the same as user part, when there are no user parameters or password fields. Otherwise, it include the whole part after scheme and before '@' in front of host.
  
 ===== Regular Expression Transformations ===== ===== Regular Expression Transformations =====
  
 <fc #0000ff>This transformation class is exported by **textops** module.</fc> <fc #0000ff>This transformation class is exported by **textops** module.</fc>
- 
  
 ==== {re.subst,expression} ==== ==== {re.subst,expression} ====
  
-Perform Perl-like substitutions on string value pseudo-variables.+Perform POSIX regex substitutions on string value pseudo-variables.
  
 <code c> <code c>
Line 446: Line 793:
     $avp(strnr) = "12345";     $avp(strnr) = "12345";
          
-    xlog("$$rm = $rm = $(rm{s.sql})"); +    xlog("$$rm = $rm = $(rm{sql.val})"); 
-    xlog("$$var(null) = $var(null) = $(var(null){s.sql})"); +    xlog("$$var(null) = $var(null) = $(var(null){sql.val})"); 
-    xlog("$$avp(null) = $avp(null) = $(avp(null){s.sql})"); +    xlog("$$avp(null) = $avp(null) = $(avp(null){sql.val})"); 
-    xlog("$$avp(str) = $avp(str) = $(avp(str){s.sql})"); +    xlog("$$avp(str) = $avp(str) = $(avp(str){sql.val})"); 
-    xlog("$$avp(nr) = $avp(nr) = $(avp(nr){s.sql})"); +    xlog("$$avp(nr) = $avp(nr) = $(avp(nr){sql.val})"); 
-    xlog("$$avp(strnr) = $avp(strnr) = $(avp(strnr){s.sql})");+    xlog("$$avp(strnr) = $avp(strnr) = $(avp(strnr){sql.val})");
  
   Output:   Output:
Line 488: Line 835:
 </code> </code>
  
 +===== HTTP URL Transformations =====
  
 +<fc #0000ff>This transformation class is exported by **xhttp** module.</fc>
 +
 +==== {url.path} ====
 +
 +Path part of an HTTP URL.
 +
 +For example,
 +<code>
 +# When the first line of HTTP request is
 +# "GET /path/to/file/?this=is&the=querystring"
 +
 +$(hu{url.path}) => "/path/to/file/"
 +</code>
 +
 +==== {url.querystring} ====
 +
 +Query string part of an HTTP URL.
 +For example,
 +
 +<code>
 +# When the first line of HTTP request is
 +# "GET /path/to/file/?this=is&the=querystring"
 +
 +$(hu{url.querystring}) => "this=is&the=querystring"
 +</code>
 +
 +===== JSON Transformations =====
 +
 +<fc #0000ff>This transformation class is exported by **json** module.</fc>
 +
 +
 +==== {json.parse} ====
 +
 +You can use the transformation to extract values from the json structured pseudo-variables
 +
 +<code>
 +
 +$var(Custom-Data) = $(rb{json.parse,Custom-Data});
 +
 +</code>
 +
 +===== Socket Address Transformations =====
 +
 +Transformations related to socket address values (**proto:host:port**).
 +
 +==== {sock.host} ====
 +
 +Return the host part.
 +
 +==== {sock.port} ====
 +
 +Return the port part.
 +
 +==== {sock.proto} ====
 +
 +Return the proto part.
 +
 +==== {sock.touri} ====
 +
 +Return the socket address converted to SIP URI: **sip:host:port;transport=proto**.
 +
 +===== URI Alias Transformations =====
 +
 +Transformations related to URI alias values (**addr~port~protoid**).
 +
 +==== {urialias.encode} ====
 +
 +Encode SIP URI to alias value.
 +
 +<code c>
 +"sip:127.0.0.1:5060;transport=udp"{urialias.encode} => "127.0.0.1~5060~1"
 +</code>
 +
 +==== {urialias.decode} ====
 +
 +Decode from alias value to SIP URI.
 +
 +<code c>
 +"127.0.0.1~5060~1"{urialias.decode} => "sip:127.0.0.1:5060;transport=udp"
 +</code>
 +
 +===== Value Transformations  =====
 +
 +Exported by **pv** module.
 +
 +==== {val.json} ====
 +
 +If value is $null, return empty string; if value is string, then it is escaped for use as json value (without surrounding quotes.
 +
 +<code c>
 +$var(x) = '"name" <sip:name@a.com>';
 +$(var(x){val.json}) => \"name\" <sip:name@a.com>
 +</code>
 +
 +==== {val.n0} ====
 +
 +Return integer 0 for values that are $null.
 +
 +<code c>
 +$sht(a=>x) = $null;
 +$(sht(a=>x){val.n0}) => 0
 +</code>
 +
 +==== {val.ne} ====
 +
 +Return empty string for values that are $null.
 +
 +<code c>
 +$sht(a=>x) = $null;
 +# $(sht(a=>x){val.ne});
 +</code>
 +
 +==== {val.jsonqe} ====
 +
 +If value is $null, return quoted empty string; if value is string, then it is escaped for use as json value already with surrounding quotes; if the value is int, then it is preserved as it is.
 +
 +<code c>
 +$var(x) = '"name" <sip:name@a.com>';
 +$(var(x){val.jsonqe}) => "\"name\" <sip:name@a.com>"
 +</code>
cookbooks/devel/transformations.1324075296.txt.gz · Last modified: 2011/12/16 22:41 by miconda
Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki