====== Lua API for Kamailio v4.1.x ======

===== Overview =====

<code c>
Initial author:
    Daniel-Constantin Mierla
</code>

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: [[http://kamailio.org/docs/modules/devel/modules/app_lua.html|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

<code c>
sr.dbg("message")
</code>

==== sr.err ====

Print message to L_ERR level using internal log API.

Prototype

<code c>
sr.err("message")
</code>

==== sr.log ====

Print message to 'level' using internal log API.

Prototype

<code c>
sr.log("level", "message")
</code>

Parameter level can be"

  * dbg
  * info
  * warn
  * err
  * crit

==== sr.modf ====

Run a function exported by a module

Prototype:

<code c>
sr.modf("function", "param1", "param2", ...);
</code>

Can be up to 6 optional parameters.

Example:

<code c>
sr.modf("sl_reply_error");
</code>

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

<code c>
sr.is_myself("uri")
</code>


==== sr.setflag ====

Set message flag.

Prototype

<code c>
sr.setflag(index)
</code>

==== sr.resetflag ====

Reset message flag.

Prototype

<code c>
sr.resetflag(index)
</code>

==== sr.isflagser ====

Test if message flag is set.

Prototype

<code c>
sr.isflagset(index)
</code>

==== sr.sebtflag ====

Set branch flag.

Prototype

<code c>
sr.setbflag(index)
</code>

==== sr.resetflag ====

Reset branch flag.

Prototype

<code c>
sr.resetflag(index)
</code>

==== sr.isbflagser ====

Test if branch flag is set.

Prototype

<code c>
sr.isbflagset(index)
</code>


==== sr.seturi ====

Set request URI.

Prototype

<code c>
sr.seturi("uri")
</code>

==== sr.setuser ====

Set request URI user part.

Prototype

<code c>
sr.setuser("user")
</code>

==== sr.sethost ====

Set request URI host part.

Prototype

<code c>
sr.sethost("host")
</code>

==== sr.setdsturi ====

Set destination URI (outbound proxy).

Prototype

<code c>
sr.setdsturi("uri")
</code>

==== sr.resetdsturi ====

Reset destination URI (outbound proxy).

Prototype

<code c>
sr.resetdsturi()
</code>

===== SR.HDR Package =====

Header management functions.

==== sr.hdr.append ====

Append header to end of headers list.

Prototype

<code c>
sr.hdr.append("text")
</code>


==== sr.hdr.insert ====

Insert header to first position.

Prototype

<code c>
sr.hdr.insert("text")
</code>

==== sr.hdr.remove ====

Remove header.

Prototype

<code c>
sr.hdr.remove("hdrname")
</code>

==== sr.hdr.append_to_reply ====

Append a header to SIP reply generated by proxy.

Prototype

<code c>
sr.hdr.append_to_reply("text")
</code>

===== SR.PV Package =====

Pseudo-variable management functions.

==== sr.pv.get ====

Get the value of a pseudo-variable.

Prototype

<code c>
sr.pv.get("pv")
</code>

==== sr.pv.seti ====

Set the integer value to pseudo-variable.

Prototype

<code c>
sr.pv.seti("pv", value)
</code>

==== sr.pv.sets ====

Set the string value to pseudo-variable.

Prototype

<code c>
sr.pv.sets("pv", "value")
</code>

==== sr.pv.unset ====

Unset pseudo-variables (assign $null).

Prototype

<code c>
sr.pv.unset("pv")
</code>


==== sr.pv.is_null ====

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

Prototype

<code c>
sr.pv.is_null("pv")
</code>

===== SR.XAVP =====

xavp management functions.

==== sr.xavp.get_keys ====

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

Prototype

<code c>
t = sr.xavp.get_keys("xavp_name", 0)
</code>

Example

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

<code c>
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
</code>

Result

<code c>
1:three
2:two
3:one
</code>

==== 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)

Prototype

<code c>
t = sr.xavp.get("xavp_name", 1, 0)
</code>

Example

<code c>
$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";
</code>

<code c>
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
</code>

Result

<code c>
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]
</code>
===== SR.SL Package =====

Functions of SL module.

==== sr.sl.send_reply ====

Send SIP reply.

Prototype

<code c>
sr.sl.send_reply(code, "reason")
</code>

Example:
<code c>
lua_dostring("sr.sl.send_reply(200, [[ok from lua]])");
</code>

==== sr.sl.get_reply_totag ====

Return To-dag for SIP reply.

Prototype

<code c>
sr.sl.get_reply_totag()
</code>

===== SR.TM Package =====


==== sr.tm.t_reply ====

Send stateful SIP reply.

Prototype

<code c>
sr.tm.t_reply(code, "reason")
</code>

==== sr.tm.t_relay ====

Forward statefully SIP request.

Prototype

<code c>
sr.tm.t_relay()
</code>

==== sr.tm.t_on_branch ====

Set on branch route.

Prototype

<code c>
sr.tm.t_on_branch("routeid")
</code>

==== sr.tm.t_on_reply ====

Set on reply route.

Prototype

<code c>
sr.tm.t_on_reply("routeid")
</code>

==== sr.tm.t_on_failure ====

Set on failure route.

Prototype

<code c>
sr.tm.t_on_failure("routeid")
</code>

==== sr.tm.t_check_trans ====

Check for existence of transaction.

Prototype

<code c>
sr.tm.t_check_trans()
</code>

==== sr.tm.t_is_canceled ====

Return >0 if the INVITE transaction is canceled.

Prototype

<code c>
sr.tm.t_is_canceled()
</code>

===== SR.SQLOPS Package =====

==== sr.sqlops.query ====

Execute SQL query.

Prototype

<code c>
sr.sqlops.query("connection", "query", "result")
</code>

==== sr.sqlops.value ====

Return a value from result of SQL query.

Prototype

<code c>
sr.sqlops.value("result", row, column)
</code>


==== sr.sqlops.is_null ====

Return true if a value from result is NULL.

Prototype

<code c>
sr.sqlops.is_null("result", row, column)
</code>

==== sr.sqlops.column ====

Return a column name from result of SQL query.

Prototype

<code c>
sr.sqlops.column("result", index)
</code>

==== sr.sqlops.nrows ====

Return number of rows from result of SQL query.

Prototype

<code c>
sr.sqlops.nrows("result")
</code>

==== sr.sqlops.ncols ====


Return number of columns from result of SQL query.

Prototype

<code c>
sr.sqlops.ncols("result")
</code>

==== sr.sqlops.reset ====


Free the result of SQL query.

Prototype

<code c>
sr.sqlops.reset("result")
</code>

==== sr.sqlops.xquery ====

Execute SQL query and store in XAVP.

Prototype

<code c>
sr.sqlops.xquery("connection", "query", "xavp")
</code>

===== SR.RR Package =====

==== sr.rr.record_route ====

Add Record-Route header.

Prototype

<code c>
sr.rr.record_route(["params"])
</code>

==== sr.rr.loose_route ====


Handle Route headers.

Prototype

<code c>
sr.rr.loose_route()
</code>


===== SR.AUTH Package =====

==== sr.auth.www_challenge ====

Send WWW digest authentication challenge reply (401).

Prototype

<code c>
sr.auth.www_challenge("realm", flags)
</code>

==== sr.auth.proxy_challenge ====

Send Proxy digest authentication challenge reply (401).

Prototype

<code c>
sr.auth.proxy_challenge("realm", flags)
</code>

==== sr.auth.pv_www_authenticate ====

Perform WWW digest authentication using password from parameter.

Prototype

<code c>
sr.auth.pv_www_authenticate("realm", "password", flags)
</code>


==== sr.auth.pv_proxy_authenticate ====


Perform Proxy digest authentication using password from parameter.

Prototype

<code c>
sr.auth.pv_proxy_authenticate("realm", "password", flags)
</code>

==== sr.auth.consume_credentials ====

Delete authentication credentials from SIP request.

Prototype

<code c>
sr.auth.consume_credentials()
</code>

===== SR.AUTH_DB Package =====

==== sr.auth_db.www_authenticate ====

Perform WWW digest authentication against database.

Prototype

<code c>
sr.auth_db.www_authenticate("realm", "table")
</code>

==== sr.auth_db.proxy_authenticate ====

Perform Proxy digest authentication against database.

Prototype

<code c>
sr.auth_db.proxy_authenticate("realm", "table")
</code>

===== SR.MAXFWD Package =====

==== sr.maxfwd.process_maxfwd ====


Handle Max Forward header.

Prototype

<code c>
sr.maxfwd.process_maxfwd(newlimit)
</code>

===== SR.REGISTRAR Package =====

==== sr.registrar.save ====

Save contacts to user location table.

Prototype

<code c>
sr.registrar.save("table" [, flags])
</code>


==== sr.registrar.lookup ====

Lookup contacts in user location table.

Prototype

<code c>
sr.registrar.lookup("table")
</code>


===== SR.DISPATCHER Package =====

==== sr.dispatcher.select ====

Select first destination address.

Prototype

<code c>
sr.dispatcher...
</code>

==== sr.dispatcher.next ====

Select next destination address.

Prototype

<code c>
sr.dispatcher...
</code>

==== sr.dispatcher.mark ====

Set status for destination address.

Prototype

<code c>
sr.dispatcher...
</code>

==== sr.dispatcher.is_from ====

Detects if the message comes from a dispatcher address.

Prototype

<code c>
sr.dispatcher...
</code>

===== SR.XHTTP Package =====

==== sr.xhttp.reply ====

Send an HTTP reply.

Prototype

<code c>
sr.xhttp.reply(code, reason, content-type, body)
</code>

===== 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 ====