Avp Module

Jiri Kuthan

FhG Fokus

Michal Matyska

iptel
Revision History
Revision $Revision: 1.3 $$Date: 2006/05/04 12:20:33 $

Overview

This module contains several functions that can be used to manipulate the contents of AVPs (Attribute-Value pairs). The AVPs are variables attached to the SIP message being processed. Each variable has its name and value. AVPs can be used to store arbitrary data or as a means of inter-module comminication.

You may also want to check the avpops module which is more flexible and contains more functions. In future SER releases the avp module will be probably deprecated in favor of avpops module.

Functions

Revision History
Revision $Revision: 1.4 $$Date: 2006/05/04 18:51:54 $

set_iattr(attribute,value)

Create an AVP of type integer.

Meaning of the parameter is as follows:

  • attribute - The name of the AVP to be created.

  • value - Integer value of the AVP.

Example 1. set_iattr usage

...
set_iattr("fr_inv_timer", "60")
...
	    

flags2attr()

Store the current state of SER flags into AVP called "flags".

Example 2. flags2attr usage

...
flags2attr()
...
	    

set_sattr(attribute,value)

Create an AVP of type string.

Meaning of the parameter is as follows:

  • attribute - The name of the AVP to be created.

  • value - String value of the AVP.

Example 3. set_sattr usage

...
set_sattr("called_number", "1234")
...
	    

uri2attr(attribute)

Store the Request-URI of the message being processed in an AVP. The new value of the Request-URI will be used if it has been already rewritten by some other function or module.

Meaning of the parameter is as follows:

  • attribute - The name of the AVP.

Example 4. uri2attr usage

...
uri2attr("saved_ruri")
...
	    

print_sattr(attribute)

Print the value of an AVP to syslog.

Meaning of the parameter is as follows:

  • attribute - The name of the AVP.

attr2uri(attribute)

Rewrite the Request-URI of the message being processed with the value of an AVP.

Meaning of the parameter is as follows:

  • attribute - The name of the AVP.

is_sattr_set(attribute)

Test for the existence of AVP with given name. The function returns 1 if given AVP exists and -1 if not.

Meaning of the parameter is as follows:

  • attribute - The name of the AVP.

Example 5. is_sattr_set usage

...
if (is_sattr_set("saved_ruri")) {
  uri2attr("saved_uri");
} else {
  rewriteuri("sip:a@iptel.org");
};
...
		

avp_equals(attribute, value)

Test whether an AVP with given name and value exists. The function returns 1 if the AVP with given name and value exists and -1 if not. The value of the AVP is compared string-wise. The comparison is case sensitive.

Meaning of the parameter is as follows:

  • attribute - The name of the AVP.

  • value - The AVP value to look for.

avp_equals_xl(attribute, xl_format)

Test whether an AVP with given name and value exists. The function returns 1 if the AVP with given name and value exists and -1 if not. The value of the AVP is compared string-wise to the result of xlog formatting call. The comparison is case sensitive.

Meaning of the parameter is as follows:

  • attribute - The name of the AVP.

  • xl_format - The xlog formatting string, result of which is looked for in AVP.

Note: You must ensure, that the xlog module is loaded to be able to use this function.

Example 6. avp_equals_xl usage

...
if (avp_equals_xl("my_avp", "%ct")) {
  # my_avp has value equal to current Contact header field
} else {
  # my_avp was different
}
...
	    

avp_exists(attribute)

Test whether an AVP with given name exists. The function returns 1 if the AVP with given name exists and -1 if not.

Meaning of the parameter is as follows:

  • attribute - The name of the AVP.

dump_avp()

Dumps all AVPs in user lists to the debug output (with level INFO).

The function does not require any parameters.

xlset_attr(attribute, xl_format)

Creates new AVP identified by attribute and assigns the result string of xlog formatting rules as its value.

Meaning of the parameter is as follows:

  • attribute - The name of the AVP.

  • xl_format - String used for xlog formatting. For detailed info see documentation of xlog module.

Note: You must ensure, that the xlog module is loaded to be able to use this function.

insert_avp_hf(name)

Inserts new header into the request, which is beeing forwarded. The AVP name is the name of the header field. If you need to insert header with name which differs from the AVP name use insert_avp_hf(header_name, avp_name) instead.

Inserting means putting the header to the beginning of the request, before any others.

Meaning of the parameter is as follows:

  • name - The name of the header field which is inserted into forwarded request as well as name of AVP which's value is put as the header field value.

insert_avp_hf(header_name, avp_name)

Inserts new header into the request, which is beeing forwarded.

Inserting means putting the header to the beginning of the request, before any others.

Meaning of the parameter is as follows:

  • header_name - The name of the header field which is inserted into forwarded request.

  • avp_name - The name of AVP which's value is put as the header field value.

Example 7. insert_avp_hf usage

...
set_sattr("my_route","<sip:user@host:port;lr>");
insert_avp_hf("Route", "my_route");
...
	    

append_avp_hf(name)

Appends new header into the request, which is beeing forwarded. The AVP name is the name of the header field. If you need to append header with name which differs from the AVP name use append_avp_hf(header_name, avp_name) instead.

Appending means putting the header to the end of the request, after any others.

Meaning of the parameter is as follows:

  • name - The name of the header field which is appended into forwarded request as well as name of AVP which's value is put as the header field value.

append_avp_hf(header_name, avp_name)

Appends new header into the request, which is beeing forwarded.

Appending means putting the header to the end of the request, after any others.

Meaning of the parameter is as follows:

  • header_name - The name of the header field which is appended into forwarded request.

  • avp_name - The name of AVP which's value is put as the header field value.

replace_avp_hf(name)

Replaces header in the request, which is beeing forwarded. The AVP name is the same as the name of the header field. If you need to replace header with name which differs from the AVP name use replace_avp_hf(header_name, avp_name) instead.

Replacing means removing all the headers with specified name and appending new one at the end, with the value from AVP.

Meaning of the parameter is as follows:

  • name - The name of the header field which is replaced in forwarded request as well as name of AVP which's value is put as the header field value.

replace_avp_hf(header_name, avp_name)

Replaces header in the request, which is beeing forwarded.

Replacing means removing all the headers with specified name and appending new one at the end, with the value from AVP.

Meaning of the parameter is as follows:

  • header_name - The name of the header field which is replaced in forwarded request.

  • avp_name - The name of AVP which's value is put as the header field value.

avp_to_reply(name)

Appends new header into the reply at the request time processing. The AVP name is the name of the header field. If you need to append header with name which differs from the AVP name use avp_to_reply(header_name, avp_name) instead.

If you need to append headers during reply processing you can use insert_avp_hf and append_avp_hf. This function stores data and waits for the reply being created.

Meaning of the parameter is as follows:

  • name - The name of the header field which is appended into reply as well as name of AVP which's value is put as the header field value.

avp_to_reply(header_name, avp_name)

Appends new header into the reply at the request time processing.

Meaning of the parameter is as follows:

  • header_name - The name of the header field which is appended into reply.

  • avp_name - The name of AVP which's value is put as the header field value.

Example 8. avp_into_reply usage

...
xlset_attr("my_route","<sip:%Hf:5080;lr>";
avp_into_reply("P-Hint-Route", "my_route");
...
	    

avp_destination(avp_name)

Sets the destination of the forwarded request to the value of AVP, which must be a SIP URI or nameaddr format.

Meaning of the parameter is as follows:

  • avp_name - The name of AVP which's value is used for further request forwarding.

Example 9. avp_destination usage

...
xlset_attr("my_route","<sip:%<next_host>:%<next_port>;myparam=a123;lr>";
insert_avp_hf("Route", "my_route");
avp_destination("my_route");
t_relay();
...
	    

xlset_destination(xl_format)

Sets the destination of the forwarded request to the value of result of xlog formatted string. Either SIP URI or nameaddr format is allowed.

Meaning of the parameter is as follows:

  • xl_format - xlog module formatting string, the result is used for request forwarding.

Note: You must ensure, that the xlog module is loaded to be able to use this function.

Example 10. xlset_destination usage

...
xlset_destination("%<next_host>:%<next_port>");
t_relay();
...
	    

avp_subst(avp_name, subst_re)

The value of the AVP identified by avp_name name is matched and substitued according to the subst_re sed like expression. Result of the substitution is then stored in the original AVP.

Meaning of the parameter is as follows:

  • avp_name - Name of the AVP which will be used for the substitution.

  • subst_re - SED like match&replace regullar expression.

Example 11. avp_subst usage

...
avp_subst("uri","/tel:[0-9]*/sip:\1@foo.bar;user=phone/");
...
	    

avp_delete(avp_name)

The AVP identified by avp_name name is deleted.

Meaning of the parameter is as follows:

  • avp_name - Name of the AVP which will be deleted.

Example 12. avp_subst usage

...
failure_route[1] {
	if (status=~4[0-9][0-9]) {
		if (is_sattr_set("backup_gw") {
			append_branch;
			avp_destination("backup_gw");
			avp_delete("backup_gw");
			t_relay();
		}
	}
...
	    

hdr_body2attrs(headername, prefix)

Function parses a header body content scans for fld1=val1,fld2=val2,... and creates bunch of avps prefixfld1:= val1, prefixfld2:= val2, .... If possible stores values as integers.

Meaning of the parameter is as follows:

  • headername - The header name, which will be scanned for the name=value pairs.

    If you want to create only AVPs with integer value use "/i" postfix to the header name.

    If you want to create only AVPs with string value use "/s" postfix to the header name.

  • prefix - The prefix, which is added before the name parsed from the header body.

hdr_body2attrs2(headername, prefix)

Function parses a header body content scans for fld1=val1,val2;fld2=val3,... and creates bunch of avps prefixfld1#1:= val1, prefixfld1#2:= val2, prefixfld2:=val3 .... If possible stores values as integers.

Meaning of the parameter is as follows:

  • headername - The header name, which will be scanned for the name=value pairs.

    If you want to create only AVPs with integer value use "/i" postfix to the header name.

    If you want to create only AVPs with string value use "/s" postfix to the header name.

  • prefix - The prefix, which is added before the name parsed from the header body.

Example 13. hdr_body2attrs and hdr_body2attrs2 usage

if (method=="BYE") {
	# QoS reporting
	if (search("^User-Agent: AVM FRITZ!Box Fon*")) {
		hdr_body2attrs2("X-RTP-Stat/i", "QoS_");
		xlog("L_INFO", "QoS: %Ts, %fu, %tu, %ci, %{User-Agent}, %{X-RTP-Stat}\n");
	} else if (search("^User-Agent: Sipura/*")) {
		hdr_body2attrs("P-RTP-Stat/i", "QoS_");
		xlog("L_INFO", "QoS: %Ts, %fu, %tu, %ci, %{User-Agent}, %{P-RTP-Stat}\n");
	}
}
# AVP QoS_xx now contain the values from appropriate header
# e.g. QoS_JI is jitter
	

Parameters

Revision History
Revision $Revision: 1.3 $$Date: 2006/05/04 12:20:34 $

xlbuf_size (integer)

Defines size of internal buffer for all xlog formatting calls. If you don't use xlog formatting calls, you can set it to 0 to preserve some memory, if you get errors while formatting due to buffer size, you can enlarge it.

Default value is 256.

Example 14. Set xlbuf_size parameter

...
modparam("avp", "xlbuf_size", 1024)
...