Lua API for Kamailio v4.1.x

Initial author:
    Daniel-Constantin Mierla

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.

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

Core functions.

Print message to L_DBG level using internal log API.

Prototype

sr.dbg("message")

Print message to L_ERR level using internal log API.

Prototype

sr.err("message")

Print message to 'level' using internal log API.

Prototype

sr.log("level", "message")

Parameter level can be“

• dbg
• info
• warn
• err
• crit

Run a function exported by a module

Prototype:

sr.modf("function", "param1", "param2", ...);

Can be up to 6 optional parameters.

Example:

sr.modf("sl_reply_error");

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.

Return true if the URI matches local IPs and aliases.

Prototype

sr.is_myself("uri")

Set message flag.

Prototype

sr.setflag(index)

Reset message flag.

Prototype

sr.resetflag(index)

Test if message flag is set.

Prototype

sr.isflagset(index)

Set branch flag.

Prototype

sr.setbflag(index)

Reset branch flag.

Prototype

sr.resetflag(index)

Test if branch flag is set.

Prototype

sr.isbflagset(index)

Set request URI.

Prototype

sr.seturi("uri")

Set request URI user part.

Prototype

sr.setuser("user")

Set request URI host part.

Prototype

sr.sethost("host")

Set destination URI (outbound proxy).

Prototype

sr.setdsturi("uri")

Reset destination URI (outbound proxy).

Prototype

sr.resetdsturi()

Header management functions.

Append header to end of headers list.

Prototype

sr.hdr.append("text")

Insert header to first position.

Prototype

sr.hdr.insert("text")

Remove header.

Prototype

sr.hdr.remove("hdrname")

Append a header to SIP reply generated by proxy.

Prototype

sr.hdr.append_to_reply("text")

Pseudo-variable management functions.

Get the value of a pseudo-variable.

Prototype

sr.pv.get("pv")

Set the integer value to pseudo-variable.

Prototype

sr.pv.seti("pv", value)

Set the string value to pseudo-variable.

Prototype

sr.pv.sets("pv", "value")

Unset pseudo-variables (assign $null).

Prototype

sr.pv.unset("pv")

Check if the pseudo-variable value is $null or not.

Prototype

sr.pv.is_null("pv")

xavp management functions.

returns an array table with the key names of the xavp variable.

Prototype

t = sr.xavp.get_keys("xavp_name", 0)

Example

$xavp(test=>one) = 1;
$xavp(test[0]=>two) = "two";
$xavp(test[0]=>three) = 3;

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

1:three
2:two
3:one

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)

Prototype

t = sr.xavp.get("xavp_name", 1, 0)

Example

$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)
for k,t2 in pairs(t) do
 for i,v in ipairs(t2) do
   sr.log("info", string.format("%s[%d]:%s[%s]\n", k, i, tostring(v), type(v)))
 end
end
 
t = sr.xavp.get("test", 0, 1)
for k,v in pairs(t) do
 sr.log("info", string.format("%s:%s[%s]\n", k, v, tostring(v), type(v)))
end

Result

a[1]:3[number]
a[2]:2[number]
a[3]:1[number]
b[1]:three[string]
b[2]:two[string]
b[3]:one[string]
 
a:3[number]
b:three[string]

Functions of SL module.

Send SIP reply.

Prototype

sr.sl.send_reply(code, "reason")

Example:

lua_dostring("sr.sl.send_reply(200, [[ok from lua]])");

Return To-dag for SIP reply.

Prototype

sr.sl.get_reply_totag()

Send stateful SIP reply.

Prototype

sr.tm.t_reply(code, "reason")

Forward statefully SIP request.

Prototype

sr.tm.t_relay()

Set on branch route.

Prototype

sr.tm.t_on_branch("routeid")

Set on reply route.

Prototype

sr.tm.t_on_reply("routeid")

Set on failure route.

Prototype

sr.tm.t_on_failure("routeid")

Check for existence of transaction.

Prototype

sr.tm.t_check_trans()

Return >0 if the INVITE transaction is canceled.

Prototype

sr.tm.t_is_canceled()

Execute SQL query.

Prototype

sr.sqlops.query("connection", "query", "result")

Return a value from result of SQL query.

Prototype

sr.sqlops.value("result", row, column)

Return true if a value from result is NULL.

Prototype

sr.sqlops.is_null("result", row, column)

Return a column name from result of SQL query.

Prototype

sr.sqlops.column("result", index)

Return number of rows from result of SQL query.

Prototype

sr.sqlops.nrows("result")

Return number of columns from result of SQL query.

Prototype

sr.sqlops.ncols("result")

Free the result of SQL query.

Prototype

sr.sqlops.reset("result")

Execute SQL query and store in XAVP.

Prototype

sr.sqlops.xquery("connection", "query", "xavp")

Add Record-Route header.

Prototype

sr.rr.record_route(["params"])

Handle Route headers.

Prototype

sr.rr.loose_route()

Send WWW digest authentication challenge reply (401).

Prototype

sr.auth.www_challenge("realm", flags)

Send Proxy digest authentication challenge reply (401).

Prototype

sr.auth.proxy_challenge("realm", flags)

Perform WWW digest authentication using password from parameter.

Prototype

sr.auth.pv_www_authenticate("realm", "password", flags)

Perform Proxy digest authentication using password from parameter.

Prototype

sr.auth.pv_proxy_authenticate("realm", "password", flags)

Delete authentication credentials from SIP request.

Prototype

sr.auth.consume_credentials()

Perform WWW digest authentication against database.

Prototype

sr.auth_db.www_authenticate("realm", "table")

Perform Proxy digest authentication against database.

Prototype

sr.auth_db.proxy_authenticate("realm", "table")

Handle Max Forward header.

Prototype

sr.maxfwd.process_maxfwd(newlimit)

Save contacts to user location table.

Prototype

sr.registrar.save("table" [, flags])

Lookup contacts in user location table.

Prototype

sr.registrar.lookup("table")

Select first destination address.

Prototype

sr.dispatcher...

Select next destination address.

Prototype

sr.dispatcher...

Set status for destination address.

Prototype

sr.dispatcher...

Detects if the message comes from a dispatcher address.

Prototype

sr.dispatcher...

Send an HTTP reply.

Prototype

sr.xhttp.reply(code, reason, content-type, body)