cfg_rpc: improved documentation

- aliased set_now_int to seti and set_now_string to sets

modules/cfg_rpc/README

@@ -4,80 +4,192 @@ Miklos Tirpak
 
    <[email protected]>
 
-   Copyright © 2007 iptelorg GmbH
+   Copyright © 2007 iptelorg GmbH
      __________________________________________________________________
 
    1.1. Overview
-   1.2. RPC Interface
+   1.2. Dependencies
+
+        1.2.1. SIP Router Modules
+        1.2.2. External Libraries or Applications
+
+   1.3. RPC Interface
+
+        1.3.1. cfg.list
+        1.3.2. cfg.get
+        1.3.3. cfg.seti
+        1.3.4. cfg.set_now_int
+        1.3.5. cfg.sets
+        1.3.6. cfg.set_now_string
+        1.3.7. cfg.set
+        1.3.8. cfg.del
+        1.3.9. cfg.set_delayed_int
+        1.3.10. cfg.set_delayed_string
+        1.3.11. cfg.set_delayed
+        1.3.12. cfg.del_delayed
+        1.3.13. cfg.commit
+        1.3.14. cfg.rollback
+        1.3.15. cfg.help
+        1.3.16. cfg.diff
+        1.3.17. cfg.add_group_inst
+        1.3.18. cfg.del_group_inst
 
 1.1. Overview
 
-   The module implements RPC functions to set and get configuration
+   The module implements RPC commands to set and get configuration
    variables on-the-fly, that are declared by SIP Router core and by the
-   modules. It can be used to fine-tune or debug SIP Router without the
-   need of restart.
-
-1.2. RPC Interface
-
-   The module implements the following RPC interface commands:
-     * cfg.set_now_int - Set the value of a configuration variable and
-       commit the change immediately. The function accepts three
-       parameters: group name, variable name, integer value. The group
-       name can optionally contain the group instance id, for example
-       foo[5].
-     * cfg.set_now_string - Set the value of a configuration variable and
-       commit the change immediately. The function accepts three
-       parameters: group name, variable name, string value. The group name
-       can optionally contain the group instance id, for example foo[5].
-     * cfg.set - Set the value of a configuration variable and commit the
-       change immediately. This is a wrapper command for cfg.set_now_int
-       and cfg.set_now_string depending on the type of the value provided.
-       The function accepts three parameters: group name, variable name,
-       int/string value. The group name can optionally contain the group
-       instance id, for example foo[5].
-     * cfg.del - Delete the value of a configuration variable from a group
-       instance and commit the change immediately. The value is reset to
-       the default value and it follows the changes of that. The function
-       accepts two parameters: group name, variable name. The group name
-       must contain the group instance id, for example foo[5].
-     * cfg.set_delayed_int - Prepare the change of a configuration
-       variable, but does not commit the new value yet. The function
-       accepts three parameters: group name, variable name, integer value.
-       The group name can optionally contain the group instance id, for
-       example foo[5].
-     * cfg.set_delayed_string - Prepare the change of a configuration
-       variable, but does not commit the new value yet. The function
-       accepts three parameters: group name, variable name, string value.
-       The group name can optionally contain the group instance id, for
-       example foo[5].
-     * cfg.set_delayed - Prepare the change of a configuration variable,
-       but does not commit the new value yet. This is a wrapper command
-       for cfg.set_delayed_int and cfg.set_delayed_string depending on the
-       type of the value provided. The function accepts three parameters:
-       group name, variable name, int/string value. The group name can
-       optionally contain the group instance id, for example foo[5].
-     * cfg.del_delayed - Prepare the deletion of the value of a
-       configuration variable from a group instance, but does not commit
-       the change yet. The value is reset to the default value and it
-       follows the changes of that. The function accepts two parameters:
-       group name, variable name. The group name must contain the group
-       instance id, for example foo[5].
-     * cfg.commit - Commit the previously prepared configuration changes.
-       The function does not have any parameters.
-     * cfg.rollback - Drop the prepared configuration changes. The
-       function does not have any parameters.
-     * cfg.get - Get the value of a configuration variable. The function
-       accepts two parameters: group name, variable name. The group name
-       can optionally contain the group instance id, for example foo[5].
-     * cfg.help - Print the description of a configuration variable. The
-       function accepts two parameters: group name, variable name.
-     * cfg.list - List the configuration variables. The function has one
-       optional parameter: group name.
-     * cfg.diff - List the pending configuration changes that have not
-       been committed yet. The function does not have any parameters.
-     * cfg.add_group_inst - Add a new instance to an existing
-       configuration group. The function accepts one parameter: group
-       name[instance id], for example foo[5].
-     * cfg.del_group_inst - Delete an instance of an existing
-       configuration group. The function accepts one parameter: group
-       name[instance id], for example foo[5].
+   modules.
+
+   For example, it can be used to fine-tune values for global parameters
+   such as debug, tcp/sctp/dns attributes, a.s.o. without the need of
+   restart.
+
+   RPC connector modules, such as ctl or xmlrpc, although not a dependecy,
+   should be loaded in order to execute the RPC commands exported by this
+   module. When ctl module is loaded, the tool 'sercmd' can be used to
+   execute the RPC commands implemented in this module.
+
+1.2. Dependencies
+
+1.2.1. SIP Router Modules
+
+   The following modules must be loaded before this module:
+     * No dependencies on other SIP Router modules.
+
+1.2.2. External Libraries or Applications
+
+   The following libraries or applications must be installed before
+   running SIP Router with this module loaded:
+     * None.
+
+1.3. RPC Interface
+
+   The module implements the RPC commands documented in the next sections.
+
+1.3.1. cfg.list
+
+   cfg.list - List the configuration variables. The function has one
+   optional parameter: group name.
+
+   Example 1. Use cfg.get RPC command
+...
+# sercmd cfg.list
+...
+
+1.3.2. cfg.get
+
+   cfg.get - Get the value of a configuration variable. The function
+   accepts two parameters: group name, variable name. The group name can
+   optionally contain the group instance id, for example foo[5].
+
+   Example 2. Use cfg.get RPC command
+...
+# sercmd cfg.get core debug
+...
+
+1.3.3. cfg.seti
+
+   cfg.seti - Set the value of a configuration variable and commit the
+   change immediately. The function accepts three parameters: group name,
+   variable name, integer value. The group name can optionally contain the
+   group instance id, for example foo[5].
+
+   Example 3. Use cfg.seti RPC command
+...
+# sercmd cfg.seti core debug 1
+...
+
+1.3.4. cfg.set_now_int
+
+   cfg.set_now_int - This is an alias to the command cfg.seti.
+
+1.3.5. cfg.sets
+
+   cfg.sets - Set the value of a configuration variable and commit the
+   change immediately. The function accepts three parameters: group name,
+   variable name, string value. The group name can optionally contain the
+   group instance id, for example foo[5].
+
+1.3.6. cfg.set_now_string
+
+   cfg.set_now_string - This is an alias to the command cfg.sets.
+
+1.3.7. cfg.set
+
+   cfg.set - Set the value of a configuration variable and commit the
+   change immediately. This is a wrapper command for cfg.set_now_int and
+   cfg.set_now_string depending on the type of the value provided. The
+   function accepts three parameters: group name, variable name,
+   int/string value. The group name can optionally contain the group
+   instance id, for example foo[5].
+
+1.3.8. cfg.del
+
+   cfg.del - Delete the value of a configuration variable from a group
+   instance and commit the change immediately. The value is reset to the
+   default value and it follows the changes of that. The function accepts
+   two parameters: group name, variable name. The group name must contain
+   the group instance id, for example foo[5].
+
+1.3.9. cfg.set_delayed_int
+
+   cfg.set_delayed_int - Prepare the change of a configuration variable,
+   but does not commit the new value yet. The function accepts three
+   parameters: group name, variable name, integer value. The group name
+   can optionally contain the group instance id, for example foo[5].
+
+1.3.10. cfg.set_delayed_string
+
+   cfg.set_delayed_string - Prepare the change of a configuration
+   variable, but does not commit the new value yet. The function accepts
+   three parameters: group name, variable name, string value. The group
+   name can optionally contain the group instance id, for example foo[5].
+
+1.3.11. cfg.set_delayed
+
+   cfg.set_delayed - Prepare the change of a configuration variable, but
+   does not commit the new value yet. This is a wrapper command for
+   cfg.set_delayed_int and cfg.set_delayed_string depending on the type of
+   the value provided. The function accepts three parameters: group name,
+   variable name, int/string value. The group name can optionally contain
+   the group instance id, for example foo[5].
+
+1.3.12. cfg.del_delayed
+
+   cfg.del_delayed - Prepare the deletion of the value of a configuration
+   variable from a group instance, but does not commit the change yet. The
+   value is reset to the default value and it follows the changes of that.
+   The function accepts two parameters: group name, variable name. The
+   group name must contain the group instance id, for example foo[5].
+
+1.3.13. cfg.commit
+
+   cfg.commit - Commit the previously prepared configuration changes. The
+   function does not have any parameters.
+
+1.3.14. cfg.rollback
+
+   cfg.rollback - Drop the prepared configuration changes. The function
+   does not have any parameters.
+
+1.3.15. cfg.help
+
+   cfg.help - Print the description of a configuration variable. The
+   function accepts two parameters: group name, variable name.
+
+1.3.16. cfg.diff
+
+   cfg.diff - List the pending configuration changes that have not been
+   committed yet. The function does not have any parameters.
+
+1.3.17. cfg.add_group_inst
+
+   cfg.add_group_inst - Add a new instance to an existing configuration
+   group. The function accepts one parameter: group name[instance id], for
+   example foo[5].
+
+1.3.18. cfg.del_group_inst
+
+   cfg.del_group_inst - Delete an instance of an existing configuration
+   group. The function accepts one parameter: group name[instance id], for
+   example foo[5].

modules/cfg_rpc/cfg_rpc.c

@@ -535,7 +535,9 @@ static void rpc_del_group_inst(rpc_t* rpc, void* c)
 static rpc_export_t rpc_calls[] = {
 	{"cfg.set",		rpc_set,		rpc_set_now_doc,	0},
 	{"cfg.set_now_int",	rpc_set_now_int,	rpc_set_now_doc,	0},
+	{"cfg.seti",	rpc_set_now_int,	rpc_set_now_doc,	0},
 	{"cfg.set_now_string",	rpc_set_now_string,	rpc_set_now_doc,	0},
+	{"cfg.sets",	rpc_set_now_string,	rpc_set_now_doc,	0},
 	{"cfg.del",		rpc_del,		rpc_del_now_doc,	0},
 	{"cfg.set_delayed",	rpc_set_delayed,	rpc_set_delayed_doc,	0},
 	{"cfg.set_delayed_int",	rpc_set_delayed_int,	rpc_set_delayed_doc,	0},

modules/cfg_rpc/doc/cfg_rpc.xml

@@ -27,13 +27,55 @@
     <section id="cfg_rpc.overview">
 	<title>Overview</title>
 	<para>
-	    The module implements RPC functions to set and get
+	    The module implements RPC commands to set and get
 	    configuration variables on-the-fly, that are declared
-	    by &siprouter; core and by the modules. It can be used to fine-tune
-	    or debug &siprouter; without the need of restart.
+		by &siprouter; core and by the modules.
+	</para>
+	<para>
+		For example, it can be used to fine-tune values for
+		global parameters such as debug, tcp/sctp/dns attributes,
+	    a.s.o. without the need of restart.
+	</para>
+	<para>
+		RPC connector modules, such as ctl or xmlrpc, although
+		not a dependecy, should be loaded in order to execute
+		the RPC commands exported by this module. When ctl module
+		is loaded, the tool 'sercmd' can be used to execute
+		the RPC commands implemented in this module.
 	</para>
     </section>
 
+	<section id="cfg_rpc.dependencies">
+	<title>Dependencies</title>
+	<section id="cfg_rpc.depmods">
+		<title>&siprouter; Modules</title>
+		<para>
+		The following modules must be loaded before this module:
+			<itemizedlist>
+			<listitem>
+			<para>
+				<emphasis>No dependencies on other &siprouter; modules</emphasis>.
+			</para>
+			</listitem>
+			</itemizedlist>
+		</para>
+	</section>
+	<section id="cfg_rpc.deplibs">
+		<title>External Libraries or Applications</title>
+		<para>
+		The following libraries or applications must be installed before running
+		&siprouter; with this module loaded:
+			<itemizedlist>
+			<listitem>
+			<para>
+				<emphasis>None</emphasis>.
+			</para>
+			</listitem>
+			</itemizedlist>
+		</para>
+	</section>
+	</section>
+
     <xi:include href="rpc.xml"/>
 
 </section>

modules/cfg_rpc/doc/rpc.xml

@@ -7,28 +7,85 @@
     <title>RPC Interface</title>
 
     <para>
-	The module implements the following RPC interface commands:
-    </para>
-    <itemizedlist>
-	<listitem>
+	The module implements the RPC commands documented in the next sections.
+	</para>
+	<section id="cfg_rpc.rpc.list">
+    <title>cfg.list</title>
 	    <para>
-		<emphasis>cfg.set_now_int</emphasis> - Set the value of
+		<emphasis>cfg.list</emphasis> - List the configuration
+		variables. The function has one optional parameter:
+		group name.
+		</para>
+		<example>
+		<title>Use <varname>cfg.get</varname> RPC command</title>
+		<programlisting format="linespecific">
+...
+# sercmd cfg.list
+...
+</programlisting>
+		</example>
+	</section>
+	<section id="cfg_rpc.rpc.get">
+    <title>cfg.get</title>
+	    <para>
+		<emphasis>cfg.get</emphasis> - Get the value of
+		a configuration variable. The function accepts two parameters:
+		group name, variable name. The group name can optionally contain the
+		group instance id, for example foo[5].
+	    </para>
+		<example>
+		<title>Use <varname>cfg.get</varname> RPC command</title>
+		<programlisting format="linespecific">
+...
+# sercmd cfg.get core debug
+...
+</programlisting>
+		</example>
+	</section>
+	<section id="cfg_rpc.rpc.seti">
+    <title>cfg.seti</title>
+	    <para>
+		<emphasis>cfg.seti</emphasis> - Set the value of
 		a configuration variable and commit the change immediately.
 		The function accepts three parameters: group name, variable
 		name, integer value. The group name can optionally contain the
 		group instance id, for example foo[5].
 	    </para>
-	</listitem>
-	<listitem>
-	    <para>
-		<emphasis>cfg.set_now_string</emphasis> - Set the value of
+		<example>
+		<title>Use <varname>cfg.seti</varname> RPC command</title>
+		<programlisting format="linespecific">
+...
+# sercmd cfg.seti core debug 1
+...
+</programlisting>
+		</example>
+	</section>
+	<section id="cfg_rpc.rpc.set_now_int">
+    <title>cfg.set_now_int</title>
+	    <para>
+		<emphasis>cfg.set_now_int</emphasis> - This is an alias to
+		the command <emphasis>cfg.seti</emphasis>.
+	    </para>
+	</section>
+	<section id="cfg_rpc.rpc.sets">
+    <title>cfg.sets</title>
+	    <para>
+		<emphasis>cfg.sets</emphasis> - Set the value of
 		a configuration variable and commit the change immediately.
 		The function accepts three parameters: group name, variable
 		name, string value. The group name can optionally contain the
 		group instance id, for example foo[5].
 	    </para>
-	</listitem>
-	<listitem>
+	</section>
+	<section id="cfg_rpc.rpc.set_now_string">
+    <title>cfg.set_now_string</title>
+	    <para>
+		<emphasis>cfg.set_now_string</emphasis> - This is an alias to
+		the command <emphasis>cfg.sets</emphasis>.
+	    </para>
+	</section>
+	<section id="cfg_rpc.rpc.set">
+    <title>cfg.set</title>
 	    <para>
 		<emphasis>cfg.set</emphasis> - Set the value of
 		a configuration variable and commit the change immediately.
@@ -38,8 +95,9 @@
 		name, int/string value. The group name can optionally contain the
 		group instance id, for example foo[5].
 	    </para>
-	</listitem>
-	<listitem>
+	</section>
+	<section id="cfg_rpc.rpc.del">
+    <title>cfg.del</title>
 	    <para>
 		<emphasis>cfg.del</emphasis> - Delete the value of
 		a configuration variable from a group instance and commit the change immediately.
@@ -49,8 +107,9 @@
 		name. The group name must contain the
 		group instance id, for example foo[5].
 	    </para>
-	</listitem>
-	<listitem>
+	</section>
+	<section id="cfg_rpc.rpc.set_delayed_int">
+    <title>cfg.set_delayed_int</title>
 	    <para>
 		<emphasis>cfg.set_delayed_int</emphasis> - Prepare the change of
 		a configuration variable, but does not commit the new value yet.
@@ -58,8 +117,9 @@
 		name, integer value. The group name can optionally contain the
 		group instance id, for example foo[5].
 	    </para>
-	</listitem>
-	<listitem>
+	</section>
+	<section id="cfg_rpc.rpc.set_delayed_string">
+    <title>cfg.set_delayed_string</title>
 	    <para>
 		<emphasis>cfg.set_delayed_string</emphasis> - Prepare the change of
 		a configuration variable, but does not commit the new value yet.
@@ -67,8 +127,9 @@
 		name, string value. The group name can optionally contain the
 		group instance id, for example foo[5].
 	    </para>
-	</listitem>
-	<listitem>
+	</section>
+	<section id="cfg_rpc.rpc.set_delayed">
+    <title>cfg.set_delayed</title>
 	    <para>
 		<emphasis>cfg.set_delayed</emphasis> - Prepare the change of
 		a configuration variable, but does not commit the new value yet.
@@ -78,8 +139,9 @@
 		name, int/string value. The group name can optionally contain the
 		group instance id, for example foo[5].
 	    </para>
-	</listitem>
-	<listitem>
+	</section>
+	<section id="cfg_rpc.rpc.del_delayed">
+    <title>cfg.del_delayed</title>
 	    <para>
 		<emphasis>cfg.del_delayed</emphasis> - Prepare the deletion of the value of
 		a configuration variable from a group instance, but does not commit the change yet.
@@ -89,63 +151,53 @@
 		name. The group name must contain the
 		group instance id, for example foo[5].
 	    </para>
-	</listitem>
-	<listitem>
+	</section>
+	<section id="cfg_rpc.rpc.commit">
+    <title>cfg.commit</title>
 	    <para>
 		<emphasis>cfg.commit</emphasis> - Commit the previously
 		prepared configuration changes. The function does not have
 		any parameters.
 	    </para>
-	</listitem>
-	<listitem>
+	</section>
+	<section id="cfg_rpc.rpc.rollback">
+    <title>cfg.rollback</title>
 	    <para>
 		<emphasis>cfg.rollback</emphasis> - Drop the prepared
 		configuration changes. The function does not have any
 		parameters.
 	    </para>
-	</listitem>
-	<listitem>
-	    <para>
-		<emphasis>cfg.get</emphasis> - Get the value of
-		a configuration variable. The function accepts two parameters:
-		group name, variable name. The group name can optionally contain the
-		group instance id, for example foo[5].
-	    </para>
-	</listitem>
-	<listitem>
+	</section>
+	<section id="cfg_rpc.rpc.help">
+    <title>cfg.help</title>
 	    <para>
 		<emphasis>cfg.help</emphasis> - Print the description of
 		a configuration variable. The function accepts two parameters:
 		group name, variable name.
 	    </para>
-	</listitem>
-	<listitem>
-	    <para>
-		<emphasis>cfg.list</emphasis> - List the configuration
-		variables. The function has one optional parameter:
-		group name.
-	    </para>
-	</listitem>
-	<listitem>
+	</section>
+	<section id="cfg_rpc.rpc.diff">
+    <title>cfg.diff</title>
 	    <para>
 		<emphasis>cfg.diff</emphasis> - List the pending
 		configuration changes that have not been committed yet.
 		The function does not have any parameters.
 	    </para>
-	</listitem>
-	<listitem>
+	</section>
+	<section id="cfg_rpc.rpc.add_group_inst">
+    <title>cfg.add_group_inst</title>
 	    <para>
 		<emphasis>cfg.add_group_inst</emphasis> - Add a new instance
 		to an existing configuration group. The function accepts one parameter:
 		group name[instance id], for example foo[5].
 	    </para>
-	</listitem>
-	<listitem>
+	</section>
+	<section id="cfg_rpc.rpc.del_group_inst">
+    <title>cfg.del_group_inst</title>
 	    <para>
 		<emphasis>cfg.del_group_inst</emphasis> - Delete an instance
 		of an existing configuration group. The function accepts one parameter:
 		group name[instance id], for example foo[5].
 	    </para>
-	</listitem>
-    </itemizedlist>
+	</section>
 </section>