modules/cfgutils: added some RPC commands

modules/cfgutils/README

@@ -22,14 +22,18 @@ Olle E. Johansson
 
    <[email protected]>
 
+Juha Heinanen
+
+   <[email protected]>
+
 Edited by
 
 Daniel-Constantin Mierla
 
    <[email protected]>
 
-   Copyright © 2013, 2007, 2008, 2004 Edvina AB, 1und1 Internet AG, BASIS
-   AudioNet GmbH, Elena-Ramona Modroiu, FhG FOKUS
+   Copyright (c) 2014, 2013, 2007, 2008, 2004 Edvina AB, 1und1 Internet
+   AG, BASIS AudioNet GmbH, Elena-Ramona Modroiu, Juha Heinanen, FhG FOKUS
      __________________________________________________________________
 
    Table of Contents
@@ -79,9 +83,15 @@ Daniel-Constantin Mierla
               5.8. is_gflag
               5.9. get_gflags
 
-        6. Exported pseudo-variables
+        6. RPC Commands
+
+              6.1. cfgutils.set_gflag
+              6.2. cfgutils.reset_gflag
+              6.3. cfgutils.is_gflag
 
-              6.1. $RANDOM
+        7. Exported pseudo-variables
+
+              7.1. $RANDOM
 
    List of Examples
 
@@ -117,7 +127,10 @@ Daniel-Constantin Mierla
    1.30. reset_gflag usage
    1.31. is_gflag usage
    1.32. get_gflags usage
-   1.33. RANDOM pseudo-variable usage
+   1.33. cfgutils.set_gflag usage
+   1.34. cfgutils.reset_gflag usage
+   1.35. cfgutils.is_gflag usage
+   1.36. RANDOM pseudo-variable usage
 
 Chapter 1. Admin Guide
 
@@ -166,9 +179,15 @@ Chapter 1. Admin Guide
         5.8. is_gflag
         5.9. get_gflags
 
-   6. Exported pseudo-variables
+   6. RPC Commands
+
+        6.1. cfgutils.set_gflag
+        6.2. cfgutils.reset_gflag
+        6.3. cfgutils.is_gflag
 
-        6.1. $RANDOM
+   7. Exported pseudo-variables
+
+        7.1. $RANDOM
 
 1. Overview
 
@@ -218,8 +237,8 @@ Chapter 1. Admin Guide
    The size of bitmap is 32.
 
    The module exports external commands that can be used to change the
-   global flags via Management Interface. The MI commands are:
-   "set_gflag", "reset_gflag" and "is_gflag".
+   global flags via Management Interface and RPC. See relevant sections
+   below.
 
 2. Dependencies
 
@@ -338,7 +357,7 @@ rand_reset_prob();
 ...
 rand_get_prob();
 
-4.5. sleep(time)
+4.5.  sleep(time)
 
    Waits "time" seconds.
 
@@ -353,7 +372,7 @@ rand_get_prob();
 sleep("1");
 ...
 
-4.6. usleep(time)
+4.6.  usleep(time)
 
    Waits "time" micro-seconds.
 
@@ -369,7 +388,7 @@ sleep("1");
 usleep("5000");
 ...
 
-4.7. abort()
+4.7.  abort()
 
    Debugging function that aborts the server. Depending on the
    configuration of the server a core dump will be created.
@@ -382,7 +401,7 @@ usleep("5000");
 abort();
 ...
 
-4.8. pkg_status()
+4.8.  pkg_status()
 
    Debugging function that dumps the status for the private (PKG) memory.
    This information is logged to the default log facility, depending on
@@ -397,7 +416,7 @@ abort();
 pkg_status();
 ...
 
-4.9. pkg_summary()
+4.9.  pkg_summary()
 
    Debugging function that dumps the summary for the private (PKG) memory
    usage. This information is logged to the default log facility,
@@ -412,7 +431,7 @@ pkg_status();
 pkg_summary();
 ...
 
-4.10. shm_status()
+4.10.  shm_status()
 
    Debugging function that dumps the status for the shared (SHM) memory.
    This information is logged to the default log facility, depending on
@@ -427,7 +446,7 @@ pkg_summary();
 shm_status();
 ...
 
-4.11. shm_summary()
+4.11.  shm_summary()
 
    Debugging function that dumps the summary for the shared (SHM) memory
    usage. This information is logged to the default log facility,
@@ -613,7 +632,7 @@ $ kamctl fifo rand_set_prob 10
 
    This command don't need a parameter.
 
-   Example 1.25. rand_reset_prob usage
+   Example 1.25.  rand_reset_prob usage
 ...
 $ kamctl fifo rand_reset_prob
 ...
@@ -677,7 +696,7 @@ $ kamctl fifo set_gflag 0x3
    The parameter value must be a bitmask in decimal or hexadecimal format.
    The bitmask has a 32 bit size.
 
-   Example 1.30. reset_gflag usage
+   Example 1.30.  reset_gflag usage
 ...
 $ kamctl fifo reset_gflag 1
 $ kamctl fifo reset_gflag 0x3
@@ -716,22 +735,74 @@ TRUE
    Return the bitmap with all flags. The function gets no parameters and
    returns the bitmap in hexadecimal and decimal format.
 
-   Example 1.32. get_gflags usage
+   Example 1.32.  get_gflags usage
 ...
 $ kamctl fifo get_gflags
 0x3039
 12345
 ...
 
-6. Exported pseudo-variables
+6. RPC Commands
+
+   6.1. cfgutils.set_gflag
+   6.2. cfgutils.reset_gflag
+   6.3. cfgutils.is_gflag
+
+6.1. cfgutils.set_gflag
+
+   Set the value of some flags (specified by bitmask) to 1.
+
+   The parameter value must be a bitmask in decimal or hexadecimal format.
+   The bitmask has a 32 bit size.
+
+   Example 1.33. cfgutils.set_gflag usage
+...
+$ kamctl cfgutils.set_gflag s:1
+...
+
+6.2. cfgutils.reset_gflag
+
+   Reset the value of some flags to 0.
+
+   Reset the value of some flags (specified by bitmask) to 1.
+
+   The parameter value must be a bitmask in decimal or hexadecimal format.
+   The bitmask has a 32 bit size.
+
+   Example 1.34.  cfgutils.reset_gflag usage
+...
+$ kamctl cfgutils.reset_gflag s:0x1
+...
+
+6.3. cfgutils.is_gflag
+
+   Returns string "TRUE" if all the flags from the given set are set and
+   "FALSE" if at least one is not set.
+
+   The parameter value must be a bitmask in decimal or hexadecimal format.
+   The bitmask has a 32 bit size.
+
+   Example 1.35. cfgutils.is_gflag usage
+...
+$ kamctl cfgutils.set_gflag s:1024
+$ kamctl cfgutils.is_gflag s:1024
+TRUE
+$ kamctl cfgutils.is_gflag s:1023
+FALSE
+$ kamctl cfgutils.set_gflag s:0x7FFF
+$ kamctl cfgutils.is_gflag s:1023
+TRUE
+...
+
+7. Exported pseudo-variables
 
-   6.1. $RANDOM
+   7.1. $RANDOM
 
-6.1. $RANDOM
+7.1. $RANDOM
 
    Returns a random value from the [0 - 2^31) range.
 
-   Example 1.33. RANDOM pseudo-variable usage
+   Example 1.36. RANDOM pseudo-variable usage
 ...
 if (rand_event()) {
   $avp(i:10) = ($RANDOM / 16777216); # 2^24

modules/cfgutils/cfgutils.c

@@ -72,6 +72,7 @@
 #include "../../hashes.h"
 #include "../../locking.h"
 #include "../../route.h"
+#include "../../rpc_lookup.h"
 #include <stdio.h>
 #include <stdlib.h>
 #include <sys/types.h>
@@ -215,6 +216,106 @@ static mi_export_t mi_cmds[] = {
 };
 
 
+static void rpc_is_gflag(rpc_t* rpc, void* c)
+{
+	str flag_str;
+	unsigned int flag;
+	
+	if (rpc->scan(c, "S", &flag_str) != 1) {
+		rpc->fault(c, 400, "flag parameter error");
+		return;
+	}
+
+	flag = 0;
+	if ((strno2int(&flag_str, &flag) < 0) || !flag) {
+		rpc->fault(c, 400, "incorrect flag parameter value");
+		return;
+	}
+
+	if (((*gflags) & flag) == flag)
+		rpc->add(c, "s", "TRUE");
+	else
+		rpc->add(c, "s", "FALSE");
+
+	return;
+}
+
+
+static void rpc_set_gflag(rpc_t* rpc, void* c)
+{
+	str flag_str;
+	unsigned int flag;
+	
+	if (rpc->scan(c, "S", &flag_str) != 1) {
+		rpc->fault(c, 400, "flag parameter error");
+		return;
+	}
+
+	flag = 0;
+	if ((strno2int(&flag_str, &flag) < 0) || !flag) {
+		rpc->fault(c, 400, "incorrect flag parameter value '%.*s'",
+			   flag_str.len, flag_str.s);
+		return;
+	}
+
+	lock_get(gflags_lock);
+	(*gflags) |= flag;
+	lock_release(gflags_lock);
+	
+	return;
+}
+
+
+static void rpc_reset_gflag(rpc_t* rpc, void* c)
+{
+	str flag_str;
+	unsigned int flag;
+	
+	if (rpc->scan(c, "S", &flag_str) != 1) {
+		rpc->fault(c, 400, "flag parameter error");
+		return;
+	}
+
+	flag = 0;
+	if ((strno2int(&flag_str, &flag) < 0) || !flag) {
+		rpc->fault(c, 400, "incorrect flag parameter value");
+		return;
+	}
+
+	lock_get(gflags_lock);
+	(*gflags) &= ~ flag;
+	lock_release(gflags_lock);
+	
+	return;
+}
+
+
+static const char* is_gflag_doc[2] = {
+	"Checks if the bits specified by the argument are all set.",
+	0
+};
+
+
+static const char* set_gflag_doc[2] = {
+	"Sets the bits specified by the argument.",
+	0
+};
+
+
+static const char* reset_gflag_doc[2] = {
+	"Resets the bits specified by the argument.",
+	0
+};
+
+
+static rpc_export_t rpc_cmds[] = {
+	{"cfgutils.is_gflag", rpc_is_gflag, is_gflag_doc, 0},
+	{"cfgutils.set_gflag", rpc_set_gflag, set_gflag_doc, 0},
+	{"cfgutils.reset_gflag", rpc_reset_gflag, reset_gflag_doc, 0},
+	{0, 0, 0, 0}
+};
+
+
 static pv_export_t mod_items[] = {
 	{ {"RANDOM", sizeof("RANDOM")-1}, PVT_OTHER, pv_get_random_val, 0,
 		0, 0, 0, 0 },
@@ -774,6 +875,12 @@ static int route_exists(struct sip_msg *msg, char *route)
 
 static int mod_init(void)
 {
+	/* Register RPC commands */
+	if (rpc_register_array(rpc_cmds)!=0) {
+		LM_ERR("failed to register RPC commands\n");
+		return -1;
+	}
+
 	if(register_mi_mod(exports.name, mi_cmds)!=0)
 	{
 		LM_ERR("failed to register MI commands\n");

modules/cfgutils/doc/cfgutils.xml

@@ -42,6 +42,11 @@
 		<surname>Johansson</surname>
 		<email>[email protected]</email>
 		</author>
+		<author>
+		<firstname>Juha</firstname>
+		<surname>Heinanen</surname>
+		<email>[email protected]</email>
+		</author>
 		<editor>
 		<firstname>Daniel-Constantin</firstname>
 		<surname>Mierla</surname>
@@ -49,6 +54,7 @@
 		</editor>
 	</authorgroup>
 	<copyright>
+		<year>2014</year>
 		<year>2013</year>
 		<year>2007</year>
 		<year>2008</year>
@@ -57,6 +63,7 @@
 		<holder>1und1 Internet AG</holder>
 		<holder>BASIS AudioNet GmbH</holder>
 		<holder>Elena-Ramona Modroiu</holder>
+		<holder>Juha Heinanen</holder>
 		<holder>&fhg;</holder>
 	</copyright>
 	</bookinfo>

modules/cfgutils/doc/cfgutils_admin.xml

@@ -73,9 +73,8 @@
 	</para>
 	<para>
 	The module exports external commands that can be used to change
-	the global flags via Management Interface. The MI commands are:
-	<quote>set_gflag</quote>, <quote>reset_gflag</quote> and
-	<quote>is_gflag</quote>.
+	the global flags via Management Interface and RPC. See relevant
+	sections below.
 	</para>
 	</section>
 	<section>
@@ -803,6 +802,78 @@ $ &ctltool; fifo get_gflags
 0x3039
 12345
 ...
+</programlisting>
+			</example>
+		</section>
+</section>
+	<section>
+		<title><acronym>RPC</acronym> Commands</title>
+		<section  id="cfgutils.rpc.set_gflag">
+			<title><function moreinfo="none">cfgutils.set_gflag</function></title>
+			<para>
+			Set the value of some flags (specified by bitmask) to 1.
+			</para>
+			<para>
+			The parameter value must be a bitmask in decimal or
+			hexadecimal format.  The bitmask has a 32 bit size.
+			</para>
+			<example>
+			<title><function moreinfo="none">cfgutils.set_gflag</function> usage</title>
+			<programlisting format="linespecific">
+...
+$ &ctltool; cfgutils.set_gflag s:1
+...
+</programlisting>
+			</example>
+
+		</section>
+		<section  id="cfgutils.rpc.reset_gflag">
+			<title><function moreinfo="none">cfgutils.reset_gflag</function></title>
+			<para>
+			Reset the value of some flags to 0.
+			</para>
+			<para>
+			Reset the value of some flags (specified by bitmask)
+			to 1.
+			</para>
+			<para>
+			The parameter value must be a bitmask in decimal or
+			hexadecimal format.  The bitmask has a 32 bit size.
+			</para>
+			<example>
+			<title>
+				<function moreinfo="none">cfgutils.reset_gflag</function> usage</title>
+			<programlisting format="linespecific">
+...
+$ &ctltool; cfgutils.reset_gflag s:0x1
+...
+</programlisting>
+			</example>
+		</section>
+		<section  id="cfgutils.rpc.is_gflag">
+			<title><function moreinfo="none">cfgutils.is_gflag</function></title>
+			<para>
+			Returns string "TRUE" if all the
+			flags from the given set are set
+			and "FALSE" if at least one is not set.
+			</para>
+			<para>
+			The parameter value must be a bitmask in decimal or
+			hexadecimal format.  The bitmask has a 32 bit size.
+			</para>
+			<example>
+			<title><function moreinfo="none">cfgutils.is_gflag</function> usage</title>
+			<programlisting format="linespecific">
+...
+$ &ctltool; cfgutils.set_gflag s:1024
+$ &ctltool; cfgutils.is_gflag s:1024
+TRUE
+$ &ctltool; cfgutils.is_gflag s:1023
+FALSE
+$ &ctltool; cfgutils.set_gflag s:0x7FFF
+$ &ctltool; cfgutils.is_gflag s:1023
+TRUE
+...
 </programlisting>
 			</example>
 		</section>