added tutorial for kamailio kemi framework

kamailio-kemi-framework/docs/acc.md

@@ -0,0 +1,15 @@
+## Acc Module KEMI Functions ##
+
+The functions exported by `acc` module to KEMI are listed in the next sections.
+
+### KSR.acc.acc_log_request(...) ###
+
+`int KSR.acc.acc_log_request("comment")`
+
+### KSR.acc.acc_db_request(...) ###
+
+`int KSR.acc.acc_db_request("comment", "dbtable")`
+
+### KSR.acc.acc_request(...) ###
+
+`int KSR.acc.acc_request("comment", "dbtable")`

kamailio-kemi-framework/docs/contributions.md

@@ -0,0 +1,10 @@
+## Contributions ##
+
+Anyone is welcome to contribute to this document. It is recommended to make a
+pull request via:
+
+  * [github.com/kamailio/kamailio-docs/pulls](https://github.com/kamailio/kamailio-docs/pulls)
+
+Errors and other issues can be reported via the tracker at:
+
+  * [github.com/kamailio/kamailio-docs/issues](https://github.com/kamailio/kamailio-docs/issues)

kamailio-kemi-framework/docs/core.md

@@ -0,0 +1,171 @@
+## Core KEMI Functions ##
+
+The core of Kamailio exports via KEMI:
+
+  * several functions directly to `KSR` module (like `KSR.function(params)`), which are mostly
+  the main function from the core and for writing log messages
+  * the `KSR.hdr` submodule, which are the most used functions for managing SIP message headers
+
+Example of using KEMI functions exported to Lua interpreter:
+
+```Lua
+KSR.dbg("a debug message from Lua script\n");
+KSR.hdr.remove("Route");
+```
+Exported functions from core directly to KSR module or KSR.hdr submodule are listed in the next sections.
+
+### void KSR.dbg(...) ###
+
+`void KSR.dbg("msg")`
+
+### void KSR.err(...) ###
+
+`void KSR.err("msg")`
+
+### void KSR.info(...) ###
+
+`void KSR.info("msg")`
+
+### oid KSR.log(...) ###
+
+`void KSR.log("level", "msg")`
+
+### KSR.drop(...) ###
+
+`void KSR.drop()`
+
+### KSR.is_myself(...) ###
+
+`bool KSR.is_myself("uri")`
+
+### KSR.setflag(...) ###
+
+`bool KSR.setflag(flag)`
+
+### KSR.resetflag(...) ###
+
+`bool KSR.resetflag(flag)`
+
+### KSR.isflagset(...) ###
+
+`bool KSR.isflagset(flag)`
+
+### KSR.setbflag(...) ###
+
+`bool KSR.setbflag(flag)`
+
+### KSR.resetbflag(...) ###
+
+`bool KSR.resetbflag(flag)`
+
+### KSR.isbflagset(...) ###
+
+`bool KSR.isbflagset(flag)`
+
+### KSR.setbiflag(...) ###
+
+`bool KSR.setbiflag(flag, branch)`
+
+### KSR.resetbiflag(...) ###
+
+`bool KSR.resetbiflag(flag, branch)`
+
+### KSR.isbiflagset(...) ###
+
+`bool KSR.isbiflagset(flag, branch)`
+
+### KSR.setsflag(...) ###
+
+`bool KSR.setsflag(flag)`
+
+### KSR.resetsflag(...) ###
+
+`bool KSR.resetsflag(flag)`
+
+### KSR.issflagset(...) ###
+
+`bool KSR.issflagset(flag)`
+
+### KSR.seturi(...) ###
+
+`bool KSR.seturi("uri")`
+
+### KSR.setuser(...) ###
+
+`bool KSR.setuser("user")`
+
+### KSR.sethost(...) ###
+
+`bool KSR.sethost("host")`
+
+### KSR.setdsturi(...) ###
+
+`bool KSR.setdsturi("uri")`
+
+### KSR.resetdsturi(...) ###
+
+`bool KSR.resetdsturi()`
+
+### KSR.isdsturiset(...) ###
+
+`bool KSR.isdsturiset()`
+
+### KSR.is_method(...) ###
+
+`bool KSR.is_method("methods")`
+
+### KSR.force_rport(...) ###
+
+`bool KSR.force_rport()`
+
+### KSR.set_forward_close(...) ###
+
+`bool KSR.set_forward_close()`
+
+### KSR.set_forward_no_connect(...) ###
+
+`bool KSR.set_forward_no_connect()`
+
+### KSR.set_reply_close(...) ###
+
+`bool KSR.set_reply_close()`
+
+### KSR.set_reply_no_connect(...) ###
+
+`bool KSR.set_reply_no_connect()`
+
+### KSR.forward(...) ###
+
+`int KSR.forward()`
+
+### KSR.forward_uri(...) ###
+
+`int KSR.forward_uri("uri")`
+
+### KSR.hdr.append(...) ###
+
+`int KSR.hdr.append("hdrval")`
+
+### KSR.hdr.append_after(...) ###
+
+`int KSR.hdr.append_after("hdrval", "hdrname")`
+
+### KSR.hdr.insert(...) ###
+
+`int KSR.hdr.insert("hdrval")`
+
+### KSR.hdr.insert_before(...) ###
+
+`int KSR.hdr.insert_before("hdrval", "hdrname")`
+
+### KSR.hdr.remove(...) ###
+
+`int KSR.hdr.remove("hdrval")`
+
+### KSR.hdr.is_present(...) ###
+
+`int KSR.hdr.is_present("hdrval")`
+
+### KSR.hdr.append_to_reply(...) ###
+
+`int KSR.hdr.append_to_reply("hdrval")`

kamailio-kemi-framework/docs/extra.css

@@ -0,0 +1,19 @@
+.wy-nav-side {
+	background: #2980B9;
+}
+
+/*
+.wy-side-nav-search {
+	background: #2980B9;
+}
+.rst-versions .rst-current-version {
+	background: #2980B9;
+}
+*/
+
+.wy-side-nav-search {
+	background: #222c32;
+}
+.rst-versions {
+	border-top:solid 10px #222c32;
+}

kamailio-kemi-framework/docs/index.md

@@ -0,0 +1,36 @@
+# Kamailio Kemi Framework #
+
+```
+Author: Daniel-Constantin Mierla ([email protected])
+```
+
+## Introduction ##
+
+Kamailio uses a scripting laguage for its configuration file (kamailio.cfg). This scripting language (referred also as
+native scripting language) was developed from scratch, with initial design going back to years 2001-2002.
+
+The configuration file is composed from several main statements:
+
+  * global parameters
+  * loading modules
+  * module parameters
+  * routing blocks
+
+In terms of execution, kamailio.cfg interprets only once, at startup, the statements related to:
+
+  * global parameters
+  * loading modules
+  * module parameters
+
+The routing blocks are similar to functions and can be executed many times, some of them for each received
+SIP message, some of them on various events fired by core or modules.
+
+While the native scripting language offers a large set of functions and is able to do many logical, arithmetic
+and string operations, its limits are met in many cases, especially when in need to integrate with external systems.
+
+Another missing feature in the native scripting language is reloading without a restart.
+
+Kamailio Embedded Interface (KEMI) framework was added first in Kamailio v5.0.0 to allow using other scripting
+languages to write SIP routing logic instead of using the native routing blocks. The interpreters for these scripting
+languages are embedded by Kamailio, initialized at startup, in this way being also as fast as poosible during runtime
+execution.

kamailio-kemi-framework/docs/kemi.md

@@ -0,0 +1,181 @@
+## KEMI Interpreters ##
+
+Following KEMI scripting languages can be used to write SIP routing logic for Kamailio:
+
+  * JavaScript
+  * Lua
+  * Python
+  * Squirrel
+
+A configuration file for Kamailio that uses a KEMI scripting language has the glabal parameters, loading modules and
+module parameters in the native scripting and sets the value of `cfgengine` to the KEMI scripting language identifier.
+
+The KEMI scripting language identifiers are:
+
+  * `jsdt` - for JavaScript
+  * `lua` - for Lua
+  * `python` - for Python
+  * `sqlang` - for Squirrel
+
+### JavaScript KEMI Interpreter ###
+
+It is implemented by `app_jsdt` module. The JavaScript interpreter is imported inside the module from
+[DukTape](www.ducktape.org) project, therefore it doesn't require to install any external libraries.
+
+To use it, set inside `kamailio.cfg`:
+
+```
+loadmodule "app_jsdk.so"
+modparam("app_jsdk", "load", "/path/to/script.js")
+cfgengine "jsdt"
+```
+
+A complete example of using JavaScript as KEMI languages is offered by the next two files:
+
+  * [kamailio-basic-kemi.cfg](https://github.com/kamailio/kamailio/blob/master/misc/examples/kemi/kamailio-basic-kemi.cfg)
+  * [kamailio-basic-kemi-jsdt.js](https://github.com/kamailio/kamailio/blob/master/misc/examples/kemi/kamailio-basic-kemi-jsdt.js)
+
+The file `kamailio-basic-kemi.cfg` has to be saved as `kamailio.cfg` and inside it add after the first line:
+
+```
+#!define WITH_CFGJSDT
+```
+
+The file `kamailio-basic-kemi-jsdt.js` has to be saved to local disk and the `load` parameter for `app_jsdt` module
+inside `kamailio.cfg` has to be updated to point to it. Then run `kamailio` with this `kamailio.cfg`.
+
+The documentation for `app_jsdk` is available at:
+
+  * [app_jsdt.html](https://kamailio.org/docs/modules/devel/modules/app_jsdt.html)
+
+### Lua KEMI Interpreter ###
+
+It is implemented by `app_lua` module. The Lua interpreter is linked from `liblua` library, supported Lua versions: 
+5.1 and 5.2.
+
+```
+loadmodule "app_lua.so"
+modparam("app_lua", "load", "/path/to/script.lua")
+cfgengine "lua"
+```
+
+A complete example of using Lua as KEMI languages is offered by the next two files:
+
+  * [kamailio-basic-kemi.cfg](https://github.com/kamailio/kamailio/blob/master/misc/examples/kemi/kamailio-basic-kemi.cfg)
+  * [kamailio-basic-kemi-lua.lua](https://github.com/kamailio/kamailio/blob/master/misc/examples/kemi/kamailio-basic-kemi-lua.lua)
+
+The file `kamailio-basic-kemi.cfg` has to be saved as `kamailio.cfg` and inside it add after the first line:
+
+```
+#!define WITH_CFGLUA
+```
+
+The file `kamailio-basic-kemi-lua.lua` has to be saved to local disk and the `load` parameter for `app_lua` module
+inside `kamailio.cfg` has to be updated to point to it. Then run `kamailio` with this `kamailio.cfg`.
+
+The documentation for `app_lua` is available at:
+
+  * [app_lua.html](https://kamailio.org/docs/modules/devel/modules/app_lua.html)
+
+### Python KEMI Interpreter ###
+
+It is implemented by `app_python` module. The Python interpreter is linked from `libpython`, supported Python versions:
+2.5, 2.6 and 3.x.
+
+```
+loadmodule "app_python.so"
+modparam("app_python", "script_name", "/path/to/script.py")
+cfgengine "python"
+```
+
+A complete example of using Python as KEMI languages is offered by the next two files:
+
+  * [kamailio-basic-kemi.cfg](https://github.com/kamailio/kamailio/blob/master/misc/examples/kemi/kamailio-basic-kemi.cfg)
+  * [kamailio-basic-kemi-python.py](https://github.com/kamailio/kamailio/blob/master/misc/examples/kemi/kamailio-basic-kemi-python.py)
+
+The file `kamailio-basic-kemi.cfg` has to be saved as `kamailio.cfg` and inside it add after the first line:
+
+```
+#!define WITH_CFGPYTHON
+```
+
+The file `kamailio-basic-kemi-python.py` has to be saved to local disk and the `script_name` parameter for
+`app_python` module inside `kamailio.cfg` has to be updated to point to it. Then run `kamailio` with this `kamailio.cfg`.
+
+The documentation for `app_python` is available at:
+
+  * [app_python.html](https://kamailio.org/docs/modules/devel/modules/app_python.html)
+
+### Squirrel KEMI Interpreter ###
+
+It is implemented by `app_sqlang` module. The Squirrel language interpreter is imported inside the module from
+[Squirrel](www.squirrel-lang.org) project, therefore it doesn't require to install any external libraries.
+
+```
+loadmodule "app_sqlang.so"
+modparam("app_sqlang", "load", "/path/to/script.sq")
+cfgengine "sqlang"
+```
+
+A complete example of using Squirrel as KEMI languages is offered by the next two files:
+
+  * [kamailio-basic-kemi.cfg](https://github.com/kamailio/kamailio/blob/master/misc/examples/kemi/kamailio-basic-kemi.cfg)
+  * [kamailio-basic-kemi-squirrel.sq](https://github.com/kamailio/kamailio/blob/master/misc/examples/kemi/kamailio-basic-kemi-squirrel.sq)
+
+The file `kamailio-basic-kemi.cfg` has to be saved as `kamailio.cfg` and inside it add after the first line:
+
+```
+#!define WITH_CFGSQLANG
+```
+
+The file `kamailio-basic-kemi-squirrel.sq` has to be saved to local disk and the `load` parameter for `app_sqlang`
+module inside `kamailio.cfg` has to be updated to point to it. Then run `kamailio` with this `kamailio.cfg`.
+
+The documentation for `app_sqlang` is available at:
+
+  * [app_sqlang.html](https://kamailio.org/docs/modules/devel/modules/app_sqlang.html)
+
+## KEMI Functions ##
+
+Inside the routing script, the functions exported by Kamailio through KEMI are available via `KSR` module. With very
+few exceptions, the KEMI functions return either an integer or a bool value and can take up to six parameters of type
+string or integer.
+
+The integer return code from a Kemi functions has to be evaluated with the following rules:
+
+  * `the value is greater than 0`, then the function was successfully executed and a logical evaluation should be
+  considered true
+  * `the value is less than 0`, then the function was not successfully executed or the function was successfully
+  executed and the a logical evaluation should be considered false
+  * `the value is equal to 0`, then the execution of the KEMI script should be terminated (be careful with execution of
+  `exit()` function from the embedded interpreter language, it may kill the interpreter completely, which in this case
+  is Kamailio, resulting in shutting down Kamailio - hint: check `KSR.x.exit()`)
+
+The bool return code is expected to be evaluated as `true` or `false` inside the KEMI script.
+
+If a function has `void` as return type in the signature, the it doesn't return any value.
+
+Few functions may return a string value.
+
+The convention for the parameters in the signature of the functions is to enclose in double quotes if the parameter
+has a string type and no quotes if the parameter has integer type.
+
+Most of the functions exported through KEMI have an equivalent in the functions available in the native scripting
+language. Generic mapping rules:
+
+  * if a parameter value is expected to be used as integer, then KEMI function has it as integer parameter (note: in
+  the native scripting language, it used to be a rule that all parameters of the functions exported by modules to be
+  provided as string)
+  * if a function from native scripting language has variants with different number of parameters, then KEMI exports
+  one function for each of the variants (to cope with the scripting languages that do not support variadic number of
+  parameters). The names of the related functions are similar.
+
+The available KEMI functions in a running instance of Kamailio can be listed via an RPC command. A matter of the
+interpreter used, one of the following commands needs to be run:
+
+```
+kamctl rpc app_jsdt.api_list
+kamctl rpc app_lua.api_list
+kamctl rpc app_python.api_list
+kamctl rpc app_sqlang.api_list
+```

kamailio-kemi-framework/docs/kemimods.md

@@ -0,0 +1,64 @@
+## PV And Special KEMI Functions ##
+
+Each KEMI interpreter module (respectively `app_jsdt`, `app_lua`, `app_python` and `app_sqlang`) exports the
+submodules `KSR.pv` and `KSR.x`.
+
+`KSR.pv` submodule provides the functions to get, set and test the values of pseduo-variables. It is implemented per
+module because the get function has to return either integer or string value.
+
+The `pvname` that appears in the next sections in the function prototypes has to be a valid pseudo-variable name for
+ Kamailio native configuration file (for example `$ru`, `$var(x)`, `$shv(z)`, ...).
+
+`KSR.x` submodule provides special functions that need custom code per interpreter.
+
+The functions exported by these modules are listed in the next sections.
+
+### KSR.pv.get(...) ###
+
+`val KSR.pv.get("pvname")`
+
+Return the value of pseudo-variable `pvname`. The returned value can be string or integer.
+
+### KSR.pv.seti(...) ###
+
+`void KSR.pv.seti("pvname", intval)`
+
+Set the value of pseudo-variable `pvname` to integer value provided by parameter `intval`.
+
+### KSR.pv.sets(...) ###
+
+`void KSR.pv.sets("pvname", "strval")`
+
+Set the value of pseudo-variable `pvname` to string value provided by parameter `strval`.
+
+### KSR.pv.unset(...) ###
+
+`void KSR.pv.unset("pvname")`
+
+Set the value of pseudo-variable `pvname` to `$null`.
+
+### KSR.pv.is_null(...) ###
+
+`bool KSR.pv.is_null("pvname")`
+
+Return true if pseudo-variable `pvname` is `$null`.
+
+### KSR.x.modf(...) ###
+
+`int KSR.x.modf("fname", params...)`
+
+Execute a function (specified by `fname`) exported by a Kamailio module. Additional parameters must be string and
+they are passed to the Kamailio module function.
+
+### KSR.x.exit(...) ###
+
+`void KSR.x.exit()`
+
+Equivalent of `exit` from native kamailio.cfg scripting language, stop the execution of the SIP routing script.
+
+### KSR.x.drop(...) ###
+
+`void KSR.x.drop()`
+
+Equivalent of `drop` from native kamailio.cfg scripting language, stop the execution of the SIP routing script
+and drop routing further the SIP request branch or response.

kamailio-kemi-framework/docs/support.md

@@ -0,0 +1,12 @@
+## Support ##
+
+Questions about how to use Kamailio and the content of kamailio.cfg can be
+addressed via email to:
+
+  * [[email protected]](http://lists.kamailio.org/cgi-bin/mailman/listinfo/sr-users)
+
+More documentation resources can be found at:
+
+  * [www.kamailio.org/w/documentation](https://www.kamailio.org/w/documentation/)
+  * [www.kamailio.org/wiki](https://www.kamailio.org/wiki/)
+

kamailio-kemi-framework/mkdocs.yml

@@ -0,0 +1,11 @@
+site_name: Kamailio KEMI Framework
+theme: readthedocs
+extra_css: [extra.css]
+pages:
+    - 'Kamailio KEMI Framework': 'index.md'
+    - 'KEMI Interpreters': 'kemi.md'
+    - 'Core Functions': 'core.md'
+    - 'PV And Special Functions': 'kemimods.md'
+    - 'Acc Module Functions': 'acc.md'
+    - 'Support': 'support.md'
+    - 'Contributions': 'contributions.md'