3. Module documentation

3.1. Parameters

xavp_name (string)

Name of the XAVP there the collected headers are stored.

Default: headers

modparam("pv_headers", "xavp_name", "headers")

Result:
  $xavp(headers[0]=>From)
  $xavp(headers[0]=>To)
  $xavp(headers[0]=>Call-ID)
  ....

skip_headers (string)

A comma separated headers list that must be excluded from processing (they are skipped when pv_apply_headers() changes the sip message headers). If the parameter is not set then the "Default" list is used. If the parameter is set to an empty string then all the sip message headers are processed.

Default: Record-Route,Via,Route,Content-Length,Max-Forwards

split_headers (string)

A comma separated headers list that must be split into multi headers if their value is a comma separated list. If the parameter is not set then the "Default" is used. If the parameter is set to an empty string then no headers are split.

Default: None

modparam("pv_headers", "split_headers", "Diversion")

    Result:
        Received Diversion header:
            Diversion: <user1@test.local>,<user2@test.local>,<user3@test.local>
        After split:
            Diversion: <user1@test.local>
            Diversion: <user2@test.local>
            Diversion: <user3@test.local>
        Becomes handy if used together with pv_modify_header() or pv_remove_header()
        to change or remove value 2 for instance.

3.2. Functions

pv_collect_headers()

This function collects all headers from the message into the XAVP. It should be used preferably just when the sip message is reveived by kamailio.

Returns:

1 - on success
-1 - if there were errors

pv_apply_headers()

This function applies the current XAVP headers state to the real headers and should be called only once per branch when the message is about to leave kamailio.

The following rules apply:

all headers in the XAVP except for ones provided in the "skip_headers" parameter and From/To are recreated in the sip message.
From/To headers are processed by the uac module if it is loaded.
From/To headers are not changed in the reply messages.
headers with NULL value are removed if exist in the sip message.
the initial order of the sip headers is preserved.

Usage:

if (pv_apply_headers())
{
    "success"
}
else
{
    "errors"
}

pv_reset_headers()

This function resets the current XAVP headers list and enables pv_collect_headers() and pv_apply_headers() to be called again in the same branch.

Usage:

if (pv_reset_headers())
{
    "success"
}
else
{
    "errors"
}

pv_check_header(hname)

This function checks if the header already exists in the XAVP. It can be freely called from anywere, but only after pv_collect_headers().

Usage:

if (pv_check_header(hname))
{
    "exists"
}
else
{
    "does not exist"
}

pv_append_header(hname, hvalue)

This function appends a new header into the XAVP. It can be freely called from anywere, but only after pv_collect_headers(). Please note that subsequent "pv_append_header" calls will result in multiple headers. If the provided "hvalue" is $null then the header is added into the XAVP but it is not going to be added into the message.

Usage:

if (pv_append_header(hname, hvalue))
{
    "appended"
}
else
{
    "errors"
}

pv_modify_header(hname, hvalue)

This function modifies an existing header in the XAVP. It can be freely called from anywere, but only after pv_collect_headers(). Please note that if the header does not exist it will be explicitly appended. If there are multiple headers with the same name only the first one will be affected. If the provided header value is $null then the header is modified in the XAVP then it is removed from the sip message when pv_apply_headers() is called.

Usage:

if (pv_modify_header(hname, hvalue))
{
    "modified"
}
else
{
    "errors"
}

pv_modify_header(hname, idx, hvalue)

This function works similar to pv_modify_header(hname, hvalue) but should be used when there are multiple headers with the same name one of them to be modified. Index order is top to bottom.

Usage:

if (pv_modify_header(hname, idx, hvalue))
{
    "modified"
}
else
{
    "errors"
}

pv_remove_header(hname)

This function removes an existing header from the XAVP. It can be freely called from anywere, but only after pv_collect_headers(). If there are multiple headers with the same name all of them are removed. It returns -1 if the header does not exist.

Usage:

if (pv_remove_header(hname, hvalue))
{
    "removed"
}
else
{
    "does not exist or errors"
}

pv_remove_header(hname, idx, hvalue)

This function works similar to pv_remove_header(hname, hvalue) but should be used when there are multiple headers with the same name one of them to be removed. Index order is top to bottom.

Usage:

if (pv_remove_header(hname, idx, hvalue))
{
    "removed"
}
else
{
    "does not exist or errors"
}

3.3. Pseudovariables

$x_hdr

This pseudovariable is used to append/modify/remove headers by their name and can be used instead of the pv_append_header(), pv_modify_header(), pv_remove_header() functions.

Usage:

append header "X-Header" with value "example". NOTE: It always appends a header, even there is already one with the same name

$x_hdr(X-Header) = "example";

modify header "X-Header" with index 0. Returns an error if there is no such index

$(x_hdr(X-Header)[0]) = "example";

remove all occurrences of header "X-Header" and append one with value "example"

$(x_hdr(X-Header)[*]) = "example";

remove header "X-Header" with index 2 (if there are multiple headers). Returns an error if there is no such index

$(x_hdr(X-Header)[2]) = $null;

remove all occurrences of the header. Does not produce an error if there is no such header

$(x_hdr(X-Header)[*]) = $null;

retrieve a value of header "X-Header" with index 0, otherwise $null

$var(test) = $x_hdr(X-Header);

retrieve a value of header "X-Header" with index 0 otherwise $null

$var(test) = $x_hdr(X-Header)[*]);

retrieve a value of header "X-Header" with index 2 otherwise $null

$var(test) = $(x_hdr(X-Header)[2]);

$x_fu, $x_tu

These pseudovariables are used to modify/retreive the "From" and "To" headers.

Usage:

modify the header

$x_fu = "User1 <440001@example.local>";

retrieve a value of the header

$var(test) = $x_fu;

$x_tu usage is the same

$x_fU, $x_tU

These pseudovariables are used to modify/retreive the username part of the "From" and "To" headers.

Usage:

modify the username part

$x_fU = "440001";

retrieve the username part

$var(test) = $x_fU;

$x_tU usage is the same

$x_fd, $x_td

These pseudovariables are used to modify/retreive the domain part of the "From" and "To" headers.

Usage:

modify the domain part

$x_fd = "example.local";

retrieve the domain part

$var(test) = $x_fd;

$x_td usage is the same

$x_fn, $x_tn

These pseudovariables are used to modify/retreive the display part of the "From" and "To" headers.

Usage:

modify the username part

$x_fn = "User1";

retrieve the domain part

$var(test) = $x_fn;

$x_tn usage is the same

$x_ft, $x_tt

These pseudovariables are used to retreive the tag part of the "From" and "To" headers.

Usage:

retrieve the tag part

$var(test) = $x_ft;

$x_tt usage is the same