mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
543 lines
17 KiB
543 lines
17 KiB
The AVP module
|
|
|
|
Jiri Kuthan
|
|
|
|
FhG Fokus
|
|
<jiri@iptel.org>
|
|
|
|
Michal Matyska
|
|
|
|
iptel
|
|
<michal@iptel.org>
|
|
|
|
Copyright © 2004, 2005, 2006 FhG FOKUS, iptelorg GmbH
|
|
__________________________________________________________________
|
|
|
|
Table of Contents
|
|
|
|
1. Admin Guide
|
|
|
|
1. Overview
|
|
2. Functions
|
|
|
|
2.1. set_iattr(attribute,value)
|
|
2.2. flags2attr("$avp")
|
|
2.3. set_sattr(attribute,value)
|
|
2.4. print_attr($attribute)
|
|
2.5. attr2uri($attribute[,uri-part])
|
|
2.6. attr_exists(attribute)
|
|
2.7. attr_equals(attribute, value)
|
|
2.8. attr_equals_xl(attribute, xl_format)
|
|
2.9. dump_attrs()
|
|
2.10. xlset_attr($attribute, xl_format)
|
|
2.11. xlfix_attr($attribute)
|
|
2.12. insert_attr_hf(name)
|
|
2.13. insert_attr_hf(header_name, $avp_name)
|
|
2.14. append_attr_hf(name)
|
|
2.15. append_attr_hf(header_name, $avp_name)
|
|
2.16. replace_attr_hf(name)
|
|
2.17. replace_attr_hf(header_name, $avp_name)
|
|
2.18. attr_to_reply(name)
|
|
2.19. attr_to_reply(header_name, $avp_name)
|
|
2.20. attr_destination($avp_name)
|
|
2.21. xlset_destination(xl_format)
|
|
2.22. subst_attr($avp_name, subst_re)
|
|
2.23. del_attr($avp_name)
|
|
2.24. hdr_body2attrs(headername, prefix)
|
|
2.25. hdr_body2attrs2(headername, prefix)
|
|
|
|
3. Parameters
|
|
|
|
3.1. xlbuf_size (integer)
|
|
|
|
List of Examples
|
|
|
|
1.1. set_iattr usage
|
|
1.2. flags2attr usage
|
|
1.3. set_sattr usage
|
|
1.4. attr_exists usage
|
|
1.5. attr_equals_xl usage
|
|
1.6. insert_attr_hf usage
|
|
1.7. attr_to_reply usage
|
|
1.8. attr_destination usage
|
|
1.9. xlset_destination usage
|
|
1.10. subst_attr usage
|
|
1.11. del_attr usage
|
|
1.12. hdr_body2attrs and hdr_body2attrs2 usage
|
|
1.13. Set xlbuf_size parameter
|
|
|
|
Chapter 1. Admin Guide
|
|
|
|
Table of Contents
|
|
|
|
1. Overview
|
|
2. Functions
|
|
|
|
2.1. set_iattr(attribute,value)
|
|
2.2. flags2attr("$avp")
|
|
2.3. set_sattr(attribute,value)
|
|
2.4. print_attr($attribute)
|
|
2.5. attr2uri($attribute[,uri-part])
|
|
2.6. attr_exists(attribute)
|
|
2.7. attr_equals(attribute, value)
|
|
2.8. attr_equals_xl(attribute, xl_format)
|
|
2.9. dump_attrs()
|
|
2.10. xlset_attr($attribute, xl_format)
|
|
2.11. xlfix_attr($attribute)
|
|
2.12. insert_attr_hf(name)
|
|
2.13. insert_attr_hf(header_name, $avp_name)
|
|
2.14. append_attr_hf(name)
|
|
2.15. append_attr_hf(header_name, $avp_name)
|
|
2.16. replace_attr_hf(name)
|
|
2.17. replace_attr_hf(header_name, $avp_name)
|
|
2.18. attr_to_reply(name)
|
|
2.19. attr_to_reply(header_name, $avp_name)
|
|
2.20. attr_destination($avp_name)
|
|
2.21. xlset_destination(xl_format)
|
|
2.22. subst_attr($avp_name, subst_re)
|
|
2.23. del_attr($avp_name)
|
|
2.24. hdr_body2attrs(headername, prefix)
|
|
2.25. hdr_body2attrs2(headername, prefix)
|
|
|
|
3. Parameters
|
|
|
|
3.1. xlbuf_size (integer)
|
|
|
|
1. 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 communication.
|
|
|
|
You may also want to check the avpops module which is more flexible and
|
|
contains more functions. In future Kamailio releases the avp module
|
|
will be probably deprecated in favor of avpops module.
|
|
|
|
2. Functions
|
|
|
|
2.1. set_iattr(attribute,value)
|
|
2.2. flags2attr("$avp")
|
|
2.3. set_sattr(attribute,value)
|
|
2.4. print_attr($attribute)
|
|
2.5. attr2uri($attribute[,uri-part])
|
|
2.6. attr_exists(attribute)
|
|
2.7. attr_equals(attribute, value)
|
|
2.8. attr_equals_xl(attribute, xl_format)
|
|
2.9. dump_attrs()
|
|
2.10. xlset_attr($attribute, xl_format)
|
|
2.11. xlfix_attr($attribute)
|
|
2.12. insert_attr_hf(name)
|
|
2.13. insert_attr_hf(header_name, $avp_name)
|
|
2.14. append_attr_hf(name)
|
|
2.15. append_attr_hf(header_name, $avp_name)
|
|
2.16. replace_attr_hf(name)
|
|
2.17. replace_attr_hf(header_name, $avp_name)
|
|
2.18. attr_to_reply(name)
|
|
2.19. attr_to_reply(header_name, $avp_name)
|
|
2.20. attr_destination($avp_name)
|
|
2.21. xlset_destination(xl_format)
|
|
2.22. subst_attr($avp_name, subst_re)
|
|
2.23. del_attr($avp_name)
|
|
2.24. hdr_body2attrs(headername, prefix)
|
|
2.25. hdr_body2attrs2(headername, prefix)
|
|
|
|
2.1. 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.1. set_iattr usage
|
|
...
|
|
set_iattr("fr_inv_timer", "60")
|
|
...
|
|
|
|
2.2. flags2attr("$avp")
|
|
|
|
Store the current state of Kamailio flags into the specified AVP.
|
|
|
|
Example 1.2. flags2attr usage
|
|
...
|
|
flags2attr("$msg_flags")
|
|
...
|
|
|
|
2.3. 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 1.3. set_sattr usage
|
|
...
|
|
set_sattr("called_number", "1234")
|
|
...
|
|
|
|
2.4. print_attr($attribute)
|
|
|
|
Print the value of an AVP to syslog.
|
|
|
|
Meaning of the parameter is as follows:
|
|
* attribute - The name of the AVP.
|
|
|
|
2.5. attr2uri($attribute[,uri-part])
|
|
|
|
Rewrite the whole Request-URI of the message being processed with the
|
|
value of an AVP, or if an uri-part is specified, rewrite only that
|
|
specific part.
|
|
|
|
Meaning of the parameter is as follows:
|
|
* $attribute - The name of the AVP.
|
|
* uri-part - The name of the part of the uri that will be rewritten.
|
|
The supported values are: "prefix", "uri", "username", "user",
|
|
"usernamepassword", "userpass", "domain", "host", "domainport",
|
|
"hostport", "port", "strip", "strip_tail". "prefix" will add the
|
|
AVP as a prefix to the username (equivalent to prefix("string")),
|
|
"strip" and "strip_tail" expect a number in the AVP and they will
|
|
remove the specified number of characters from the beginning,
|
|
respective the end of the username part of the uri. The rest of the
|
|
uri-part values names are self-explaining.
|
|
|
|
2.6. attr_exists(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 1.4. attr_exists usage
|
|
...
|
|
if (attr_exists("saved_ruri")) {
|
|
attr2uri("saved_uri");
|
|
} else {
|
|
rewriteuri("sip:a@iptel.org");
|
|
};
|
|
...
|
|
|
|
2.7. attr_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.
|
|
|
|
2.8. attr_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 xprint
|
|
formatting call. The comparison is case sensitive.
|
|
|
|
Meaning of the parameter is as follows:
|
|
* attribute - The name of the AVP.
|
|
* xl_format - The xprint formatting string, result of which is looked
|
|
for in AVP.
|
|
|
|
Note: You must ensure, that the xprint module is loaded to be able to
|
|
use this function.
|
|
|
|
Example 1.5. attr_equals_xl usage
|
|
...
|
|
if (attr_equals_xl("my_avp", "%ct")) {
|
|
# my_avp has value equal to current Contact header field
|
|
} else {
|
|
# my_avp was different
|
|
}
|
|
...
|
|
|
|
2.9. dump_attrs()
|
|
|
|
Dumps all AVPs in user lists to the debug output (with level INFO).
|
|
|
|
The function does not require any parameters.
|
|
|
|
2.10. xlset_attr($attribute, xl_format)
|
|
|
|
Creates new AVP identified by attribute and assigns the result string
|
|
of xprint formatting rules as its value.
|
|
|
|
Meaning of the parameter is as follows:
|
|
* $attribute - The name of the AVP.
|
|
* xl_format - String used for xprint formatting. For detailed info
|
|
see documentation of xprint module.
|
|
|
|
Note: You must ensure, that the xprint module is loaded to be able to
|
|
use this function.
|
|
|
|
2.11. xlfix_attr($attribute)
|
|
|
|
Fixes an xl formatted attribute value to pure string.
|
|
|
|
Meaning of the parameter is as follows:
|
|
* $attribute - The name of the AVP.
|
|
|
|
2.12. insert_attr_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_attr_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.
|
|
|
|
2.13. insert_attr_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 1.6. insert_attr_hf usage
|
|
...
|
|
set_sattr("my_route","<sip:user@host:port;lr>");
|
|
insert_attr_hf("Route", "$my_route");
|
|
...
|
|
|
|
2.14. append_attr_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_attr_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.
|
|
|
|
2.15. append_attr_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.
|
|
|
|
2.16. replace_attr_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_attr_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.
|
|
|
|
2.17. replace_attr_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.
|
|
|
|
2.18. attr_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
|
|
attr_to_reply(header_name, $avp_name) instead.
|
|
|
|
If you need to append headers during reply processing you can use
|
|
insert_attr_hf and append_attr_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.
|
|
|
|
2.19. attr_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 1.7. attr_to_reply usage
|
|
...
|
|
xlset_attr("$my_route","<sip:%Hf:5080;lr>";
|
|
attr_to_reply("P-Hint-Route", "my_route");
|
|
...
|
|
|
|
2.20. attr_destination($avp_name)
|
|
|
|
Sets the destination of the forwarded request to the value of AVP,
|
|
which must be either a SIP URI or a string in nameaddr format (e.g.
|
|
"Foo Bar" <sip:uri>).
|
|
|
|
Meaning of the parameter is as follows:
|
|
* $avp_name - The name of AVP which's value is used for further
|
|
request forwarding.
|
|
|
|
Example 1.8. attr_destination usage
|
|
...
|
|
xlset_attr("$my_route","<sip:%<next_host>:%<next_port>;myparam=a123;lr>");
|
|
insert_attr_hf("Route", "$my_route");
|
|
attr_destination("$my_route");
|
|
t_relay();
|
|
...
|
|
|
|
2.21. xlset_destination(xl_format)
|
|
|
|
Sets the destination of the forwarded request to the value of result of
|
|
xprint formatted string. Either SIP URI or nameaddr format is allowed.
|
|
|
|
Meaning of the parameter is as follows:
|
|
* xl_format - xprint module formatting string, the result is used for
|
|
request forwarding.
|
|
|
|
Note: You must ensure, that the xprint module is loaded to be able to
|
|
use this function.
|
|
|
|
Example 1.9. xlset_destination usage
|
|
...
|
|
xlset_destination("%<next_host>:%<next_port>");
|
|
t_relay();
|
|
...
|
|
|
|
2.22. subst_attr($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 1.10. subst_attr usage
|
|
...
|
|
subst_attr("$uri","/tel:[0-9]*/sip:\1@foo.bar;user=phone/");
|
|
...
|
|
|
|
2.23. del_attr($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 1.11. del_attr usage
|
|
...
|
|
failure_route[1] {
|
|
if (status=~4[0-9][0-9]) {
|
|
if (attr_exists("backup_gw") {
|
|
append_branch;
|
|
attr_destination("backup_gw");
|
|
del_attr("backup_gw");
|
|
t_relay();
|
|
}
|
|
}
|
|
...
|
|
|
|
2.24. 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.
|
|
|
|
2.25. 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 1.12. 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_");
|
|
xplog("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_");
|
|
xplog("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
|
|
|
|
3. Parameters
|
|
|
|
3.1. xlbuf_size (integer)
|
|
|
|
3.1. xlbuf_size (integer)
|
|
|
|
Defines size of internal buffer for all xprint formatting calls. If you
|
|
don't use xprint 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 1.13. Set xlbuf_size parameter
|
|
...
|
|
modparam("avp", "xlbuf_size", 1024)
|
|
...
|