kamailio-kemi-framework: document the return type xval

- relocated docs for KSR.pv to core listing

kamailio-kemi-framework/docs/core.md

@@ -5,6 +5,10 @@ The exports to KEMI framework from the core of Kamailio:
   * several functions directly to `KSR` module (like `KSR.function(params)`), which are mostly
   the main functions from the core and for writing log messages (some being part of xlog module for
   native kamailio.cfg language)
+  * the `KSR.pv` submodule, which are the generic functions to manage pseudo-variables, like set and get
+  operations (some types of variables can have dedicated functions exported by various module, like
+  `htable` to work with items in the shared memory hash table, or r-uri and xavp operations from `pv`
+  and `kemix` modules).
   * the `KSR.hdr` submodule, which are the most used functions for managing SIP message headers
   (some of the functions in this submodules correspond to the ones in `textops` or `textopsx`
   modules for `kamailio.cfg`).
@@ -568,6 +572,132 @@ URI parameter.
 KSR.forward_uri("sip:127.0.0.1:5080;transport=tcp");
 ```
 
+### KSR.pv. Submodule ###
+
+`KSR.pv` submodule provides the functions to get, set and test the values of pseduo-variables. 
+
+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)`, ...).
+
+Note: functions exported by Kamailio's `pv` module are in `KSR.pvx` package.
+
+### KSR.pv.get(...) ###
+
+`xval KSR.pv.get(str "pvname")`
+
+Return the value of pseudo-variable `pvname`. The returned value can be string or integer.
+
+Example:
+
+```
+KSR.dbg("ruri is: " + KSR.pv.get("$ru") + "\n");
+```
+
+### KSR.pv.gete(...) ###
+
+`xval KSR.pv.gete(str "pvname")`
+
+Return the value of pseudo-variable `pvname` if it is different than `$null` or the empty string
+("") if the variable is having the `$null` value.
+
+Example:
+
+```
+KSR.dbg("avp is: " + KSR.pv.gete("$avp(x)") + "\n");
+```
+
+### KSR.pv.getvn(...) ###
+
+`xval KSR.pv.getvn(str "pvname", int vn)`
+
+Return the value of pseudo-variable `pvname` if it is different than `$null` or the parameter `vn`
+if the variable is having the `$null` value.
+
+Example:
+
+```
+KSR.dbg("avp is: " + KSR.pv.getvn("$avp(x)", 0) + "\n");
+```
+
+### KSR.pv.getvs(...) ###
+
+`xval KSR.pv.getvs(str "pvname", str "vs")`
+
+Return the value of pseudo-variable `pvname` if it is different than `$null` or the parameter `vs`
+if the variable is having the `$null` value.
+
+Example:
+
+```
+KSR.dbg("avp is: " + KSR.pv.getvs("$avp(x)", "foo") + "\n");
+```
+
+### KSR.pv.getw(...) ###
+
+`xval KSR.pv.getw(str "pvname")`
+
+Return the value of pseudo-variable `pvname` if it is different than `$null` or the string `<<null>>`
+if the variable is having the `$null` value. This should be used instead of `KSR.pv.get(...)`
+in the scripting languages that throw and error when attempting to print a `NULL` (or `NIL`) value.
+
+Example:
+
+```
+KSR.dbg("avp is: " + KSR.pv.getw("$avp(x)") + "\n");
+```
+
+### KSR.pv.seti(...) ###
+
+`void KSR.pv.seti(str "pvname", int val)`
+
+Set the value of pseudo-variable `pvname` to integer value provided by parameter `val`.
+
+Example:
+
+```
+KSR.pv.seti("$var(x)", 10);
+```
+
+### KSR.pv.sets(...) ###
+
+`void KSR.pv.sets(str "pvname", str "val")`
+
+Set the value of pseudo-variable `pvname` to string value provided by parameter `val`.
+
+Example:
+
+```
+KSR.pv.sets("$var(x)", "kamailio");
+```
+
+### KSR.pv.unset(...) ###
+
+`void KSR.pv.unset(str "pvname")`
+
+Set the value of pseudo-variable `pvname` to `$null`.
+
+Example:
+
+```
+KSR.pv.unset("$avp(x)");
+```
+
+### KSR.pv.is_null(...) ###
+
+`bool KSR.pv.is_null(str "pvname")`
+
+Return true if pseudo-variable `pvname` is `$null`.
+
+Example:
+
+```
+if(KSR.pv.is_null("$avp(x)")) {
+  ...
+}
+```
+
+### KSR.hdr Submodule ###
+
 ### KSR.hdr.append(...) ###
 
 `int KSR.hdr.append(str "hdrval")`

kamailio-kemi-framework/docs/kemi.md

@@ -465,7 +465,7 @@ The bool return code is expected to be evaluated as `true` or `false` inside the
 
 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, for example in the `KSR.pv` submodule to get the value of pseudo-variables.
+Several functions may return a string or `xval` value, for example in the `KSR.pv` submodule to get the value of pseudo-variables. If a function returns `xval`, then the result value can be `string`, `integer` or `null`.
 
 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.
@@ -567,8 +567,7 @@ Not all combinations of extra (after `sip_msg_t*`) parameters types are supporte
   * `1 param` - can be `int` of `str*`
   * `2 params` - any combination of `int` or `str*`
   * `3 params` - any combination of `int` or `str*`
-  * `4 params` - several combination of `int` or `str*` (all `str*`, all `int`, first parameters `str*` and the rest `int`,
-  first parameters `int` and the rest `str*`, other combinations to be added as needed)
-  * `5 params` - all have to be `str*` (other combinations to be added as needed)
+  * `4 params` - any combination of `int` or `str*`
+  * `5 params` - any combination of `int` or `str*`
   * `6 params` - all have to be `str*` (other combinations to be added as needed)
 

kamailio-kemi-framework/docs/kemimods.md

@@ -1,135 +1,12 @@
-## PV And Special KEMI Functions ##
+## 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)`, ...).
-
-Note: functions exported by Kamailio's `pv` module are in `KSR.pvx` package.
+Each KEMI interpreter module (respectively `app_jsdt`, `app_lua`, `app_python`,`app_python3`, `app_ruby`
+and `app_sqlang`) exports the submodule `KSR.x`.
 
 `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(str "pvname")`
-
-Return the value of pseudo-variable `pvname`. The returned value can be string or integer.
-
-Example:
-
-```
-KSR.dbg("ruri is: " + KSR.pv.get("$ru") + "\n");
-```
-
-### KSR.pv.gete(...) ###
-
-`val KSR.pv.gete(str "pvname")`
-
-Return the value of pseudo-variable `pvname` if it is different than `$null` or the empty string
-("") if the variable is having the `$null` value.
-
-Example:
-
-```
-KSR.dbg("avp is: " + KSR.pv.gete("$avp(x)") + "\n");
-```
-
-### KSR.pv.getvn(...) ###
-
-`val KSR.pv.getvn(str "pvname", int vn)`
-
-Return the value of pseudo-variable `pvname` if it is different than `$null` or the parameter `vn`
-if the variable is having the `$null` value.
-
-Example:
-
-```
-KSR.dbg("avp is: " + KSR.pv.getvn("$avp(x)", 0) + "\n");
-```
-
-### KSR.pv.getvs(...) ###
-
-`val KSR.pv.getvs(str "pvname", str "vs")`
-
-Return the value of pseudo-variable `pvname` if it is different than `$null` or the parameter `vs`
-if the variable is having the `$null` value.
-
-Example:
-
-```
-KSR.dbg("avp is: " + KSR.pv.getvs("$avp(x)", "foo") + "\n");
-```
-
-### KSR.pv.getw(...) ###
-
-`val KSR.pv.getw(str "pvname")`
-
-Return the value of pseudo-variable `pvname` if it is different than `$null` or the string `<<null>>`
-if the variable is having the `$null` value. This should be used instead of `KSR.pv.get(...)`
-in the scripting languages that throw and error when attempting to print a `NULL` (or `NIL`) value.
-
-Example:
-
-```
-KSR.dbg("avp is: " + KSR.pv.getw("$avp(x)") + "\n");
-```
-
-### KSR.pv.seti(...) ###
-
-`void KSR.pv.seti(str "pvname", int val)`
-
-Set the value of pseudo-variable `pvname` to integer value provided by parameter `val`.
-
-Example:
-
-```
-KSR.pv.seti("$var(x)", 10);
-```
-
-### KSR.pv.sets(...) ###
-
-`void KSR.pv.sets(str "pvname", str "val")`
-
-Set the value of pseudo-variable `pvname` to string value provided by parameter `val`.
-
-Example:
-
-```
-KSR.pv.sets("$var(x)", "kamailio");
-```
-
-### KSR.pv.unset(...) ###
-
-`void KSR.pv.unset(str "pvname")`
-
-Set the value of pseudo-variable `pvname` to `$null`.
-
-Example:
-
-```
-KSR.pv.unset("$avp(x)");
-```
-
-### KSR.pv.is_null(...) ###
-
-`bool KSR.pv.is_null(str "pvname")`
-
-Return true if pseudo-variable `pvname` is `$null`.
-
-Example:
-
-```
-if(KSR.pv.is_null("$avp(x)")) {
-  ...
-}
-```
-
 ### KSR.x.modf(...) ###
 
 `int KSR.x.modf(str "fname", params...)`
@@ -143,7 +20,7 @@ Example:
 KSR.x.modf("sl_send_reply", "200", "OK");
 ```
 
-Important note: try not to use this function, prefer the use of dedicated KSR fuctions. If you have to use
+Important note: try not to use this function, prefer the use of dedicated KSR functions. If you have to use
 this function, check if it has fixup and fixup-free functions in the C code in order to avoid memory leaks.
 If you are not sure how to do the check, ask on sr-users mailing list if it is safe to use it for a specific
 module fuction.
@@ -154,14 +31,23 @@ module fuction.
 
 Equivalent of `exit` from native kamailio.cfg scripting language, stop the execution of the SIP routing script.
 
+Example:
+
+```
+KSR.x.exit();
+```
+
 It is not exported by each KEMI interpreter module, in that case likely the scripting
-language has an `exit` function that can be used for this purpose. In the case there
-is no `exit`, just do `return` from the main KEMI callback functions
-(e.g., for SIP request routing do `return` from `ksr_request_route()`).
+language has an `exit` function that can be used for this purpose. Respectively:
+
+  * for Python and Python3, use `exit()` or `os.exit()`.
+  * for Ruby, use `exit`.
 
-For Python, one can use `exit()` or `os.exit()`.
+In the case there is no `KSR.x.exit` and no usable `exit` in the KEMI scripting language, just do `return`
+from the main KEMI callback functions (e.g., for SIP request routing do `return` from `ksr_request_route()`).
 
-For Ruby, one can use `exit`.
+IMPORTANT: be careful with the native `exit` functions in some KEMI interpreters, such as Lua, because they
+can trigger the stop of the application, in this case stopping Kamailio completely.
 
 ### KSR.x.drop(...) ###
 
@@ -170,5 +56,18 @@ For Ruby, one can use `exit`.
 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.
 
+Example:
+
+```
+KSR.x.drop();
+```
+
 If not exported by a KEMI interpreter module, use `KSR.set_drop()` before terminating
-the execution of the KEMI callback function (see the notes for `KSR.x.exit`).
+the execution of the KEMI callback function (see the notes for `KSR.x.exit`). For example:
+
+  * for Python or Python3, use:
+
+```
+KSR.set_drop()
+exit()
+```