- applied patch from Dragos Vingarzan <vingarzan@fokus.fraunhofer.de> which
[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  */
42
43
44 #ifndef sr_module_h
45 #define sr_module_h
46
47 #include "parser/msg_parser.h" /* for sip_msg */
48 #include "version.h"
49 #include "rpc.h"
50 #include "route_struct.h"
51 #include "str.h"
52
53 typedef  struct module_exports* (*module_register)();
54 typedef  int (*cmd_function)(struct sip_msg*, char*, char*);
55 typedef  int (*fixup_function)(void** param, int param_no);
56 typedef  int (*response_function)(struct sip_msg*);
57 typedef  void (*onbreak_function)(struct sip_msg*);
58 typedef void (*destroy_function)();
59 typedef int (*init_function)(void);
60 typedef int (*child_init_function)(int rank);
61
62
63 #define PARAM_STRING     (1U<<0)  /* String (char *) parameter type */
64 #define PARAM_INT        (1U<<1)  /* Integer parameter type */
65 #define PARAM_STR        (1U<<2)  /* struct str parameter type */
66 #define PARAM_USE_FUNC   (1U<<(8*sizeof(int)-1))
67 #define PARAM_TYPE_MASK(_x)   ((_x)&(~PARAM_USE_FUNC))
68
69 /* temporary, for backward compatibility only until all modules adjust it */
70 #define STR_PARAM PARAM_STRING
71 #define INT_PARAM PARAM_INT
72 #define USE_FUNC_PARAM PARAM_USE_FUNC
73
74 typedef unsigned int modparam_t;
75
76 typedef int (*param_func_t)( modparam_t type, void* val);
77
78 #define REQUEST_ROUTE 1  /* Function can be used in request route blocks */
79 #define FAILURE_ROUTE 2  /* Function can be used in reply route blocks */
80 #define ONREPLY_ROUTE 4  /* Function can be used in on_reply */
81 #define BRANCH_ROUTE  8  /* Function can be used in branch_route blocks */
82 #define ONSEND_ROUTE   16  /* Function can be used in onsend_route blocks */
83
84 /* Macros - used as rank in child_init function */
85 #define PROC_MAIN      0  /* Main ser process */
86 #define PROC_TIMER    -1  /* Timer attendant process */
87 #define PROC_FIFO     -2  /* FIFO attendant process */
88 #define PROC_TCP_MAIN -4  /* TCP main process */
89 #define PROC_UNIXSOCK -5  /* Unix socket server */
90 #define PROC_NOCHLDINIT -128 /* no child init functions will be called
91                                 if this rank is used in fork_process() */
92
93 #define PROC_MIN PROC_UNIXSOCK /* Minimum process rank */
94
95 #define MODULE_VERSION \
96         char *module_version=SER_FULL_VERSION; \
97         char *module_flags=SER_COMPILE_FLAGS;
98
99 struct cmd_export_ {
100         char* name;             /* null terminated command name */
101         cmd_function function;  /* pointer to the corresponding function */
102         int param_no;           /* number of parameters used by the function */
103         fixup_function fixup;   /* pointer to the function called to "fix" the
104                                                            parameters */
105         int flags;              /* Function flags */
106 };
107
108
109 struct param_export_ {
110         char* name;             /* null terminated param. name */
111         modparam_t type;        /* param. type */
112         void* param_pointer;    /* pointer to the param. memory location */
113 };
114
115
116 enum {
117         FPARAM_UNSPEC = 0,
118         FPARAM_STRING = (1 << 0),
119         FPARAM_STR    = (1 << 1),
120         FPARAM_INT    = (1 << 2),
121         FPARAM_REGEX  = (1 << 3),
122         FPARAM_AVP    = (1 << 5),
123         FPARAM_SELECT = (1 << 6),
124         FPARAM_SUBST  = (1 << 7)
125 };
126
127 /*
128  * Function parameter
129  */
130 typedef struct fparam {
131         char* orig;                       /* The original value */
132         int type;                         /* Type of parameter */
133         union {
134                 char* asciiz;             /* Zero terminated ASCII string */
135                 struct _str str;          /* pointer/len string */
136                 int i;                    /* Integer value */
137                 regex_t* regex;           /* Compiled regular expression */
138                 avp_ident_t avp;          /* AVP identifier */
139                 select_t* select;         /* select structure */ 
140                 struct subst_expr* subst; /* Regex substitution */
141         } v;
142 } fparam_t;
143
144
145 typedef struct cmd_export_ cmd_export_t;
146 typedef struct param_export_ param_export_t;
147
148 struct module_exports {
149         char* name;                     /* null terminated module name */
150
151         cmd_export_t* cmds;             /* null terminated array of the exported
152                                                                            commands */
153         rpc_export_t* rpc_methods;      /* null terminated array of exported rpc methods */
154         param_export_t* params;         /* null terminated array of the exported
155                                                                            module parameters */
156
157         init_function init_f;           /* Initialization function */
158         response_function response_f;   /* function used for responses,
159                                                                            returns yes or no; can be null */
160         destroy_function destroy_f;     /* function called when the module should
161                                                                            be "destroyed", e.g: on ser exit;
162                                                                            can be null */
163         onbreak_function onbreak_f;
164         child_init_function init_child_f;  /* function called by all processes
165                                                                                   after the fork */
166 };
167
168
169 struct sr_module{
170         char* path;
171         void* handle;
172         struct module_exports* exports;
173         struct sr_module* next;
174 };
175
176
177 struct sr_module* modules; /* global module list*/
178
179 int register_builtin_modules();
180 int register_module(struct module_exports*, char*,  void*);
181 int load_module(char* path);
182 cmd_export_t* find_export_record(char* name, int param_no, int flags);
183 cmd_function find_export(char* name, int param_no, int flags);
184 cmd_function find_mod_export(char* mod, char* name, int param_no, int flags);
185 rpc_export_t* find_rpc_export(char* name, int flags);
186 void destroy_modules();
187 int init_child(int rank);
188 int init_modules(void);
189 struct sr_module* find_module_by_name(char* mod);
190
191 /*
192  * Find a parameter with given type and return it's
193  * address in memory
194  * If there is no such parameter, NULL is returned
195  */
196 void* find_param_export(struct sr_module* mod, char* name, modparam_t type_mask, modparam_t *param_type);
197
198 /* modules function prototypes:
199  * struct module_exports* mod_register(); (type module_register)
200  * int   foo_cmd(struct sip_msg* msg, char* param);
201  *  - returns >0 if ok , <0 on error, 0 to stop processing (==DROP)
202  * int   response_f(struct sip_msg* msg)
203  *  - returns >0 if ok, 0 to drop message
204  */
205
206
207 /* API function to get other parameters from fixup */
208 action_u_t *fixup_get_param(void **cur_param, int cur_param_no, int required_param_no);
209 int fixup_get_param_count(void **cur_param, int cur_param_no);
210
211 int fix_flag( modparam_t type, void* val,
212                                         char* mod_name, char* param_name, int* flag);
213
214
215 /*
216  * Common function parameter fixups
217  */
218
219 /*
220  * Generic parameter fixup function which creates
221  * fparam_t structure. type parameter contains allowed
222  * parameter types
223  */
224 int fix_param(int type, void** param);
225
226 /*
227  * Fixup variable string, the parameter can be
228  * AVP, SELECT, or ordinary string. AVP and select
229  * identifiers will be resolved to their values during
230  * runtime
231  *
232  * The parameter value will be converted to fparam structure
233  * This function returns -1 on an error
234  */
235 int fixup_var_str_12(void** param, int param_no);
236
237 /* Same as fixup_var_str_12 but applies to the 1st parameter only */
238 int fixup_var_str_1(void** param, int param_no);
239
240 /* Same as fixup_var_str_12 but applies to the 2nd parameter only */
241 int fixup_var_str_2(void** param, int param_no);
242
243 /*
244  * Fixup variable integer, the parameter can be
245  * AVP, SELECT, or ordinary integer. AVP and select
246  * identifiers will be resolved to their values and 
247  * converted to int if necessary during runtime
248  *
249  * The parameter value will be converted to fparam structure
250  * This function returns -1 on an error
251  */
252 int fixup_var_int_12(void** param, int param_no);
253
254 /* Same as fixup_var_int_12 but applies to the 1st parameter only */
255 int fixup_var_int_1(void** param, int param_no);
256
257 /* Same as fixup_var_int_12 but applies to the 2nd parameter only */
258 int fixup_var_int_2(void** param, int param_no);
259
260 /*
261  * The parameter must be a regular expression which must compile, the
262  * parameter will be converted to compiled regex
263  */
264 int fixup_regex_12(void** param, int param_no);
265
266 /* Same as fixup_regex_12 but applies to the 1st parameter only */
267 int fixup_regex_1(void** param, int param_no);
268
269 /* Same as fixup_regex_12 but applies to the 2nd parameter only */
270 int fixup_regex_2(void** param, int param_no);
271
272 /*
273  * The string parameter will be converted to integer
274  */
275 int fixup_int_12(void** param, int param_no);
276
277 /* Same as fixup_int_12 but applies to the 1st parameter only */
278 int fixup_int_1(void** param, int param_no);
279
280 /* Same as fixup_int_12 but applies to the 2nd parameter only */
281 int fixup_int_2(void** param, int param_no);
282
283 /*
284  * Parse the parameter as static string, do not resolve
285  * AVPs or selects, convert the parameter to str structure
286  */
287 int fixup_str_12(void** param, int param_no);
288
289 /* Same as fixup_str_12 but applies to the 1st parameter only */
290 int fixup_str_1(void** param, int param_no);
291
292 /* Same as fixup_str_12 but applies to the 2nd parameter only */
293 int fixup_str_2(void** param, int param_no);
294
295 /*
296  * Get the function parameter value as string
297  * Return values:  0 - Success
298  *                -1 - Cannot get value
299  */
300 int get_str_fparam(str* dst, struct sip_msg* msg, fparam_t* param);
301
302 /*
303  * Get the function parameter value as integer
304  * Return values:  0 - Success
305  *                -1 - Cannot get value
306  */
307 int get_int_fparam(int* dst, struct sip_msg* msg, fparam_t* param);
308
309 #endif /* sr_module_h */