1 /* 2 * Copyright (C) 2001-2003 FhG Fokus 3 * 4 * This file is part of Kamailio, a free SIP server. 5 * 6 * Kamailio is free software; you can redistribute it and/or modify 7 * it under the terms of the GNU General Public License as published by 8 * the Free Software Foundation; either version 2 of the License, or 9 * (at your option) any later version 10 * 11 * Kamailio is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 * GNU General Public License for more details. 15 * 16 * You should have received a copy of the GNU General Public License 17 * along with this program; if not, write to the Free Software 18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 19 */ 20 21 /** 22 * @file 23 * @brief Kamailio core :: modules loading, structures declarations and utilities 24 * @ingroup core 25 * Module: \ref core 26 */ 27 28 29 #ifndef sr_module_h 30 #define sr_module_h 31 32 #include <dlfcn.h> 33 34 #include "parser/msg_parser.h" /* for sip_msg */ 35 #include "ver_defs.h" 36 #include "rpc.h" 37 #include "route_struct.h" 38 #include "route.h" 39 #include "str.h" 40 41 /* kamailio compat */ 42 #include "counters.h" 43 #include "pvar.h" 44 45 #define MODULE_INTERFACE_VER 4 46 47 /** 48 * @brief type used for the mod_register function export 49 * 50 * mod_register is a function called when loading a module 51 * (if present), prior to registering the module exports. 52 * @param path path to the module, including file name 53 * @param dlflags pointer to the dlflags used when loading the module. 54 * If the value is changed to a different and non-zero value, the 55 * module will be reloaded with the new flags. 56 * @param reserved1 - reserved for future use. 57 * @param reserved2 - reserved for future use 58 * @return 0 on success, -1 on error, all the other values are reserved 59 * for future use (<0 meaning error and >0 success) 60 */ 61 typedef int (*mod_register_function)(char* path, int* dlflags, void* reserved1, 62 void* reserved2); 63 64 typedef struct module_exports* (*module_register)(void); 65 66 /** 67 * @brief main two parameter module function 68 * 69 * Main two parameter module function, default and oldest version. 70 * @param sip_msg SIP message 71 * @param param1 first parameter 72 * @param param2 second parameter 73 * @return positive on success, negative on error, 0 to stop processing (drop message) 74 */ 75 typedef int (*cmd_function)(struct sip_msg*, char* param1, char* param2); 76 typedef int (*cmd_function3)(struct sip_msg*, char*, char*, char*); 77 typedef int (*cmd_function4)(struct sip_msg*, char*, char*, char*, char*); 78 typedef int (*cmd_function5)(struct sip_msg*, char*, char*, char*, 79 char*, char*); 80 typedef int (*cmd_function6)(struct sip_msg*, char*, char*, char*, 81 char*, char*, char*); 82 /** 83 * @brief variable number of parameter module function 84 * 85 * Variable number of parameter module function, takes as param the sip_msg, 86 * extra parameters number and a pointer to an array of parameters 87 * @param sip_msg SIP message 88 * @param no extra parameters number 89 * @param vals extra parameters 90 * @return positive on success, negative on error, 0 to stop processing (drop message) 91 */ 92 typedef int (*cmd_function_var)(struct sip_msg*, int no, action_u_t* vals ); 93 typedef int (*fixup_function)(void** param, int param_no); 94 typedef int (*free_fixup_function)(void** param, int param_no); 95 96 /** 97 * @brief response module function prototype 98 * @param sip_msg SIP message 99 * @return positive if ok, 0 to stop processing 100 */ 101 typedef int (*response_function)(struct sip_msg*); 102 typedef void (*onbreak_function)(struct sip_msg*); 103 typedef void (*destroy_function)(void); 104 105 typedef int (*init_function)(void); 106 typedef int (*child_init_function)(int rank); 107 108 109 #define PARAM_STRING (1U<<0) /**< String (char *) parameter type */ 110 #define PARAM_INT (1U<<1) /**< Integer parameter type */ 111 #define PARAM_STR (1U<<2) /**< struct str parameter type */ 112 #define PARAM_USE_FUNC (1U<<(8*sizeof(int)-1)) 113 #define PARAM_TYPE_MASK(_x) ((_x)&(~PARAM_USE_FUNC)) 114 115 /* temporary, for backward compatibility only until all modules adjust it */ 116 #define STR_PARAM PARAM_STRING 117 #define INT_PARAM PARAM_INT 118 #define USE_FUNC_PARAM PARAM_USE_FUNC 119 120 typedef unsigned int modparam_t; 121 122 typedef int (*param_func_t)( modparam_t type, void* val); 123 124 /* magic parameter number values */ 125 126 #define NO_SCRIPT -1 /**< export not usable from scripts */ 127 #define VAR_PARAM_NO -128 /**< function has variable number of parameters 128 (see cmd_function_var for the prototype) */ 129 130 /** 131 * special fixup function flags fparam fixup, rve ready, 132 * they are kept in the first 2 bits inside the pointer 133 */ 134 #define FIXUP_F_FPARAM_RVE (unsigned long)1 135 136 #define call_fixup(fixup, param, param_no) \ 137 ((fixup) ? (fixup)(param, param_no) : 0) 138 139 /* Macros - used as rank in child_init function */ 140 #define PROC_MAIN 0 /**< Main ser process */ 141 #define PROC_TIMER -1 /**< Timer attendant process */ 142 #define PROC_RPC -2 /**< RPC type process */ 143 #define PROC_FIFO PROC_RPC /**< FIFO attendant process */ 144 #define PROC_TCP_MAIN -4 /**< TCP main process */ 145 #define PROC_UNIXSOCK -5 /**< Unix socket server */ 146 #define PROC_ATTENDANT -10 /**< main "attendant process */ 147 #define PROC_INIT -127 /**< special rank, the context is the main ser 148 process, but this is guaranteed to be executed 149 before any process is forked, so it can be used 150 to setup shared variables that depend on some 151 after mod_init available information (e.g. 152 total number of processes). 153 @warning child_init(PROC_MAIN) is again called 154 in the same process (main), but latter 155 (before tcp), so make sure you don't init things 156 twice, bot in PROC_MAIN and PROC_INT */ 157 #define PROC_NOCHLDINIT -128 /**< no child init functions will be called 158 if this rank is used in fork_process() */ 159 160 #define PROC_SIPINIT 1 /**< First (special) SIP worker - some modules do 161 special processing in this child, like loading db data */ 162 #define PROC_SIPROUTER 2 /**< First (pure) SIP worker - can be used to check 163 if just a normal sip router or initialize custom worker 164 processes by starting from this value */ 165 #define PROC_RANK127 127 /**< Used to init RPC worker as SIP commands 166 handler. Don't do any special processing in the 167 child init with this rank - just bare child 168 initialization */ 169 170 #define PROC_SIPRPC PROC_RANK127 171 172 #define PROC_XWORKER PROC_RANK127 173 174 #define PROC_MIN PROC_NOCHLDINIT /**< Minimum process rank */ 175 176 177 #define DEFAULT_DLFLAGS 0 /**< value that signals to module loader to 178 use default dlopen flags in Kamailio */ 179 #ifndef RTLD_NOW 180 /* for openbsd */ 181 #define RTLD_NOW DL_LAZY 182 #endif 183 184 #define KAMAILIO_DLFLAGS RTLD_NOW 185 186 187 #define MODULE_VERSION \ 188 char *module_version=SER_FULL_VERSION; \ 189 char *module_flags=SER_COMPILE_FLAGS; \ 190 unsigned int module_interface_ver=MODULE_INTERFACE_VER; 191 192 193 /** kamailio/openser version */ 194 typedef struct cmd_export { 195 char* name; /**< null terminated command name */ 196 cmd_function function; /**< pointer to the corresponding function */ 197 int param_no; /**< number of parameters used by the function */ 198 fixup_function fixup; /**< pointer to the function called to "fix" the 199 parameters */ 200 free_fixup_function free_fixup; /**< function called to free the "fixed" 201 parameters */ 202 unsigned int flags; /**< Function flags */ 203 } cmd_export_t; 204 205 /** sip-router version */ 206 typedef struct ksr_cmd_export { 207 char* name; /**< null terminated command name */ 208 cmd_function function; /**< pointer to the corresponding function */ 209 int param_no; /**< number of parameters used by the function */ 210 fixup_function fixup; /**< pointer to the function called to "fix" the 211 parameters */ 212 free_fixup_function free_fixup; /**< function called to free the "fixed" 213 parameters */ 214 unsigned int flags; /**< Function flags */ 215 unsigned int fixup_flags; 216 void* module_exports; /**< pointer to module structure */ 217 } ksr_cmd_export_t; 218 219 220 typedef struct param_export { 221 char* name; /**< null terminated param. name */ 222 modparam_t type; /**< param. type */ 223 void* param_pointer; /**< pointer to the param. memory location */ 224 } param_export_t; 225 226 227 /* 228 * Allowed parameter types, the types _must_ be in "fallback" order, 229 * e.g. FPARAM_STR should be the last to allow fallback to it, 230 * F_PARAM_PVS should be in front of F_PARAM_AVP (so that 231 * for fix_param_types(FPARAM_AVP|FPARAM_PVS|FPARAM_STR, param) and $foo 232 * the pvars will be checked first and only if no pvar is found the 233 * param will be resolved to an avp) 234 */ 235 enum { 236 FPARAM_UNSPEC = 0, 237 FPARAM_INT = (1 << 0), 238 FPARAM_SELECT = (1 << 1), 239 FPARAM_PVS = (1 << 2), 240 FPARAM_AVP = (1 << 3), 241 FPARAM_STRING = (1 << 4), 242 FPARAM_STR = (1 << 5), 243 /* special types: no fallback between them possible */ 244 FPARAM_REGEX = (1 << 6), 245 FPARAM_SUBST = (1 << 7), 246 FPARAM_PVE = (1 << 8) 247 }; 248 249 /** 250 * Function parameter 251 */ 252 typedef struct fparam { 253 char* orig; /**< The original value */ 254 int type; /**< Type of parameter */ 255 union { 256 char* asciiz; /**< Zero terminated ASCII string */ 257 struct _str str; /**< pointer/len string */ 258 int i; /**< Integer value */ 259 regex_t* regex; /**< Compiled regular expression */ 260 avp_ident_t avp; /**< AVP identifier */ 261 select_t* select; /**< select structure */ 262 struct subst_expr* subst; /**< Regex substitution */ 263 pv_spec_t* pvs; /**< kamailio pseudo-vars */ 264 pv_elem_t* pve; /**< kamailio pseudo-vars in a string */ 265 } v; 266 void *fixed; 267 } fparam_t; 268 269 /** kamailio module exports version */ 270 typedef struct module_exports { 271 /**< null terminated module name */ 272 char* name; 273 /**< flags for dlopen */ 274 unsigned int dlflags; 275 /**< null terminated array of the exported commands (config functions)*/ 276 cmd_export_t* cmds; 277 /**< null terminated array of the exported module parameters */ 278 param_export_t* params; 279 /**< null terminated array of exported rpc methods */ 280 rpc_export_t* rpc_methods; 281 /*!< null terminated array of the exported module items (pseudo-variables) */ 282 pv_export_t* pv_items; 283 /**< function used for responses, returns yes or no; can be null */ 284 response_function response_f; 285 /**< Initialization function */ 286 init_function init_mod_f; 287 /**< function called by all processes after the fork */ 288 child_init_function init_child_f; 289 /**< function called when the module is "destroyed" (on server shut down) */ 290 destroy_function destroy_mod_f; 291 } module_exports_t; 292 293 294 /** kamailio module exports version coverted for core operations */ 295 typedef struct ksr_module_exports { 296 /**< null terminated module name */ 297 char* name; 298 /**< flags for dlopen */ 299 unsigned int dlflags; 300 /**< null terminated array of the exported commands (config functions)*/ 301 ksr_cmd_export_t* cmds; 302 /**< null terminated array of the exported module parameters */ 303 param_export_t* params; 304 /**< null terminated array of exported rpc methods */ 305 rpc_export_t* rpc_methods; 306 /*!< null terminated array of the exported module items (pseudo-variables) */ 307 pv_export_t* pv_items; 308 /**< function used for responses, returns yes or no; can be null */ 309 response_function response_f; 310 /**< Initialization function */ 311 init_function init_mod_f; 312 /**< function called by all processes after the fork */ 313 child_init_function init_child_f; 314 /**< function called when the module is "destroyed" (on server shut down) */ 315 destroy_function destroy_mod_f; 316 } ksr_module_exports_t; 317 318 typedef struct sr_module { 319 char* path; 320 void* handle; 321 ksr_module_exports_t exports; 322 struct sr_module* next; 323 } sr_module_t; 324 325 326 extern struct sr_module* modules; /**< global module list*/ 327 extern response_function* mod_response_cbks; /**< response callback array */ 328 extern int mod_response_cbk_no; /**< size of reponse callbacks array */ 329 330 int register_builtin_modules(void); 331 int load_module(char* path); 332 ksr_cmd_export_t* find_export_record(char* name, int param_no, int flags); 333 cmd_function find_export(char* name, int param_no, int flags); 334 cmd_function find_mod_export(char* mod, char* name, int param_no, int flags); 335 rpc_export_t* find_rpc_export(char* name, int flags); 336 void destroy_modules(void); 337 int init_child(int rank); 338 int init_modules(void); 339 struct sr_module* find_module_by_name(char* mod); 340 sr_module_t* get_loaded_modules(void); 341 342 /**< true if the module with name 'mod_name' is loaded */ 343 #define module_loaded(mod_name) (find_module_by_name(mod_name)!=0) 344 345 346 /** 347 * @brief Find a parameter with given type 348 * @param mod module 349 * @param name parameter name 350 * @param type_mask parameter mask 351 * @param param_type parameter type 352 * @return parameter address in memory, if there is no such parameter, NULL is returned 353 */ 354 void* find_param_export(struct sr_module* mod, char* name, modparam_t type_mask, 355 modparam_t *param_type); 356 357 358 /** API function to get other parameters from fixup */ 359 action_u_t *fixup_get_param(void **cur_param, int cur_param_no, 360 int required_param_no); 361 int fixup_get_param_count(void **cur_param, int cur_param_no); 362 363 int fix_flag( modparam_t type, void* val, 364 char* mod_name, char* param_name, int* flag); 365 366 367 /* 368 * Common function parameter fixups 369 */ 370 371 /** 372 * @brief Generic parameter fixup function 373 * 374 * Generic parameter fixup function which creates fparam_t structure. 375 * Type parameter contains allowed parameter types. 376 * @param type parameter type 377 * @param param fixed parameter 378 * @return 0 on success, -1 on error 379 */ 380 int fix_param(int type, void** param); 381 void fparam_free_contents(fparam_t* fp); 382 383 /** fix a param to one of the given types (mask). 384 */ 385 int fix_param_types(int types, void** param); 386 387 /** 388 * @brief Fixup variable string, 389 * 390 * Fixup variable string, the parameter can be AVP, SELECT, or ordinary 391 * string. AVP and select identifiers will be resolved to their values 392 * during runtime. The parameter value will be converted to fparam structure. 393 * @param param fixed parameter value 394 * @param param_no number of parameter 395 * @return 0 on success, -1 on an error 396 */ 397 int fixup_var_str_12(void** param, int param_no); 398 399 /** Same as fixup_var_str_12 but applies to the 1st parameter only */ 400 int fixup_var_str_1(void** param, int param_no); 401 402 /** Same as fixup_var_str_12 but applies to the 2nd parameter only */ 403 int fixup_var_str_2(void** param, int param_no); 404 405 /** fixup variable-pve-only-string. */ 406 int fixup_var_pve_12(void** param, int param_no); 407 408 /** fixup variable-pve-string. 409 * The parameter can be a PVAR, AVP, SELECT, PVE (pv based format string) 410 * or string. 411 */ 412 int fixup_var_pve_str_12(void** param, int param_no); 413 414 /** same as fixup_var_pve_str_12 but applies to the 1st parameter only */ 415 int fixup_var_pve_str_1(void** param, int param_no); 416 417 /** same as fixup_var_pve_str_12 but applies to the 2nd parameter only */ 418 int fixup_var_pve_str_2(void** param, int param_no); 419 420 /** 421 * @brief Fixup variable integer 422 * 423 * Fixup variable integer, the parameter can be AVP, SELECT, or ordinary 424 * integer. AVP and select identifiers will be resolved to their values 425 * and converted to int if necessary during runtime. The parameter value will 426 * be converted to fparam structure 427 * @param param fixed parameter value 428 * @param param_no number of parameter 429 * @return 0 on success, -1 on an error 430 */ 431 int fixup_var_int_12(void** param, int param_no); 432 433 /** Same as fixup_var_int_12 but applies to the 1st parameter only */ 434 int fixup_var_int_1(void** param, int param_no); 435 436 /** Same as fixup_var_int_12 but applies to the 2nd parameter only */ 437 int fixup_var_int_2(void** param, int param_no); 438 439 /** 440 * The parameter must be a regular expression which must compile, the 441 * parameter will be converted to compiled regex 442 */ 443 int fixup_regex_12(void** param, int param_no); 444 445 /** Same as fixup_regex_12 but applies to the 1st parameter only */ 446 int fixup_regex_1(void** param, int param_no); 447 448 /** Same as fixup_regex_12 but applies to the 2nd parameter only */ 449 int fixup_regex_2(void** param, int param_no); 450 451 /** 452 * The string parameter will be converted to integer 453 */ 454 int fixup_int_12(void** param, int param_no); 455 456 /** Same as fixup_int_12 but applies to the 1st parameter only */ 457 int fixup_int_1(void** param, int param_no); 458 459 /** Same as fixup_int_12 but applies to the 2nd parameter only */ 460 int fixup_int_2(void** param, int param_no); 461 462 /** 463 * Parse the parameter as static string, do not resolve 464 * AVPs or selects, convert the parameter to str structure 465 */ 466 int fixup_str_12(void** param, int param_no); 467 468 /** Same as fixup_str_12 but applies to the 1st parameter only */ 469 int fixup_str_1(void** param, int param_no); 470 471 /** Same as fixup_str_12 but applies to the 2nd parameter only */ 472 int fixup_str_2(void** param, int param_no); 473 474 /** 475 * @brief Get the function parameter value as string 476 * @param dst string destination 477 * @param msg SIP message 478 * @param param function parameters 479 * @return 0 on success, 1 on error, e.g. cannot get value 480 */ 481 int get_str_fparam(str* dst, struct sip_msg* msg, fparam_t* param); 482 483 /** 484 * @brief Get the function parameter value as integer 485 * @param dst string destination 486 * @param msg SIP message 487 * @param param function parameters 488 * @return 0 on success, 1 on error, e.g. cannot get value 489 */ 490 int get_int_fparam(int* dst, struct sip_msg* msg, fparam_t* param); 491 492 /** 493 * @brief Get the function parameter value as integer/string 494 * @param i_dst int destination 495 * @param s_dst string destination 496 * @param msg SIP message 497 * @param param function parameters 498 * @param flags flags to indicate destinations 499 * @return 0 on success, 1 on error, e.g. cannot get value 500 */ 501 int get_is_fparam(int* i_dst, str* s_dst, struct sip_msg* msg, fparam_t* param, 502 unsigned int *flags); 503 504 /** 505 * @brief Get the function parameter value as compiled regular expression 506 * @param dst string destination 507 * @param msg SIP message 508 * @param param function parameters 509 * @return 0 on success, 1 on error, e.g. cannot get value 510 */ 511 int get_regex_fparam(regex_t *dst, struct sip_msg* msg, fparam_t* param); 512 513 514 int is_fparam_rve_fixup(fixup_function f); 515 516 /** 517 * @brief Generic free fixup type function for a fixed fparam 518 * 519 * Generic free fixup type function for a fixed fparam. It will free whatever 520 * was allocated during the initial fparam fixup and restore the original param 521 * value. 522 * @param param freed parameters 523 */ 524 void fparam_free_restore(void** param); 525 int fixup_free_fparam_all(void** param, int param_no); 526 int fixup_free_fparam_1(void** param, int param_no); 527 int fixup_free_fparam_2(void** param, int param_no); 528 529 /** 530 * @brief returns the corresponding fixup_free* for various known fixup types 531 * 532 * Returns the corresponding fixup_free* for various known fixup types. 533 * Used to automatically fill in free_fixup* functions. 534 * @param f fixup function pointer 535 * @return free fixup function pointer on success, 0 on failure (unknown 536 * fixup or no free fixup function). 537 */ 538 free_fixup_function get_fixup_free(fixup_function f); 539 540 void set_child_sip_rpc_mode(void); 541 void set_child_rpc_sip_mode(void); 542 int is_sip_worker(int rank); 543 int is_rpc_worker(int rank); 544 545 unsigned int set_modinit_delay(unsigned int v); 546 int destroy_modules_phase(void); 547 int ksr_shutdown_phase_init(void); 548 int ksr_shutdown_phase(void); 549 550 #endif /* sr_module_h */ 551