siptrace(k) Add RPC command for turning on/off

Copying the functionality of the existing MI command.

Also, setting the value of the trace_flag to 0 by default, as
documented in the documentation.

modules_k/siptrace/README

@@ -23,7 +23,7 @@ Daniel-Constantin Mierla
 
    Table of Contents
 
-   1. Admin Guide
+   1. SIPtrace Admin Guide
 
         1. Overview
         2. Dependencies
@@ -58,8 +58,12 @@ Daniel-Constantin Mierla
 
               5.1. sip_trace
 
-        6. Database setup
-        7. Known issues
+        6. RPC Commands
+
+              6.1. siptrace.status param
+
+        7. Database setup
+        8. Known issues
 
    List of Examples
 
@@ -81,7 +85,7 @@ Daniel-Constantin Mierla
    1.16. Set trace_delayed parameter
    1.17. sip_trace() usage
 
-Chapter 1. Admin Guide
+Chapter 1. SIPtrace Admin Guide
 
    Table of Contents
 
@@ -118,25 +122,29 @@ Chapter 1. Admin Guide
 
         5.1. sip_trace
 
-   6. Database setup
-   7. Known issues
+   6. RPC Commands
+
+        6.1. siptrace.status param
+
+   7. Database setup
+   8. Known issues
 
 1. Overview
 
-   Offer a possibility to store incoming/outgoing SIP messages in database
-   and/or duplicate to the capturing server (homer encapsulation protocol
-   or plain sip mode)
+   Offer a possibility to store incoming and outgoing SIP messages in a
+   database and/or duplicate to the capturing server (using the Homer
+   encapsulation protocol or plain SIP mode)
 
    There are two ways of storing information.
      * by calling explicitely the sip_trace() method in Kamailio
        configuration file. In this case the original message is processed.
      * by setting the flag equal with the value of 'trace_flag' (e.g.,
-       setflag(__trace_flag__)) parameter of the module. In this case,
-       the\ message sent forward is processed. The logging mechanism is
-       based on TM/SL callbacks, so only messages processed with TM/SL are
+       setflag(__trace_flag__)) parameter of the module. In this case, the
+       message sent forward is processed. The logging mechanism is based
+       on TM/SL callbacks, so only messages processed with TM/SL are
        logged.
 
-   The tracing can be turned on/off using fifo commad.
+   The tracing can be turned on/off using Kamailio mi or RPC commands.
 
    kamctl fifo sip_trace on
 
@@ -150,7 +158,7 @@ Chapter 1. Admin Guide
 2.1. Kamailio Modules
 
    The following modules must be loaded before this module:
-     * database module - mysql, postrgress, dbtext, unixodbc...
+     * database module - Mysql, Postgres, dbtext, unixODBC...
      * tm and sl modules - optional, only if you want to trace messages
        forwarded by these modules.
 
@@ -400,7 +408,7 @@ modparam("siptrace", "trace_delayed", 1)
 
    4.1. sip_trace()
 
-4.1. sip_trace()
+4.1.  sip_trace()
 
    Store current processed SIP message in database. It is stored in the
    form prior applying chages made to it.
@@ -417,7 +425,7 @@ sip_trace();
 
    5.1. sip_trace
 
-5.1. sip_trace
+5.1.  sip_trace
 
    Name: sip_trace
 
@@ -434,7 +442,22 @@ sip_trace();
                 trace_mode
                 _empty_line_
 
-6. Database setup
+6. RPC Commands
+
+   6.1. siptrace.status param
+
+6.1.  siptrace.status param
+
+   Name: siptrace.status
+
+   Parameters:
+     * on or off: turns on/off SIP message tracing.. Possible values are:
+          + on
+          + off
+     * "check" does not change siptrace status, just reports the current
+       status.
+
+7. Database setup
 
    Before running Kamailio with siptrace, you have to setup the database
    tables where the module will store the data. For that, if the table
@@ -444,7 +467,7 @@ sip_trace();
    You can also find the complete database documentation on the project
    webpage, http://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.
 
-7. Known issues
+8. Known issues
 
    Stateless forwarded messages (forward()) are not logged if you set the
    flag, use sip_trace().

modules_k/siptrace/doc/siptrace_admin.xml

@@ -11,14 +11,14 @@
 
 <chapter>
 	
-	<title>&adminguide;</title>
+	<title>SIPtrace  &adminguide;</title>
 	
 	<section>
 	<title>Overview</title>
 	<para>
-		Offer a possibility to store incoming/outgoing SIP messages in database
-		and/or duplicate to the capturing server (homer encapsulation protocol 
-		or plain sip mode)
+		Offer a possibility to store incoming and outgoing SIP messages in a database
+		and/or duplicate to the capturing server (using the Homer encapsulation protocol 
+		or plain SIP mode)
 	</para>
 	<para>
 	There are two ways of storing information.
@@ -32,7 +32,7 @@
 		<listitem>
 		<para>
 		by setting the flag equal with the value of 'trace_flag' (e.g.,
-		setflag(__trace_flag__)) parameter of the module. In this case, the\
+		setflag(__trace_flag__)) parameter of the module. In this case, the
 		message sent forward is processed. The logging mechanism is based on
 		TM/SL callbacks, so only messages processed with TM/SL are logged.
 		</para>
@@ -41,7 +41,7 @@
 	</para>
 
 	<para>
-	The tracing can be turned on/off using fifo commad.
+	The tracing can be turned on/off using Kamailio mi or RPC commands.
 	</para>
 	<para>
 	&ctltool; fifo sip_trace on
@@ -59,8 +59,8 @@
 			<itemizedlist>
 			<listitem>
 			<para>
-				<emphasis>database module</emphasis> - mysql, postrgress,
-				dbtext, unixodbc...
+				<emphasis>database module</emphasis> - Mysql, Postgres,
+				dbtext, unixODBC...
 			</para>
 			</listitem>
 			<listitem>
@@ -515,7 +515,35 @@ sip_trace();
 		_empty_line_
 		</programlisting>
 	</section>
+	</section><!-- MI Commands -->
+    	<section>
+	<title>RPC Commands</title>
+	<section>
+		<title>
+		<function moreinfo="none">siptrace.status param</function>
+		</title>
+		<para>
+
+		</para>
+		<para>
+		Name: <emphasis>siptrace.status</emphasis>
+		</para>
+		<para>Parameters: </para>
+		<itemizedlist>
+			<listitem><para>on or off: turns on/off SIP message tracing..
+			Possible values are:</para>
+			<itemizedlist>
+				<listitem><para>on</para></listitem> 
+				<listitem><para>off</para></listitem>
+			</itemizedlist>
+			</listitem>
+			<listitem><para><quote>check</quote> does not change 
+			siptrace status, just reports the current status.</para>
+			</listitem>
+		</itemizedlist>
+
 	</section>
+	</section><!-- RPC commands -->
 	
 	<section>
 		<title>Database setup</title>

modules_k/siptrace/siptrace.c

@@ -41,6 +41,8 @@
 #include "../../mem/mem.h"
 #include "../../mem/shm_mem.h"
 #include "../../lib/kmi/mi.h"
+#include "../../rpc.h"
+#include "../../rpc_lookup.h"
 #include "../../lib/srdb1/db.h"
 #include "../../parser/parse_content.h"
 #include "../../parser/parse_from.h"
@@ -86,6 +88,7 @@ sl_api_t slb;
 
 /* module function prototypes */
 static int mod_init(void);
+static int siptrace_init_rpc(void);
 static int child_init(int rank);
 static void destroy(void);
 static int sip_trace(struct sip_msg*, char*, char*);
@@ -124,8 +127,8 @@ static str time_us_column     = str_init("time_us");     /* 10 */
 
 #define XHEADERS_BUFSIZE 512
 
-int trace_flag = -1;
-int trace_on   = 0;
+int trace_flag = 0;
+=nt trace_on   = 0;
 int trace_sl_acks = 1;
 
 int trace_to_database = 1;
@@ -265,6 +268,11 @@ static int mod_init(void)
 		LM_ERR("failed to register MI commands\n");
 		return -1;
 	}
+	if(siptrace_init_rpc() != 0) 
+	{
+		LM_ERR("failed to register RPC commands\n");
+		return -1;
+	}
 
 	db_url.len = strlen(db_url.s);
 	siptrace_table.len = strlen(siptrace_table.s);
@@ -1765,3 +1773,55 @@ static int pipport2su (char *pipport, union sockaddr_union *tmp_su, unsigned int
 error:
 	return -1;
 }
+
+static void siptrace_rpc_status (rpc_t* rpc, void* c) {
+	str status = {0, 0};
+
+	if (rpc->scan(c, "S", &status) < 1) {
+		rpc->fault(c, 500, "Not enough parameters (on, off or check)");
+		return;
+	}
+
+	if(trace_on_flag==NULL) {
+		rpc->fault(c, 500, "Internal error");
+		return;
+	}
+
+	if (strncasecmp(status.s, "on", strlen("on")) == 0) {
+		*trace_on_flag = 1;
+		rpc->printf(c, "Enabled");
+		return;
+	}
+	if (strncasecmp(status.s, "off", strlen("off")) == 0) {
+		*trace_on_flag = 0;
+		rpc->printf(c, "Disabled");
+		return;
+	}
+	if (strncasecmp(status.s, "check", strlen("check")) == 0) {
+		rpc->printf(c, *trace_on_flag ? "Enabled" : "Disabled");
+		return;
+	} 
+	rpc->fault(c, 500, "Bad parameter (on, off or check)");
+	return;
+}
+
+static const char* siptrace_status_doc[2] = {
+        "Get status or turn on/off siptrace. Parameters: on, off or check.",
+        0
+};
+
+rpc_export_t siptrace_rpc[] = {
+	{"siptrace.status", siptrace_rpc_status, siptrace_status_doc, 0},
+	{0, 0, 0, 0}
+};
+
+static int siptrace_init_rpc(void)
+{
+	if (rpc_register_array(siptrace_rpc)!=0)
+	{
+		LM_ERR("failed to register RPC commands\n");
+		return -1;
+	}
+	return 0;
+}
+