git.sip-router.org Git - sip-router/blob - 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 /* special fixup function flags.
 153  * They are kept in the first 2 bits inside the pointer
 154  */
 155 #define FIXUP_F_FPARAM_RVE (unsigned long)1 /* fparam fixup, rve ready */
 156
 157 #define call_fixup(fixup, param, param_no) \
 158         ((fixup) ? (fixup)(param, param_no) : 0)
 159
 160 /* Macros - used as rank in child_init function */
 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
 169                                                           process, but this is guaranteed to be executed
 170                                                           before any process is forked, so it can be used
 171                                                           to setup shared variables that depend on some
 172                                                           after mod_init available information (e.g.
 173                                                           total number of processes).
 174                                                          WARNING: child_init(PROC_MAIN) is again called
 175                                                          in the same process (main), but latter
 176                                                          (before tcp), so make sure you don't init things
 177                                                          twice, bot in PROC_MAIN and PROC_INT */
 178 #define PROC_NOCHLDINIT -128 /* no child init functions will be called
 179                                 if this rank is used in fork_process() */
 180
 181 #define PROC_MIN PROC_NOCHLDINIT /* Minimum process rank */
 182
 183
 184 #define DEFAULT_DLFLAGS 0 /* value that signals to module loader to
 185                                                         use default dlopen flags in Kamailio */
 186 #ifndef RTLD_NOW
 187 /* for openbsd */
 188 #define RTLD_NOW DL_LAZY
 189 #endif
 190
 191 #define KAMAILIO_DLFLAGS        RTLD_NOW
 192
 193
 194 #define MODULE_VERSION \
 195         char *module_version=SER_FULL_VERSION; \
 196         char *module_flags=SER_COMPILE_FLAGS; \
 197         unsigned int module_interface_ver=MODULE_INTERFACE_VER;
 198
 199 /* ser version */
 200 struct ser_cmd_export_ {
 201         char* name;             /* null terminated command name */
 202         cmd_function function;  /* pointer to the corresponding function */
 203         int param_no;           /* number of parameters used by the function */
 204         fixup_function fixup;   /* pointer to the function called to "fix" the
 205                                                            parameters */
 206         int flags;              /* Function flags */
 207 };
 208
 209
 210 /* kamailo/openser version */
 211 struct kam_cmd_export_ {
 212         char* name;             /* null terminated command name */
 213         cmd_function function;  /* pointer to the corresponding function */
 214         int param_no;           /* number of parameters used by the function */
 215         fixup_function fixup;   /* pointer to the function called to "fix" the
 216                                                            parameters */
 217         free_fixup_function free_fixup; /* function called to free the "fixed"
 218                                                                            parameters */
 219         int flags;              /* Function flags */
 220 };
 221
 222
 223 struct sr31_cmd_export_ {
 224         char* name;             /* null terminated command name */
 225         cmd_function function;  /* pointer to the corresponding function */
 226         int param_no;           /* number of parameters used by the function */
 227         fixup_function fixup;   /* pointer to the function called to "fix" the
 228                                                            parameters */
 229         free_fixup_function free_fixup; /* function called to free the "fixed"
 230                                                                            parameters */
 231         int flags;              /* Function flags */
 232         int fixup_flags;
 233         void* module_exports; /* pointer to module structure */
 234 };
 235
 236
 237 /* members situated at the same place in memory in both ser & kamailio
 238    cmd_export */
 239 struct cmd_export_common_ {
 240         char* name;
 241         cmd_function function;
 242         int param_no;
 243         fixup_function fixup;
 244 };
 245
 246
 247 struct param_export_ {
 248         char* name;             /* null terminated param. name */
 249         modparam_t type;        /* param. type */
 250         void* param_pointer;    /* pointer to the param. memory location */
 251 };
 252
 253
 254
 255 /** allowed parameter types.
 256   * the types _must_ be in "fallback" order,
 257   * e.g. FPARAM_STR should be the last to allow fallback to it,
 258   *  F_PARAM_PVS should be in front of F_PARAM_AVP (so that
 259   *  for fix_param_types(FPARAM_AVP|FPARAM_PVS|FPARAM_STR, param) and $foo
 260   *  the pvars will be checked first and only if no pvar is found the
 261   *  param will be resolved to an avp)
 262   */
 263 enum {
 264         FPARAM_UNSPEC = 0,
 265         FPARAM_INT    = (1 << 0),
 266         FPARAM_SELECT = (1 << 1),
 267         FPARAM_PVS    = (1 << 2),
 268         FPARAM_AVP    = (1 << 3),
 269         FPARAM_STRING = (1 << 4),
 270         FPARAM_STR    = (1 << 5),
 271         /* special types: no fallback between them possible */
 272         FPARAM_REGEX  = (1 << 6),
 273         FPARAM_SUBST  = (1 << 7),
 274         FPARAM_PVE    = (1 << 8)
 275 };
 276
 277 /*
 278  * Function parameter
 279  */
 280 typedef struct fparam {
 281         char* orig;                       /* The original value */
 282         int type;                         /* Type of parameter */
 283         union {
 284                 char* asciiz;             /* Zero terminated ASCII string */
 285                 struct _str str;          /* pointer/len string */
 286                 int i;                    /* Integer value */
 287                 regex_t* regex;           /* Compiled regular expression */
 288                 avp_ident_t avp;          /* AVP identifier */
 289                 select_t* select;         /* select structure */
 290                 struct subst_expr* subst; /* Regex substitution */
 291                 pv_spec_t* pvs;    /* kamailo pseudo-vars */
 292                 pv_elem_t* pve;    /* kamailo pseudo-vars in a string */
 293         } v;
 294         void *fixed;
 295 } fparam_t;
 296
 297
 298 typedef struct param_export_ param_export_t;
 299 typedef struct ser_cmd_export_ ser_cmd_export_t;
 300 typedef struct kam_cmd_export_ kam_cmd_export_t;
 301 typedef struct cmd_export_common_ cmd_export_common_t;
 302 typedef struct sr31_cmd_export_ sr31_cmd_export_t;
 303
 304 #if 0
 305 union cmd_export_u{
 306         cmd_export_common_t c; /* common members for everybody */
 307         ser_cmd_export_t v0;
 308         kam_cmd_export_t v1;
 309 };
 310 #endif
 311
 312
 313 /* ser module exports version */
 314 struct ser_module_exports {
 315         char* name;                     /* null terminated module name */
 316         ser_cmd_export_t* cmds;         /* null terminated array of the exported
 317                                                                            commands */
 318         rpc_export_t* rpc_methods;      /* null terminated array of exported rpc methods */
 319         param_export_t* params;         /* null terminated array of the exported
 320                                                                            module parameters */
 321         init_function init_f;           /* Initialization function */
 322         response_function response_f;   /* function used for responses,
 323                                                                            returns yes or no; can be null */
 324         destroy_function destroy_f;     /* function called when the module should
 325                                                                            be "destroyed", e.g: on ser exit;
 326                                                                            can be null */
 327         onbreak_function onbreak_f;
 328         child_init_function init_child_f;  /* function called by all processes
 329                                                                                   after the fork */
 330 };
 331
 332
 333 /* kamailio/openser proc_export (missing from ser) */
 334 typedef void (*mod_proc)(int no);
 335
 336 typedef int (*mod_proc_wrapper)(void);
 337
 338 struct proc_export_ {
 339         char *name;
 340         mod_proc_wrapper pre_fork_function;
 341         mod_proc_wrapper post_fork_function;
 342         mod_proc function;
 343         unsigned int no;
 344 };
 345
 346 typedef struct proc_export_ proc_export_t;
 347
 348
 349 /* kamailio/openser module exports version */
 350 struct kam_module_exports {
 351         char* name;                     /* null terminated module name */
 352         unsigned int dlflags;                   /*!< flags for dlopen  */
 353         kam_cmd_export_t* cmds;                 /* null terminated array of the exported
 354                                                                            commands */
 355         param_export_t* params;                 /* null terminated array of the exported
 356                                                                            module parameters */
 357         stat_export_t* stats;                   /*!< null terminated array of the exported
 358                                                                           module statistics */
 359         mi_export_t* mi_cmds;                   /*!< null terminated array of the exported
 360                                                                           MI functions */
 361         pv_export_t* items;                             /*!< null terminated array of the exported
 362                                                                            module items (pseudo-variables) */
 363         proc_export_t* procs;                   /*!< null terminated array of the
 364                                                                           additional processes required by the
 365                                                                           module */
 366         init_function init_f;           /* Initialization function */
 367         response_function response_f;   /* function used for responses,
 368                                                                            returns yes or no; can be null */
 369         destroy_function destroy_f;     /* function called when the module should
 370                                                                            be "destroyed", e.g: on ser exit;
 371                                                                            can be null */
 372         child_init_function init_child_f;  /* function called by all processes
 373                                                                                   after the fork */
 374 };
 375
 376
 377
 378 /** sr/ser 3.1+ module exports version.
 379  * Includes ser and kamailio versions, re-arraranged + some extras.
 380  * Note: some of the members will be obsoleted and are kept only for
 381  * backward compatibility (avoid re-writing all the modules exports
 382  * declarations).
 383  */
 384 struct sr31_module_exports {
 385         char* name;                     /* null terminated module name */
 386         sr31_cmd_export_t* cmds;      /* null terminated array of the exported
 387                                                                            commands */
 388         param_export_t* params;         /* null terminated array of the exported
 389                                                                            module parameters */
 390         init_function init_f;           /* Initialization function */
 391         response_function response_f;   /* function used for responses,
 392                                                                            returns yes or no; can be null */
 393         destroy_function destroy_f;     /* function called when the module should
 394                                                                            be "destroyed", e.g: on ser exit;
 395                                                                            can be null */
 396         onbreak_function onbreak_f;
 397         child_init_function init_child_f;  /* function called by all processes
 398                                                                                   after the fork */
 399         unsigned int dlflags;           /**< flags for dlopen */
 400         /* ser specific exports
 401            (to be obsoleted and replaced by register_...) */
 402         rpc_export_t* rpc_methods;      /* null terminated array of exported
 403                                                                            rpc methods */
 404         /* kamailio specific exports
 405            (to be obsoleted and replaced by register_...) */
 406         stat_export_t* stats;                   /*!< null terminated array of the exported
 407                                                                           module statistics */
 408         mi_export_t* mi_cmds;                   /*!< null terminated array of the exported
 409                                                                           MI functions */
 410         pv_export_t* items;                             /*!< null terminated array of the exported
 411                                                                            module items (pseudo-variables) */
 412         proc_export_t* procs;                   /*!< null terminated array of the
 413                                                                           additional processes required by the
 414                                                                           module */
 415 };
 416
 417
 418
 419 /* module exports in the same place in memory in both ser & kamailio */
 420 struct module_exports_common{
 421         char* name;
 422 };
 423
 424
 425 union module_exports_u {
 426                 struct module_exports_common c; /*common members for all the versions*/
 427                 struct ser_module_exports v0;
 428                 struct kam_module_exports v1;
 429 };
 430
 431
 432 struct sr_module{
 433         char* path;
 434         void* handle;
 435         unsigned int orig_mod_interface_ver;
 436         struct sr31_module_exports exports;
 437         struct sr_module* next;
 438 };
 439
 440
 441 extern struct sr_module* modules; /* global module list*/
 442 extern response_function* mod_response_cbks;/* response callback array */
 443 extern int mod_response_cbk_no;    /* size of reponse callbacks array */
 444
 445 int register_builtin_modules(void);
 446 int load_module(char* path);
 447 sr31_cmd_export_t* find_export_record(char* name, int param_no, int flags,
 448                                                                                 unsigned *ver);
 449 cmd_function find_export(char* name, int param_no, int flags);
 450 cmd_function find_mod_export(char* mod, char* name, int param_no, int flags);
 451 rpc_export_t* find_rpc_export(char* name, int flags);
 452 void destroy_modules(void);
 453 int init_child(int rank);
 454 int init_modules(void);
 455 struct sr_module* find_module_by_name(char* mod);
 456
 457 /* true if the module with name 'mod_name' is loaded */
 458 #define module_loaded(mod_name) (find_module_by_name(mod_name)!=0)
 459
 460
 461 /*! \brief
 462  * Find a parameter with given type and return it's
 463  * address in memory
 464  * If there is no such parameter, NULL is returned
 465  */
 466 void* find_param_export(struct sr_module* mod, char* name, modparam_t type_mask, modparam_t *param_type);
 467
 468 /* modules function prototypes:
 469  * struct module_exports* mod_register(); (type module_register)
 470  * int   foo_cmd(struct sip_msg* msg, char* param);
 471  *  - returns >0 if ok , <0 on error, 0 to stop processing (==DROP)
 472  * int   response_f(struct sip_msg* msg)
 473  *  - returns >0 if ok, 0 to drop message
 474  */
 475
 476
 477 /* API function to get other parameters from fixup */
 478 action_u_t *fixup_get_param(void **cur_param, int cur_param_no, int required_param_no);
 479 int fixup_get_param_count(void **cur_param, int cur_param_no);
 480
 481 int fix_flag( modparam_t type, void* val,
 482                                         char* mod_name, char* param_name, int* flag);
 483
 484
 485 /*
 486  * Common function parameter fixups
 487  */
 488
 489 /*
 490  * Generic parameter fixup function which creates
 491  * fparam_t structure. type parameter contains allowed
 492  * parameter types
 493  */
 494 int fix_param(int type, void** param);
 495 void fparam_free_contents(fparam_t* fp);
 496
 497 /** fix a param to one of the given types (mask).
 498   */
 499 int fix_param_types(int types, void** param);
 500
 501 /*
 502  * Fixup variable string, the parameter can be
 503  * AVP, SELECT, or ordinary string. AVP and select
 504  * identifiers will be resolved to their values during
 505  * runtime
 506  *
 507  * The parameter value will be converted to fparam structure
 508  * This function returns -1 on an error
 509  */
 510 int fixup_var_str_12(void** param, int param_no);
 511
 512 /* Same as fixup_var_str_12 but applies to the 1st parameter only */
 513 int fixup_var_str_1(void** param, int param_no);
 514
 515 /* Same as fixup_var_str_12 but applies to the 2nd parameter only */
 516 int fixup_var_str_2(void** param, int param_no);
 517
 518 /*
 519  * Fixup variable integer, the parameter can be
 520  * AVP, SELECT, or ordinary integer. AVP and select
 521  * identifiers will be resolved to their values and
 522  * converted to int if necessary during runtime
 523  *
 524  * The parameter value will be converted to fparam structure
 525  * This function returns -1 on an error
 526  */
 527 int fixup_var_int_12(void** param, int param_no);
 528
 529 /* Same as fixup_var_int_12 but applies to the 1st parameter only */
 530 int fixup_var_int_1(void** param, int param_no);
 531
 532 /* Same as fixup_var_int_12 but applies to the 2nd parameter only */
 533 int fixup_var_int_2(void** param, int param_no);
 534
 535 /*
 536  * The parameter must be a regular expression which must compile, the
 537  * parameter will be converted to compiled regex
 538  */
 539 int fixup_regex_12(void** param, int param_no);
 540
 541 /* Same as fixup_regex_12 but applies to the 1st parameter only */
 542 int fixup_regex_1(void** param, int param_no);
 543
 544 /* Same as fixup_regex_12 but applies to the 2nd parameter only */
 545 int fixup_regex_2(void** param, int param_no);
 546
 547 /*
 548  * The string parameter will be converted to integer
 549  */
 550 int fixup_int_12(void** param, int param_no);
 551
 552 /* Same as fixup_int_12 but applies to the 1st parameter only */
 553 int fixup_int_1(void** param, int param_no);
 554
 555 /* Same as fixup_int_12 but applies to the 2nd parameter only */
 556 int fixup_int_2(void** param, int param_no);
 557
 558 /*
 559  * Parse the parameter as static string, do not resolve
 560  * AVPs or selects, convert the parameter to str structure
 561  */
 562 int fixup_str_12(void** param, int param_no);
 563
 564 /* Same as fixup_str_12 but applies to the 1st parameter only */
 565 int fixup_str_1(void** param, int param_no);
 566
 567 /* Same as fixup_str_12 but applies to the 2nd parameter only */
 568 int fixup_str_2(void** param, int param_no);
 569
 570 /*
 571  * Get the function parameter value as string
 572  * Return values:  0 - Success
 573  *                -1 - Cannot get value
 574  */
 575 int get_str_fparam(str* dst, struct sip_msg* msg, fparam_t* param);
 576
 577 /*
 578  * Get the function parameter value as integer
 579  * Return values:  0 - Success
 580  *                -1 - Cannot get value
 581  */
 582 int get_int_fparam(int* dst, struct sip_msg* msg, fparam_t* param);
 583
 584
 585 /**
 586  * Retrieve the compiled RegExp.
 587  * @return: 0 for success, negative on error.
 588  */
 589 int get_regex_fparam(regex_t *dst, struct sip_msg* msg, fparam_t* param);
 590
 591
 592 int is_fparam_rve_fixup(fixup_function f);
 593
 594
 595 /** generic free fixup type function for a fixed fparam.
 596  * It will free whatever was allocated during the initial fparam fixup
 597  * and restore the original param value.
 598  */
 599 void fparam_free_restore(void** param);
 600 int fixup_free_fparam_all(void** param, int param_no);
 601 int fixup_free_fparam_1(void** param, int param_no);
 602 int fixup_free_fparam_2(void** param, int param_no);
 603 #endif /* sr_module_h */