====== Lua API ====== ===== 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**. References: * **app_lua** module: [[http://sip-router.org/docbook/sip-router/branch/master/modules/app_lua/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 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 * 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.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.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)