modules/avp/README
1f28ea63
 The AVP module
71ce6e45
 
e400ae22
 Jiri Kuthan
71ce6e45
 
e400ae22
    FhG Fokus
    <jiri@iptel.org>
 
 Michal Matyska
 
    iptel
    <michal@iptel.org>
 
1f28ea63
    Copyright � 2004, 2005, 2006 FhG FOKUS, iptelorg GmbH
e7dc20ba
      __________________________________________________________________
0577abba
 
    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)
e400ae22
 
1f28ea63
    List of Examples
 
0577abba
    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)
1f28ea63
 
 1. Overview
e400ae22
 
e7dc20ba
    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.
e400ae22
 
e7dc20ba
    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.
e400ae22
 
1f28ea63
 2. Functions
e400ae22
 
98b4fd46
    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)
 
1f28ea63
 2.1. set_iattr(attribute,value)
e400ae22
 
    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.
 
0577abba
    Example 1.1. set_iattr usage
e400ae22
 ...
 set_iattr("fr_inv_timer", "60")
 ...
 
1f28ea63
 2.2. flags2attr("$avp")
e400ae22
 
c79c33f1
    Store the current state of Kamailio flags into the specified AVP.
e400ae22
 
0577abba
    Example 1.2. flags2attr usage
e400ae22
 ...
 flags2attr("$msg_flags")
 ...
 
1f28ea63
 2.3. set_sattr(attribute,value)
e400ae22
 
    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.
 
0577abba
    Example 1.3. set_sattr usage
e400ae22
 ...
 set_sattr("called_number", "1234")
 ...
 
1f28ea63
 2.4. print_attr($attribute)
e400ae22
 
    Print the value of an AVP to syslog.
 
    Meaning of the parameter is as follows:
      * attribute - The name of the AVP.
 
1f28ea63
 2.5. attr2uri($attribute[,uri-part])
e400ae22
 
e7dc20ba
    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
e400ae22
    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.
e7dc20ba
        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.
e400ae22
 
1f28ea63
 2.6. attr_exists(attribute)
e400ae22
 
e7dc20ba
    Test for the existence of AVP with given name. The function returns 1
e400ae22
    if given AVP exists and -1 if not.
 
    Meaning of the parameter is as follows:
      * attribute - The name of the AVP.
 
0577abba
    Example 1.4. attr_exists usage
e400ae22
 ...
 if (attr_exists("saved_ruri")) {
c79c33f1
     attr2uri("saved_uri");
e400ae22
 } else {
c79c33f1
     rewriteuri("sip:a@iptel.org");
e400ae22
 };
 ...
 
1f28ea63
 2.7. attr_equals(attribute, value)
e400ae22
 
e7dc20ba
    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
e400ae22
    sensitive.
 
    Meaning of the parameter is as follows:
      * attribute - The name of the AVP.
      * value - The AVP value to look for.
 
1f28ea63
 2.8. attr_equals_xl(attribute, xl_format)
e400ae22
 
e7dc20ba
    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
e400ae22
    formatting call. The comparison is case sensitive.
 
    Meaning of the parameter is as follows:
      * attribute - The name of the AVP.
e7dc20ba
      * xl_format - The xprint formatting string, result of which is looked
        for in AVP.
e400ae22
 
e7dc20ba
    Note: You must ensure, that the xprint module is loaded to be able to
1f28ea63
    use this function.
e400ae22
 
0577abba
    Example 1.5. attr_equals_xl usage
e400ae22
 ...
 if (attr_equals_xl("my_avp", "%ct")) {
   # my_avp has value equal to current Contact header field
 } else {
   # my_avp was different
 }
 ...
 
1f28ea63
 2.9. dump_attrs()
e400ae22
 
    Dumps all AVPs in user lists to the debug output (with level INFO).
 
    The function does not require any parameters.
 
1f28ea63
 2.10. xlset_attr($attribute, xl_format)
e400ae22
 
e7dc20ba
    Creates new AVP identified by attribute and assigns the result string
6909bcae
    of xprint formatting rules as its value.
e400ae22
 
    Meaning of the parameter is as follows:
      * $attribute - The name of the AVP.
e7dc20ba
      * xl_format - String used for xprint formatting. For detailed info
1f28ea63
        see documentation of xprint module.
e400ae22
 
e7dc20ba
    Note: You must ensure, that the xprint module is loaded to be able to
1f28ea63
    use this function.
e400ae22
 
1f28ea63
 2.11. xlfix_attr($attribute)
ffb2f93a
 
    Fixes an xl formatted attribute value to pure string.
 
    Meaning of the parameter is as follows:
      * $attribute - The name of the AVP.
 
1f28ea63
 2.12. insert_attr_hf(name)
e400ae22
 
e7dc20ba
    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.
e400ae22
 
e7dc20ba
    Inserting means putting the header to the beginning of the request,
e400ae22
    before any others.
 
    Meaning of the parameter is as follows:
e7dc20ba
      * 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
e400ae22
        the header field value.
 
1f28ea63
 2.13. insert_attr_hf(header_name, $avp_name)
e400ae22
 
    Inserts new header into the request, which is beeing forwarded.
 
e7dc20ba
    Inserting means putting the header to the beginning of the request,
e400ae22
    before any others.
 
    Meaning of the parameter is as follows:
e7dc20ba
      * header_name - The name of the header field which is inserted into
e400ae22
        forwarded request.
e7dc20ba
      * $avp_name - The name of AVP which's value is put as the header
e400ae22
        field value.
 
0577abba
    Example 1.6. insert_attr_hf usage
e400ae22
 ...
 set_sattr("my_route","<sip:user@host:port;lr>");
 insert_attr_hf("Route", "$my_route");
 ...
 
1f28ea63
 2.14. append_attr_hf(name)
e400ae22
 
e7dc20ba
    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.
e400ae22
 
e7dc20ba
    Appending means putting the header to the end of the request, after any
    others.
e400ae22
 
    Meaning of the parameter is as follows:
e7dc20ba
      * 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
e400ae22
        the header field value.
 
1f28ea63
 2.15. append_attr_hf(header_name, $avp_name)
e400ae22
 
    Appends new header into the request, which is beeing forwarded.
 
e7dc20ba
    Appending means putting the header to the end of the request, after any
    others.
e400ae22
 
    Meaning of the parameter is as follows:
e7dc20ba
      * header_name - The name of the header field which is appended into
e400ae22
        forwarded request.
e7dc20ba
      * $avp_name - The name of AVP which's value is put as the header
e400ae22
        field value.
 
1f28ea63
 2.16. replace_attr_hf(name)
e400ae22
 
e7dc20ba
    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
e400ae22
    replace_attr_hf(header_name, $avp_name) instead.
 
e7dc20ba
    Replacing means removing all the headers with specified name and
e400ae22
    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
e7dc20ba
        request as well as name of AVP which's value is put as the header
e400ae22
        field value.
 
1f28ea63
 2.17. replace_attr_hf(header_name, $avp_name)
e400ae22
 
    Replaces header in the request, which is beeing forwarded.
 
e7dc20ba
    Replacing means removing all the headers with specified name and
e400ae22
    appending new one at the end, with the value from AVP.
 
    Meaning of the parameter is as follows:
e7dc20ba
      * header_name - The name of the header field which is replaced in
e400ae22
        forwarded request.
e7dc20ba
      * $avp_name - The name of AVP which's value is put as the header
e400ae22
        field value.
 
1f28ea63
 2.18. attr_to_reply(name)
e400ae22
 
e7dc20ba
    Appends new header into the reply at the request time processing. The
e400ae22
    AVP name is the name of the header field. If you need to append header
e7dc20ba
    with name which differs from the AVP name use
e400ae22
    attr_to_reply(header_name, $avp_name) instead.
 
e7dc20ba
    If you need to append headers during reply processing you can use
e400ae22
    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:
e7dc20ba
      * 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.
e400ae22
 
1f28ea63
 2.19. attr_to_reply(header_name, $avp_name)
e400ae22
 
    Appends new header into the reply at the request time processing.
 
    Meaning of the parameter is as follows:
e7dc20ba
      * header_name - The name of the header field which is appended into
e400ae22
        reply.
e7dc20ba
      * $avp_name - The name of AVP which's value is put as the header
e400ae22
        field value.
 
0577abba
    Example 1.7. attr_to_reply usage
e400ae22
 ...
 xlset_attr("$my_route","<sip:%Hf:5080;lr>";
 attr_to_reply("P-Hint-Route", "my_route");
 ...
 
1f28ea63
 2.20. attr_destination($avp_name)
e400ae22
 
e7dc20ba
    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.
e400ae22
    "Foo Bar" <sip:uri>).
 
    Meaning of the parameter is as follows:
e7dc20ba
      * $avp_name - The name of AVP which's value is used for further
e400ae22
        request forwarding.
 
0577abba
    Example 1.8. attr_destination usage
e400ae22
 ...
 xlset_attr("$my_route","<sip:%<next_host>:%<next_port>;myparam=a123;lr>");
 insert_attr_hf("Route", "$my_route");
 attr_destination("$my_route");
 t_relay();
 ...
 
1f28ea63
 2.21. xlset_destination(xl_format)
e400ae22
 
e7dc20ba
    Sets the destination of the forwarded request to the value of result of
    xprint formatted string. Either SIP URI or nameaddr format is allowed.
e400ae22
 
    Meaning of the parameter is as follows:
e7dc20ba
      * xl_format - xprint module formatting string, the result is used for
        request forwarding.
e400ae22
 
e7dc20ba
    Note: You must ensure, that the xprint module is loaded to be able to
1f28ea63
    use this function.
e400ae22
 
0577abba
    Example 1.9. xlset_destination usage
e400ae22
 ...
 xlset_destination("%<next_host>:%<next_port>");
 t_relay();
 ...
 
1f28ea63
 2.22. subst_attr($avp_name, subst_re)
e400ae22
 
e7dc20ba
    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.
e400ae22
 
    Meaning of the parameter is as follows:
e7dc20ba
      * $avp_name - Name of the AVP which will be used for the
e400ae22
        substitution.
      * subst_re - SED like match&replace regullar expression.
 
0577abba
    Example 1.10. subst_attr usage
e400ae22
 ...
 subst_attr("$uri","/tel:[0-9]*/sip:\1@foo.bar;user=phone/");
 ...
 
1f28ea63
 2.23. del_attr($avp_name)
e400ae22
 
    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.
 
0577abba
    Example 1.11. del_attr usage
e400ae22
 ...
 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();
                 }
         }
 ...
 
1f28ea63
 2.24. hdr_body2attrs(headername, prefix)
e400ae22
 
e7dc20ba
    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.
e400ae22
 
    Meaning of the parameter is as follows:
e7dc20ba
      * headername - The header name, which will be scanned for the
e400ae22
        name=value pairs.
e7dc20ba
        If you want to create only AVPs with integer value use "/i" postfix
        to the header name.
e400ae22
        If you want to create only AVPs with string value use "/s" postfix
        to the header name.
e7dc20ba
      * prefix - The prefix, which is added before the name parsed from the
        header body.
e400ae22
 
1f28ea63
 2.25. hdr_body2attrs2(headername, prefix)
e400ae22
 
e7dc20ba
    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
e400ae22
    values as integers.
 
    Meaning of the parameter is as follows:
e7dc20ba
      * headername - The header name, which will be scanned for the
e400ae22
        name=value pairs.
e7dc20ba
        If you want to create only AVPs with integer value use "/i" postfix
        to the header name.
e400ae22
        If you want to create only AVPs with string value use "/s" postfix
        to the header name.
e7dc20ba
      * prefix - The prefix, which is added before the name parsed from the
        header body.
e400ae22
 
0577abba
    Example 1.12. hdr_body2attrs and hdr_body2attrs2 usage
e400ae22
 if (method=="BYE") {
         # QoS reporting
         if (search("^User-Agent: AVM FRITZ!Box Fon*")) {
                 hdr_body2attrs2("X-RTP-Stat/i", "QoS_");
e7dc20ba
                 xplog("L_INFO", "QoS: %Ts, %fu, %tu, %ci, %{User-Agent}, %{X-RTP
 -Stat}\n");
e400ae22
         } else if (search("^User-Agent: Sipura/*")) {
                 hdr_body2attrs("P-RTP-Stat/i", "QoS_");
e7dc20ba
                 xplog("L_INFO", "QoS: %Ts, %fu, %tu, %ci, %{User-Agent}, %{P-RTP
 -Stat}\n");
e400ae22
         }
 }
 # AVP QoS_xx now contain the values from appropriate header
 # e.g. QoS_JI is jitter
 
1f28ea63
 3. Parameters
e400ae22
 
98b4fd46
    3.1. xlbuf_size (integer)
 
1f28ea63
 3.1. xlbuf_size (integer)
e400ae22
 
e7dc20ba
    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.
e400ae22
 
    Default value is 256.
 
0577abba
    Example 1.13. Set xlbuf_size parameter
e400ae22
 ...
 modparam("avp", "xlbuf_size", 1024)
 ...