doc: rpc doc updated

- added rpc_register_array(rpc_export_array)
- added rpc_register(rcp_export)
- regenerated ser_rpc.txt

doc/rpc/ser_rpc.txt

@@ -108,9 +108,50 @@ typedef void (*rpc_function_t)(rpc_t* rpc);
    function with "_doc" suffix.
 
    Each module containing RPC functions has to export all the RPC
-   functions to SER core in order to make them visible to RPC transport
-   modules. For this purpose, the module_exports structure of SER module
-   API contains a new attribute called rpc_methods:
+   functions to SER core in order to make them visible to the RPC
+   transport modules. The export process involves a rpc_export_t structure
+   (either by itself or in an array):
+typedef struct rpc_export {
+    const char* name;        /* Name of the RPC function (null terminated) */
+    rpc_function_t function; /* Pointer to the function */
+    const char** doc_str;    /* Documentation strings, method signature and desc
+ription */
+    unsigned int flags;      /* Various flags, reserved for future use */
+} rpc_export_t;
+
+   The flags attribute of the rpc_export structure is reserved for future
+   use and is currently unused.
+
+   There are several ways of exporting the RPC functions to the SER core:
+     * register a null terminated array of rpc_export_t structures using
+       the rpc_register_array() function (defined in rpc_lookup.h), from
+       the module init function (mod_init()). This is the recommended
+       method for all the new modules.
+       Example 1.
+       The rpc_export_t array for the usrloc module looks like:
+rpc_export_t ul_rpc[] = {
+    {"usrloc.statistics",      rpc_stats,           rpc_stats_doc,          0},
+    {"usrloc.delete_aor",      rpc_delete_aor,      rpc_delete_aor_doc,     0},
+    {"usrloc.delete_contact",  rpc_delete_contact,  rpc_delete_contact_doc, 0},
+    {"usrloc.dump",            rpc_dump,            rpc_dump_doc,           0},
+    {"usrloc.flush",           rpc_flush,           rpc_flush_doc,          0},
+    {"usrloc.add_contact",     rpc_add_contact,     rpc_add_contact_doc,    0},
+    {"usrloc.show_contacts",   rpc_show_contacts,   rpc_show_contacts_doc,  0},
+    {0, 0, 0, 0}
+};
+
+       To register it from the module init function one would use
+       something similar to:
+        if (rpc_register_array(ul_rpc) != 0) {
+                ERR("failed to register RPC commands\n");
+                return -1;
+        }
+     * register RPCs one by one using the rpc_register_function() (defined
+       in rpc_lookup.h), from the module init function.
+     * register a null terminated array of rpc_export_t structures using
+       the SER module interface. For this purpose, the module_exports
+       structure of SER module API contains a new attribute called
+       rpc_methods:
 struct module_exports {
     char* name;                 /* null terminated module name */
     cmd_export_t* cmds;         /* null terminated array of the exported command
@@ -127,20 +168,13 @@ parameters */
     child_init_function init_child_f;  /* function called by all processes after
  the fork */
 };
-
-
-typedef struct rpc_export {
-    const char* name;        /* Name of the RPC function (null terminated) */
-    rpc_function_t function; /* Pointer to the function */
-    const char** doc_str;    /* Documentation strings, method signature and desc
-ription */
-    unsigned int flags;      /* Various flags, reserved for future use */
-} rpc_export_t;
-
-   rpc_methods is pointer to an array of rpc_export_t structures. The last
-   element of the array is a bumper containing zeroes in all attributes of
-   the structure. The following program listing shows exported RPC
-   functions of usrloc module:
+       rpc_methods is a pointer to an array of rpc_export_t structures.
+       The last element of the array is a bumper containing zeroes in all
+       the attributes of the structure. The following program listing
+       shows the exported RPC functions of the usrloc module, using the
+       rpc_export_t array ul_rpc defined above, in the
+       rpc_register_array() example:
+       Example 2.
 struct module_exports exports = {
     "usrloc",
     cmds,      /* Exported functions */
@@ -152,26 +186,17 @@ struct module_exports exports = {
     0,         /* OnCancel function */
     child_init /* Child initialization function */ };
 
-
-rpc_export_t ul_rpc[] = {
-    {"usrloc.statistics",      rpc_stats,           rpc_stats_doc,          0},
-    {"usrloc.delete_aor",      rpc_delete_aor,      rpc_delete_aor_doc,     0},
-    {"usrloc.delete_contact",  rpc_delete_contact,  rpc_delete_contact_doc, 0},
-    {"usrloc.dump",            rpc_dump,            rpc_dump_doc,           0},
-    {"usrloc.flush",           rpc_flush,           rpc_flush_doc,          0},
-    {"usrloc.add_contact",     rpc_add_contact,     rpc_add_contact_doc,    0},
-    {"usrloc.show_contacts",   rpc_show_contacts,   rpc_show_contacts_doc,  0},
-    {0, 0, 0, 0}
-};
+Note
+       This mode works only with modules using the SER module interface.
+       It does not work for kamailio modules and it will probably not work
+       for future sip-router modules. It is safer and recommended to use
+       instead the rpc_register_array() function.
 
    By convention the name of every exported function consists of two parts
    delimited by a dot. The first part is the name of the module or SER
    subsystem this function belongs to. The second part is the name of the
    function.
 
-   Attribute flags of rpc_export structure is reserved for future use and
-   is currently unused.
-
 1.2.2. Data Types
 
    The RPC API defines several basic and 1 compound data type that can be
@@ -287,7 +312,7 @@ rpc->struct_scan(handle, "sd", "str_attr", &str_val, "int_attr", &int_val);
    function). The function also indicates an error if a requested
    attribute is missing in the structure.
 
-   Example 1. Retrieving Parameters
+   Example 3. Retrieving Parameters
 static void rpc_delete_contact(rpc_t* rpc)
 {
     str aor, contact;
@@ -332,7 +357,7 @@ static void rpc_delete_contact(rpc_t* rpc)
    will be returned by the RPC transport module if you do not call any of
    the reply-related functions described in this section.
 
-   Example 2. Sending default reply
+   Example 4. Sending default reply
 static void rpc_dummy(rpc_t* rpc)
 {
   /* 200 OK with no data will be returned */
@@ -390,7 +415,7 @@ static void rpc_my_function(rpc_t* rpc)
    function needs to perform some (potentially destructive) actions after
    the reply has been sent.
 
-   Example 3. Kill the server
+   Example 5. Kill the server
 static void core_kill(rpc_t* rpc)
 {
     int sig_no;
@@ -475,7 +500,7 @@ static void rpc_func(rpc_t* rpc)
    The following example illustrates the use of most of the functions from
    the API together:
 
-   Example 4. Real World Example RPC Function
+   Example 6. Real World Example RPC Function
 static void rpc_register(rpc_t* rpc)
 {
     char* domain;

doc/rpc/ser_rpc.xml

@@ -126,11 +126,74 @@ typedef void (*rpc_function_t)(rpc_t* rpc);
 	    </para>
 	    <para>
 		Each module containing RPC functions has to export all the
-		RPC functions to SER core in order to make them visible to RPC
-		transport modules. For this purpose, the
-		<varname>module_exports</varname> structure of SER module API
-		contains a new attribute called <varname>rpc_methods</varname>:
+		RPC functions to SER core in order to make them visible to the RPC
+		transport modules.
+		The export process involves a <emphasis>rpc_export_t</emphasis> 
+		structure (either by itself or in an array):
 		<programlisting>
+<emphasis>
+typedef struct rpc_export {
+    const char* name;        /* Name of the RPC function (null terminated) */
+    rpc_function_t function; /* Pointer to the function */
+    const char** doc_str;    /* Documentation strings, method signature and description */
+    unsigned int flags;      /* Various flags, reserved for future use */
+} rpc_export_t;
+</emphasis>
+		</programlisting>
+		</para>
+		<para>
+		The <varname>flags</varname> attribute of the
+		<varname>rpc_export</varname> structure is reserved for future
+		use and is currently unused.
+	    </para>
+		<para>
+		There are several ways of exporting the RPC functions to the SER core:
+		<itemizedlist>
+			<listitem><para>
+				register a null terminated array of rpc_export_t structures
+				using the <function>rpc_register_array()</function> function
+				(defined in rpc_lookup.h), from the module init function
+				(mod_init()). This is the <emphasis>recommended</emphasis>
+				method for all the new modules.
+				<example>
+					The <varname>rpc_export_t</varname> array for the usrloc
+					module looks like:
+					<programlisting>
+<emphasis>
+rpc_export_t ul_rpc[] = {
+    {"usrloc.statistics",      rpc_stats,           rpc_stats_doc,          0},
+    {"usrloc.delete_aor",      rpc_delete_aor,      rpc_delete_aor_doc,     0},
+    {"usrloc.delete_contact",  rpc_delete_contact,  rpc_delete_contact_doc, 0},
+    {"usrloc.dump",            rpc_dump,            rpc_dump_doc,           0},
+    {"usrloc.flush",           rpc_flush,           rpc_flush_doc,          0},
+    {"usrloc.add_contact",     rpc_add_contact,     rpc_add_contact_doc,    0},
+    {"usrloc.show_contacts",   rpc_show_contacts,   rpc_show_contacts_doc,  0},
+    {0, 0, 0, 0}
+};
+</emphasis>
+					</programlisting>
+					To register it from the module init function one would use
+					something similar to:
+					<programlisting>
+	if (rpc_register_array(ul_rpc) != 0) {
+		ERR("failed to register RPC commands\n");
+		return -1;
+	}
+					</programlisting>
+				</example>
+			</para></listitem>
+			<listitem><para>
+				register RPCs one by one using the
+				<function>rpc_register_function()</function>
+				(defined in rpc_lookup.h), from the module init function.
+			</para></listitem>
+			<listitem><para>
+				register a null terminated array of rpc_export_t structures
+				using the SER module interface.
+				For this purpose, the
+				<varname>module_exports</varname> structure of SER module API
+				contains a new attribute called <varname>rpc_methods</varname>:
+				<programlisting>
 struct module_exports {
     char* name;                 /* null terminated module name */	
     cmd_export_t* cmds;         /* null terminated array of the exported commands */
@@ -143,22 +206,16 @@ struct module_exports {
     onbreak_function onbreak_f;
     child_init_function init_child_f;  /* function called by all processes after the fork */
 };
-
-<emphasis>
-typedef struct rpc_export {
-    const char* name;        /* Name of the RPC function (null terminated) */
-    rpc_function_t function; /* Pointer to the function */
-    const char** doc_str;    /* Documentation strings, method signature and description */
-    unsigned int flags;      /* Various flags, reserved for future use */
-} rpc_export_t;
-</emphasis>
-		</programlisting>
-		<varname>rpc_methods</varname> is pointer to an array of
-		rpc_export_t structures. The last element of the array is a
-		bumper containing zeroes in all attributes of the
-		structure. The following program listing shows exported RPC
-		functions of usrloc module:
-		<programlisting>
+				</programlisting>
+				<varname>rpc_methods</varname> is a pointer to an array of
+				rpc_export_t structures. The last element of the array is a
+				bumper containing zeroes in all the attributes of the
+				structure. The following program listing shows the exported RPC
+				functions of the usrloc module, using the rpc_export_t array
+				<emphasis>ul_rpc</emphasis> defined above, in the 
+				rpc_register_array() example:
+				<example>
+					<programlisting>
 struct module_exports exports = {
     "usrloc",
     cmds,      /* Exported functions */ 
@@ -170,29 +227,24 @@ struct module_exports exports = {
     0,         /* OnCancel function */ 
     child_init /* Child initialization function */ };
 
-<emphasis>
-rpc_export_t ul_rpc[] = {
-    {"usrloc.statistics",      rpc_stats,           rpc_stats_doc,          0},
-    {"usrloc.delete_aor",      rpc_delete_aor,      rpc_delete_aor_doc,     0},
-    {"usrloc.delete_contact",  rpc_delete_contact,  rpc_delete_contact_doc, 0},
-    {"usrloc.dump",            rpc_dump,            rpc_dump_doc,           0},
-    {"usrloc.flush",           rpc_flush,           rpc_flush_doc,          0},
-    {"usrloc.add_contact",     rpc_add_contact,     rpc_add_contact_doc,    0},
-    {"usrloc.show_contacts",   rpc_show_contacts,   rpc_show_contacts_doc,  0},
-    {0, 0, 0, 0}
-};
-</emphasis>
-		</programlisting>
-		By convention the name of every exported function consists of
-		two parts delimited by a dot. The first part is the name of the
-		module or SER subsystem this function belongs to. The second
-		part is the name of the function. 
-	    </para>
-	    <para>
-		Attribute <varname>flags</varname> of
-		<varname>rpc_export</varname> structure is reserved for future
-		use and is currently unused.
-	    </para>
+					</programlisting>
+				</example>
+				<note>
+					This mode works only with modules using the SER module
+					interface. It does not work for kamailio modules and it
+					will probably not work for future sip-router modules. It is
+					safer and recommended to use instead the
+					<function>rpc_register_array()</function> function.
+				</note>
+			</para></listitem>
+		</itemizedlist>
+		</para>
+		<para>
+			By convention the name of every exported function consists of
+			two parts delimited by a dot. The first part is the name of the
+			module or SER subsystem this function belongs to. The second
+			part is the name of the function.
+		</para>
 	</section>
 
 	<section id="rpc.data_types">