How Do I Use The textops Function subst() For String Substitution?

The subst() function is a really powerful string replacement method which you can use to alter any SIP message.

NOTE: You must be careful when using subst() because you can easily alter a SIP message in a way which SER will not be able to properly process.

The SER subst() function is exposed in the textops.so module. So in order to use this function you will need to load textops.so with a loadmodule directive.

Another important item to understand about subst() and the other string manipulation functions in textops.so that use regular expressions is that the regular expressions are evaluated when SER is started. If an invalid regular expression is found then SER will not be able to start. If you suspect that SER is not starting because of an invalid regular expression then you can set the debug level in ser.cfg to 9 and look for errors in your syslog.

All regular expressions take the following format:

/search-string/replacement-string/flags

The search string is the item(s) being searched for. The replacment string is the value that will be used and the flags control things like global search, case insensitive matching, etc.

Now on to an example.

Suppose we wanted to overwrite the q-value of a Contact header. The value that we will insert in to the Contact header will be 1.0. The following subst() command will do the trick.

subst("/^Contact:(.*);q=$/Contact:;q=1.0/");

Our search string is "^Contact:(.*);q=$". The carrot ^ tells SER to only evaluate lines that begin with the character sequence "Contact:". So if these characters are found elsewhere in a SIP header they will be ignored. They must be the first characters of a line.

The (.*) tells SER to match any sequence of characters following the characters "Contact:" and preceeding the characters ";q=". A very important item to understand here is that the characters matched as (.*) can be referenced later in the replacment string as the special control code "\1". If we had additional (.*) patterns, or other search groups such as (0-9{10}), in our search string then we would have "\2", "\3", etc which would correspond to the search patterns.

Next the dollar sign $ states that we want to search to the end of the line.

The replacement string is "Contact:\1;q=1.0" which looks rather odd, because of the special control code "\1" which references the (.*) portion in the search string.

So to recap, our subst() command will only evaluate lines that start with "Contact:" and the if a match is found then the characters "gathered" as (.*) in the search string will be unaltered, however, the q= tag will be completely replaced to the end of the line with ;q=1.0