- Spelling checked
[sip-router] / doc / serdev / modiface.sgml
1 <!-- $Id$ -->
2 <!DOCTYPE Book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
3 <!ENTITY ser "SIP Express Router">
4 <!ENTITY moddir "/usr/lib/ser/modules">
5 ]>
7 <book>
8     <chapter>
9         <title>Module Interface</title>
10         <abstract>
11             <para>
12                 &ser; features modular architecture which allows us to split &ser;'s functionality
13                 across several modules. This approach gives us greater flexibility, only required
14                 set of functions can be loaded upon startup which minimizes the server's memory
15                 footprint. Modules can be also provided by 3rd party developers and distributed
16                 separately from the main server. Most of the functionality that &ser; provides is
17                 available through modules, the core itself contains only minimum set of functions
18                 that is essential for proper server's behavior or that is needed by all modules.
19             </para>
20             <para>
21                 This chapter provides detailed information on module interface of &ser;, which is
22                 used to pass information on available functions and parameters from the modules to
23                 the core.
24             </para>
25         </abstract>
26         <section>
27             <title>Shared Objects</title>
28             <abstract>
29                 <para>
30                     First it would be good to know how &ser; loads and uses modules before we
31                     describe the module interface in detail. This section gives a brief overview of
32                     &ser;'s module subsystem.
33                 </para>
34             </abstract>
35             <para>
36                 &ser; modules are compiled as <quote>shared objects</quote>. A file containing a
37                 shared object has usually .so suffix. All modules (shared objects) will be stored in
38                 one directory after installation. For example <abbrev>tm</abbrev> module, which
39                 contains code essential for stateful processing, will be stored in file named
40                 <filename moreinfo="none">tm.so</filename>. By default these files are stored in
41                 <filename moreinfo="none">&moddir;</filename> directory.
42             </para>
43             <para>
44                 You can later load the modules using <command moreinfo="none">loadmodule</command>
45                 command in your configuration file. If you want to load previously mentioned
46                 <filename moreinfo="none">tm.so</filename> module, you can do it using <command
47                 moreinfo="none">loadmodule "&moddir;/tm.so"</command> in your configuration
48                 file. This command invokes dynamic linker provided by the operating system which
49                 opens <filename moreinfo="none">tm.so</filename> file, loads it into memory and
50                 resolves all symbol dependencies (a module might require symbols from the core, for
51                 example functions and variables).
52             </para>
53             <para>
54                 As the last step of the module loading the core tries to find variable named
55                 <varname>exports</varname>, which describes all functions and parameters provided by
56                 the module. These functions and parameters are later available to the server and can
57                 be used either in the configuration file or by other modules.
58             </para>
59         </section>
60         <section>
61             <title>Exporting Functions</title>
62             <abstract>
63                 <para>
64                     Each module can provide zero or more functions, which can be used in the
65                     configuration file or by other modules internally. This section gives a detailed
66                     description of structure describing exported functions and passing this
67                     information to the core through the module interface.
68                 </para>
69             </abstract>
70             <para>
71                 Each function exported by a module must be described by
72                 <structname>cmd_export_t</structname> structure. Structures describing all exported
73                 functions are arranged into an array and pointer to the array is then passed to the
74                 core. The last element of the array must contain 0 in all it's fields, this element
75                 serves as the mark telling the core that this is the very last element and it must
76                 stop scanning the array.
77             </para>
78             <para>
79                 Each exported function is described by the following structure:
80             </para>
81             <programlisting format="linespecific">
82 struct cmd_export_ {
83         char* name;             /* null terminated command name */
84         cmd_function function;  /* pointer to the corresponding function */
85         int param_no;           /* number of parameters used by the function */
86         fixup_function fixup;   /* pointer to the function called to "fix" the parameters */
87         int flags;              /* Function flags */
88 };         
90 typedef struct cmd_export_ cmd_export_t;
91 </programlisting>
92             <itemizedlist>
93                 <title>Meaning of the fileds:</title>
94                 <listitem>
95                     <simpara><varname>char* name</varname><simpara> 
96                     <simpara>
97                         This is the name under which the function will be visible to the
98                         core. Usually it is the same as the name of the corresponding function.
99                     </simpara>
100                 </listitem>
101                 <listitem>
102                     <simpara><varname>cmd_function function</varname></simpara> 
103                     <para>cmd_function type is defined as follows: </para>
104                     <programlisting format="linespecific">
105 typedef int (*cmd_function)(struct sip_msg*, char*, char*); 
106 </programlisting>
107                     <simpara>
108                         The first parameter is a <acronym>SIP</acronym> message being processed, the
109                         other 2 parameters are given from the configuration file.
110                     </simpara>
111                     <note>
112                         <simpara>
113                             From time to time you might need to export a function that has different
114                             synopsis. This can happen if you export functions that are supposed to
115                             be called by other modules only and must not be called from the
116                             configuration script. In this case you will have to do type-casting
117                             otherwise the compiler will complain and will not compile your module.
118                         </simpara>
119                         <simpara>
120                             Simply put (cmd_function) just before the function name, for example
121                             <function moreinfo="none">(cmd_function)my_function</function>.  Don't
122                             use this unless you know what are you doing ! The server might crash if
123                             you pass wrong parameters to the function later !
124                         </simpara>
125                     </note>
126                 </listitem>
127                 <listitem>
128                     <simpara><varname>int param_no</varname></simpara>
129                     <simpara>
130                         Number of parameters of the function. It can be 0, 1 or 2. The function will
131                         be not visible from the configuration script if you use another value.
132                     </simpara>
133                 </listitem>
134                 <listitem>
135                     <simpara><varname>fixup_function fixup</varname></simpara>
136                     <simpara>
137                         This is the function that will be used to <quote>fixup</quote> function
138                         parameters. Set this field to 0 if you don't need this.
139                     </simpara>
140                     <simpara>
141                         If you provide pointer to a fixup function in this field, the fixup function
142                         will be called for each occurrence of the exported function in the
143                         configuration script.
144                     </simpara>
145                     <simpara>
146                         The fixup function can be used to perform some operation on the function
147                         parameters. For example, if one of the parameters is a regular expression,
148                         you can use the fixup to compile the regular expression. The fixup functions
149                         are called only once - upon the server startup and so the regular expression
150                         will be compiled before the server starts processing messages. When the
151                         server calls the exported function to process a <acronym>SIP</acronym>
152                         message, the function will be given the already compiled regular expression
153                         and doesn't have to compile it again. This is a significant performance
154                         improvement.
155                     </simpara>
156                     <simpara>
157                         Fixup functions can also be used to convert string to integer. As you have
158                         might noticed, the exported functions accept up to 2 parameters of type
159                         char*. Because of that it is not possible to pass integer parameters from
160                         the script files directly. If you want to pass an integer as a parameter,
161                         you must pass it as string (i.e. enclosed in quotes).
162                     </simpara>
163                     <simpara>
164                         Fixup function can be used to convert the string back to integer. Such a
165                         conversion should happend only once because the string parameter doesn't
166                         change when the server is running. Fixup is therefore ideal place for the
167                         conversion, it will be converted upon the server startup before the server
168                         starts processing <acronym>SIP</acronym> messages. After the conversion the
169                         function will get directly the converted value. See existing modules for
170                         example of such a fixup function.
171                     </simpara>
172                 </listitem>
173                 <listitem>
174                     <simpara><varname>int flags</varname></simpara>
175                     <simpara>
176                         Usage of each function can be restricted. You may want to write a function
177                         that can be used by other modules but cannot be called from the script. If
178                         you write a function that is supposed to process <acronym>SIP</acronym>
179                         requests only, you may want to restrict it so it will be never called for
180                         <acronym>SIP</acronym> replies and vice versa. That's what is flags field
181                         for.
182                     </simpara>
183                     <simpara>
184                         This field is OR value of different flags. Currently only REQUEST_ROUTE and
185                         REPLY_ROUTE flags are defined and used by the core. If you use REQUEST_ROUTE
186                         flag, then the function can be called from the main route block. If you use
187                         REPLY_ROUTE flag, then the function can be called from reply route blocks
188                         (More on this in the SER User's Guide). If this field is set to 0, then the
189                         function can be called internally (i.e. from other modules) only. If you
190                         want to make your function callable anywhere in the script, you can use
191                         REQUEST_ROUTE | REPLY_ROUTE.
192                     </simpara>
193                 </listitem>
194             </itemizedlist>
195         </section>
196         <section>
197             <title>Exporting Parameters</title>
198             <abstract>
199                 <simpara>
200                     Each module can provide zero or more parameters, which can affect the module's
201                     behavior. This section gives a detailed description of structures describing
202                     exported parameters and passing this information to the core through the module
203                     interface.
204                 </simpara>
205             </abstract>
206             <simpara>
207                 Each parameter exported by a module must be described by
208                 <structname>param_export_t</structname> structure. Structures describing all
209                 exported parameters are arranged into an array and pointer to the array is then
210                 passed to the core. The last element of the array must contain 0 in all it's fields,
211                 this element serves as the mark telling the core that this is the very last element
212                 and it must stop scanning the array (This is same as in array of exported
213                 functions).
214             </simpara>
215             <simpara>
216                 Each exported parameter is described by the following structure:
217             </simpara>
218             <programlisting format="linespecific">
220 struct param_export_ {
221         char* name;             /* null terminated param. name */
222         modparam_t type;        /* param. type */
223         void* param_pointer;    /* pointer to the param. memory location */
224 };
226 typedef struct param_export_ param_export_t;
227 </programlisting>
228             <itemizedlist>
229                 <title>Meaning of the fields:</title>
230                 <listitem>
231                     <simpara><varname>char* name</varname></simpara>
232                     <simpara>
233                         This is null-terminated name of the parameters as it will be used in the
234                         scripts. Usually this is the same as the name of the variable holding the
235                         value.
236                     </simpara>
237                 </listitem>
238                 <listitem>
239                     <simpara><varname>modparam_t type</varname></simpara>
240                     <simpara>
241                         Type of the parameter. Currently only two types are defined. INT_PARAM for
242                         integer parameters (corresponding variable must be of type int) and
243                         STR_PARAM for string parameters (corresponding variable must be of type
244                         char*).
245                     </simpara>
246                 </listitem>
247                 <listitem>
248                     <simpara><varname>void* param_pointer</varname></simpara>
249                     <simpara>
250                         Pointer to the corresponding variable (stored as void* pointer, make sure
251                         that the variable has appropriate type depending on the type of the
252                         parameter !).
253                     </simpara>
254                 </listitem>
255             </itemizedlist>
256         </section>
257         <section>
258             <title>Module Initialization</title>
259             <simpara>
260                 If you need to initialize your module before the server starts processing
261                 <acronym>SIP</acronym> messages, you should provide initialization function. Each
262                 module can provide two initialization functions, main initialization function and
263                 child-specific initialization function.  Fields holding pointers to both
264                 initialization functions are in main export structure (will be described
265                 later). Simply pass 0 instead of function pointer if you don't need one or both
266                 initialization functions.
267             </simpara>
268             <simpara>
269                 The main initialization function will be called before any other function exported
270                 by the module. The function will be called only once, before the main process
271                 forks. This function is good for initialization that is common for all the children
272                 (processes). The function should return 0 if everything went OK and a negative error
273                 code otherwise. Server will abort if the function returns a negative value.
274             </simpara>
275             <simpara>
276                 Per-child initialization function will be called <emphasis>after</emphasis> the main
277                 process forks. The function will be called for each child separately. The function
278                 should perform initialization that is specific for each child. For example each
279                 child process might open it's own database connection to avoid locking of a single
280                 connection shared by many processes. Such connections can be opened in the per-child
281                 initialization function. The function accepts one parameter which is rank (integer)
282                 of child for which the function is being executed. This allows developers to
283                 distinguish different children and perform different initialization for each
284                 child. The meaning of return value is same as in the main initialization function.
285             </simpara>
286         </section>
287         <section>
288             <title>Module Clean-up</title>
289             <simpara>
290                 A module can also export a clean-up function that will be called by the main process
291                 when the server shuts down. The function accepts no parameters and return no value.
292             </simpara>
293         </section>
294         <section>
295             <title>Module Callbacks</title>
296             <para>
297                 TBD.
298             </para>
299         </section>
300         <section>
301             <title><structname>exports</structname> Structure - Assembling the Pieces Together</title>
302             <simpara>
303                 We have already described how a module can export functions and parameters, but we
304                 haven't yet described how to pass this information to the core. Each module must
305                 have variable named <varname>exports</varname> which is structure
306                 module_exports. The variable will be looked up by the core immediately after it
307                 loads the module. The structure contains pointers to both arrays (functions,
308                 parameters), pointers to both initialization functions, destroy function and the
309                 callbacks. So the structure contains everything the core will need.
310             </simpara>
311             <simpara>The structure looks like the follows:</simpara>
312             <programlisting format="linespecific">
313 struct module_exports{
314     char* name;                     /* null terminated module name */
315     cmd_export_t* cmds;             /* null terminated array of the exported commands */
316     param_export_t* params;         /* null terminated array of the exported module parameters */
317     init_function init_f;           /* Initialization function */
318     response_function response_f;   /* function used for responses, returns yes or no; can be null */
319     destroy_function destroy_f;     /* function called when the module should be "destroyed", e.g: on ser exit; can be null */
320     onbreak_function onbreak_f;
321     child_init_function init_child_f;  /* function called by all processes after the fork */
322 };
323 </programlisting>
324             <itemizedlist>
325                 <title>Field description:</title>
326                 <listitem>
327                     <simpara><varname>char* name</varname></simpara>
328                     <simpara>Null terminated name of the module</simpara>
329                 </listitem>
330                 <listitem>
331                     <simpara><varname>cmd_exports* cmds</varname></simpara>
332                     <simpara>
333                         Pointer to the array of exported functions
334                     </simpara>
335                 </listitem>
336                 <listitem>
337                     <simpara><varname>param_export_t* params</varname></simpara>
338                     <simpara>
339                         Pointer to the array of exported parameters
340                     </simpara>
341                 </listitem>
342                 <listitem>
343                     <simpara><varname>init_function init_f</varname></simpara>
344                     <simpara>Pointer to the module initialization function</simpara>
345                 </listitem>
346                 <listitem>
347                     <simpara><varname>response_function response_f</varname></simpara>
348                     <simpara>Pointer to function processing responses</simpara>
349                 </listitem>
350                 <listitem>
351                     <simpara><varname>destroy_function destroy_f</varname></simpara>
352                     <simpara>Pointer to the module clean-up function</simpara>
353                 </listitem>
354                 <listitem>
355                     <simpara><varname>onbreak_function onbreak_f</varname></simpara>
356                     <simpara>TBD</simpara>
357                 </listitem>
358                 <listitem>
359                     <simpara><varname>child_init_function init_child_f</varname></simpara>
360                     <simpara>Pointer to the per-child initialization function</simpara>
361                 </listitem>
362             </itemizedlist>
363         </section>
364         <section>
365             <title>Example - Simple Module Interface</title>
366             <para>
367                 Let's suppose that we are going to write a simple module. The module will export two functions - 
368                 <function moreinfo="none">foo_req</function> which will be processing <acronym>SIP</acronym> requests and 
369                 <function moreinfo="none">foo_int</function> which is an internal function that can be called by other modules only.
370                 Both functions will take 2 parameters.
371             </para>
372             <programlisting format="linespecific">
373 /* Prototypes */
374 int foo_req(struct sip_msg* msg, char* param1, char* param2);
375 int foo_res(struct sip_msg* msg, char* param1, char* param2);
377 static cmd_export cmds[] = {
378     {"foo_req", foo_req, 2, 0, ROUTE_REQUEST},
379     {"foo_int", foo_int, 2, 0, 0            },
380     {0, 0, 0, 0}
381 };
382 </programlisting>
383             <para>
384                 The module will also have two parameters, foo_bar of type integer and bar_foo of type string.
385             </para>
386             <programlisting format="linespecific">
387 int foo_bar = 0;
388 char* bar_foo = "default value";
390 static param_export params[] = {
391     {"foo_bar", INT_PARAM, &amp;foo_bar},
392     {"bar_foo", STR_PARAM, bar_foo     },
393     {0, 0, 0}
394 }; 
395 </programlisting>
396             <para>
397                 We will also create both initialization functions and a clean-up function:
398             </para>
399             <programlisting format="linespecific">
400 static int mod_init(void)
401 {
402     printf("foo module initializing\n");
403 }
405 static int child_init(int rank)
406 {
407     printf("child nr. %d initializing\n", rank);
408     return 0;
409 }
411 static void destroy(void)
412 {
413     printf("foo module cleaning up\n");
414 }
415 </programlisting>
416             <para>
417                 And finally we put everything into the exports structure:
418             </para>
419             <programlisting format="linespecific">
420 struct module_exports exports = {
421     "foobar",   /* Module name */
422     cmds,       /* Exported functions */
423     params,     /* Exported parameters */
424     mod_init,   /* Module initialization function */
425     0,          /* Response function */
426     destroy,    /* Clean-up function */
427     0,          /* On Cancel function */
428     child_init  /* Per-child init function */
429 };
430 </programlisting>
431             <simpara>And that's it.</simpara>
432         </section>
433     </chapter>
434 </book>