Lua API for Kamailio Devel Version
Overview
Module app_lua allows execution of Lua scripts from SIP router configuration file, providing access to SIP message which is processed at that time. Exported functions by app_lua are available in the Lua script as package sr.
This page is a documentation for the 5.0 branch of Kamailio as well, as there won't be any new features added to this way of executing lua code in Kamailio. If in doubt (and all needed modules are available), use the KEMI way for your lua application.
References:
- app_lua module: README
- Lua: http://www.lua.org
Remarks:
- check the modules' documentation that export functions to Lua (they match subpackage name) to understand better the functionality provided by specific functions
- the parameters must be strings if the prototype have them in between double quotes, or integers if there are no double quotes
- any parameter specified in prototype enclosed in between square brackets is optional
SR Package
Core functions.
sr.dbg
Print message to L_DBG level using internal log API.
Prototype
sr.err
Print message to L_ERR level using internal log API.
Prototype
sr.log
Print message to 'level' using internal log API.
Prototype
Parameter level can be"
- dbg
- info
- notice
- warn
- err
- crit
sr.modf
Run a function exported by a module
Prototype:
Can be up to 6 optional parameters.
Example:
Note that module functions that have parameter fixups cannot be executed unless they have free fixup. This is to prevent memory leaks caused by fixup functions. If you have doubts about a module function, whether it is safe to execute or not from Lua, ask on devel mailing list: sr-dev [at] lists.sip-router.org.
sr.is_myself
Return true if the URI matches local IPs and aliases.
Prototype
sr.setflag
Set message flag.
Prototype
sr.resetflag
Reset message flag.
Prototype
sr.isflagser
Test if message flag is set.
Prototype
sr.sebtflag
Set branch flag.
Prototype
sr.resetflag
Reset branch flag.
Prototype
sr.isbflagser
Test if branch flag is set.
Prototype
sr.seturi
Set request URI.
Prototype
sr.setuser
Set request URI user part.
Prototype
sr.sethost
Set request URI host part.
Prototype
sr.setdsturi
Set destination URI (outbound proxy).
Prototype
sr.resetdsturi
Reset destination URI (outbound proxy).
Prototype
SR.HDR Package
Header management functions.
sr.hdr.append
Append header to end of headers list.
Prototype
sr.hdr.insert
Insert header to first position.
Prototype
sr.hdr.remove
Remove header.
Prototype
sr.hdr.append_to_reply
Append a header to SIP reply generated by proxy.
Prototype
SR.PV Package
Pseudo-variable management functions.
sr.pv.get
Get the value of a pseudo-variable.
Prototype
sr.pv.seti
Set the integer value to pseudo-variable.
Prototype
sr.pv.sets
Set the string value to pseudo-variable.
Prototype
sr.pv.unset
Unset pseudo-variables (assign $null).
Prototype
sr.pv.is_null
Check if the pseudo-variable value is $null or not.
Prototype
SR.XAVP
xavp management functions.
sr.xavp.get_keys
returns an array table with the key names of the xavp variable.
Prototype
Example
t = sr.xavp.get_keys("test", 0)
for k,v in pairs(t) do
sr.log("info", string.format("%d:%s\n", k, v))
end
Result
sr.xavp.get
returns a dictionary table with the values of the xavp variable. Third param is optional and it choose between get all the values of a key ( 0, default) or just the first ones (1)
If second param is nil will return all indexes. If second param is \<0 will return the index counting from the end ( -1 is the last value )
Prototype
Example
$xavp(test=>a) = 4;
$xavp(test[0]=>b) = "four";
$xavp(test[0]=>a) = 5;
$xavp(test[0]=>b) = "five";
$xavp(test[0]=>a) = 6;
$xavp(test[0]=>b) = "six";
$xavp(test=>a) = 1;
$xavp(test[0]=>a) = 2;
$xavp(test[0]=>a) = 3;
$xavp(test[0]=>b) = "one";
$xavp(test[0]=>b) = "two";
$xavp(test[0]=>b) = "three";
t = sr.xavp.get("test", 0, 0)
sr.log("dbg", string.format("sr.xavp.get('test', 0, 0)->%s\n", table.tostring(t)))
t = sr.xavp.get("test", 0, 1)
sr.log("dbg", string.format("sr.xavp.get('test', 0, 1)->%s\n", table.tostring(t)))
t = sr.xavp.get("test", nil, 0)
sr.log("dbg", string.format("sr.xavp.get('test', nil, 0)->%s\n", table.tostring(t)))
t = sr.xavp.get("test", nil, 1)
sr.log("dbg", string.format("sr.xavp.get('test', nil, 1)->%s\n", table.tostring(t)))
t = sr.xavp.get("test", -1, 1)
sr.log("dbg", string.format("sr.xavp.get('test', -1, 1)->%s\n", table.tostring(t)))
Result
sr.xavp.get('test', 0, 0)->{a={3,2,1},b={"three","two","one"}}
sr.xavp.get('test', 0, 1)->{a=3,b="three"}
sr.xavp.get('test', nil, 0)->{{a={3,2,1},b={"three","two","one"}},{a={6,5,4},b={"six","five","four"}}}
sr.xavp.get('test', nil, 1)->{{a=3,b="three"},{a=6,b="six"}}
sr.xavp.get('test', -1, 1)->{a=6,b="six"}
SR.SL Package
Functions of SL module.
sr.sl.send_reply
Send SIP reply.
Prototype
Example:
sr.sl.get_reply_totag
Return To-dag for SIP reply.
Prototype
SR.TM Package
sr.tm.t_reply
Send stateful SIP reply.
Prototype
sr.tm.t_relay
Forward statefully SIP request.
Prototype
sr.tm.t_on_branch
Set on branch route.
Prototype
sr.tm.t_on_reply
Set on reply route.
Prototype
sr.tm.t_on_failure
Set on failure route.
Prototype
sr.tm.t_check_trans
Check for existence of transaction.
Prototype
sr.tm.t_is_canceled
Return >0 if the INVITE transaction is canceled.
Prototype
SR.SQLOPS Package
sr.sqlops.query
Execute SQL query.
Prototype
sr.sqlops.value
Return a value from result of SQL query.
Prototype
sr.sqlops.is_null
Return true if a value from result is NULL.
Prototype
sr.sqlops.column
Return a column name from result of SQL query.
Prototype
sr.sqlops.nrows
Return number of rows from result of SQL query.
Prototype
sr.sqlops.ncols
Return number of columns from result of SQL query.
Prototype
sr.sqlops.reset
Free the result of SQL query.
Prototype
sr.sqlops.xquery
Execute SQL query and store in XAVP.
Prototype
SR.RR Package
sr.rr.record_route
Add Record-Route header.
Prototype
sr.rr.loose_route
Handle Route headers.
Prototype
SR.AUTH Package
sr.auth.www_challenge
Send WWW digest authentication challenge reply (401).
Prototype
sr.auth.proxy_challenge
Send Proxy digest authentication challenge reply (401).
Prototype
sr.auth.pv_www_authenticate
Perform WWW digest authentication using password from parameter.
Prototype
sr.auth.pv_proxy_authenticate
Perform Proxy digest authentication using password from parameter.
Prototype
sr.auth.consume_credentials
Delete authentication credentials from SIP request.
Prototype
SR.AUTH_DB Package
sr.auth_db.www_authenticate
Perform WWW digest authentication against database.
Prototype
sr.auth_db.proxy_authenticate
Perform Proxy digest authentication against database.
Prototype
SR.MAXFWD Package
sr.maxfwd.process_maxfwd
Handle Max Forward header.
Prototype
SR.REGISTRAR Package
sr.registrar.save
Save contacts to user location table.
Prototype
sr.registrar.lookup
Lookup contacts in user location table.
Prototype
SR.DISPATCHER Package
sr.dispatcher.select
Select first destination address.
Prototype
sr.dispatcher.next
Select next destination address.
Prototype
sr.dispatcher.mark
Set status for destination address.
Prototype
sr.dispatcher.is_from
Detects if the message comes from a dispatcher address.
Prototype
SR.XHTTP Package
sr.xhttp.reply
Send an HTTP reply.
Prototype