Table of Contents

OpenSER Transformations for Version 1.2.x

Main author:
   Daniel-Constantin Mierla <miconda (at) gmail.com>

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

Starting with 1.2.0, all PV can be used directly in the script. For example: 

# check if username in From header 
#    is equal with username in To header
if($fU==$tU) {
   ...
}

# r-uri username based processing
switch($ruri.user) {
   case "1234":
      ...
   break;
   case "5678":
      ...
   break;
   default:
     ...
}

# assign integer value to an AVP
$avp(i:11) = 1;

#assing string value to an AVP
$avp(i:22) = "openser";

# write ruri in an AVP
$avp(i:33) = $ruri;

# concat "sip:" + From username + "@" + To domain 
#   in a script variable x
$var(x) = "sip:" + $fU +"@" + $td;

The transformations are intended to facilitate access to different attributes of PV (like strlen of value, parts of value, substrings) or complete different value of PV (encoded in hexa, md5 value, escape/unescape PV value for DB operations…).

A transformation is represented in between '{' and '}' and follows the name of a PV. When using transformations, the PV name and transformations must be enclosed in '(' and ')'. 

# the length of From URI ($fu is PV for From URI)

$(fu{s.len})

Many transformations can be applied in the same time to a PV. 

# the length of escaped 'Test' header body

$(hdr(Test){s.escape.common}{s.len})

The transformations can be used anywhere, being considered parts of PV – in xlog, avpops or other modules' functions and parameters, in right side assignment expressions or in comparisons.

IMPORTANT: To learn what variables can be used with transformations see Pseudo variables list.

String Transformations

The name of these transformation starts with 's.'. They are intended to apply string operations to PV.

Available transformations in this class:

{s.len}

Return strlen of PV value

{s.int}

Return integer value of a string-represented number

{s.md5}

Return md5 over PV value

{s.substr,offset,length}

Return substring starting at offset having size of 'length'. If offset is negative, then it is counted from the end of PV value, -1 being the last char. In case of positive value, 0 is first char. Length must be positive, in case of 0, substring to the end of PV value is returned. offset and length can be PV as well.

Example: 

"abcd"{s.substr,1,0} = "bcd"

{s.select,index,separator}

Return a field from PV value. The field is selected based on separator and index. The separator must be a character used to identify the fields. Index must be a integer value or a PV. If index is negative, the count of fields starts from end of PV value, -1 being last field. If index is positive, 0 is the first field.

Example: 

"12,34,56"{s.select,1,,} = "34" ; "12,34,56"{s.select,-2,,} = "34"

{s.encode.hexa}

Return encoding in hexa of PV value

{s.decode.hexa}

Return decoding from hexa of PV value

{s.escape.common}

Return escaped string of PV value. Characters escaped are ''', '“', '\' and 0. Useful when doing DB queries (care should be taken for non Latin character set).

{s.unescape.common}

Return unescaped string of PV value. Reverse of above transformation.

{s.escape.user}

Return escaped string of PV value, changing to '%hexa' the characters that are not allowed in user part of SIP URI following.

{s.unescape.user}

Return unescaped string of PV value, changing '%hexa' to character code. Reverse of above transformation.

URI Transformations

The name of transformation starts with 'uri.'. The PV value is considered to be a SIP URI. This transformation returns parts of SIP URI (see struct sip_uri). If that part is missing, the returned value is an empty string.

Available transformations in this class:

{uri.user}

Return the user part

{uri.host}

(same as {uri.domain})

Return the domain part

{uri.passwd}

Return the password

{uri.port}

Return the port

{uri.params}

Return the URI parameters in a string

{uri.param,name}

Return the value of parameter with name 'name'

{uri.headers}

Return URI headers

{uri.transport}

Return the value of transport parameter

{uri.ttl}

Return the value of ttl parameter

{uri.uparam}

Return the value of user parameter

{uri.maddr}

Return the value of maddr parameter

{uri.method}

Return the value of method parameter

{uri.lr}

Return the value of lr parameter

{uri.r2}

Return the value of r2 parameter

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.

Available transformations in this class:

{param.value,name}

Return the value of parameter 'name'

Example: 

"a=1;b=2;c=3"{param.value,c} = "3"

{param.name,index}

Return the name of parameter at position 'index'.

Example: 

"a=1;b=2;c=3"{param.name,1} = "b"

Examples

Within a PV, many transformation can be applied, being executed from left to right.

* The length of the value of parameter at postion 1 (remember 0 is first position, 1 is second position) 

$var(x) = "a=1;b=22;c=333";
$(var(x){param.value,$(var(x){param.name,1})}{s.len}) = 2

* Test if whether is un-registration or not 

if(is_method("REGISTER") && is_present_hf("Expires") && $(hdr(Expires){s.int})==0)
    xlog("This is an un-registration\n");