10afc55099d5adc924de856c1c6f8a14da15a039
[sip-router] / sr_module.h
1 /* $Id$
2  *
3  * modules/plug-in structures declarations
4  *
5  *
6  * Copyright (C) 2001-2003 FhG Fokus
7  *
8  * This file is part of ser, a free SIP server.
9  *
10  * ser is free software; you can redistribute it and/or modify
11  * it under the terms of the GNU General Public License as published by
12  * the Free Software Foundation; either version 2 of the License, or
13  * (at your option) any later version
14  *
15  * For a license to use the ser software under conditions
16  * other than those described here, or to purchase support for this
17  * software, please contact iptel.org by e-mail at the following addresses:
18  *    info@iptel.org
19  *
20  * ser is distributed in the hope that it will be useful,
21  * but WITHOUT ANY WARRANTY; without even the implied warranty of
22  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
23  * GNU General Public License for more details.
24  *
25  * You should have received a copy of the GNU General Public License
26  * along with this program; if not, write to the Free Software
27  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
28  */
29 /*
30  * History:
31  * --------
32  *  2003-03-10  changed module exports interface: added struct cmd_export
33  *               and param_export (andrei)
34  *  2003-03-16  Added flags field to cmd_export_ (janakj)
35  *  2003-04-05  s/reply_route/failure_route, onreply_route introduced (jiri)
36  *  2004-03-12  extra flag USE_FUNC_PARAM added to modparam type -
37  *              instead of copying the param value, a func is called (bogdan)
38  *  2004-09-19  switched to version.h for the module versions checks (andrei)
39  *  2004-12-03  changed param_func_t to (modparam_t, void*), killed
40  *               param_func_param_t   (andrei)
41  *  2007-06-07  added PROC_INIT, called in the main process context
42  *               (same as PROC_MAIN), buf guaranteed to be called before
43  *               any other process is forked (andrei)
44  *  2008-11-17  sip-router version: includes some of the openser/kamailio
45  *               changes: f(void) instead of f(), free_fixup_function()
46  *              dual module interface support: ser & kamailio (andrei)
47  *  2008-11-18  prototypes for various fixed parameters numbers module
48  *               functions (3, 4, 5 & 6) and variable parameters (andrei)
49  *  2008-11-26  added fparam_free_contents() and fix_param_types (andrei)
50  */
51
52 /*!
53  * \file
54  * \brief modules/plug-in structures declarations
55  */
56
57
58 #ifndef sr_module_h
59 #define sr_module_h
60
61 #include <dlfcn.h>
62
63 #include "parser/msg_parser.h" /* for sip_msg */
64 #include "version.h"
65 #include "rpc.h"
66 #include "route_struct.h"
67 #include "route.h"
68 #include "str.h"
69
70 /* kamailio compat */
71 #include "statistics.h"
72 #include "mi/mi.h"
73 #include "pvar.h"
74
75
76
77 #if defined KAMAILIO_MOD_INTERFACE || defined OPENSER_MOD_INTERFACE || \
78         defined MOD_INTERFACE_V1
79
80 #define MODULE_INTERFACE_VER 1
81 #define cmd_export_t kam_cmd_export_t
82 #define module_exports kam_module_exports
83
84 #elif defined SER_MOD_INTERFACE || defined MOD_INTERFACE_V0
85
86 #define MODULE_INTERFACE_VER 0
87 #define cmd_export_t ser_cmd_export_t
88 #define module_exports ser_module_exports
89
90 #else
91
92 /* do nothing for core */
93
94 #endif
95
96 /** type used for the mod_register function export.
97  *  mod_register is a function called when loading a module
98  *  (if present), prior to registering the module exports.
99  *  @param path - path to the module, including file name
100  *  @param dlflags - pointer to the dlflags used when loading the module.
101  *                   If the value is changed to a different and non-zero
102  *                   value, the module will be reloaded with the new flags.
103  *  @param reserved1 - reserved for future use.
104  *  @param reserved2 - reserver for future use
105  *  @return 0 on success, -1 on error, all the other values are reserved
106  *                      for future use (<0 meaning error and >0 success)
107  */
108 typedef  int (*mod_register_function)(char*, int*, void*, void*);
109
110 typedef  struct module_exports* (*module_register)(void);
111 typedef  int (*cmd_function)(struct sip_msg*, char*, char*);
112 typedef  int (*cmd_function3)(struct sip_msg*, char*, char*, char*);
113 typedef  int (*cmd_function4)(struct sip_msg*, char*, char*, char*, char*);
114 typedef  int (*cmd_function5)(struct sip_msg*,  char*, char*, char*,
115                                                                                                 char*, char*);
116 typedef  int (*cmd_function6)(struct sip_msg*,  char*, char*, char*,
117                                                                                                 char*, char*, char*);
118 /* variable number of param module function, takes as param the sip_msg,
119    extra paremeters number and a pointer to an array of parameters */
120 typedef  int (*cmd_function_var)(struct sip_msg*, int no, action_u_t* vals );
121 typedef  int (*fixup_function)(void** param, int param_no);
122 typedef  int (*free_fixup_function)(void** param, int param_no);
123 typedef  int (*response_function)(struct sip_msg*);
124 typedef  void (*onbreak_function)(struct sip_msg*);
125 typedef void (*destroy_function)(void);
126
127 typedef int (*init_function)(void);
128 typedef int (*child_init_function)(int rank);
129
130
131 #define PARAM_STRING     (1U<<0)  /* String (char *) parameter type */
132 #define PARAM_INT        (1U<<1)  /* Integer parameter type */
133 #define PARAM_STR        (1U<<2)  /* struct str parameter type */
134 #define PARAM_USE_FUNC   (1U<<(8*sizeof(int)-1))
135 #define PARAM_TYPE_MASK(_x)   ((_x)&(~PARAM_USE_FUNC))
136
137 /* temporary, for backward compatibility only until all modules adjust it */
138 #define STR_PARAM PARAM_STRING
139 #define INT_PARAM PARAM_INT
140 #define USE_FUNC_PARAM PARAM_USE_FUNC
141
142 typedef unsigned int modparam_t;
143
144 typedef int (*param_func_t)( modparam_t type, void* val);
145
146 /* magic parameter number values */
147
148 #define NO_SCRIPT     -1    /* export not usable from scripts */
149 #define VAR_PARAM_NO  -128  /* function has variable number of parameters
150                                                            (see cmd_function_var for the prototype) */
151
152 /* Macros - used as rank in child_init function */
153 #define PROC_MAIN      0  /* Main ser process */
154 #define PROC_TIMER    -1  /* Timer attendant process */
155 #define PROC_RPC      -2  /* RPC type process */
156 #define PROC_FIFO      PROC_RPC  /* FIFO attendant process */
157 #define PROC_TCP_MAIN -4  /* TCP main process */
158 #define PROC_UNIXSOCK -5  /* Unix socket server */
159 #define PROC_ATTENDANT -10  /* main "attendant process */
160 #define PROC_INIT     -127 /* special rank, the context is the main ser
161                                                           process, but this is guaranteed to be executed
162                                                           before any process is forked, so it can be used
163                                                           to setup shared variables that depend on some
164                                                           after mod_init available information (e.g.
165                                                           total number of processes).
166                                                          WARNING: child_init(PROC_MAIN) is again called
167                                                          in the same process (main), but latter 
168                                                          (before tcp), so make sure you don't init things 
169                                                          twice, bot in PROC_MAIN and PROC_INT */
170 #define PROC_NOCHLDINIT -128 /* no child init functions will be called
171                                 if this rank is used in fork_process() */
172
173 #define PROC_MIN PROC_NOCHLDINIT /* Minimum process rank */
174
175
176 #define DEFAULT_DLFLAGS 0 /* value that signals to module loader to
177                                                         use default dlopen flags in Kamailio */
178 #ifndef RTLD_NOW
179 /* for openbsd */
180 #define RTLD_NOW DL_LAZY
181 #endif
182
183 #define KAMAILIO_DLFLAGS        RTLD_NOW
184
185
186 #define MODULE_VERSION \
187         char *module_version=SER_FULL_VERSION; \
188         char *module_flags=SER_COMPILE_FLAGS; \
189         unsigned int module_interface_ver=MODULE_INTERFACE_VER; 
190
191 /* ser version */
192 struct ser_cmd_export_ {
193         char* name;             /* null terminated command name */
194         cmd_function function;  /* pointer to the corresponding function */
195         int param_no;           /* number of parameters used by the function */
196         fixup_function fixup;   /* pointer to the function called to "fix" the
197                                                            parameters */
198         int flags;              /* Function flags */
199 };
200
201
202 /* kamailo/openser version */
203 struct kam_cmd_export_ {
204         char* name;             /* null terminated command name */
205         cmd_function function;  /* pointer to the corresponding function */
206         int param_no;           /* number of parameters used by the function */
207         fixup_function fixup;   /* pointer to the function called to "fix" the
208                                                            parameters */
209         free_fixup_function free_fixup; /* function called to free the "fixed"
210                                                                            parameters */
211         int flags;              /* Function flags */
212 };
213
214
215 /* members situated at the same place in memory in both ser & kamailio
216    cmd_export */
217 struct cmd_export_common_ {
218         char* name;
219         cmd_function function; 
220         int param_no;
221         fixup_function fixup;
222 };
223
224
225 struct param_export_ {
226         char* name;             /* null terminated param. name */
227         modparam_t type;        /* param. type */
228         void* param_pointer;    /* pointer to the param. memory location */
229 };
230
231
232
233 /** allowed parameter types.
234   * the types _must_ be in "fallback" order,
235   * e.g. FPARAM_STR should be the last to allow fallback to it,
236   *  F_PARAM_PVS should be in front of F_PARAM_AVP (so that
237   *  for fix_param_types(FPARAM_AVP|FPARAM_PVS|FPARAM_STR, param) and $foo
238   *  the pvars will be checked first and only if no pvar is found the
239   *  param will be resolved to an avp)
240   */
241 enum {
242         FPARAM_UNSPEC = 0,
243         FPARAM_INT    = (1 << 0),
244         FPARAM_SELECT = (1 << 1),
245         FPARAM_PVS    = (1 << 2),
246         FPARAM_AVP    = (1 << 3),
247         FPARAM_STRING = (1 << 4),
248         FPARAM_STR    = (1 << 5),
249         /* special types: no fallback between them possible */
250         FPARAM_REGEX  = (1 << 6),
251         FPARAM_SUBST  = (1 << 7),
252         FPARAM_PVE    = (1 << 8)
253 };
254
255 /*
256  * Function parameter
257  */
258 typedef struct fparam {
259         char* orig;                       /* The original value */
260         int type;                         /* Type of parameter */
261         union {
262                 char* asciiz;             /* Zero terminated ASCII string */
263                 struct _str str;          /* pointer/len string */
264                 int i;                    /* Integer value */
265                 regex_t* regex;           /* Compiled regular expression */
266                 avp_ident_t avp;          /* AVP identifier */
267                 select_t* select;         /* select structure */ 
268                 struct subst_expr* subst; /* Regex substitution */
269                 pv_spec_t* pvs;    /* kamailo pseudo-vars */
270                 pv_elem_t* pve;    /* kamailo pseudo-vars in a string */
271         } v;
272         void *fixed;
273 } fparam_t;
274
275
276 typedef struct param_export_ param_export_t;  
277 typedef struct ser_cmd_export_ ser_cmd_export_t;
278 typedef struct kam_cmd_export_ kam_cmd_export_t;
279 typedef struct cmd_export_common_ cmd_export_common_t;
280
281 union cmd_export_u{
282         cmd_export_common_t c; /* common members for everybody */
283         ser_cmd_export_t v0;
284         kam_cmd_export_t v1;
285 };
286
287
288 /* ser module exports version */
289 struct ser_module_exports {
290         char* name;                     /* null terminated module name */
291         ser_cmd_export_t* cmds;         /* null terminated array of the exported
292                                                                            commands */
293         rpc_export_t* rpc_methods;      /* null terminated array of exported rpc methods */
294         param_export_t* params;         /* null terminated array of the exported
295                                                                            module parameters */
296         init_function init_f;           /* Initialization function */
297         response_function response_f;   /* function used for responses,
298                                                                            returns yes or no; can be null */
299         destroy_function destroy_f;     /* function called when the module should
300                                                                            be "destroyed", e.g: on ser exit;
301                                                                            can be null */
302         onbreak_function onbreak_f;
303         child_init_function init_child_f;  /* function called by all processes
304                                                                                   after the fork */
305 };
306
307
308 /* kamailio/openser proc_export (missing from ser) */
309 typedef void (*mod_proc)(int no);
310
311 typedef int (*mod_proc_wrapper)(void);
312
313 struct proc_export_ {
314         char *name;
315         mod_proc_wrapper pre_fork_function;
316         mod_proc_wrapper post_fork_function;
317         mod_proc function;
318         unsigned int no;
319 };
320
321 typedef struct proc_export_ proc_export_t;
322
323
324 /* kamailio/openser module exports version */
325 struct kam_module_exports {
326         char* name;                     /* null terminated module name */
327         unsigned int dlflags;                   /*!< flags for dlopen  */
328         kam_cmd_export_t* cmds;                 /* null terminated array of the exported
329                                                                            commands */
330         param_export_t* params;                 /* null terminated array of the exported
331                                                                            module parameters */
332         stat_export_t* stats;                   /*!< null terminated array of the exported
333                                                                           module statistics */
334         mi_export_t* mi_cmds;                   /*!< null terminated array of the exported
335                                                                           MI functions */
336         pv_export_t* items;                             /*!< null terminated array of the exported
337                                                                            module items (pseudo-variables) */
338         proc_export_t* procs;                   /*!< null terminated array of the
339                                                                           additional processes required by the
340                                                                           module */
341         init_function init_f;           /* Initialization function */
342         response_function response_f;   /* function used for responses,
343                                                                            returns yes or no; can be null */
344         destroy_function destroy_f;     /* function called when the module should
345                                                                            be "destroyed", e.g: on ser exit;
346                                                                            can be null */
347         child_init_function init_child_f;  /* function called by all processes
348                                                                                   after the fork */
349 };
350
351
352
353 /* module exports in the same place in memory in both ser & kamailio */
354 struct module_exports_common{
355         char* name;
356 };
357
358
359 union module_exports_u {
360                 struct module_exports_common c; /*common members for all the versions*/
361                 struct ser_module_exports v0;
362                 struct kam_module_exports v1;
363 };
364
365
366 struct sr_module{
367         char* path;
368         void* handle;
369         unsigned int mod_interface_ver;
370         union module_exports_u* exports;
371         struct sr_module* next;
372 };
373
374
375 extern struct sr_module* modules; /* global module list*/
376 extern response_function* mod_response_cbks;/* response callback array */
377 extern int mod_response_cbk_no;    /* size of reponse callbacks array */
378
379 int register_builtin_modules(void);
380 /*int register_module(unsigned , struct module_exports*, char*,  void*);*/
381 int load_module(char* path);
382 union cmd_export_u* find_export_record(char* name, int param_no, int flags,
383                                                                                 unsigned *ver);
384 cmd_function find_export(char* name, int param_no, int flags);
385 cmd_function find_mod_export(char* mod, char* name, int param_no, int flags);
386 rpc_export_t* find_rpc_export(char* name, int flags);
387 void destroy_modules(void);
388 int init_child(int rank);
389 int init_modules(void);
390 struct sr_module* find_module_by_name(char* mod);
391
392 /* true if the module with name 'mod_name' is loaded */
393 #define module_loaded(mod_name) (find_module_by_name(mod_name)!=0)
394
395
396 /*! \brief
397  * Find a parameter with given type and return it's
398  * address in memory
399  * If there is no such parameter, NULL is returned
400  */
401 void* find_param_export(struct sr_module* mod, char* name, modparam_t type_mask, modparam_t *param_type);
402
403 /* modules function prototypes:
404  * struct module_exports* mod_register(); (type module_register)
405  * int   foo_cmd(struct sip_msg* msg, char* param);
406  *  - returns >0 if ok , <0 on error, 0 to stop processing (==DROP)
407  * int   response_f(struct sip_msg* msg)
408  *  - returns >0 if ok, 0 to drop message
409  */
410
411
412 /* API function to get other parameters from fixup */
413 action_u_t *fixup_get_param(void **cur_param, int cur_param_no, int required_param_no);
414 int fixup_get_param_count(void **cur_param, int cur_param_no);
415
416 int fix_flag( modparam_t type, void* val,
417                                         char* mod_name, char* param_name, int* flag);
418
419
420 /*
421  * Common function parameter fixups
422  */
423
424 /*
425  * Generic parameter fixup function which creates
426  * fparam_t structure. type parameter contains allowed
427  * parameter types
428  */
429 int fix_param(int type, void** param);
430 void fparam_free_contents(fparam_t* fp);
431
432 /** fix a param to one of the given types (mask).
433   */
434 int fix_param_types(int types, void** param);
435
436 /*
437  * Fixup variable string, the parameter can be
438  * AVP, SELECT, or ordinary string. AVP and select
439  * identifiers will be resolved to their values during
440  * runtime
441  *
442  * The parameter value will be converted to fparam structure
443  * This function returns -1 on an error
444  */
445 int fixup_var_str_12(void** param, int param_no);
446
447 /* Same as fixup_var_str_12 but applies to the 1st parameter only */
448 int fixup_var_str_1(void** param, int param_no);
449
450 /* Same as fixup_var_str_12 but applies to the 2nd parameter only */
451 int fixup_var_str_2(void** param, int param_no);
452
453 /*
454  * Fixup variable integer, the parameter can be
455  * AVP, SELECT, or ordinary integer. AVP and select
456  * identifiers will be resolved to their values and 
457  * converted to int if necessary during runtime
458  *
459  * The parameter value will be converted to fparam structure
460  * This function returns -1 on an error
461  */
462 int fixup_var_int_12(void** param, int param_no);
463
464 /* Same as fixup_var_int_12 but applies to the 1st parameter only */
465 int fixup_var_int_1(void** param, int param_no);
466
467 /* Same as fixup_var_int_12 but applies to the 2nd parameter only */
468 int fixup_var_int_2(void** param, int param_no);
469
470 /*
471  * The parameter must be a regular expression which must compile, the
472  * parameter will be converted to compiled regex
473  */
474 int fixup_regex_12(void** param, int param_no);
475
476 /* Same as fixup_regex_12 but applies to the 1st parameter only */
477 int fixup_regex_1(void** param, int param_no);
478
479 /* Same as fixup_regex_12 but applies to the 2nd parameter only */
480 int fixup_regex_2(void** param, int param_no);
481
482 /*
483  * The string parameter will be converted to integer
484  */
485 int fixup_int_12(void** param, int param_no);
486
487 /* Same as fixup_int_12 but applies to the 1st parameter only */
488 int fixup_int_1(void** param, int param_no);
489
490 /* Same as fixup_int_12 but applies to the 2nd parameter only */
491 int fixup_int_2(void** param, int param_no);
492
493 /*
494  * Parse the parameter as static string, do not resolve
495  * AVPs or selects, convert the parameter to str structure
496  */
497 int fixup_str_12(void** param, int param_no);
498
499 /* Same as fixup_str_12 but applies to the 1st parameter only */
500 int fixup_str_1(void** param, int param_no);
501
502 /* Same as fixup_str_12 but applies to the 2nd parameter only */
503 int fixup_str_2(void** param, int param_no);
504
505 /*
506  * Get the function parameter value as string
507  * Return values:  0 - Success
508  *                -1 - Cannot get value
509  */
510 int get_str_fparam(str* dst, struct sip_msg* msg, fparam_t* param);
511
512 /*
513  * Get the function parameter value as integer
514  * Return values:  0 - Success
515  *                -1 - Cannot get value
516  */
517 int get_int_fparam(int* dst, struct sip_msg* msg, fparam_t* param);
518
519
520 /**
521  * Retrieve the compiled RegExp.
522  * @return: 0 for success, negative on error.
523  */
524 int get_regex_fparam(regex_t *dst, struct sip_msg* msg, fparam_t* param);
525
526
527 #endif /* sr_module_h */