add new jsonrpc module

Send JSON-RPC commands to a JSON-RPC server and optionally receive
replies

modules/jsonrpc/Makefile

@@ -0,0 +1,10 @@
+#
+# Provides integration with a JSON-RPC Server
+#
+
+include ../../Makefile.defs
+auto_gen=
+NAME=jsonrpc.so
+
+include ../../Makefile.modules
+

modules/jsonrpc/README

@@ -0,0 +1,169 @@
+event_jsonrpc Module
+
+Razvan Crainea
+
+   OpenSIPS Solutions
+
+Edited by
+
+Razvan Crainea
+     __________________________________________________________
+
+   Table of Contents
+
+   1. Admin Guide
+
+        1.1. Overview
+        1.2. Dependencies
+
+              1.2.1. OpenSIPS Modules
+              1.2.2. External Libraries or Applications
+
+        1.3. Exported Parameters
+
+              1.3.1. connect_timeout (integer)
+              1.3.2. write_timeout (integer)
+              1.3.3. read_timeout (integer)
+
+        1.4. Exported Functions
+
+              1.4.1. jsonrpc_request(destination, method, params,
+                      ret_pvar)
+
+              1.4.2. jsonrpc_notification(destination, method,
+                      params)
+
+   List of Examples
+
+   1.1. Set connect_timeout parameter
+   1.2. Set write_timeout parameter
+   1.3. Set read_timeout parameter
+   1.4. jsonrpc_request() function usage
+   1.5. jsonrpc_notification() function usage
+
+Chapter 1. Admin Guide
+
+1.1. Overview
+
+   This module is an implementation of an JSON-RPC v2.0 client
+   http://www.jsonrpc.org/specification. that can send a call to a
+   JSON-RPC server over a TCP connection.
+
+   NOTE that the current version of this module does not support
+   TCP connection reusage, nor asynchronous commands.
+
+1.2. Dependencies
+
+1.2.1. OpenSIPS Modules
+
+   The following modules must be loaded before this module:
+     * none.
+
+1.2.2. External Libraries or Applications
+
+   The following libraries or applications must be installed
+   before running OpenSIPS with this module loaded:
+     * none
+
+1.3. Exported Parameters
+
+1.3.1. connect_timeout (integer)
+
+   The amount of milliseconds OpenSIPS waits to connect to the the
+   JSON-RPC server, until it times out.
+
+   Default value is "500 milliseconds".
+
+   Example 1.1. Set connect_timeout parameter
+...
+modparam("jsonrpc", "connect_timeout", 200)
+...
+
+1.3.2. write_timeout (integer)
+
+   The amount of milliseconds OpenSIPS waits to send a RPC command
+   to the JSON-RPC server, until it times out.
+
+   Default value is "500 milliseconds".
+
+   Example 1.2. Set write_timeout parameter
+...
+modparam("jsonrpc", "write_timeout", 300)
+...
+
+1.3.3. read_timeout (integer)
+
+   The amount of milliseconds OpenSIPS waits for the JSON-RPC
+   server to respond to a JSON-RPC request, until it times out.
+   Note that these parameter only affects the jsonrpc_request
+   command.
+
+   Default value is "500 milliseconds".
+
+   Example 1.3. Set read_timeout parameter
+...
+modparam("jsonrpc", "read_timeout", 300)
+...
+
+1.4. Exported Functions
+
+1.4.1.  jsonrpc_request(destination, method, params, ret_pvar)
+
+   Does a JSON-RPC request to the JSON-RPC server indicated in the
+   destination parameter, and waits for a reply from it.
+
+   This function can be used from any route.
+
+   The function has the following parameters:
+     * destination - address of the JSON-RPC server. The format
+       needs to be IP:port.
+     * method - the method used in the RPC request.
+     * params - these are the parameters sent to the RPC method.
+       This parameter needs to be a properly formated JSON array,
+       or JSON object, according the the JSON-RPC specifications.
+     * ret_pvar a writeable variable used to store the result of
+       the JSON-RPC command. If the command returns an error, the
+       variable will be populated with the error JSON, otherwise,
+       with the body of the JSON-RPC result.
+
+   The function has the following return codes:
+     * 1 - JSON-RPC command executed successfully, and the server
+       returned success. You can check the ret_pvar variable for
+       the result.
+     * -1 - There was an internal error during processing.
+     * -2 - There was a connection (timeout or connect) error with
+       the destination.
+     * -3 - The JSON-RPC was successfully run, but the server
+       returned an error. Check the ret_pvar value to find out
+       more information.
+
+   Example 1.4. jsonrpc_request() function usage
+        ...
+        if (!jsonrpc_request("127.0.0.1", "add", "[1,2]", "$var(ret)"))
+{
+                xlog("JSON-RPC command failed with $var(ret)\n");
+                exit;
+        }
+        xlog(JSON-RPC command returned $var(ret)\n");
+        # parse $var(ret) as JSON, or whatever the function returns
+        ...
+
+1.4.2.  jsonrpc_notification(destination, method, params)
+
+   Does a JSON-RPC notification to the JSON-RPC server indicated
+   in the destination parameter, but unlike jsonrpc.request, it
+   does not wait for a reply from the JSON-RPC server.
+
+   This function can be used from any route.
+
+   The function receives the same parameters as jsonrpc.request,
+   except for the ret_pvar. Also, the same values are returned.
+
+   Example 1.5. jsonrpc_notification() function usage
+        ...
+        if (!jsonrpc_notification("127.0.0.1", "block_ip", "{ \"ip": \"$
+si\" }")) {
+                xlog("JSON-RPC notification failed with $rc!\n");
+                exit;
+        }
+        ...

modules/jsonrpc/doc/jsonrpc.xml

@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding='ISO-8859-1'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+
+
+<!ENTITY admin SYSTEM "jsonrpc_admin.xml">
+<!ENTITY faq SYSTEM "../../../doc/module_faq.xml">
+
+<!-- Include general documentation entities -->
+<!ENTITY % docentities SYSTEM "../../../doc/entities.xml">
+%docentities;
+
+]>
+
+<book>
+	<bookinfo>
+	<title>event_jsonrpc Module</title>
+	<productname class="trade">&osipsname;</productname>
+	<authorgroup>
+		<author>
+		<firstname>Razvan</firstname>
+		<surname>Crainea</surname>
+		<affiliation><orgname>OpenSIPS Solutions</orgname></affiliation>
+		<address>
+		<email>razvan@opensips.org</email>
+		<otheraddr>
+			&osipssol;
+		</otheraddr>
+		</address>
+		</author>
+		<editor>
+		<firstname>Razvan</firstname>
+		<surname>Crainea</surname>
+		<address>
+			<email>razvan@opensips.org</email>
+		</address>
+		</editor>
+	</authorgroup>
+	</bookinfo>
+	<toc></toc>
+
+	&admin;
+	&faq;
+
+</book>