Loads from DB into memory the AVPs corresponding to the given source (from user, to user, ruri user, uuid). Will be loaded all AVPs with name or, if empty, all AVPs. Normally, the function looks into the default table, but there is also the possibility to specify a different table to be used.
If a DB scheme is used, the data specified by the scheme will be loaded into AVP(s) name. In this case, full AVP name is required.
Function returns true only if there was at least one AVP loaded successfully.
Meaning of the parameters is as follows:
source - what is used for identifying the AVPs. It can be used the information from a SIP URI or an UUID:
$ruri - use information from RURI
$from - use information from FROM header
$to - use information from TO header
$avp_alias - use the content of the AVP (defined by alias) as UUID
str_value - use the string value directly as UUID
The following parameters are available:
uri - use the value as an URI (extract the username and domain from it)
uuid - use the value as uuid
username - use only the username part of the URI
domain - use only the domain part of the URI
if no parameter is given, the value is considered to be 'UUID' if it is a constant string or an AVP and 'URI', otherwise.
Parameter syntax:
source = (sip_uri|avp_alias|str_value) ['/'('username'|'domain'|'uri'|'uuid')]
sip_uri = '$from' | '$to' | '$ruri'
name - which AVPs will be loaded from DB into memory. This can be an avp_name or an avp_alias. It can be empty - which means all AVPs, or you may specify only the type - 'i:' means all AVPs with ID. It accepts as parameter the name of a DB table to be used. Parameter syntax is:
name = (''|'s:'|'i:'|avp_name|avp_alias)['/'db_spec]
db_spec = table_name | '$'db_scheme_name
Example 12. avp_db_load usage
...
avp_db_load("$from","i:678");
- loads all AVPs with ID 678 for username@domain
from FROM header
avp_db_load("$ruri/domain","i:/domain_preferences");
- loads all AVPs with ID from 'domain_preferences'
table for domain from RURI
avp_db_load("$uuid","s:404fwd/fwd_table");
- loads from table 'fwd_table' all AVPs with NAME '404fwd'
and UUID given by the value of AVP defined by alias 'uuid'
avp_db_load("$to","$email");
- loads all AVPs defined by alias 'email' for
username@domain from TO header
avp_db_load("keys","s:my_keys");
- loads all AVPs with NAME 'my_keys' using
as UUID the string 'keys'
modparam("avpops","db_scheme",
"scheme1:uuid_col=uid;value_col=job;value_type=string;table=emp")
avp_db_load("$uuid","s:jobs/$scheme1");
- load from table 'emp', using 'uid' column as uuid and
'job' column as string value into AVP name 'jobs'
avp_db_load("sip:[email protected]/uri","i:678");
- loads all AVPs with ID 678 for user '[email protected]'
...
Stores to DB the AVPs corresponding to the given source (from user, to user, ruri user, uuid). Will be stored all AVPs with name or, if empty, all AVPs. Normally, the function uses the default table, but there is also the possibility to specify a different table to be used.
The AVPs which were loaded from DB or which were already stored in a previous operation will not be stored into DB!!
Function returns true only if there was at least one AVP stored successfully.
The meaning and usage of the parameters are identical as for avp_db_load(source,name) function. Please refer to its description.
NOTE: function does not support DB schemes.
Example 13. avp_db_store usage
...
avp_db_store("$to","i:678");
- all AVPs with ID 678 will be stored with username@domain
from TO header
avp_db_store("$ruri/username","$email");
- all AVPs defined by alias 'email' will be stored with
username from RURI
avp_db_store("$uuid","s:/fwd_table");
- all AVPs with NAME will be stored into
table 'fwd_table' with the UUID given by the value
of AVP defined by alias 'uuid'
avp_db_store("keys","s:my_keys");
- stores all AVPs with NAME 'my_keys' using
as uuid the string 'keys'
...
Deletes from DB the AVPs corresponding to the given source (from user, to user, ruri user, uuid). Will be deleted all AVPs with name or, if empty, all AVPs. Normally, the function uses the default table, but there is also the possibility to specify a different table to be used.
This function has no effect on the AVPs from memory!!
Function returns true if the delete operation was successfully.
The meaning and usage of the parameters are identical as for avp_db_load(source,name) function. Please refer to its description.
NOTE: function does not support DB schemes.
Example 14. avp_db_delete usage
...
avp_db_delete("$to","i:678");
- deletes all AVPs with ID 678 using username@domain
from TO header
avp_db_delete("$ruri/username","$email");
- deletes all AVPs defined by alias 'email' using
username from RURI
avp_db_delete("$uuid","s:404fwd/fwd_table");
- deletes from table 'fwd_table' all AVPs with
NAME '404fwd' using the UUID given by the value
of AVP defined by alias 'uuid'
avp_db_delete("keys","s:my_keys");
- deletes all AVPs with NAME 'my_keys' using
as UUID the string 'keys'
...
The function writes some value (given) or some information from the SIP message into a new AVP. The information is specified by source and the AVP name by name (it cannot be empty or generic).
Function returns true if the value was written into AVP successfully.
Meaning of the parameters is as follows:
value - the value to be written into the AVP. It can be a fixed value given in script or some value extracted from the SIP message:
$ruri - write RURI
$from - write FROM uri
$ruri - write TO uri
$duri - write destination URI (dst_uri)
$src_ip - write source IP
$hdr[hdr_name] - write the body of first header with name hdr_name
value - write the value
If a SIP URI is used, other than '$duri', the following parameters are available:
username - use only the username part of the URI
domain - use only the domain part of the URI
if no parameter is given, both the username and domain part of the URI will be used
Parameter syntax:
value = (variable) | (fix_value)
variable = '$src_ip' | '$duri' | '$hdr[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. This can be an avp_name or an avp_alias. It cannot be empty. Parameter syntax is:
name = avp_name | avp_alias
Example 15. avp_write usage
...
avp_write("$to","i:678");
- writes the whole TO uri as AVP ID 678
avp_write("$ruri/username","$email");
- writes the RURI username into AVP defined
by alias 'email'
avp_write("foobar","s:test");
- writes the 'foobar' string into AVP
NAME 'test'
avp_write("i:333","i:6");
- writes the integer 333 into AVP ID 6
avp_write("$src_ip","ip");
- writes the source IP into AVP name 'ip'
avp_write("$hdr[My-header]","i:11");
- writes the body of the first header
named 'My-header' into AVP id '11'
...
Deletes from memory the AVP(s) with name or, if empty, all AVPs.
Function returns true if at least one AVP was deleted successfully.
Meaning of the parameters is as follows:
name - which AVPs will be deleted from memory. This can be an avp_name or an avp_alias. It can be empty - which means all AVPs, or you may specify only the type - 'i:' means all AVPs with ID. Parameter syntax is:
name = (''|'s:'|'i:'|avp_name|avp_alias)['/'flag]
flag = 'g' | 'G'
Without 'g' global flag, if a full AVP name is given, only the first matching AVP will be deleted. The global flag can force the deletion of all AVP matching the given name.
Pushes the value of the (all) AVP(s) with name into the SIP message as RURI or header (destination).
Function returns true if at least one AVP was pushed successfully into the SIP message.
Meaning of the parameters is as follows:
destination - as what will be the AVP value pushed into SIP message. It can be:
$ruri - push the AVP value as RURI; it accepts as parameter what part of RURI to be written:
username
domain
By default the whole RURI will be replaced.
$duri - push the AVP value as destination URI (dst_uri)
$hdr_name - push the AVP value as header with name 'hdr_name'; it accepts as parameter the header belonging:
request
reply
By default the header is consider belonging to request.
Parameter syntax:
destination = ruri_dst | '$duri' | hdr_dst
ruri_dst = '$ruri'['/'('username'|'domain')]
hdr_dst = '$hdr_name'['/'('request'|'reply')]
name - which AVP(s) should be pushed into the SIP message. This can be an avp_name or an avp_alias. It cannot be empty. It accepts the global flag (g)- if all the AVPs should be used or only the first one. Parameter syntax is:
name = ( avp_name | avp_alias )['/'flags]
flags = 'g'
Example 17. avp_pushto usage
...
avp_pushto("$ruri","i:678");
- first AVP with ID 678 will be pushed to RURI
avp_pushto("$ruri/domain","s:backup_domains/g");
- all AVPs with NAME 'backup_domains' will be
pushed into domain RURI (request will fork)
avp_pushto("$Email/reply","s:email");
- first AVP with NAME 'email' will be pushed
as header into reply
avp_pushto("$Foo","$bar/g");
- all AVPs defined by alias 'bar' will be
pushed as header into request
avp_pushto("$duri","i:670");
- first AVP with ID 670 will be pushed to dst_uri
...
Checks the value of the (all) AVP(s) with name against the operator and value (op_value).
If the two involved values have different types (string/integer), the check will be considered failed and skipped.
Function returns true if at least one AVP satisfies successfully the check.
Meaning of the parameters is as follows:
name - which AVP(s) should be checked. This can be an avp_name or an avp_alias. It cannot be empty. Parameter syntax is:
name = ( avp_name | avp_alias )
op_value - defines the check (operator) to be used, the value against which the check should be performed and some additional flags. Check operators can be:
eq - AVP value equal to value
ne - AVP value not equal to value
lt - AVP value less than value
le - AVP value less than or equal to value
gt - AVP value greater than value
ge - AVP value greater than or equal to value
re - AVP value match the regular expression given by the value.
fm - AVP value match (using filename like expression) the regular expression given as value or indirect via an AVP value.
and - bitwise AND test (only for AVPs with integer value)
or - bitwise OR test (only for AVPs with integer value)
xor - bitwise XOR test (only for AVPs with integer value)
The value can be:
$ruri - check against RURI
$from - check against FROM URI
$to - check against TO URI
$src_ip - check against source IP
$avp_alias - check against the value of another AVP defined by its alias (the values of all these AVPs will be checked)
value - check against a fixed, given value
Integer values can be given in hexadecimal using notation: 'i:0xhex_number' (e.g.,: 'i:0xabcd');
Possible flags are:
g/G - use all values of the checked AVP (first parameter)
i/I - if strings are checked, do it case insensitive
Parameter syntax is:
op_value = operator '/' value ['/'flags]
operator = 'eq' | 'ne' | 'lt' | 'le' | 'gt' | 'ge' | 're' | 'fm' | 'and' | 'or' | 'xor'
value = variable | fix_value
variable = '$src_ip'|'$from'|'$ruri'|'$from'|avp_alias
fix_value = 'i:'integer | 's:'string | string
flags = 'g' | 'G' | 'i' | 'I'
NOTE: for 're' operator, the value can be only a string fixed value which defines the regular expression.
NOTE: for 'fm' operator, the value can be only a string fixed value which defines the regular expression or an AVP ALIAS which containes the regular expression.
Example 18. avp_check usage
...
avp_check("i:678", "lt/i:345/g");
- check values of all AVP with ID 678 if
less than integer 345.
avp_check("s:person","eq/$from/I");
- check case insensitive if AVP NAME 'person'
equals to FROM URI
avp_check("s:foo","gt/$bar/g");
- checks if one of the values of the AVP
NAME "foo" is greater than the one of values
of AVP defined by alias 'bar'
avp_check("s:friends","re/sip:.*@bar.com/g");
- checks if one of the values of the AVP
NAME "friends" matches the regular
expression "sip:.*@bar.com"
avp_write("*@siphub.net","$fm_avp");
avp_write("$from","$value");
avp_check("$value","fm/$fm_avp/g");
- checks if one of the values of the AVP
NAME "value" matches the regular
expression "*@siphub.net" (checks if
the FROM URI belongs to "siphub.net"
domain)
NOTE: the regular expresion can be
also loaded from DB
avp_check("i:678", "lt/i:345/g");
- check values of all AVP with ID 678 if
less than integer 345
avp_check("i:678", "and/i:0x02");
- check if the value of AVP i:678 has the second
bit set
...
Copies / moves (all) AVP(s) with old_name under a different name (new_name), keeping the original value.
Both names can be AVP aliases and there is no restriction about their types (AVP ID or AVP NAME); any combination is allowed.
Function returns true if at least one AVP was successfully copied or moved.
Meaning of the parameters is as follows:
old_name - which AVP(s) should be copied/moved. This can be an avp_name or an avp_alias. It cannot be empty. Parameter syntax is:
name = ( avp_name | avp_alias )
new_name - the new name of the copied/moved AVP(s). This can be an avp_name or an avp_alias. It cannot be empty.
Parameter syntax is:
name = ( avp_name | avp_alias ) ['/'flags]
flags = 'g' | 'G' | 'd' | 'D' | 'n' | 'N' | 's' | 'S'
Meaning of the flags:
'g' | 'G' - copy/move all AVPs with 'old_name'
'd' | 'D' - delete old AVP after copy (results in move operation)
'n' | 'N' - convert the value to number (integer) (cast operation)
's' | 'S' - convert the value to string (cast operation)
The function executes integer operations with AVPs.
Meaning of the parameters is as follows:
name - 'source_avp/destination_avp' - which AVP(s) should be processed and where to store the result. If 'destination_avp' is missing, same name as 'source_avp' is used to store the result.
Parameter syntax is:
name = ( source_avp[/destination_avp] )
source_avp = ( avp_name | avp_alias )
destination_avp = ( avp_name | avp_alias )
op_value - define the operation, the value and flags.
Parameter syntax is:
op_value = operator '/' value ['/'flags]
operator = 'add' | 'sub' | 'mul' | 'div' | 'mod' | 'and' | 'or' | 'xor' | 'not'
Meaning of the operators:
add - arithmetic addition (in C: '+')
sub - arithmetic substitution (in C: '-')
mul - arithmetic multiplication (in C: '*')
div - arithmetic division (in C: '/')
mod - arithmetic modulo (in C: '%')
and - bitwise AND (in C: '&')
or - bitwise OR (in C: '|')
xor - bitwise XOR (in C: '^')
not - bitwise negation (in C: '~')
value = variable | fix_value
variable = avp_alias
fix_value = 'i:'integer
flags = 'g' | 'G' | 'd' | 'D'
Meaning of the flags:
'g' | 'G' - apply the operations to all 'source_avp'
'd' | 'D' - delete the 'source_avp' after operation.
Integer values can be given in hexadecimal using notation 'i:0xhex_number' (e.g.,: 'i:0xabcd');
Prints the formatted string 'format' in the AVP 'dest'. The 'format' parameter can include any pseudo-variable defined in OpenSER. The list with all pseudo-variables in OpenSER can be found at: http://openser.org/docs/pseudo-variables.html.
The function can be used for string concatenation between AVPs, pseudo-variables and constants. Functionalities like prefix or suffix are covered, as well.
Meaning of the parameters is as follows:
dest - in which AVP should be stored the result. Parameter syntax is:
name = ( avp_name | avp_alias )
format - the formatted string to be printed in 'dest' AVP. It can include any pseudo-variable as specifier to be replaced.
Perl/sed-like substitutions applied to AVPs having string value.
Meaning of the parameters is as follows:
avps - source AVP, destination AVP and flags. Parameter syntax is:
avps = src_avp [ '/' dst_avp [ '/' flags ] ]
src_avp = ( avp_name | avp_alias )
dst_avp = ( avp_name | avp_alias ) - if dst_avp is missing then the value of src_avp will be replaced
flags = ( d | D | g | G )
Meaning of the flags:
'g' | 'G' - apply the operations to all 'source_avp'
'd' | 'D' - delete the 'source_avp' after operation.
subst - perl/sed-like reqular expression.
Parameter syntax is:
subst = "/regexp/replacement/flags"
regexp - regular expression
replacement - replacement string, can include pseudo-variables and \1, ..., \9 for matching tokens, \0 for whole matching text
flags = 'g' | 'G' | 'i' | 'i'
Meaning of the flags:
'g' | 'G' - replace all matching tokens
'i' | 'I' - match ignore-case.
Example 22. avp_subst usage
...
# if avp i:678 has a string value in e-mail format, replace the
# domain part with the value of domain part from R-URI
avp_subst("i:678", "/(.*)@(.*)/\1@$rd/");
# if any avp i:678 has a string value in e-mail format, replace the
# domain part with the value of domain part from R-URI
# and place the result in avp i:679
avp_subst("i:678/i:679/g", "/(.*)@(.*)/\1@$rd/");
...
IMPORTANT NOTE: if the replacement string includes src_avp or dst_avp you will get something that you may not expect. In case you have many src_avp and you make the substitution to be applied to all of them, after the first src_avp is processed, it will be added in avp list and next processing will use it.
Check if any AVP identified by name is set. Flags can be used to test if the AVP has number or string value, as well.
Meaning of the parameters is as follows:
name - name of AVP to look for. Parameter syntax is:
name = ('s:'|'i:'|avp_name|avp_alias [ '/' flags ])
flags = ('s'|'S'|'n'|'N') .
Meaning of the flags:
'n' | 'N' - return true only when the AVP 'name' exists and has number (integer) value.
's' | 'S' - return true only when the AVP 'name' exists and has string value.
If no flag is specified, the function returns true if any AVP with name 'name' exists.