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.
Victor Seva
28bb5a9977
|
13 years ago | |
|---|---|---|
| .. | ||
| doc | 13 years ago | |
| Makefile | 13 years ago | |
| README | 13 years ago | |
| avp.c | 13 years ago | |
| avp.xml | 13 years ago | |
README
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-RT
P-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-RT
P-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)
...