1. Avpops Module

Ramona-Elena Modroiu

   Voice Sistem

   Copyright  2004 Voice Sistem
   Revision History
   Revision $Revision: 1.7.6.1 $ $Date: 2008/06/11 13:11:57 $
     __________________________________________________________________

   1.1. Overview
   1.2. Dependencies

        1.2.1. SER Modules

   1.3. Parameters

        1.3.1. avp_url (string)
        1.3.2. avp_table (string)
        1.3.3. avp_aliases (string)
        1.3.4. use_domain (integer)
        1.3.5. uid_column (string)
        1.3.6. username_column (string)
        1.3.7. domain_column (string)
        1.3.8. attribute_column (string)
        1.3.9. value_column (string)
        1.3.10. type_column (string)
        1.3.11. db_scheme (string)

   1.4. Functions

        1.4.1. avp_db_load(source,name)
        1.4.2. avp_db_store(source,name)
        1.4.3. avp_db_delete(source,name)
        1.4.4. avp_write(value,name)
        1.4.5. avp_delete(name)
        1.4.6. avp_pushto(destination,name)
        1.4.7. avp_check(name,op_value)
        1.4.8. avp_copy(old_name,new_name)
        1.4.9. is_avp_set()
        1.4.10. avp_print()

   1.5. Frequently Asked Questions

1.1. Overview

   AVPops (AVP-operations) modules implements a set of script functions
   which allow access and manipulation of user AVPs (preferences). AVPs
   are a powerful tool for implementing services/preferences per
   user/domain. Now they are usable directly from configuration script.
   Functions for interfacing DB resources (loading/storing/removing),
   functions for swapping information between AVPs and SIP messages,
   function for testing/checking the value of an AVP.

   An up-to-date tutorial providing more information (detailed
   explanations and commented examples) can be found on Voice Sistem
   documentation web page at http://voice-system.ro/docs/avpops.

1.2. Dependencies

1.2.1. SER Modules

   The following modules must be loaded before this module:
     * Optionally a database module

1.3. Parameters

   Revision History
   Revision $Revision: 1.7.6.1 $ $Date: 2008/06/11 13:11:57 $

1.3.1. avp_url (string)

   DB URL for database connection.

   This parameter is optional, it's default value being NULL.

   Example 1. Set avp_url parameter
...
modparam("avpops","avp_url","mysql://user:passwd@host/database")
...

1.3.2. avp_table (string)

   DB table to be used.

   This parameter is optional, it's default value being NULL.

   Example 2. Set avp_table parameter
...
modparam("avpops","avp_table","avptable")
...

1.3.3. avp_aliases (string)

   Contains a multiple definition of aliases for AVP names.

   This parameter is optional.

   Example 3. Set avp_aliases parameter
...
modparam("avpops","avp_aliases","uid=I:660;email=s:email_addr;fwd=i:753")
...

1.3.4. use_domain (integer)

   If the domain part of the an URI should be used for identifying an AVP
   in DB operations.

   Default value is 0 (no).

   Example 4. Set use_domain parameter
...
modparam("avpops","use_domain","1")
...

1.3.5. uid_column (string)

   Name of column containing the uid (unique user id).

   Default value is "uid".

   Example 5. Set uid_column parameter
...
modparam("avpops","uid_column","uid")
...

1.3.6. username_column (string)

   Name of column containing the username.

   Default value is "username".

   Example 6. Set username_column parameter
...
modparam("avpops","username_column","username")
...

1.3.7. domain_column (string)

   Name of column containing the domain name.

   Default value is "domain".

   Example 7. Set domain_column parameter
...
modparam("avpops","domain_column","domain")
...

1.3.8. attribute_column (string)

   Name of column containing the attribute name (AVP name).

   Default value is "attribute".

   Example 8. Set attribute_column parameter
...
modparam("avpops","attribute_column","attribute")
...

1.3.9. value_column (string)

   Name of column containing the AVP value.

   Default value is "value".

   Example 9. Set value_column parameter
...
modparam("avpops","value_column","value")
...

1.3.10. type_column (string)

   Name of column containing the AVP type.

   Default value is "type".

   Example 10. Set type_column parameter
...
modparam("avpops","type_column","type")
...

1.3.11. db_scheme (string)

   Definition of a DB schemeto be used for non-standard access to Database
   information.

   Default value is "NULL".

   Example 11. Set db_scheme parameter
...
modparam("avpops","db_scheme", "scheme1:table=subscriber;uid_column=uid;value_co
lumn=first_name")
...

1.4. Functions

   Revision History
   Revision $Revision: 1.7.6.1 $ $Date: 2008/06/11 13:11:57 $

1.4.1.  avp_db_load(source,name)

   Loads from DB into memory the AVPs corresponding to the given source.

   Meaning of the parameters is as follows:
     * source - what info is used for identifying the AVPs. Parameter
       syntax:
source = (sip_uri) [ '/' ( 'username' | 'domain' ) ] ) | (avp_alias) | str_value
sip_uri = '$from' | '$to' | '$ruri'
     * name - which AVPs will be loaded from DB into memory. Parameter
       syntax is:
          +
name = avp_spec [ '/' ( table_name | '$' db_scheme ) ]
avp_spec = '' | 's:' | 'i:' | avp_name | avp_alias

   Example 12. avp_db_load usage
...
avp_db_load("$from","i:678");
avp_db_load("$ruri/domain","i:/domain_preferences");
avp_db_load("$uid","s:404fwd/fwd_table");
avp_db_load("$ruri","i:123/$some_scheme");
...

1.4.2.  avp_db_store(source,name)

   Stores to DB the AVPs corresponding to the given source.

   The meaning and usage of the parameters are identical as for
   avp_db_load(source,name) function. Please refer to its description.

   Example 13. avp_db_store usage
...
avp_db_store("$to","i:678");
avp_db_store("$ruri/username","$email");
...

1.4.3.  avp_db_delete(source,name)

   Deletes from DB the AVPs corresponding to the given source.

   The meaning and usage of the parameters are identical as for
   avp_db_load(source,name) function. Please refer to its description.

   Example 14. avp_db_delete usage
...
avp_db_delete("$to","i:678");
avp_db_delete("$ruri/username","$email");
avp_db_delete("$uid","s:404fwd/fwd_table");
...

1.4.4.  avp_write(value,name)

   The function writes some value (given) or some information from the SIP
   message into a new AVP.

   Meaning of the parameters is as follows:
     * value - the value to be written into the AVP. Parameter syntax:
value = (variable) | (fix_value)
variable = '$src_ip' | '$dst_ip' | '$hdr[name]' | (sip_uri) [ '/' ( 'username' |
 'domain' ) ] )
sip_uri = '$from' | '$to' | '$ruri'
fix_value = 'i:'integer | 's:'string | string
     * name - the name of the new written AVP. Parameter syntax is:
name = avp_name | avp_alias

   Example 15. avp_write usage
...
avp_write("$to","i:678");
avp_write("$ruri/username","$email");
avp_write("$src_ip","s:ip");
avp_write("$hdr[call-id]","i:11");
avp_write("i:333","i:6");
...

1.4.5.  avp_delete(name)

   Deletes from memory the AVPs with name or, if empty, all AVPs.

   Meaning of the parameters is as follows:
     * name - which AVPs will be deleted from memory. Parameter syntax is:
name = ('' | 's:' | 'i:' | avp_name | avp_alias ) [ '/' flag ]
flag = 'g' | 'G'

   Example 16. avp_delete usage
...
avp_delete("i:678/g");
avp_delete("$email");
avp_delete("i:");
avp_delete("");
...

1.4.6.  avp_pushto(destination,name)

   Pushes the value of AVP(s) into the SIP message.

   Meaning of the parameters is as follows:
     * destination - as what will be the AVP value pushed into SIP
       message. Parameter syntax:
destination = ruri_dst | hdr_dst
ruri_dst = '$ruri' [ '/' ( 'username' | 'domain' ) ]
hdr_dst = '$hdr_name' [ '/' ( 'request' | 'reply' ) ]
     * name - which AVP(s) should be pushed into the SIP message.
       Parameter syntax is:
name = ( avp_name | avp_alias ) [ '/' flags ]
flags = 'g'

   Example 17. avp_pushto usage
...
avp_pushto("$ruri","i:678");
avp_pushto("$ruri/domain","s:backup_domains/g");
avp_pushto("$Email/reply","s:email");
avp_pushto("$Foo","$bar/g");
...

1.4.7.  avp_check(name,op_value)

   Checks the value of the AVP(s) against an operator and value.

   Meaning of the parameters is as follows:
     * name - which AVP(s) should be checked. Parameter syntax is:
name = ( avp_name | avp_alias )
     * op_value - define the operator, the value and flags for checking.
       Parameter syntax is:
op_value = operator '/' value [ '/' flags ]
operator = 'eq' | 'lt' | 'gt' | 're' | 'fm'
value = variable | fix_value
variable = '$from' | '$ruri' | '$from' | '$src_ip' | '$dst_ip' | avp_alias
fix_value = 'i:' integer | 's:' string | string
flags = 'g' | 'G' | 'i' | 'I'

   Example 18. avp_check usage
...
avp_check("i:678", "lt/i:345/g");
avp_check("s:person","eq/$from/I");
avp_check("s:foo","gt/$bar/g");
avp_check("s:foo","re/sip:.*@bar.net/g");
avp_check("s:foo","fm/$fm_avp/g");
...

1.4.8.  avp_copy(old_name,new_name)

   Copy / move an AVP under a new name.

   Meaning of the parameters is as follows:
     * name1 - which AVP(s) should be copied/moved. Parameter syntax is:
name = ( avp_name | avp_alias )
     * name2 - the new name of the copied/moved AVP(s). Parameter syntax
       is:
name = ( avp_name | avp_alias ) [ '/' flags ]
flags = 'g' | 'G' | 'd' | 'D'

   Example 19. avp_copy usage
...
avp_copy("i:678", "s:345/g");
avp_copy("$old","$new/gd");
...

1.4.9.  is_avp_set()

   Check if any AVP with name is set.

   Meaning of the parameters is as follows:
     * name - name of AVP to look for. Parameter syntax is:
          + name = ('s:'|'i:'|avp_name|avp_alias)

   Example 20. is_avp_set usage
...
if(is_avp_set("i:678/g"))
    log("AVP with integer id 678 exists\n");
...

1.4.10.  avp_print()

   Prints the list with all the AVPs from memory. This is only a
   helper/debug function.

   Example 21. avp_print usage
...
avp_print();
...

1.5. Frequently Asked Questions

   Revision History
   Revision $Revision: 1.7.6.1 $ $Date: 2008/06/11 13:11:57 $

   1.5.1. Where can I find more documentation about this module?
   1.5.2. Where can I post a question about this module?
   1.5.3. How can I report a bug?

   1.5.1.

         Where can I find more documentation about this module?

         An up-to-date tutorial providing more information (detailed
         explanations and commneted examples) can be found on Voice Sistem
         documentation web page at http://voice-system.ro/docs/avpops.

   1.5.2.

         Where can I post a question about this module?

         Sent an email to <support@voice-system.ro> or, if you want to keep the
         mail private, send it to <ramona@voice-system.ro>.

         Remember: first at all, check if your question was already answered on
         one of SER mailing lists:
           * serusers mailing list
           * serdev mailing list

   1.5.3.

         How can I report a bug?

         Accumulate as much as possible information (SER version, ser -V output,
         your OS (uname -a), SER logs, network dumps, core dump files,
         configuration file) and send a mail to <support@voice-system.ro>
