[sr-dev] git:5.2:0387df55: xmlrpc: docs for event_callback parameter

[Daniel-Constantin Mierla]

Module: kamailio
Branch: 5.2
Commit: 0387df55d08c435e8ee4d8dde41c260f2ddb839b
URL: https://github.com/kamailio/kamailio/commit/0387df55d08c435e8ee4d8dde41c260f2ddb839b

Author: Surendra Tiwari <surendratiwari3 at gmail.com>
Committer: Daniel-Constantin Mierla <miconda at gmail.com>
Date: 2018-11-27T20:03:34+01:00

xmlrpc: docs for event_callback parameter

- GH #1736

(cherry picked from commit d74d67976905c9d0c49f00485046117bc2581e65)

---

Modified: src/modules/xmlrpc/doc/xmlrpc_admin.xml

---

Diff:  https://github.com/kamailio/kamailio/commit/0387df55d08c435e8ee4d8dde41c260f2ddb839b.diff
Patch: https://github.com/kamailio/kamailio/commit/0387df55d08c435e8ee4d8dde41c260f2ddb839b.patch

---

diff --git a/src/modules/xmlrpc/doc/xmlrpc_admin.xml b/src/modules/xmlrpc/doc/xmlrpc_admin.xml
index 381a1feff7..a61d63e6db 100644
--- a/src/modules/xmlrpc/doc/xmlrpc_admin.xml
+++ b/src/modules/xmlrpc/doc/xmlrpc_admin.xml
@@ -60,7 +60,7 @@ modparam("xmlrpc", "route", "route_for_xmlrpcs")
 	<section id="autoconversion">
 	<title><varname>autoconversion</varname> (string)</title>
 	<para>
-		Enable or disable automatic parameter type conversion globally, 
+		Enable or disable automatic parameter type conversion globally,
 		for all the methods parameters.
 		If on, a type mismatch in a method parameter
 		will not cause a fault if it is possible to automatically
@@ -192,6 +192,45 @@ modparam("xmlrpc", "url_match", "^/RPC2")
 </programlisting>
 		</example>
 	</section>
+	<section id="event_callback">
+		<title><varname>event_callback</varname> (string)</title>
+		<para>
+		The name of the function in the kemi configuration file (embedded
+		scripting language such as Lua, Python, ...) to be executed instead
+		of route blocks defined by route parameter for xmlrpc request.
+		</para>
+		<para>
+		This route will be called only for HTTP messages whose method is
+		either GET or POST. The message visible inside the route
+		will be a HTTP request converted to SIP (the uri will be fixed and
+		a fake via will be added).
+		</para>
+		<para>
+		The route should perform additional security checks to
+		ensure the client is authorized to execute management/RPC functions
+		and then it should call the <function>dispatch_rpc()</function>.
+		</para>
+		<example>
+			<title>Set <varname>event_callback</varname> parameter</title>
+			<programlisting format="linespecific">
+...
+modparam("xmlrpc", "event_callback", "ksr_xmlrpc_event")
+...
+-- event callback function implemented in Lua
+function ksr_xmlrpc_event(evname)
+	KSR.info("===== xmlrpc triggered event: " .. evname .. "\n");
+	local rpc_method = KSR.pv.get("$rm") or ""
+	if ((rpc_method == "POST" or rpc_method == "GET")) then
+		if (KSR.xmlrpc.dispatch_rpc() < 0) then
+			KSR.err("error while executing xmlrpc event")
+		end
+	end
+	return 1;
+end
+...
+</programlisting>
+	</example>
+	</section>
 </section>
 <section>