User Tools

Site Tools


cookbooks:devel:transformations

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
cookbooks:devel:transformations [2016/09/02 14:53]
coudot [{s.escape.csv}]
cookbooks:devel:transformations [2021/06/25 11:05]
miconda [{s.rbefore,x}]
Line 1: Line 1:
-====== Kamailio SIP Server v5.0.x (devel): Transformations ======+====== Transformations ====== 
 + 
 +Version: Kamailio SIP Server v5.6.x (devel)
  
 <code> <code>
Line 6: Line 8:
 </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 131: Line 133:
  
 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} ==== ==== {s.encode.base64} ====
  
 Return base64 encoding of PV value Return base64 encoding of PV value
- 
 ==== {s.decode.base64} ==== ==== {s.decode.base64} ====
  
 Decode base64 encoded PV and return value 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 294: Line 334:
 $(var(x){s.rm,test}) $(var(x){s.rm,test})
 </code> </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 358: 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.
  
  
Line 372: Line 563:
 <code> <code>
 "a=1;b=2;c=3"{param.value,c} = "3" "a=1;b=2;c=3"{param.value,c} = "3"
 +</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.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> </code>
  
Line 490: Line 694:
 ==== {line.at,pos} ==== ==== {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).+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: Example:
Line 546: Line 750:
 ==== {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 589: 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 657: Line 861:
  
 $(hu{url.querystring}) => "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>
 +
 +===== 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> </code>
  
cookbooks/devel/transformations.txt · Last modified: 2021/06/25 11:05 by miconda