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 built, 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 use after resuming a suspended request or reply, at that moment the transaction is already created.

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

Set the content of the SIP message buffer, replacing the exiting data. The parameter can contain variables, its value must be a valid SIP request or reply, a matter of what the old message is.

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 use after resuming a suspended request or reply, at that moment the transaction is already created.

...
msg_set_buffer("INVITE sip:...");
...

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:

This function can be used from ONREPLY_ROUTE.

...
reply_route {
    if (status == "603") {
        change_reply_status(404, "Not Found");
        exit;
    }
}
...

Change the status code for a SIP reply .

Meaning of the parameters is as follows:

This function can be used from ONREPLY_ROUTE.

...
reply_route {
    if (status == "604") {
        change_reply_status_code("404");
        exit;
    }
}
...

Use this function to remove the body of SIP requests or replies.

This function can be used from ANY_ROUTE.

...
remove_body();
...

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.

...
keep_hf("User-Agent");
...

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.

...
if(fnmatch("$rU", "123*"))
{
    ...
}
...

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:

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

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 a value behind the last value use append_hf_value.

Meaning of the parameters is as follows:

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

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:

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

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:

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

Assign value to specified header value / param.

Meaning of the parameters is as follows:

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

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:

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

Add value in set if not exists, eg. "Supported: path,100rel".

Meaning of the parameters is as follows:

...
include_hf_value("Supported", "path");
...

Remove value from set if exists, eg. "Supported: path,100rel".

Meaning of the parameters is as follows:

...
exclude_hf_value("Supported", "100rel");
...

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:

...
if (hf_value_exists("Supported", "100rel")) {

}

if (@hf_value_exists.supported.path == "1") {

}
...

Start an iterator for headers in the current SIP message. The parameter iname is used to identify the iterator. There can be up to 4 iterators at the same time, with different name.

The parameter can be a dynamic string with variables.

This function can be used from ANY_ROUTE.

...
hf_iterator_start("i1");
...

Close the iterator identified by iname parameter. The iname value must be the same used for hf_iterator_start().

The parameter can be dynamic string with variables.

This function can be used from ANY_ROUTE.

...
hf_iterator_end("i1");
...

Move the iterator to the next header. It must be called also after hf_iterator_start() to get the first header.

The return code is false when there is no other header in the list.

The item name and value are accessible via variables: $hfitname(iname) and $hfitbody(iname).

The parameter can be dynamic string with variables.

This function can be used from ANY_ROUTE.

...
    hf_iterator_start("i1");
    while(hf_iterator_next("i1")) {
        xlog("hdr[$hfitname(i1)] is: $hfitbody(i1)\n");
    }
    hf_iterator_end("i1");
...

Move the iterator to the previous header. It must be called also after hf_iterator_start() and hf_iterator_next().

The parameter can be dynamic string with variables.

This function can be used from ANY_ROUTE.

...
    hf_iterator_start("i1");
    hf_iterator_next("i1");
...
    hf_iterator_next("i1");
...
    hf_iterator_prev("i1");
...
    hf_iterator_end("i1");
...

Remove the header at the current iterator position.

The parameter can be dynamic string with variables.

This function can be used from ANY_ROUTE.

...
    hf_iterator_start("i1");
    while(hf_iterator_next("i1")) {
        if($hfitname(i1)=="My-Header") {
            hf_iterator_rm("i1");
        }
    }
    hf_iterator_end("i1");
...

Add headers after the one at the current iterator possition.

The parameters can be dynamic strings with variables.

This function can be used from ANY_ROUTE.

...
    hf_iterator_start("i1");
    while(hf_iterator_next("i1")) {
        if($hfitname(i1)=="My-Header") {
            hf_iterator_append("i1", "My-New-Header: abc\r\n");
            break;
        }
    }
    hf_iterator_end("i1");
...

Add headers before the one at the current iterator possition.

The parameters can be dynamic strings with variables.

This function can be used from ANY_ROUTE.

...
    hf_iterator_start("i1");
    while(hf_iterator_next("i1")) {
        if($hfitname(i1)=="My-Header") {
            hf_iterator_insert("i1", "My-New-Header: abc\r\n");
            break;
        }
    }
    hf_iterator_end("i1");
...

Start an iterator for lines in the body of the current SIP message. The parameter iname is used to identify the iterator. There can be up to 4 iterators at the same time, with different name.

The parameter can be a dynamic string with variables.

This function can be used from ANY_ROUTE.

...
bl_iterator_start("b1");
...

Close the iterator identified by iname parameter. The iname value must be the same used for bl_iterator_start().

The parameter can be dynamic string with variables.

This function can be used from ANY_ROUTE.

...
bl_iterator_end("b1");
...

Move the iterator to the next line in the body. It must be called also after bl_iterator_start() to get the first header.

The return code is false when there is no other header in the list.

The body line accessible via variable $blitval(iname) - it contains also the EOL chars.

The parameter can be dynamic string with variables.

This function can be used from ANY_ROUTE.

...
    bl_iterator_start("b1");
    while(bl_iterator_next("b1")) {
        xlog("body line: $blitval(b1)");
    }
    bl_iterator_end("b1");
...

Remove the body line at the current iterator position.

The parameter can be dynamic string with variables.

This function can be used from ANY_ROUTE.

...
    bl_iterator_start("b1");
    while(bl_iterator_next("b1")) {
        if($blitval(b1)=~"abc") {
            bl_iterator_rm("b1");
        }
    }
    bl_iterator_end("b1");
...

Add text after the line at the current iterator possition.

The parameters can be dynamic strings with variables.

This function can be used from ANY_ROUTE.

...
    bl_iterator_start("b1");
    while(bl_iterator_next("b1")) {
        if($blitval(b1)=~"^a=info:xyz") {
            bl_iterator_append("b1", "a=info:abc\r\n");
            break;
        }
    }
    bl_iterator_end("b1");
...

Add text before the line at the current iterator possition.

The parameters can be dynamic strings with variables.

This function can be used from ANY_ROUTE.

...
    bl_iterator_start("b1");
    while(bl_iterator_next("b1")) {
        if($blitval(b1)=~"^a=info:xyz") {
            bl_iterator_insert("b1", "a=info:abc\r\n");
            break;
        }
    }
    bl_iterator_end("b1");
...

Get value of required header-value or param. Note that selects called 'hf_value2' work with Authorization-like headers where comma is not treated as value delimiter.

Formats:

Meaning of the parameters is as follows:

...
$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;
...

Similar to selects called 'hf_value', but work with Authorization-like headers where comma is treated as attribute delimiter instead of header value delimiter.

TBA.