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 40
  *  2008-11-26  added fparam_free_contents() and fix_param_types (andrei)
41 41
  */
42 42
 
43
-/** module loading, standard fixups.
44
- * @file sr_module.c
43
+/**
44
+ * @file
45
+ * @brief SIP-Router core :: modules loading, structures declarations and utilities
45 46
  * @ingroup core
47
+ * Module: \ref core
46 48
  */
47 49
 
50
+
48 51
 #include "sr_module.h"
49 52
 #include "mod_fix.h"
50 53
 #include "dprint.h"
... ...
@@ -701,6 +705,14 @@ struct sr_module* find_module_by_name(char* mod) {
701 701
 }
702 702
 
703 703
 
704
+/*!
705
+ * \brief Find a parameter with given type
706
+ * \param mod module
707
+ * \param name parameter name
708
+ * \param type_mask parameter mask
709
+ * \param param_type parameter type
710
+ * \return parameter address in memory, if there is no such parameter, NULL is returned
711
+ */
704 712
 void* find_param_export(struct sr_module* mod, char* name,
705 713
 						modparam_t type_mask, modparam_t *param_type)
706 714
 {
... ...
@@ -1233,10 +1245,13 @@ void fparam_free_contents(fparam_t* fp)
1233 1233
 }
1234 1234
 
1235 1235
 
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.
1236
+/**
1237
+ * @brief Generic free fixup type function for a fixed fparam
1238
+ * 
1239
+ * Generic free fixup type function for a fixed fparam. It will free whatever
1240
+ * was allocated during the initial fparam fixup and restore the original param
1241
+ * value.
1242
+ * @param param freed parameters
1240 1243
  */
1241 1244
 void fparam_free_restore(void** param)
1242 1245
 {
... ...
@@ -1725,12 +1740,14 @@ int is_fparam_rve_fixup(fixup_function f)
1725 1725
 }
1726 1726
 
1727 1727
 
1728
-
1729
-/** returns the corresponding fixup_free* for various known fixup types.
1728
+/**
1729
+ * @brief returns the corresponding fixup_free* for various known fixup types
1730
+ * 
1731
+ * Returns the corresponding fixup_free* for various known fixup types.
1730 1732
  * 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).
1733
+ * @param f fixup function pointer
1734
+ * @return free fixup function pointer on success, 0 on failure (unknown
1735
+ * fixup or no free fixup function).
1734 1736
  */
1735 1737
 free_fixup_function get_fixup_free(fixup_function f)
1736 1738
 {
... ...
@@ -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 26
  * along with this program; if not, write to the Free Software
27 27
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
28 28
  */
29
+
29 30
 /*
30 31
  * History:
31 32
  * --------
... ...
@@ -49,8 +46,11 @@
49 49
  *  2008-11-26  added fparam_free_contents() and fix_param_types (andrei)
50 50
  */
51 51
 
52
-/** modules structures/exports declarations and utilities (fixups a.s.o).
53
- * @file sr_module.h
52
+/**
53
+ * @file
54
+ * @brief SIP-Router core :: modules loading, structures declarations and utilities
55
+ * @ingroup core
56
+ * Module: \ref core
54 57
  */
55 58
 
56 59
 
... ...
@@ -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 144
 
145 145
 /* magic parameter number values */
146 146
 
147
-#define NO_SCRIPT     -1    /* export not usable from scripts */
148
-#define VAR_PARAM_NO  -128  /* function has variable number of parameters
147
+#define NO_SCRIPT     -1    /**< export not usable from scripts */
148
+#define VAR_PARAM_NO  -128  /**< function has variable number of parameters
149 149
 							   (see cmd_function_var for the prototype) */
150 150
 
151
-/* special fixup function flags.
152
- * They are kept in the first 2 bits inside the pointer
151
+/**
152
+ * special fixup function flags fparam fixup, rve ready,
153
+ * they are kept in the first 2 bits inside the pointer
153 154
  */
154
-#define FIXUP_F_FPARAM_RVE (unsigned long)1 /* fparam fixup, rve ready */
155
+#define FIXUP_F_FPARAM_RVE (unsigned long)1
155 156
 
156 157
 #define call_fixup(fixup, param, param_no) \
157 158
 	((fixup) ? (fixup)(param, param_no) : 0)
158 159
 
159 160
 /* 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
161
+#define PROC_MAIN      0  /**< Main ser process */
162
+#define PROC_TIMER    -1  /**< Timer attendant process */
163
+#define PROC_RPC      -2  /**< RPC type process */
164
+#define PROC_FIFO      PROC_RPC  /**< FIFO attendant process */
165
+#define PROC_TCP_MAIN -4  /**< TCP main process */
166
+#define PROC_UNIXSOCK -5  /**< Unix socket server */
167
+#define PROC_ATTENDANT -10  /**< main "attendant process */
168
+#define PROC_INIT     -127 /**< special rank, the context is the main ser
168 169
 							  process, but this is guaranteed to be executed
169 170
 							  before any process is forked, so it can be used
170 171
 							  to setup shared variables that depend on some
171 172
 							  after mod_init available information (e.g.
172 173
 							  total number of processes).
173
-							 WARNING: child_init(PROC_MAIN) is again called
174
+							  @warning child_init(PROC_MAIN) is again called
174 175
 							 in the same process (main), but latter 
175 176
 							 (before tcp), so make sure you don't init things 
176 177
 							 twice, bot in PROC_MAIN and PROC_INT */
177
-#define PROC_NOCHLDINIT -128 /* no child init functions will be called
178
+#define PROC_NOCHLDINIT -128 /**< no child init functions will be called
178 179
                                 if this rank is used in fork_process() */
179 180
 
180
-#define PROC_MIN PROC_NOCHLDINIT /* Minimum process rank */
181
+#define PROC_MIN PROC_NOCHLDINIT /**< Minimum process rank */
181 182
 
182 183
 
183
-#define DEFAULT_DLFLAGS	0 /* value that signals to module loader to
184
+#define DEFAULT_DLFLAGS	0 /**< value that signals to module loader to
184 185
 							use default dlopen flags in Kamailio */
185 186
 #ifndef RTLD_NOW
186 187
 /* for openbsd */
... ...
@@ -195,45 +222,45 @@ typedef int (*param_func_t)( modparam_t type, void* val);
195 195
 	char *module_flags=SER_COMPILE_FLAGS; \
196 196
 	unsigned int module_interface_ver=MODULE_INTERFACE_VER; 
197 197
 
198
-/* ser version */
198
+/** ser version */
199 199
 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
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
204 204
 							   parameters */
205
-	int flags;              /* Function flags */
205
+	int flags;              /**< Function flags */
206 206
 };
207 207
 
208 208
 
209
-/* kamailo/openser version */
209
+/** kamailo/openser version */
210 210
 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
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
215 215
 							   parameters */
216
-	free_fixup_function free_fixup; /* function called to free the "fixed"
216
+	free_fixup_function free_fixup; /**< function called to free the "fixed"
217 217
 									   parameters */
218
-	int flags;              /* Function flags */
218
+	int flags;              /**< Function flags */
219 219
 };
220 220
 
221
-
221
+/** sip-router version */
222 222
 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
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
227 227
 							   parameters */
228
-	free_fixup_function free_fixup; /* function called to free the "fixed"
228
+	free_fixup_function free_fixup; /**< function called to free the "fixed"
229 229
 									   parameters */
230
-	int flags;              /* Function flags */
230
+	int flags;              /**< Function flags */
231 231
 	int fixup_flags;
232
-	void* module_exports; /* pointer to module structure */
232
+	void* module_exports; /**< pointer to module structure */
233 233
 };
234 234
 
235 235
 
236
-/* members situated at the same place in memory in both ser & kamailio
236
+/** members situated at the same place in memory in both ser & kamailio
237 237
    cmd_export */
238 238
 struct cmd_export_common_ {
239 239
 	char* name;
... ...
@@ -244,21 +271,20 @@ struct cmd_export_common_ {
244 244
 
245 245
 
246 246
 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 */
247
+	char* name;             /**< null terminated param. name */
248
+	modparam_t type;        /**< param. type */
249
+	void* param_pointer;    /**< pointer to the param. memory location */
250 250
 };
251 251
 
252 252
 
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
-  */
253
+/*
254
+ * Allowed parameter types, the types _must_ be in "fallback" order,
255
+ * e.g. FPARAM_STR should be the last to allow fallback to it,
256
+ * F_PARAM_PVS should be in front of F_PARAM_AVP (so that
257
+ * for fix_param_types(FPARAM_AVP|FPARAM_PVS|FPARAM_STR, param) and $foo
258
+ * the pvars will be checked first and only if no pvar is found the
259
+ * param will be resolved to an avp)
260
+ */
262 261
 enum {
263 262
 	FPARAM_UNSPEC = 0,
264 263
 	FPARAM_INT    = (1 << 0),
... ...
@@ -273,22 +299,22 @@ enum {
273 273
 	FPARAM_PVE    = (1 << 8)
274 274
 };
275 275
 
276
-/*
276
+/**
277 277
  * Function parameter
278 278
  */
279 279
 typedef struct fparam {
280
-	char* orig;                       /* The original value */
281
-	int type;                         /* Type of parameter */
280
+	char* orig;                       /**< The original value */
281
+	int type;                         /**< Type of parameter */
282 282
 	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 */
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 */
292 292
 	} v;
293 293
 	void *fixed;
294 294
 } fparam_t;
... ...
@@ -309,27 +335,27 @@ union cmd_export_u{
309 309
 #endif
310 310
 
311 311
 
312
-/* ser module exports version */
312
+/** ser module exports version */
313 313
 struct ser_module_exports {
314
-	char* name;                     /* null terminated module name */
315
-	ser_cmd_export_t* cmds;         /* null terminated array of the exported
314
+	char* name;			/**< null terminated module name */
315
+	ser_cmd_export_t* cmds;         /**< null terminated array of the exported
316 316
 									   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
317
+	rpc_export_t* rpc_methods;      /**< null terminated array of exported rpc methods */
318
+	param_export_t* params;         /**< null terminated array of the exported
319 319
 									   module parameters */
320
-	init_function init_f;           /* Initialization function */
321
-	response_function response_f;   /* function used for responses,
320
+	init_function init_f;           /**< Initialization function */
321
+	response_function response_f;   /**< function used for responses,
322 322
 									   returns yes or no; can be null */
323
-	destroy_function destroy_f;     /* function called when the module should
323
+	destroy_function destroy_f;     /**< function called when the module should
324 324
 									   be "destroyed", e.g: on ser exit;
325 325
 									   can be null */
326 326
 	onbreak_function onbreak_f;
327
-	child_init_function init_child_f;  /* function called by all processes
327
+	child_init_function init_child_f;  /**< function called by all processes
328 328
 										  after the fork */
329 329
 };
330 330
 
331 331
 
332
-/* kamailio/openser proc_export (missing from ser) */
332
+/** kamailio/openser proc_export (missing from ser) */
333 333
 typedef void (*mod_proc)(int no);
334 334
 
335 335
 typedef int (*mod_proc_wrapper)(void);
... ...
@@ -345,90 +371,93 @@ struct proc_export_ {
345 345
 typedef struct proc_export_ proc_export_t;
346 346
 
347 347
 
348
-/* kamailio/openser module exports version */
348
+/** kamailio/openser module exports version */
349 349
 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
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
353 353
 									   commands */
354
-	param_export_t* params;			/* null terminated array of the exported
354
+	param_export_t* params;			/**< null terminated array of the exported
355 355
 									   module parameters */
356
-	stat_export_t* stats;			/*!< null terminated array of the exported
356
+	stat_export_t* stats;			/**< null terminated array of the exported
357 357
 									  module statistics */
358
-	mi_export_t* mi_cmds;			/*!< null terminated array of the exported
358
+	mi_export_t* mi_cmds;			/**< null terminated array of the exported
359 359
 									  MI functions */
360 360
 	pv_export_t* items;				/*!< null terminated array of the exported
361 361
 									   module items (pseudo-variables) */
362
-	proc_export_t* procs;			/*!< null terminated array of the
362
+	proc_export_t* procs;			/**< null terminated array of the
363 363
 									  additional processes required by the
364 364
 									  module */
365
-	init_function init_f;           /* Initialization function */
366
-	response_function response_f;   /* function used for responses,
365
+	init_function init_f;			/**< Initialization function */
366
+	response_function response_f;		/**< function used for responses,
367 367
 									   returns yes or no; can be null */
368
-	destroy_function destroy_f;     /* function called when the module should
368
+	destroy_function destroy_f;			/**< function called when the module should
369 369
 									   be "destroyed", e.g: on ser exit;
370 370
 									   can be null */
371
-	child_init_function init_child_f;  /* function called by all processes
371
+	child_init_function init_child_f;	/**< function called by all processes
372 372
 										  after the fork */
373 373
 };
374 374
 
375 375
 
376 376
 
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
377
+/**
378
+ * @brief sr/ser 3.1+ module exports version
379
+ * 
380
+ * sr/ser 3.1+ module exports version, Includes ser and kamailio versions,
381
+ * re-arraranged + some extras.
382
+ * @note Some of the members will be obsoleted and are kept only for
380 383
  * backward compatibility (avoid re-writing all the modules exports
381 384
  * declarations).
382 385
  */
383 386
 struct sr31_module_exports {
384
-	char* name;                     /* null terminated module name */
385
-	sr31_cmd_export_t* cmds;      /* null terminated array of the exported
387
+	char* name;			/**< null terminated module name */
388
+	sr31_cmd_export_t* cmds;	/**< null terminated array of the exported
386 389
 									   commands */
387
-	param_export_t* params;         /* null terminated array of the exported
390
+	param_export_t* params;         /**< null terminated array of the exported
388 391
 									   module parameters */
389
-	init_function init_f;           /* Initialization function */
390
-	response_function response_f;   /* function used for responses,
392
+	init_function init_f;           /**< Initialization function */
393
+	response_function response_f;   /**< function used for responses,
391 394
 									   returns yes or no; can be null */
392
-	destroy_function destroy_f;     /* function called when the module should
395
+	destroy_function destroy_f;     /**< function called when the module should
393 396
 									   be "destroyed", e.g: on ser exit;
394 397
 									   can be null */
395 398
 	onbreak_function onbreak_f;
396
-	child_init_function init_child_f;  /* function called by all processes
399
+	child_init_function init_child_f;/**< function called by all processes
397 400
 										  after the fork */
398
-	unsigned int dlflags;           /**< flags for dlopen */
401
+	unsigned int dlflags;		/**< flags for dlopen */
399 402
 	/* ser specific exports
400 403
 	   (to be obsoleted and replaced by register_...) */
401
-	rpc_export_t* rpc_methods;      /* null terminated array of exported
402
-									   rpc methods */
404
+	rpc_export_t* rpc_methods;	/**< null terminated array of exported
405
+							rpc methods */
403 406
 	/* kamailio specific exports
404 407
 	   (to be obsoleted and replaced by register_...) */
405
-	stat_export_t* stats;			/*!< null terminated array of the exported
408
+	stat_export_t* stats;			/**< null terminated array of the exported
406 409
 									  module statistics */
407
-	mi_export_t* mi_cmds;			/*!< null terminated array of the exported
410
+	mi_export_t* mi_cmds;			/**< null terminated array of the exported
408 411
 									  MI functions */
409
-	pv_export_t* items;				/*!< null terminated array of the exported
412
+	pv_export_t* items;			/**< null terminated array of the exported
410 413
 									   module items (pseudo-variables) */
411
-	proc_export_t* procs;			/*!< null terminated array of the
414
+	proc_export_t* procs;			/**< null terminated array of the
412 415
 									  additional processes required by the
413 416
 									  module */
414 417
 };
415 418
 
416 419
 
417 420
 
418
-/* module exports in the same place in memory in both ser & kamailio */
419
-struct module_exports_common{
421
+/** module exports in the same place in memory in both ser & kamailio */
422
+struct module_exports_common {
420 423
 	char* name;
421 424
 };
422 425
 
423 426
 
424 427
 union module_exports_u {
425
-		struct module_exports_common c; /*common members for all the versions*/
428
+		struct module_exports_common c; /**< common members for all the versions */
426 429
 		struct ser_module_exports v0;
427 430
 		struct kam_module_exports v1;
428 431
 };
429 432
 
430 433
 
431
-struct sr_module{
434
+struct sr_module {
432 435
 	char* path;
433 436
 	void* handle;
434 437
 	unsigned int orig_mod_interface_ver;
... ...
@@ -437,9 +466,9 @@ struct sr_module{
437 437
 };
438 438
 
439 439
 
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 */
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 */
443 443
 
444 444
 int register_builtin_modules(void);
445 445
 int load_module(char* path);
... ...
@@ -453,27 +482,22 @@ int init_child(int rank);
453 453
 int init_modules(void);
454 454
 struct sr_module* find_module_by_name(char* mod);
455 455
 
456
-/* true if the module with name 'mod_name' is loaded */
456
+/**< true if the module with name 'mod_name' is loaded */
457 457
 #define module_loaded(mod_name) (find_module_by_name(mod_name)!=0)
458 458
 
459 459
 
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
460
+/**
461
+ * @brief Find a parameter with given type
462
+ * @param mod module
463
+ * @param name parameter name
464
+ * @param type_mask parameter mask
465
+ * @param param_type parameter type
466
+ * @return parameter address in memory, if there is no such parameter, NULL is returned
464 467
  */
465 468
 void* find_param_export(struct sr_module* mod, char* name, modparam_t type_mask, modparam_t *param_type);
466 469
 
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 470
 
476
-/* API function to get other parameters from fixup */
471
+/** API function to get other parameters from fixup */
477 472
 action_u_t *fixup_get_param(void **cur_param, int cur_param_no, int required_param_no);
478 473
 int fixup_get_param_count(void **cur_param, int cur_param_no);
479 474
 
... ...
@@ -485,10 +509,14 @@ int fix_flag( modparam_t type, void* val,
485 485
  * Common function parameter fixups
486 486
  */
487 487
 
488
-/*
489
- * Generic parameter fixup function which creates
490
- * fparam_t structure. type parameter contains allowed
491
- * parameter types
488
+/**
489
+ * @brief Generic parameter fixup function
490
+ * 
491
+ * Generic parameter fixup function which creates fparam_t structure.
492
+ * Type parameter contains allowed parameter types.
493
+ * @param type parameter type
494
+ * @param param fixed parameter
495
+ * @return 0 on success, -1 on error
492 496
  */
493 497
 int fix_param(int type, void** param);
494 498
 void fparam_free_contents(fparam_t* fp);
... ...
@@ -497,21 +525,22 @@ void fparam_free_contents(fparam_t* fp);
497 497
   */
498 498
 int fix_param_types(int types, void** param);
499 499
 
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
500
+/**
501
+ * @brief Fixup variable string, 
502
+ * 
503
+ * Fixup variable string, the parameter can be AVP, SELECT, or ordinary
504
+ * string. AVP and select identifiers will be resolved to their values
505
+ * during runtime. The parameter value will be converted to fparam structure.
506
+ * @param param fixed parameter value
507
+ * @param param_no number of parameter
508
+ * @return 0 on success, -1 on an error
508 509
  */
509 510
 int fixup_var_str_12(void** param, int param_no);
510 511
 
511
-/* Same as fixup_var_str_12 but applies to the 1st parameter only */
512
+/** Same as fixup_var_str_12 but applies to the 1st parameter only */
512 513
 int fixup_var_str_1(void** param, int param_no);
513 514
 
514
-/* Same as fixup_var_str_12 but applies to the 2nd parameter only */
515
+/** Same as fixup_var_str_12 but applies to the 2nd parameter only */
515 516
 int fixup_var_str_2(void** param, int param_no);
516 517
 
517 518
 /** fixup variable-pve-string.
... ...
@@ -520,98 +549,118 @@ int fixup_var_str_2(void** param, int param_no);
520 520
  */
521 521
 int fixup_var_pve_str_12(void** param, int param_no);
522 522
 
523
-/* same as fixup_var_pve_str_12 but applies to the 1st parameter only */
523
+/** same as fixup_var_pve_str_12 but applies to the 1st parameter only */
524 524
 int fixup_var_pve_str_1(void** param, int param_no);
525 525
 
526
-/* same as fixup_var_pve_str_12 but applies to the 2nd parameter only */
526
+/** same as fixup_var_pve_str_12 but applies to the 2nd parameter only */
527 527
 int fixup_var_pve_str_2(void** param, int param_no);
528 528
 
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
529
+/**
530
+ * @brief Fixup variable integer
534 531
  *
535
- * The parameter value will be converted to fparam structure
536
- * This function returns -1 on an error
532
+ * Fixup variable integer, the parameter can be AVP, SELECT, or ordinary
533
+ * integer. AVP and select identifiers will be resolved to their values
534
+ * and converted to int if necessary during runtime. The parameter value will
535
+ * be converted to fparam structure
536
+ * @param param fixed parameter value
537
+ * @param param_no number of parameter
538
+ * @return 0 on success, -1 on an error
537 539
  */
538 540
 int fixup_var_int_12(void** param, int param_no);
539 541
 
540
-/* Same as fixup_var_int_12 but applies to the 1st parameter only */
542
+/** Same as fixup_var_int_12 but applies to the 1st parameter only */
541 543
 int fixup_var_int_1(void** param, int param_no);
542 544
 
543
-/* Same as fixup_var_int_12 but applies to the 2nd parameter only */
545
+/** Same as fixup_var_int_12 but applies to the 2nd parameter only */
544 546
 int fixup_var_int_2(void** param, int param_no);
545 547
 
546
-/*
548
+/**
547 549
  * The parameter must be a regular expression which must compile, the
548 550
  * parameter will be converted to compiled regex
549 551
  */
550 552
 int fixup_regex_12(void** param, int param_no);
551 553
 
552
-/* Same as fixup_regex_12 but applies to the 1st parameter only */
554
+/** Same as fixup_regex_12 but applies to the 1st parameter only */
553 555
 int fixup_regex_1(void** param, int param_no);
554 556
 
555
-/* Same as fixup_regex_12 but applies to the 2nd parameter only */
557
+/** Same as fixup_regex_12 but applies to the 2nd parameter only */
556 558
 int fixup_regex_2(void** param, int param_no);
557 559
 
558
-/*
560
+/**
559 561
  * The string parameter will be converted to integer
560 562
  */
561 563
 int fixup_int_12(void** param, int param_no);
562 564
 
563
-/* Same as fixup_int_12 but applies to the 1st parameter only */
565
+/** Same as fixup_int_12 but applies to the 1st parameter only */
564 566
 int fixup_int_1(void** param, int param_no);
565 567
 
566
-/* Same as fixup_int_12 but applies to the 2nd parameter only */
568
+/** Same as fixup_int_12 but applies to the 2nd parameter only */
567 569
 int fixup_int_2(void** param, int param_no);
568 570
 
569
-/*
571
+/**
570 572
  * Parse the parameter as static string, do not resolve
571 573
  * AVPs or selects, convert the parameter to str structure
572 574
  */
573 575
 int fixup_str_12(void** param, int param_no);
574 576
 
575
-/* Same as fixup_str_12 but applies to the 1st parameter only */
577
+/** Same as fixup_str_12 but applies to the 1st parameter only */
576 578
 int fixup_str_1(void** param, int param_no);
577 579
 
578
-/* Same as fixup_str_12 but applies to the 2nd parameter only */
580
+/** Same as fixup_str_12 but applies to the 2nd parameter only */
579 581
 int fixup_str_2(void** param, int param_no);
580 582
 
581
-/*
582
- * Get the function parameter value as string
583
- * Return values:  0 - Success
584
- *                -1 - Cannot get value
583
+/**
584
+ * @brief Get the function parameter value as string
585
+ * @param dst string destination
586
+ * @param msg SIP message
587
+ * @param param function parameters
588
+ * @return 0 on success, 1 on error, e.g. cannot get value
585 589
  */
586 590
 int get_str_fparam(str* dst, struct sip_msg* msg, fparam_t* param);
587 591
 
588
-/*
589
- * Get the function parameter value as integer
590
- * Return values:  0 - Success
591
- *                -1 - Cannot get value
592
+/**
593
+ * @brief Get the function parameter value as integer
594
+ * @param dst string destination
595
+ * @param msg SIP message
596
+ * @param param function parameters
597
+ * @return 0 on success, 1 on error, e.g. cannot get value
592 598
  */
593 599
 int get_int_fparam(int* dst, struct sip_msg* msg, fparam_t* param);
594 600
 
595
-
596 601
 /**
597
- * Retrieve the compiled RegExp.
598
- * @return: 0 for success, negative on error.
602
+ * @brief Get the function parameter value as compiled regular expression
603
+ * @param dst string destination
604
+ * @param msg SIP message
605
+ * @param param function parameters
606
+ * @return 0 on success, 1 on error, e.g. cannot get value
599 607
  */
600 608
 int get_regex_fparam(regex_t *dst, struct sip_msg* msg, fparam_t* param);
601 609
 
602 610
 
603 611
 int is_fparam_rve_fixup(fixup_function f);
604 612
 
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.
613
+/**
614
+ * @brief Generic free fixup type function for a fixed fparam
615
+ * 
616
+ * Generic free fixup type function for a fixed fparam. It will free whatever
617
+ * was allocated during the initial fparam fixup and restore the original param
618
+ * value.
619
+ * @param param freed parameters
609 620
  */
610 621
 void fparam_free_restore(void** param);
611 622
 int fixup_free_fparam_all(void** param, int param_no);
612 623
 int fixup_free_fparam_1(void** param, int param_no);
613 624
 int fixup_free_fparam_2(void** param, int param_no);
614 625
 
626
+/**
627
+ * @brief returns the corresponding fixup_free* for various known fixup types
628
+ * 
629
+ * Returns the corresponding fixup_free* for various known fixup types.
630
+ * Used to automatically fill in free_fixup* functions.
631
+ * @param f fixup function pointer
632
+ * @return free fixup function pointer on success, 0 on failure (unknown
633
+ * fixup or no free fixup function).
634
+ */
615 635
 free_fixup_function get_fixup_free(fixup_function f);
616 636
 
617 637
 #endif /* sr_module_h */