Attribute Value Pair (AVP) Variables in OpenSIPS


Here i want to talk about AVPs from routing script’s point of view and the database’s point of view.

AVPs IN The Routing Script

These variables are used in the routing script. They are allocated at the beginning of the transaction and unallocated when the transaction is completed. So they are called transaction-persistent variables (if stateful processing is used). If stateless processing is used, theses variables will be attached to a singular message. When the message is received or the transaction is created, it will initially have an empty list of AVPs. The AVPs will be created directly in the routing script or through functions called from the script. They will automatically attached to the message/transaction.

The AVPs are visible in the routes where the message will be processed (i.e. branch_route , failure_route, onreply_route). If we want the AVPs to be visible in the onreply_route, we need to enable the TM parameter “onreply_avp_mode”.

OpenSIPS ‘s AVPs are Read-Write variables (You can read data from AVP or write data to AVP). AVP can also deleted. When we assign a value to an AVP, the new value is appended to the AVP. So the AVP may contain multiple values. New assignment (write operation) will add a new value to the AVP. The AVP is like a stack (Last in First out).

AVP’s Synatx: The name starts with $ sign. It looks like $avp(name) or $(avp(name)[N]). The index “N”  referes to a specific value. If no index is used, the last added value will be returned. See the figure below

The assignment can be done directly in the script or by calling a function which brings values from database and add them to the AVP. To delete a specific AVP’s value, we do this  $(avp(test)[N])=NULL. To remove the last value, we do this $(avp(test))=NULL. If no values remained, the AVP will be deleted. You can also delete the AVP by avp_delete(“$avp(test)/g”).

AVPs In The Database

The AVPs in the routing script can be loaded by values taken from the database. The default table to store the AVPs is “usr_preferences”. This table is used by the “avpops” module. Each user which uniquely identified by Unique User ID (UUID) or (username and domain), may have several preferences formed in (attribute, value) pairs and stored in the usr_preferences table.  The AVP is defined by this tuple (Attribute, Type , Value). The Attribute is the name of the AVP(The name can be string or number). The type is number (0 (str:str), 1 (str:int), 2 (int:str), 3 (int:int)). For example $avp(123)=2 <=> Type = 3 (integer name and integer value). The value (as a field) is a string.

The figure below explains the structure of the usr_preferences table.

The table “usr_preferences” is the default but you can change it by adding this line in the opensips configuration file with your table’s name:

modparam(“avpops”, “avp_table”, “usr_preferences”)

When a SIP message is received or new SIP transaction is created, the user’s preferences should be taken into account otherwise it will not called preferences, right?.

The function avp_db_load(“$fu”,”$avp(test-name)”) loads the AVP which belongs to $fu and has the name “test_name”.  This function exists in the “avpops” module. So the module must be loaded when using this function or any other AVP ‘s functions. The second parameter of this function can be empty – which means all AVPs identified by the source(first parameter).

Opensipsctl and AVPs

You can use opensipsctl tool to manage AVPs (add, remove, or configure) in the database. To get help info, type #./opensipsctl avp help

For example to add AVP which has the name “trace”, type 1 (string,integer), and the value =1 (e.g. <=> true):

opensipsctl avp add  -T usr_preferences test@youripaddress trace 1 1

This correspond to $(AVP(trace)) in the routing script. The value will be 1.

Note: You can use your favourite database editor to manage  the AVPs  in the database directly (in “usr_preferences” table). For example “phpMyAdmin” (Mysql Administration on the web).

More Information


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s