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