Browse code

doc: rpc doc updated

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

Andrei Pelinescu-Onciul authored on 13/05/2009 11:49:51
Showing 2 changed files
... ...
@@ -108,9 +108,50 @@ typedef void (*rpc_function_t)(rpc_t* rpc);
108 108
    function with "_doc" suffix.
109 109
 
110 110
    Each module containing RPC functions has to export all the RPC
111
-   functions to SER core in order to make them visible to RPC transport
112
-   modules. For this purpose, the module_exports structure of SER module
113
-   API contains a new attribute called rpc_methods:
111
+   functions to SER core in order to make them visible to the RPC
112
+   transport modules. The export process involves a rpc_export_t structure
113
+   (either by itself or in an array):
114
+typedef struct rpc_export {
115
+    const char* name;        /* Name of the RPC function (null terminated) */
116
+    rpc_function_t function; /* Pointer to the function */
117
+    const char** doc_str;    /* Documentation strings, method signature and desc
118
+ription */
119
+    unsigned int flags;      /* Various flags, reserved for future use */
120
+} rpc_export_t;
121
+
122
+   The flags attribute of the rpc_export structure is reserved for future
123
+   use and is currently unused.
124
+
125
+   There are several ways of exporting the RPC functions to the SER core:
126
+     * register a null terminated array of rpc_export_t structures using
127
+       the rpc_register_array() function (defined in rpc_lookup.h), from
128
+       the module init function (mod_init()). This is the recommended
129
+       method for all the new modules.
130
+       Example 1.
131
+       The rpc_export_t array for the usrloc module looks like:
132
+rpc_export_t ul_rpc[] = {
133
+    {"usrloc.statistics",      rpc_stats,           rpc_stats_doc,          0},
134
+    {"usrloc.delete_aor",      rpc_delete_aor,      rpc_delete_aor_doc,     0},
135
+    {"usrloc.delete_contact",  rpc_delete_contact,  rpc_delete_contact_doc, 0},
136
+    {"usrloc.dump",            rpc_dump,            rpc_dump_doc,           0},
137
+    {"usrloc.flush",           rpc_flush,           rpc_flush_doc,          0},
138
+    {"usrloc.add_contact",     rpc_add_contact,     rpc_add_contact_doc,    0},
139
+    {"usrloc.show_contacts",   rpc_show_contacts,   rpc_show_contacts_doc,  0},
140
+    {0, 0, 0, 0}
141
+};
142
+
143
+       To register it from the module init function one would use
144
+       something similar to:
145
+        if (rpc_register_array(ul_rpc) != 0) {
146
+                ERR("failed to register RPC commands\n");
147
+                return -1;
148
+        }
149
+     * register RPCs one by one using the rpc_register_function() (defined
150
+       in rpc_lookup.h), from the module init function.
151
+     * register a null terminated array of rpc_export_t structures using
152
+       the SER module interface. For this purpose, the module_exports
153
+       structure of SER module API contains a new attribute called
154
+       rpc_methods:
114 155
 struct module_exports {
115 156
     char* name;                 /* null terminated module name */
116 157
     cmd_export_t* cmds;         /* null terminated array of the exported command
... ...
@@ -127,20 +168,13 @@ parameters */
127 127
     child_init_function init_child_f;  /* function called by all processes after
128 128
  the fork */
129 129
 };
130
-
131
-
132
-typedef struct rpc_export {
133
-    const char* name;        /* Name of the RPC function (null terminated) */
134
-    rpc_function_t function; /* Pointer to the function */
135
-    const char** doc_str;    /* Documentation strings, method signature and desc
136
-ription */
137
-    unsigned int flags;      /* Various flags, reserved for future use */
138
-} rpc_export_t;
139
-
140
-   rpc_methods is pointer to an array of rpc_export_t structures. The last
141
-   element of the array is a bumper containing zeroes in all attributes of
142
-   the structure. The following program listing shows exported RPC
143
-   functions of usrloc module:
130
+       rpc_methods is a pointer to an array of rpc_export_t structures.
131
+       The last element of the array is a bumper containing zeroes in all
132
+       the attributes of the structure. The following program listing
133
+       shows the exported RPC functions of the usrloc module, using the
134
+       rpc_export_t array ul_rpc defined above, in the
135
+       rpc_register_array() example:
136
+       Example 2.
144 137
 struct module_exports exports = {
145 138
     "usrloc",
146 139
     cmds,      /* Exported functions */
... ...
@@ -152,26 +186,17 @@ struct module_exports exports = {
152 152
     0,         /* OnCancel function */
153 153
     child_init /* Child initialization function */ };
154 154
 
155
-
156
-rpc_export_t ul_rpc[] = {
157
-    {"usrloc.statistics",      rpc_stats,           rpc_stats_doc,          0},
158
-    {"usrloc.delete_aor",      rpc_delete_aor,      rpc_delete_aor_doc,     0},
159
-    {"usrloc.delete_contact",  rpc_delete_contact,  rpc_delete_contact_doc, 0},
160
-    {"usrloc.dump",            rpc_dump,            rpc_dump_doc,           0},
161
-    {"usrloc.flush",           rpc_flush,           rpc_flush_doc,          0},
162
-    {"usrloc.add_contact",     rpc_add_contact,     rpc_add_contact_doc,    0},
163
-    {"usrloc.show_contacts",   rpc_show_contacts,   rpc_show_contacts_doc,  0},
164
-    {0, 0, 0, 0}
165
-};
155
+Note
156
+       This mode works only with modules using the SER module interface.
157
+       It does not work for kamailio modules and it will probably not work
158
+       for future sip-router modules. It is safer and recommended to use
159
+       instead the rpc_register_array() function.
166 160
 
167 161
    By convention the name of every exported function consists of two parts
168 162
    delimited by a dot. The first part is the name of the module or SER
169 163
    subsystem this function belongs to. The second part is the name of the
170 164
    function.
171 165
 
172
-   Attribute flags of rpc_export structure is reserved for future use and
173
-   is currently unused.
174
-
175 166
 1.2.2. Data Types
176 167
 
177 168
    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);
287 287
    function). The function also indicates an error if a requested
288 288
    attribute is missing in the structure.
289 289
 
290
-   Example 1. Retrieving Parameters
290
+   Example 3. Retrieving Parameters
291 291
 static void rpc_delete_contact(rpc_t* rpc)
292 292
 {
293 293
     str aor, contact;
... ...
@@ -332,7 +357,7 @@ static void rpc_delete_contact(rpc_t* rpc)
332 332
    will be returned by the RPC transport module if you do not call any of
333 333
    the reply-related functions described in this section.
334 334
 
335
-   Example 2. Sending default reply
335
+   Example 4. Sending default reply
336 336
 static void rpc_dummy(rpc_t* rpc)
337 337
 {
338 338
   /* 200 OK with no data will be returned */
... ...
@@ -390,7 +415,7 @@ static void rpc_my_function(rpc_t* rpc)
390 390
    function needs to perform some (potentially destructive) actions after
391 391
    the reply has been sent.
392 392
 
393
-   Example 3. Kill the server
393
+   Example 5. Kill the server
394 394
 static void core_kill(rpc_t* rpc)
395 395
 {
396 396
     int sig_no;
... ...
@@ -475,7 +500,7 @@ static void rpc_func(rpc_t* rpc)
475 475
    The following example illustrates the use of most of the functions from
476 476
    the API together:
477 477
 
478
-   Example 4. Real World Example RPC Function
478
+   Example 6. Real World Example RPC Function
479 479
 static void rpc_register(rpc_t* rpc)
480 480
 {
481 481
     char* domain;
... ...
@@ -126,11 +126,74 @@ typedef void (*rpc_function_t)(rpc_t* rpc);
126 126
 	    </para>
127 127
 	    <para>
128 128
 		Each module containing RPC functions has to export all the
129
-		RPC functions to SER core in order to make them visible to RPC
130
-		transport modules. For this purpose, the
131
-		<varname>module_exports</varname> structure of SER module API
132
-		contains a new attribute called <varname>rpc_methods</varname>:
129
+		RPC functions to SER core in order to make them visible to the RPC
130
+		transport modules.
131
+		The export process involves a <emphasis>rpc_export_t</emphasis> 
132
+		structure (either by itself or in an array):
133 133
 		<programlisting>
134
+<emphasis>
135
+typedef struct rpc_export {
136
+    const char* name;        /* Name of the RPC function (null terminated) */
137
+    rpc_function_t function; /* Pointer to the function */
138
+    const char** doc_str;    /* Documentation strings, method signature and description */
139
+    unsigned int flags;      /* Various flags, reserved for future use */
140
+} rpc_export_t;
141
+</emphasis>
142
+		</programlisting>
143
+		</para>
144
+		<para>
145
+		The <varname>flags</varname> attribute of the
146
+		<varname>rpc_export</varname> structure is reserved for future
147
+		use and is currently unused.
148
+	    </para>
149
+		<para>
150
+		There are several ways of exporting the RPC functions to the SER core:
151
+		<itemizedlist>
152
+			<listitem><para>
153
+				register a null terminated array of rpc_export_t structures
154
+				using the <function>rpc_register_array()</function> function
155
+				(defined in rpc_lookup.h), from the module init function
156
+				(mod_init()). This is the <emphasis>recommended</emphasis>
157
+				method for all the new modules.
158
+				<example>
159
+					The <varname>rpc_export_t</varname> array for the usrloc
160
+					module looks like:
161
+					<programlisting>
162
+<emphasis>
163
+rpc_export_t ul_rpc[] = {
164
+    {"usrloc.statistics",      rpc_stats,           rpc_stats_doc,          0},
165
+    {"usrloc.delete_aor",      rpc_delete_aor,      rpc_delete_aor_doc,     0},
166
+    {"usrloc.delete_contact",  rpc_delete_contact,  rpc_delete_contact_doc, 0},
167
+    {"usrloc.dump",            rpc_dump,            rpc_dump_doc,           0},
168
+    {"usrloc.flush",           rpc_flush,           rpc_flush_doc,          0},
169
+    {"usrloc.add_contact",     rpc_add_contact,     rpc_add_contact_doc,    0},
170
+    {"usrloc.show_contacts",   rpc_show_contacts,   rpc_show_contacts_doc,  0},
171
+    {0, 0, 0, 0}
172
+};
173
+</emphasis>
174
+					</programlisting>
175
+					To register it from the module init function one would use
176
+					something similar to:
177
+					<programlisting>
178
+	if (rpc_register_array(ul_rpc) != 0) {
179
+		ERR("failed to register RPC commands\n");
180
+		return -1;
181
+	}
182
+					</programlisting>
183
+				</example>
184
+			</para></listitem>
185
+			<listitem><para>
186
+				register RPCs one by one using the
187
+				<function>rpc_register_function()</function>
188
+				(defined in rpc_lookup.h), from the module init function.
189
+			</para></listitem>
190
+			<listitem><para>
191
+				register a null terminated array of rpc_export_t structures
192
+				using the SER module interface.
193
+				For this purpose, the
194
+				<varname>module_exports</varname> structure of SER module API
195
+				contains a new attribute called <varname>rpc_methods</varname>:
196
+				<programlisting>
134 197
 struct module_exports {
135 198
     char* name;                 /* null terminated module name */	
136 199
     cmd_export_t* cmds;         /* null terminated array of the exported commands */
... ...
@@ -143,22 +206,16 @@ struct module_exports {
143 143
     onbreak_function onbreak_f;
144 144
     child_init_function init_child_f;  /* function called by all processes after the fork */
145 145
 };
146
-
147
-<emphasis>
148
-typedef struct rpc_export {
149
-    const char* name;        /* Name of the RPC function (null terminated) */
150
-    rpc_function_t function; /* Pointer to the function */
151
-    const char** doc_str;    /* Documentation strings, method signature and description */
152
-    unsigned int flags;      /* Various flags, reserved for future use */
153
-} rpc_export_t;
154
-</emphasis>
155
-		</programlisting>
156
-		<varname>rpc_methods</varname> is pointer to an array of
157
-		rpc_export_t structures. The last element of the array is a
158
-		bumper containing zeroes in all attributes of the
159
-		structure. The following program listing shows exported RPC
160
-		functions of usrloc module:
161
-		<programlisting>
146
+				</programlisting>
147
+				<varname>rpc_methods</varname> is a pointer to an array of
148
+				rpc_export_t structures. The last element of the array is a
149
+				bumper containing zeroes in all the attributes of the
150
+				structure. The following program listing shows the exported RPC
151
+				functions of the usrloc module, using the rpc_export_t array
152
+				<emphasis>ul_rpc</emphasis> defined above, in the 
153
+				rpc_register_array() example:
154
+				<example>
155
+					<programlisting>
162 156
 struct module_exports exports = {
163 157
     "usrloc",
164 158
     cmds,      /* Exported functions */ 
... ...
@@ -170,29 +227,24 @@ struct module_exports exports = {
170 170
     0,         /* OnCancel function */ 
171 171
     child_init /* Child initialization function */ };
172 172
 
173
-<emphasis>
174
-rpc_export_t ul_rpc[] = {
175
-    {"usrloc.statistics",      rpc_stats,           rpc_stats_doc,          0},
176
-    {"usrloc.delete_aor",      rpc_delete_aor,      rpc_delete_aor_doc,     0},
177
-    {"usrloc.delete_contact",  rpc_delete_contact,  rpc_delete_contact_doc, 0},
178
-    {"usrloc.dump",            rpc_dump,            rpc_dump_doc,           0},
179
-    {"usrloc.flush",           rpc_flush,           rpc_flush_doc,          0},
180
-    {"usrloc.add_contact",     rpc_add_contact,     rpc_add_contact_doc,    0},
181
-    {"usrloc.show_contacts",   rpc_show_contacts,   rpc_show_contacts_doc,  0},
182
-    {0, 0, 0, 0}
183
-};
184
-</emphasis>
185
-		</programlisting>
186
-		By convention the name of every exported function consists of
187
-		two parts delimited by a dot. The first part is the name of the
188
-		module or SER subsystem this function belongs to. The second
189
-		part is the name of the function. 
190
-	    </para>
191
-	    <para>
192
-		Attribute <varname>flags</varname> of
193
-		<varname>rpc_export</varname> structure is reserved for future
194
-		use and is currently unused.
195
-	    </para>
173
+					</programlisting>
174
+				</example>
175
+				<note>
176
+					This mode works only with modules using the SER module
177
+					interface. It does not work for kamailio modules and it
178
+					will probably not work for future sip-router modules. It is
179
+					safer and recommended to use instead the
180
+					<function>rpc_register_array()</function> function.
181
+				</note>
182
+			</para></listitem>
183
+		</itemizedlist>
184
+		</para>
185
+		<para>
186
+			By convention the name of every exported function consists of
187
+			two parts delimited by a dot. The first part is the name of the
188
+			module or SER subsystem this function belongs to. The second
189
+			part is the name of the function.
190
+		</para>
196 191
 	</section>
197 192
 
198 193
 	<section id="rpc.data_types">