Browse code

core: many extensions and fixes at doxygen docs for module infrastructure

Henning Westerholt authored on 01/08/2011 22:29:42
Showing 2 changed files
... ...
@@ -22,6 +22,7 @@
22 22
  * along with this program; if not, write to the Free Software
23 23
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
24 24
  */
25
+
25 26
 /*
26 27
  * History:
27 28
  * --------
... ...
@@ -40,11 +41,14 @@
40 41
  *  2008-11-26  added fparam_free_contents() and fix_param_types (andrei)
41 42
  */
42 43
 
43
-/** module loading, standard fixups.
44
- * @file sr_module.c
44
+/**
45
+ * @file
46
+ * @brief SIP-Router core :: modules loading, structures declarations and utilities
45 47
  * @ingroup core
48
+ * Module: \ref core
46 49
  */
47 50
 
51
+
48 52
 #include "sr_module.h"
49 53
 #include "mod_fix.h"
50 54
 #include "dprint.h"
... ...
@@ -701,6 +705,14 @@ struct sr_module* find_module_by_name(char* mod) {
701 705
 }
702 706
 
703 707
 
708
+/*!
709
+ * \brief Find a parameter with given type
710
+ * \param mod module
711
+ * \param name parameter name
712
+ * \param type_mask parameter mask
713
+ * \param param_type parameter type
714
+ * \return parameter address in memory, if there is no such parameter, NULL is returned
715
+ */
704 716
 void* find_param_export(struct sr_module* mod, char* name,
705 717
 						modparam_t type_mask, modparam_t *param_type)
706 718
 {
... ...
@@ -1233,10 +1245,13 @@ void fparam_free_contents(fparam_t* fp)
1233 1245
 }
1234 1246
 
1235 1247
 
1236
-
1237
-/** generic free fixup type function for a fixed fparam.
1238
- * It will free whatever was allocated during the initial fparam fixup
1239
- * and restore the original param value.
1248
+/**
1249
+ * @brief Generic free fixup type function for a fixed fparam
1250
+ * 
1251
+ * Generic free fixup type function for a fixed fparam. It will free whatever
1252
+ * was allocated during the initial fparam fixup and restore the original param
1253
+ * value.
1254
+ * @param param freed parameters
1240 1255
  */
1241 1256
 void fparam_free_restore(void** param)
1242 1257
 {
... ...
@@ -1725,12 +1740,14 @@ int is_fparam_rve_fixup(fixup_function f)
1725 1740
 }
1726 1741
 
1727 1742
 
1728
-
1729
-/** returns the corresponding fixup_free* for various known fixup types.
1743
+/**
1744
+ * @brief returns the corresponding fixup_free* for various known fixup types
1745
+ * 
1746
+ * Returns the corresponding fixup_free* for various known fixup types.
1730 1747
  * Used to automatically fill in free_fixup* functions.
1731
- * @param f - fixup function pointer
1732
- * @return - free fixup function pointer on success, 0 on failure (unknown
1733
- *           fixup or no free fixup function).
1748
+ * @param f fixup function pointer
1749
+ * @return free fixup function pointer on success, 0 on failure (unknown
1750
+ * fixup or no free fixup function).
1734 1751
  */
1735 1752
 free_fixup_function get_fixup_free(fixup_function f)
1736 1753
 {
... ...
@@ -1,8 +1,4 @@
1
-/* $Id$
2
- *
3
- * modules/plug-in structures declarations
4
- *
5
- *
1
+/*
6 2
  * Copyright (C) 2001-2003 FhG Fokus
7 3
  *
8 4
  * This file is part of ser, a free SIP server.
... ...
@@ -26,6 +22,7 @@
26 22
  * along with this program; if not, write to the Free Software
27 23
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
28 24
  */
25
+
29 26
 /*
30 27
  * History:
31 28
  * --------
... ...
@@ -49,8 +46,11 @@
49 46
  *  2008-11-26  added fparam_free_contents() and fix_param_types (andrei)
50 47
  */
51 48
 
52
-/** modules structures/exports declarations and utilities (fixups a.s.o).
53
- * @file sr_module.h
49
+/**
50
+ * @file
51
+ * @brief SIP-Router core :: modules loading, structures declarations and utilities
52
+ * @ingroup core
53
+ * Module: \ref core
54 54
  */
55 55
 
56 56
 
... ...
@@ -92,44 +92,70 @@
92 92
 
93 93
 #endif
94 94
 
95
-/** type used for the mod_register function export.
96
- *  mod_register is a function called when loading a module
97
- *  (if present), prior to registering the module exports.
98
- *  @param path - path to the module, including file name
99
- *  @param dlflags - pointer to the dlflags used when loading the module.
100
- *                   If the value is changed to a different and non-zero
101
- *                   value, the module will be reloaded with the new flags.
102
- *  @param reserved1 - reserved for future use.
103
- *  @param reserved2 - reserver for future use
104
- *  @return 0 on success, -1 on error, all the other values are reserved
95
+/**
96
+ * @brief type used for the mod_register function export
97
+ * 
98
+ * mod_register is a function called when loading a module
99
+ * (if present), prior to registering the module exports.
100
+ * @param path path to the module, including file name
101
+ * @param dlflags pointer to the dlflags used when loading the module.
102
+ * If the value is changed to a different and non-zero value, the
103
+ * module will be reloaded with the new flags.
104
+ * @param reserved1 - reserved for future use.
105
+ * @param reserved2 - reserved for future use
106
+ * @return 0 on success, -1 on error, all the other values are reserved
105 107
  *                      for future use (<0 meaning error and >0 success)
106 108
  */
107
-typedef  int (*mod_register_function)(char*, int*, void*, void*);
109
+typedef  int (*mod_register_function)(char* path, int* dlflags, void* reserved1, void* reserved2);
108 110
 
109 111
 typedef  struct module_exports* (*module_register)(void);
110
-typedef  int (*cmd_function)(struct sip_msg*, char*, char*);
112
+
113
+/**
114
+ * @brief main two parameter module function
115
+ * 
116
+ * Main two parameter module function, default and oldest version.
117
+ * @param sip_msg SIP message
118
+ * @param param1 first parameter
119
+ * @param param2 second parameter
120
+ * @return positive on success, negative on error, 0 to stop processing (drop message)
121
+ */
122
+typedef  int (*cmd_function)(struct sip_msg*, char* param1, char* param2);
111 123
 typedef  int (*cmd_function3)(struct sip_msg*, char*, char*, char*);
112 124
 typedef  int (*cmd_function4)(struct sip_msg*, char*, char*, char*, char*);
113 125
 typedef  int (*cmd_function5)(struct sip_msg*,  char*, char*, char*,
114 126
 												char*, char*);
115 127
 typedef  int (*cmd_function6)(struct sip_msg*,  char*, char*, char*,
116 128
 												char*, char*, char*);
117
-/* variable number of param module function, takes as param the sip_msg,
118
-   extra paremeters number and a pointer to an array of parameters */
119
-typedef  int (*cmd_function_var)(struct sip_msg*, int no, action_u_t* vals );
120
-typedef  int (*fixup_function)(void** param, int param_no);
121
-typedef  int (*free_fixup_function)(void** param, int param_no);
122
-typedef  int (*response_function)(struct sip_msg*);
123
-typedef  void (*onbreak_function)(struct sip_msg*);
129
+/**
130
+ * @brief variable number of parameter module function
131
+ * 
132
+ * Variable number of parameter module function, takes as param the sip_msg,
133
+ * extra parameters number and a pointer to an array of parameters
134
+ * @param sip_msg SIP message
135
+ * @param no extra parameters number
136
+ * @param vals extra parameters
137
+ * @return positive on success, negative on error, 0 to stop processing (drop message)
138
+ */
139
+typedef int (*cmd_function_var)(struct sip_msg*, int no, action_u_t* vals );
140
+typedef int (*fixup_function)(void** param, int param_no);
141
+typedef int (*free_fixup_function)(void** param, int param_no);
142
+
143
+/**
144
+ * @brief response module function prototype
145
+ * @param sip_msg SIP message
146
+ * @return positive if ok, 0 to stop processing
147
+ */
148
+typedef int (*response_function)(struct sip_msg*);
149
+typedef void (*onbreak_function)(struct sip_msg*);
124 150
 typedef void (*destroy_function)(void);
125 151
 
126 152
 typedef int (*init_function)(void);
127 153
 typedef int (*child_init_function)(int rank);
128 154
 
129 155
 
130
-#define PARAM_STRING     (1U<<0)  /* String (char *) parameter type */
131
-#define PARAM_INT        (1U<<1)  /* Integer parameter type */
132
-#define PARAM_STR        (1U<<2)  /* struct str parameter type */
156
+#define PARAM_STRING     (1U<<0)  /**< String (char *) parameter type */
157
+#define PARAM_INT        (1U<<1)  /**< Integer parameter type */
158
+#define PARAM_STR        (1U<<2)  /**< struct str parameter type */
133 159
 #define PARAM_USE_FUNC   (1U<<(8*sizeof(int)-1))
134 160
 #define PARAM_TYPE_MASK(_x)   ((_x)&(~PARAM_USE_FUNC))
135 161
 
... ...
@@ -144,43 +170,44 @@ typedef int (*param_func_t)( modparam_t type, void* val);
144 170
 
145 171
 /* magic parameter number values */
146 172
 
147
-#define NO_SCRIPT     -1    /* export not usable from scripts */
148
-#define VAR_PARAM_NO  -128  /* function has variable number of parameters
173
+#define NO_SCRIPT     -1    /**< export not usable from scripts */
174
+#define VAR_PARAM_NO  -128  /**< function has variable number of parameters
149 175
 							   (see cmd_function_var for the prototype) */
150 176
 
151
-/* special fixup function flags.
152
- * They are kept in the first 2 bits inside the pointer
177
+/**
178
+ * special fixup function flags fparam fixup, rve ready,
179
+ * they are kept in the first 2 bits inside the pointer
153 180
  */
154
-#define FIXUP_F_FPARAM_RVE (unsigned long)1 /* fparam fixup, rve ready */
181
+#define FIXUP_F_FPARAM_RVE (unsigned long)1
155 182
 
156 183
 #define call_fixup(fixup, param, param_no) \
157 184
 	((fixup) ? (fixup)(param, param_no) : 0)
158 185
 
159 186
 /* Macros - used as rank in child_init function */
160
-#define PROC_MAIN      0  /* Main ser process */
161
-#define PROC_TIMER    -1  /* Timer attendant process */
162
-#define PROC_RPC      -2  /* RPC type process */
163
-#define PROC_FIFO      PROC_RPC  /* FIFO attendant process */
164
-#define PROC_TCP_MAIN -4  /* TCP main process */
165
-#define PROC_UNIXSOCK -5  /* Unix socket server */
166
-#define PROC_ATTENDANT -10  /* main "attendant process */
167
-#define PROC_INIT     -127 /* special rank, the context is the main ser
187
+#define PROC_MAIN      0  /**< Main ser process */
188
+#define PROC_TIMER    -1  /**< Timer attendant process */
189
+#define PROC_RPC      -2  /**< RPC type process */
190
+#define PROC_FIFO      PROC_RPC  /**< FIFO attendant process */
191
+#define PROC_TCP_MAIN -4  /**< TCP main process */
192
+#define PROC_UNIXSOCK -5  /**< Unix socket server */
193
+#define PROC_ATTENDANT -10  /**< main "attendant process */
194
+#define PROC_INIT     -127 /**< special rank, the context is the main ser
168 195
 							  process, but this is guaranteed to be executed
169 196
 							  before any process is forked, so it can be used
170 197
 							  to setup shared variables that depend on some
171 198
 							  after mod_init available information (e.g.
172 199
 							  total number of processes).
173
-							 WARNING: child_init(PROC_MAIN) is again called
200
+							  @warning child_init(PROC_MAIN) is again called
174 201
 							 in the same process (main), but latter 
175 202
 							 (before tcp), so make sure you don't init things 
176 203
 							 twice, bot in PROC_MAIN and PROC_INT */
177
-#define PROC_NOCHLDINIT -128 /* no child init functions will be called
204
+#define PROC_NOCHLDINIT -128 /**< no child init functions will be called
178 205
                                 if this rank is used in fork_process() */
179 206
 
180
-#define PROC_MIN PROC_NOCHLDINIT /* Minimum process rank */
207
+#define PROC_MIN PROC_NOCHLDINIT /**< Minimum process rank */
181 208
 
182 209
 
183
-#define DEFAULT_DLFLAGS	0 /* value that signals to module loader to
210
+#define DEFAULT_DLFLAGS	0 /**< value that signals to module loader to
184 211
 							use default dlopen flags in Kamailio */
185 212
 #ifndef RTLD_NOW
186 213
 /* for openbsd */
... ...
@@ -195,45 +222,45 @@ typedef int (*param_func_t)( modparam_t type, void* val);
195 222
 	char *module_flags=SER_COMPILE_FLAGS; \
196 223
 	unsigned int module_interface_ver=MODULE_INTERFACE_VER; 
197 224
 
198
-/* ser version */
225
+/** ser version */
199 226
 struct ser_cmd_export_ {
200
-	char* name;             /* null terminated command name */
201
-	cmd_function function;  /* pointer to the corresponding function */
202
-	int param_no;           /* number of parameters used by the function */
203
-	fixup_function fixup;   /* pointer to the function called to "fix" the
227
+	char* name;             /**< null terminated command name */
228
+	cmd_function function;  /**< pointer to the corresponding function */
229
+	int param_no;           /**< number of parameters used by the function */
230
+	fixup_function fixup;   /**< pointer to the function called to "fix" the
204 231
 							   parameters */
205
-	int flags;              /* Function flags */
232
+	int flags;              /**< Function flags */
206 233
 };
207 234
 
208 235
 
209
-/* kamailo/openser version */
236
+/** kamailo/openser version */
210 237
 struct kam_cmd_export_ {
211
-	char* name;             /* null terminated command name */
212
-	cmd_function function;  /* pointer to the corresponding function */
213
-	int param_no;           /* number of parameters used by the function */
214
-	fixup_function fixup;   /* pointer to the function called to "fix" the
238
+	char* name;             /**< null terminated command name */
239
+	cmd_function function;  /**< pointer to the corresponding function */
240
+	int param_no;           /**< number of parameters used by the function */
241
+	fixup_function fixup;   /**< pointer to the function called to "fix" the
215 242
 							   parameters */
216
-	free_fixup_function free_fixup; /* function called to free the "fixed"
243
+	free_fixup_function free_fixup; /**< function called to free the "fixed"
217 244
 									   parameters */
218
-	int flags;              /* Function flags */
245
+	int flags;              /**< Function flags */
219 246
 };
220 247
 
221
-
248
+/** sip-router version */
222 249
 struct sr31_cmd_export_ {
223
-	char* name;             /* null terminated command name */
224
-	cmd_function function;  /* pointer to the corresponding function */
225
-	int param_no;           /* number of parameters used by the function */
226
-	fixup_function fixup;   /* pointer to the function called to "fix" the
250
+	char* name;             /**< null terminated command name */
251
+	cmd_function function;  /**< pointer to the corresponding function */
252
+	int param_no;           /**< number of parameters used by the function */
253
+	fixup_function fixup;   /**< pointer to the function called to "fix" the
227 254
 							   parameters */
228
-	free_fixup_function free_fixup; /* function called to free the "fixed"
255
+	free_fixup_function free_fixup; /**< function called to free the "fixed"
229 256
 									   parameters */
230
-	int flags;              /* Function flags */
257
+	int flags;              /**< Function flags */
231 258
 	int fixup_flags;
232
-	void* module_exports; /* pointer to module structure */
259
+	void* module_exports; /**< pointer to module structure */
233 260
 };
234 261
 
235 262
 
236
-/* members situated at the same place in memory in both ser & kamailio
263
+/** members situated at the same place in memory in both ser & kamailio
237 264
    cmd_export */
238 265
 struct cmd_export_common_ {
239 266
 	char* name;
... ...
@@ -244,21 +271,20 @@ struct cmd_export_common_ {
244 271
 
245 272
 
246 273
 struct param_export_ {
247
-	char* name;             /* null terminated param. name */
248
-	modparam_t type;        /* param. type */
249
-	void* param_pointer;    /* pointer to the param. memory location */
274
+	char* name;             /**< null terminated param. name */
275
+	modparam_t type;        /**< param. type */
276
+	void* param_pointer;    /**< pointer to the param. memory location */
250 277
 };
251 278
 
252 279
 
253
-
254
-/** allowed parameter types.
255
-  * the types _must_ be in "fallback" order,
256
-  * e.g. FPARAM_STR should be the last to allow fallback to it,
257
-  *  F_PARAM_PVS should be in front of F_PARAM_AVP (so that
258
-  *  for fix_param_types(FPARAM_AVP|FPARAM_PVS|FPARAM_STR, param) and $foo
259
-  *  the pvars will be checked first and only if no pvar is found the
260
-  *  param will be resolved to an avp)
261
-  */
280
+/*
281
+ * Allowed parameter types, the types _must_ be in "fallback" order,
282
+ * e.g. FPARAM_STR should be the last to allow fallback to it,
283
+ * F_PARAM_PVS should be in front of F_PARAM_AVP (so that
284
+ * for fix_param_types(FPARAM_AVP|FPARAM_PVS|FPARAM_STR, param) and $foo
285
+ * the pvars will be checked first and only if no pvar is found the
286
+ * param will be resolved to an avp)
287
+ */
262 288
 enum {
263 289
 	FPARAM_UNSPEC = 0,
264 290
 	FPARAM_INT    = (1 << 0),
... ...
@@ -273,22 +299,22 @@ enum {
273 299
 	FPARAM_PVE    = (1 << 8)
274 300
 };
275 301
 
276
-/*
302
+/**
277 303
  * Function parameter
278 304
  */
279 305
 typedef struct fparam {
280
-	char* orig;                       /* The original value */
281
-	int type;                         /* Type of parameter */
306
+	char* orig;                       /**< The original value */
307
+	int type;                         /**< Type of parameter */
282 308
 	union {
283
-		char* asciiz;             /* Zero terminated ASCII string */
284
-		struct _str str;          /* pointer/len string */
285
-		int i;                    /* Integer value */
286
-		regex_t* regex;           /* Compiled regular expression */
287
-		avp_ident_t avp;          /* AVP identifier */
288
-		select_t* select;         /* select structure */ 
289
-		struct subst_expr* subst; /* Regex substitution */
290
-		pv_spec_t* pvs;    /* kamailio pseudo-vars */
291
-		pv_elem_t* pve;    /* kamailio pseudo-vars in a string */
309
+		char* asciiz;             /**< Zero terminated ASCII string */
310
+		struct _str str;          /**< pointer/len string */
311
+		int i;                    /**< Integer value */
312
+		regex_t* regex;           /**< Compiled regular expression */
313
+		avp_ident_t avp;          /**< AVP identifier */
314
+		select_t* select;         /**< select structure */ 
315
+		struct subst_expr* subst; /**< Regex substitution */
316
+		pv_spec_t* pvs;    /**< kamailio pseudo-vars */
317
+		pv_elem_t* pve;    /**< kamailio pseudo-vars in a string */
292 318
 	} v;
293 319
 	void *fixed;
294 320
 } fparam_t;
... ...
@@ -309,27 +335,27 @@ union cmd_export_u{
309 335
 #endif
310 336
 
311 337
 
312
-/* ser module exports version */
338
+/** ser module exports version */
313 339
 struct ser_module_exports {
314
-	char* name;                     /* null terminated module name */
315
-	ser_cmd_export_t* cmds;         /* null terminated array of the exported
340
+	char* name;			/**< null terminated module name */
341
+	ser_cmd_export_t* cmds;         /**< null terminated array of the exported
316 342
 									   commands */
317
-	rpc_export_t* rpc_methods;      /* null terminated array of exported rpc methods */
318
-	param_export_t* params;         /* null terminated array of the exported
343
+	rpc_export_t* rpc_methods;      /**< null terminated array of exported rpc methods */
344
+	param_export_t* params;         /**< null terminated array of the exported
319 345
 									   module parameters */
320
-	init_function init_f;           /* Initialization function */
321
-	response_function response_f;   /* function used for responses,
346
+	init_function init_f;           /**< Initialization function */
347
+	response_function response_f;   /**< function used for responses,
322 348
 									   returns yes or no; can be null */
323
-	destroy_function destroy_f;     /* function called when the module should
349
+	destroy_function destroy_f;     /**< function called when the module should
324 350
 									   be "destroyed", e.g: on ser exit;
325 351
 									   can be null */
326 352
 	onbreak_function onbreak_f;
327
-	child_init_function init_child_f;  /* function called by all processes
353
+	child_init_function init_child_f;  /**< function called by all processes
328 354
 										  after the fork */
329 355
 };
330 356
 
331 357
 
332
-/* kamailio/openser proc_export (missing from ser) */
358
+/** kamailio/openser proc_export (missing from ser) */
333 359
 typedef void (*mod_proc)(int no);
334 360
 
335 361
 typedef int (*mod_proc_wrapper)(void);
... ...
@@ -345,90 +371,93 @@ struct proc_export_ {
345 371
 typedef struct proc_export_ proc_export_t;
346 372
 
347 373
 
348
-/* kamailio/openser module exports version */
374
+/** kamailio/openser module exports version */
349 375
 struct kam_module_exports {
350
-	char* name;                     /* null terminated module name */
351
-	unsigned int dlflags;			/*!< flags for dlopen  */
352
-	kam_cmd_export_t* cmds;			/* null terminated array of the exported
376
+	char* name;				/**< null terminated module name */
377
+	unsigned int dlflags;			/**< flags for dlopen  */
378
+	kam_cmd_export_t* cmds;			/**< null terminated array of the exported
353 379
 									   commands */
354
-	param_export_t* params;			/* null terminated array of the exported
380
+	param_export_t* params;			/**< null terminated array of the exported
355 381
 									   module parameters */
356
-	stat_export_t* stats;			/*!< null terminated array of the exported
382
+	stat_export_t* stats;			/**< null terminated array of the exported
357 383
 									  module statistics */
358
-	mi_export_t* mi_cmds;			/*!< null terminated array of the exported
384
+	mi_export_t* mi_cmds;			/**< null terminated array of the exported
359 385
 									  MI functions */
360 386
 	pv_export_t* items;				/*!< null terminated array of the exported
361 387
 									   module items (pseudo-variables) */
362
-	proc_export_t* procs;			/*!< null terminated array of the
388
+	proc_export_t* procs;			/**< null terminated array of the
363 389
 									  additional processes required by the
364 390
 									  module */
365
-	init_function init_f;           /* Initialization function */
366
-	response_function response_f;   /* function used for responses,
391
+	init_function init_f;			/**< Initialization function */
392
+	response_function response_f;		/**< function used for responses,
367 393
 									   returns yes or no; can be null */
368
-	destroy_function destroy_f;     /* function called when the module should
394
+	destroy_function destroy_f;			/**< function called when the module should
369 395
 									   be "destroyed", e.g: on ser exit;
370 396
 									   can be null */
371
-	child_init_function init_child_f;  /* function called by all processes
397
+	child_init_function init_child_f;	/**< function called by all processes
372 398
 										  after the fork */
373 399
 };
374 400
 
375 401
 
376 402
 
377
-/** sr/ser 3.1+ module exports version.
378
- * Includes ser and kamailio versions, re-arraranged + some extras.
379
- * Note: some of the members will be obsoleted and are kept only for
403
+/**
404
+ * @brief sr/ser 3.1+ module exports version
405
+ * 
406
+ * sr/ser 3.1+ module exports version, Includes ser and kamailio versions,
407
+ * re-arraranged + some extras.
408
+ * @note Some of the members will be obsoleted and are kept only for
380 409
  * backward compatibility (avoid re-writing all the modules exports
381 410
  * declarations).
382 411
  */
383 412
 struct sr31_module_exports {
384
-	char* name;                     /* null terminated module name */
385
-	sr31_cmd_export_t* cmds;      /* null terminated array of the exported
413
+	char* name;			/**< null terminated module name */
414
+	sr31_cmd_export_t* cmds;	/**< null terminated array of the exported
386 415
 									   commands */
387
-	param_export_t* params;         /* null terminated array of the exported
416
+	param_export_t* params;         /**< null terminated array of the exported
388 417
 									   module parameters */
389
-	init_function init_f;           /* Initialization function */
390
-	response_function response_f;   /* function used for responses,
418
+	init_function init_f;           /**< Initialization function */
419
+	response_function response_f;   /**< function used for responses,
391 420
 									   returns yes or no; can be null */
392
-	destroy_function destroy_f;     /* function called when the module should
421
+	destroy_function destroy_f;     /**< function called when the module should
393 422
 									   be "destroyed", e.g: on ser exit;
394 423
 									   can be null */
395 424
 	onbreak_function onbreak_f;
396
-	child_init_function init_child_f;  /* function called by all processes
425
+	child_init_function init_child_f;/**< function called by all processes
397 426
 										  after the fork */
398
-	unsigned int dlflags;           /**< flags for dlopen */
427
+	unsigned int dlflags;		/**< flags for dlopen */
399 428
 	/* ser specific exports
400 429
 	   (to be obsoleted and replaced by register_...) */
401
-	rpc_export_t* rpc_methods;      /* null terminated array of exported
402
-									   rpc methods */
430
+	rpc_export_t* rpc_methods;	/**< null terminated array of exported
431
+							rpc methods */
403 432
 	/* kamailio specific exports
404 433
 	   (to be obsoleted and replaced by register_...) */
405
-	stat_export_t* stats;			/*!< null terminated array of the exported
434
+	stat_export_t* stats;			/**< null terminated array of the exported
406 435
 									  module statistics */
407
-	mi_export_t* mi_cmds;			/*!< null terminated array of the exported
436
+	mi_export_t* mi_cmds;			/**< null terminated array of the exported
408 437
 									  MI functions */
409
-	pv_export_t* items;				/*!< null terminated array of the exported
438
+	pv_export_t* items;			/**< null terminated array of the exported
410 439
 									   module items (pseudo-variables) */
411
-	proc_export_t* procs;			/*!< null terminated array of the
440
+	proc_export_t* procs;			/**< null terminated array of the
412 441
 									  additional processes required by the
413 442
 									  module */
414 443
 };
415 444
 
416 445
 
417 446
 
418
-/* module exports in the same place in memory in both ser & kamailio */
419
-struct module_exports_common{
447
+/** module exports in the same place in memory in both ser & kamailio */
448
+struct module_exports_common {
420 449
 	char* name;
421 450
 };
422 451
 
423 452
 
424 453
 union module_exports_u {
425
-		struct module_exports_common c; /*common members for all the versions*/
454
+		struct module_exports_common c; /**< common members for all the versions */
426 455
 		struct ser_module_exports v0;
427 456
 		struct kam_module_exports v1;
428 457
 };
429 458
 
430 459
 
431
-struct sr_module{
460
+struct sr_module {
432 461
 	char* path;
433 462
 	void* handle;
434 463
 	unsigned int orig_mod_interface_ver;
... ...
@@ -437,9 +466,9 @@ struct sr_module{
437 466
 };
438 467
 
439 468
 
440
-extern struct sr_module* modules; /* global module list*/
441
-extern response_function* mod_response_cbks;/* response callback array */
442
-extern int mod_response_cbk_no;    /* size of reponse callbacks array */
469
+extern struct sr_module* modules; /**< global module list*/
470
+extern response_function* mod_response_cbks; /**< response callback array */
471
+extern int mod_response_cbk_no; /**< size of reponse callbacks array */
443 472
 
444 473
 int register_builtin_modules(void);
445 474
 int load_module(char* path);
... ...
@@ -453,27 +482,22 @@ int init_child(int rank);
453 482
 int init_modules(void);
454 483
 struct sr_module* find_module_by_name(char* mod);
455 484
 
456
-/* true if the module with name 'mod_name' is loaded */
485
+/**< true if the module with name 'mod_name' is loaded */
457 486
 #define module_loaded(mod_name) (find_module_by_name(mod_name)!=0)
458 487
 
459 488
 
460
-/*! \brief
461
- * Find a parameter with given type and return it's
462
- * address in memory
463
- * If there is no such parameter, NULL is returned
489
+/**
490
+ * @brief Find a parameter with given type
491
+ * @param mod module
492
+ * @param name parameter name
493
+ * @param type_mask parameter mask
494
+ * @param param_type parameter type
495
+ * @return parameter address in memory, if there is no such parameter, NULL is returned
464 496
  */
465 497
 void* find_param_export(struct sr_module* mod, char* name, modparam_t type_mask, modparam_t *param_type);
466 498
 
467
-/* modules function prototypes:
468
- * struct module_exports* mod_register(); (type module_register)
469
- * int   foo_cmd(struct sip_msg* msg, char* param);
470
- *  - returns >0 if ok , <0 on error, 0 to stop processing (==DROP)
471
- * int   response_f(struct sip_msg* msg)
472
- *  - returns >0 if ok, 0 to drop message
473
- */
474
-
475 499
 
476
-/* API function to get other parameters from fixup */
500
+/** API function to get other parameters from fixup */
477 501
 action_u_t *fixup_get_param(void **cur_param, int cur_param_no, int required_param_no);
478 502
 int fixup_get_param_count(void **cur_param, int cur_param_no);
479 503
 
... ...
@@ -485,10 +509,14 @@ int fix_flag( modparam_t type, void* val,
485 509
  * Common function parameter fixups
486 510
  */
487 511
 
488
-/*
489
- * Generic parameter fixup function which creates
490
- * fparam_t structure. type parameter contains allowed
491
- * parameter types
512
+/**
513
+ * @brief Generic parameter fixup function
514
+ * 
515
+ * Generic parameter fixup function which creates fparam_t structure.
516
+ * Type parameter contains allowed parameter types.
517
+ * @param type parameter type
518
+ * @param param fixed parameter
519
+ * @return 0 on success, -1 on error
492 520
  */
493 521
 int fix_param(int type, void** param);
494 522
 void fparam_free_contents(fparam_t* fp);
... ...
@@ -497,21 +525,22 @@ void fparam_free_contents(fparam_t* fp);
497 525
   */
498 526
 int fix_param_types(int types, void** param);
499 527
 
500
-/*
501
- * Fixup variable string, the parameter can be
502
- * AVP, SELECT, or ordinary string. AVP and select
503
- * identifiers will be resolved to their values during
504
- * runtime
505
- *
506
- * The parameter value will be converted to fparam structure
507
- * This function returns -1 on an error
528
+/**
529
+ * @brief Fixup variable string, 
530
+ * 
531
+ * Fixup variable string, the parameter can be AVP, SELECT, or ordinary
532
+ * string. AVP and select identifiers will be resolved to their values
533
+ * during runtime. The parameter value will be converted to fparam structure.
534
+ * @param param fixed parameter value
535
+ * @param param_no number of parameter
536
+ * @return 0 on success, -1 on an error
508 537
  */
509 538
 int fixup_var_str_12(void** param, int param_no);
510 539
 
511
-/* Same as fixup_var_str_12 but applies to the 1st parameter only */
540
+/** Same as fixup_var_str_12 but applies to the 1st parameter only */
512 541
 int fixup_var_str_1(void** param, int param_no);
513 542
 
514
-/* Same as fixup_var_str_12 but applies to the 2nd parameter only */
543
+/** Same as fixup_var_str_12 but applies to the 2nd parameter only */
515 544
 int fixup_var_str_2(void** param, int param_no);
516 545
 
517 546
 /** fixup variable-pve-string.
... ...
@@ -520,98 +549,118 @@ int fixup_var_str_2(void** param, int param_no);
520 549
  */
521 550
 int fixup_var_pve_str_12(void** param, int param_no);
522 551
 
523
-/* same as fixup_var_pve_str_12 but applies to the 1st parameter only */
552
+/** same as fixup_var_pve_str_12 but applies to the 1st parameter only */
524 553
 int fixup_var_pve_str_1(void** param, int param_no);
525 554
 
526
-/* same as fixup_var_pve_str_12 but applies to the 2nd parameter only */
555
+/** same as fixup_var_pve_str_12 but applies to the 2nd parameter only */
527 556
 int fixup_var_pve_str_2(void** param, int param_no);
528 557
 
529
-/*
530
- * Fixup variable integer, the parameter can be
531
- * AVP, SELECT, or ordinary integer. AVP and select
532
- * identifiers will be resolved to their values and 
533
- * converted to int if necessary during runtime
558
+/**
559
+ * @brief Fixup variable integer
534 560
  *
535
- * The parameter value will be converted to fparam structure
536
- * This function returns -1 on an error
561
+ * Fixup variable integer, the parameter can be AVP, SELECT, or ordinary
562
+ * integer. AVP and select identifiers will be resolved to their values
563
+ * and converted to int if necessary during runtime. The parameter value will
564
+ * be converted to fparam structure
565
+ * @param param fixed parameter value
566
+ * @param param_no number of parameter
567
+ * @return 0 on success, -1 on an error
537 568
  */
538 569
 int fixup_var_int_12(void** param, int param_no);
539 570
 
540
-/* Same as fixup_var_int_12 but applies to the 1st parameter only */
571
+/** Same as fixup_var_int_12 but applies to the 1st parameter only */
541 572
 int fixup_var_int_1(void** param, int param_no);
542 573
 
543
-/* Same as fixup_var_int_12 but applies to the 2nd parameter only */
574
+/** Same as fixup_var_int_12 but applies to the 2nd parameter only */
544 575
 int fixup_var_int_2(void** param, int param_no);
545 576
 
546
-/*
577
+/**
547 578
  * The parameter must be a regular expression which must compile, the
548 579
  * parameter will be converted to compiled regex
549 580
  */
550 581
 int fixup_regex_12(void** param, int param_no);
551 582
 
552
-/* Same as fixup_regex_12 but applies to the 1st parameter only */
583
+/** Same as fixup_regex_12 but applies to the 1st parameter only */
553 584
 int fixup_regex_1(void** param, int param_no);
554 585
 
555
-/* Same as fixup_regex_12 but applies to the 2nd parameter only */
586
+/** Same as fixup_regex_12 but applies to the 2nd parameter only */
556 587
 int fixup_regex_2(void** param, int param_no);
557 588
 
558
-/*
589
+/**
559 590
  * The string parameter will be converted to integer
560 591
  */
561 592
 int fixup_int_12(void** param, int param_no);
562 593
 
563
-/* Same as fixup_int_12 but applies to the 1st parameter only */
594
+/** Same as fixup_int_12 but applies to the 1st parameter only */
564 595
 int fixup_int_1(void** param, int param_no);
565 596
 
566
-/* Same as fixup_int_12 but applies to the 2nd parameter only */
597
+/** Same as fixup_int_12 but applies to the 2nd parameter only */
567 598
 int fixup_int_2(void** param, int param_no);
568 599
 
569
-/*
600
+/**
570 601
  * Parse the parameter as static string, do not resolve
571 602
  * AVPs or selects, convert the parameter to str structure
572 603
  */
573 604
 int fixup_str_12(void** param, int param_no);
574 605
 
575
-/* Same as fixup_str_12 but applies to the 1st parameter only */
606
+/** Same as fixup_str_12 but applies to the 1st parameter only */
576 607
 int fixup_str_1(void** param, int param_no);
577 608
 
578
-/* Same as fixup_str_12 but applies to the 2nd parameter only */
609
+/** Same as fixup_str_12 but applies to the 2nd parameter only */
579 610
 int fixup_str_2(void** param, int param_no);
580 611
 
581
-/*
582
- * Get the function parameter value as string
583
- * Return values:  0 - Success
584
- *                -1 - Cannot get value
612
+/**
613
+ * @brief Get the function parameter value as string
614
+ * @param dst string destination
615
+ * @param msg SIP message
616
+ * @param param function parameters
617
+ * @return 0 on success, 1 on error, e.g. cannot get value
585 618
  */
586 619
 int get_str_fparam(str* dst, struct sip_msg* msg, fparam_t* param);
587 620
 
588
-/*
589
- * Get the function parameter value as integer
590
- * Return values:  0 - Success
591
- *                -1 - Cannot get value
621
+/**
622
+ * @brief Get the function parameter value as integer
623
+ * @param dst string destination
624
+ * @param msg SIP message
625
+ * @param param function parameters
626
+ * @return 0 on success, 1 on error, e.g. cannot get value
592 627
  */
593 628
 int get_int_fparam(int* dst, struct sip_msg* msg, fparam_t* param);
594 629
 
595
-
596 630
 /**
597
- * Retrieve the compiled RegExp.
598
- * @return: 0 for success, negative on error.
631
+ * @brief Get the function parameter value as compiled regular expression
632
+ * @param dst string destination
633
+ * @param msg SIP message
634
+ * @param param function parameters
635
+ * @return 0 on success, 1 on error, e.g. cannot get value
599 636
  */
600 637
 int get_regex_fparam(regex_t *dst, struct sip_msg* msg, fparam_t* param);
601 638
 
602 639
 
603 640
 int is_fparam_rve_fixup(fixup_function f);
604 641
 
605
-
606
-/** generic free fixup type function for a fixed fparam.
607
- * It will free whatever was allocated during the initial fparam fixup
608
- * and restore the original param value.
642
+/**
643
+ * @brief Generic free fixup type function for a fixed fparam
644
+ * 
645
+ * Generic free fixup type function for a fixed fparam. It will free whatever
646
+ * was allocated during the initial fparam fixup and restore the original param
647
+ * value.
648
+ * @param param freed parameters
609 649
  */
610 650
 void fparam_free_restore(void** param);
611 651
 int fixup_free_fparam_all(void** param, int param_no);
612 652
 int fixup_free_fparam_1(void** param, int param_no);
613 653
 int fixup_free_fparam_2(void** param, int param_no);
614 654
 
655
+/**
656
+ * @brief returns the corresponding fixup_free* for various known fixup types
657
+ * 
658
+ * Returns the corresponding fixup_free* for various known fixup types.
659
+ * Used to automatically fill in free_fixup* functions.
660
+ * @param f fixup function pointer
661
+ * @return free fixup function pointer on success, 0 on failure (unknown
662
+ * fixup or no free fixup function).
663
+ */
615 664
 free_fixup_function get_fixup_free(fixup_function f);
616 665
 
617 666
 #endif /* sr_module_h */