Lua API for Kamailio Devel Version

Overview

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.

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:

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.dbg("message")

sr.err

Print message to L_ERR level using internal log API.

Prototype

sr.err("message")

sr.log

Print message to 'level' using internal log API.

Prototype

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

Parameter level can be"

  • dbg
  • info
  • notice
  • warn
  • err
  • crit

sr.modf

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.

sr.is_myself

Return true if the URI matches local IPs and aliases.

Prototype

sr.is_myself("uri")

sr.setflag

Set message flag.

Prototype

sr.setflag(index)

sr.resetflag

Reset message flag.

Prototype

sr.resetflag(index)

sr.isflagser

Test if message flag is set.

Prototype

sr.isflagset(index)

sr.sebtflag

Set branch flag.

Prototype

sr.setbflag(index)

sr.resetflag

Reset branch flag.

Prototype

sr.resetflag(index)

sr.isbflagser

Test if branch flag is set.

Prototype

sr.isbflagset(index)

sr.seturi

Set request URI.

Prototype

sr.seturi("uri")

sr.setuser

Set request URI user part.

Prototype

sr.setuser("user")

sr.sethost

Set request URI host part.

Prototype

sr.sethost("host")

sr.setdsturi

Set destination URI (outbound proxy).

Prototype

sr.setdsturi("uri")

sr.resetdsturi

Reset destination URI (outbound proxy).

Prototype

sr.resetdsturi()

SR.HDR Package

Header management functions.

sr.hdr.append

Append header to end of headers list.

Prototype

sr.hdr.append("text")

sr.hdr.insert

Insert header to first position.

Prototype

sr.hdr.insert("text")

sr.hdr.remove

Remove header.

Prototype

sr.hdr.remove("hdrname")

sr.hdr.append_to_reply

Append a header to SIP reply generated by proxy.

Prototype

sr.hdr.append_to_reply("text")

SR.PV Package

Pseudo-variable management functions.

sr.pv.get

Get the value of a pseudo-variable.

Prototype

sr.pv.get("pv")

sr.pv.seti

Set the integer value to pseudo-variable.

Prototype

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

sr.pv.sets

Set the string value to pseudo-variable.

Prototype

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

sr.pv.unset

Unset pseudo-variables (assign $null).

Prototype

sr.pv.unset("pv")

sr.pv.is_null

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

Prototype

sr.pv.is_null("pv")

SR.XAVP

xavp management functions.

sr.xavp.get_keys

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

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

 sr.xavp.get(xavp_name, indx, flag)

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

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

Example:

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

sr.sl.get_reply_totag

Return To-dag for SIP reply.

Prototype

sr.sl.get_reply_totag()

SR.TM Package

sr.tm.t_reply

Send stateful SIP reply.

Prototype

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

sr.tm.t_relay

Forward statefully SIP request.

Prototype

sr.tm.t_relay()

sr.tm.t_on_branch

Set on branch route.

Prototype

sr.tm.t_on_branch("routeid")

sr.tm.t_on_reply

Set on reply route.

Prototype

sr.tm.t_on_reply("routeid")

sr.tm.t_on_failure

Set on failure route.

Prototype

sr.tm.t_on_failure("routeid")

sr.tm.t_check_trans

Check for existence of transaction.

Prototype

sr.tm.t_check_trans()

sr.tm.t_is_canceled

Return >0 if the INVITE transaction is canceled.

Prototype

sr.tm.t_is_canceled()

SR.SQLOPS Package

sr.sqlops.query

Execute SQL query.

Prototype

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

sr.sqlops.value

Return a value from result of SQL query.

Prototype

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

sr.sqlops.is_null

Return true if a value from result is NULL.

Prototype

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

sr.sqlops.column

Return a column name from result of SQL query.

Prototype

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

sr.sqlops.nrows

Return number of rows from result of SQL query.

Prototype

sr.sqlops.nrows("result")

sr.sqlops.ncols

Return number of columns from result of SQL query.

Prototype

sr.sqlops.ncols("result")

sr.sqlops.reset

Free the result of SQL query.

Prototype

sr.sqlops.reset("result")

sr.sqlops.xquery

Execute SQL query and store in XAVP.

Prototype

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

SR.RR Package

sr.rr.record_route

Add Record-Route header.

Prototype

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

sr.rr.loose_route

Handle Route headers.

Prototype

sr.rr.loose_route()

SR.AUTH Package

sr.auth.www_challenge

Send WWW digest authentication challenge reply (401).

Prototype

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

sr.auth.proxy_challenge

Send Proxy digest authentication challenge reply (401).

Prototype

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

sr.auth.pv_www_authenticate

Perform WWW digest authentication using password from parameter.

Prototype

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

sr.auth.pv_proxy_authenticate

Perform Proxy digest authentication using password from parameter.

Prototype

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

sr.auth.consume_credentials

Delete authentication credentials from SIP request.

Prototype

sr.auth.consume_credentials()

SR.AUTH_DB Package

sr.auth_db.www_authenticate

Perform WWW digest authentication against database.

Prototype

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

sr.auth_db.proxy_authenticate

Perform Proxy digest authentication against database.

Prototype

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

SR.MAXFWD Package

sr.maxfwd.process_maxfwd

Handle Max Forward header.

Prototype

sr.maxfwd.process_maxfwd(newlimit)

SR.REGISTRAR Package

sr.registrar.save

Save contacts to user location table.

Prototype

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

sr.registrar.lookup

Lookup contacts in user location table.

Prototype

sr.registrar.lookup("table")

SR.DISPATCHER Package

sr.dispatcher.select

Select first destination address.

Prototype

sr.dispatcher...

sr.dispatcher.next

Select next destination address.

Prototype

sr.dispatcher...

sr.dispatcher.mark

Set status for destination address.

Prototype

sr.dispatcher...

sr.dispatcher.is_from

Detects if the message comes from a dispatcher address.

Prototype

sr.dispatcher...

SR.XHTTP Package

sr.xhttp.reply

Send an HTTP reply.

Prototype

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

SR.MSILO Package

sr.msilo.store

sr.msilo.dump

SR.SDPOPS Package

sr.sdpops.sdp_with_media

SR.PRESENCE Package

sr.presence.pres_auth_status

sr.presence.handle_publish

sr.presence.handle_subscribe

SR.PRESENCE_XML Package

sr.presence_xml.pres_check_basic

sr.presence_xml.pres_check_activities

SR.TEXTOPS Package

sr.textops.is_privacy

SR.PUA_USRLOC Package

sr.pua_usrloc.set_publish

SR.SIPUTILS Package

sr.siputils.has_totag

sr.siputils.is_uri_user_e164

SR.RLS Package

sr.rls.handle_subscribe

sr.rls.handle_notify

SR.ALIAS_DB Package

sr.alias_db.lookup

SR.UAC Package

sr.uac.replace_from

SR.TMX Package

sr.tmx.t_suspend

SR.MQUEUE Package

sr.mq.add