sr_module.h

Go to the documentation of this file.

/*
 * Copyright (C) 2001-2003 FhG Fokus
 *
 * This file is part of ser, a free SIP server.
 *
 * ser is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version
 *
 * For a license to use the ser software under conditions
 * other than those described here, or to purchase support for this
 * software, please contact iptel.org by e-mail at the following addresses:
 *    info@iptel.org
 *
 * ser is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

/*
 * History:
 * --------
 *  2003-03-10  changed module exports interface: added struct cmd_export
 *               and param_export (andrei)
 *  2003-03-16  Added flags field to cmd_export_ (janakj)
 *  2003-04-05  s/reply_route/failure_route, onreply_route introduced (jiri)
 *  2004-03-12  extra flag USE_FUNC_PARAM added to modparam type -
 *              instead of copying the param value, a func is called (bogdan)
 *  2004-09-19  switched to version.h for the module versions checks (andrei)
 *  2004-12-03  changed param_func_t to (modparam_t, void*), killed
 *               param_func_param_t   (andrei)
 *  2007-06-07  added PROC_INIT, called in the main process context
 *               (same as PROC_MAIN), buf guaranteed to be called before
 *               any other process is forked (andrei)
 *  2008-11-17  sip-router version: includes some of the openser/kamailio
 *               changes: f(void) instead of f(), free_fixup_function()
 *              dual module interface support: ser & kamailio (andrei)
 *  2008-11-18  prototypes for various fixed parameters numbers module
 *               functions (3, 4, 5 & 6) and variable parameters (andrei)
 *  2008-11-26  added fparam_free_contents() and fix_param_types (andrei)
 */

#ifndef sr_module_h
#define sr_module_h

#include <dlfcn.h>

#include "parser/msg_parser.h" /* for sip_msg */
#include "ver_defs.h"
#include "rpc.h"
#include "route_struct.h"
#include "route.h"
#include "str.h"

/* kamailio compat */
#include "kstats_types.h"
#include "mi/mi_types.h"
#include "pvar.h"



#if defined KAMAILIO_MOD_INTERFACE || defined OPENSER_MOD_INTERFACE || \
        defined MOD_INTERFACE_V1

#define MODULE_INTERFACE_VER 1
#define cmd_export_t kam_cmd_export_t
#define module_exports kam_module_exports

#elif defined SER_MOD_INTERFACE || defined MOD_INTERFACE_V0

#define MODULE_INTERFACE_VER 0
#define cmd_export_t ser_cmd_export_t
#define module_exports ser_module_exports

#else

/* do nothing for core */

#endif

typedef  int (*mod_register_function)(char* path, int* dlflags, void* reserved1, void* reserved2);

typedef  struct module_exports* (*module_register)(void);

typedef  int (*cmd_function)(struct sip_msg*, char* param1, char* param2);
typedef  int (*cmd_function3)(struct sip_msg*, char*, char*, char*);
typedef  int (*cmd_function4)(struct sip_msg*, char*, char*, char*, char*);
typedef  int (*cmd_function5)(struct sip_msg*,  char*, char*, char*,
                                                                                                char*, char*);
typedef  int (*cmd_function6)(struct sip_msg*,  char*, char*, char*,
                                                                                                char*, char*, char*);
typedef int (*cmd_function_var)(struct sip_msg*, int no, action_u_t* vals );
typedef int (*fixup_function)(void** param, int param_no);
typedef int (*free_fixup_function)(void** param, int param_no);

typedef int (*response_function)(struct sip_msg*);
typedef void (*onbreak_function)(struct sip_msg*);
typedef void (*destroy_function)(void);

typedef int (*init_function)(void);
typedef int (*child_init_function)(int rank);


#define PARAM_STRING     (1U<<0)  
#define PARAM_INT        (1U<<1)  
#define PARAM_STR        (1U<<2)  
#define PARAM_USE_FUNC   (1U<<(8*sizeof(int)-1))
#define PARAM_TYPE_MASK(_x)   ((_x)&(~PARAM_USE_FUNC))

/* temporary, for backward compatibility only until all modules adjust it */
#define STR_PARAM PARAM_STRING
#define INT_PARAM PARAM_INT
#define USE_FUNC_PARAM PARAM_USE_FUNC

typedef unsigned int modparam_t;

typedef int (*param_func_t)( modparam_t type, void* val);

/* magic parameter number values */

#define NO_SCRIPT     -1    
#define VAR_PARAM_NO  -128  
#define FIXUP_F_FPARAM_RVE (unsigned long)1

#define call_fixup(fixup, param, param_no) \
        ((fixup) ? (fixup)(param, param_no) : 0)

/* Macros - used as rank in child_init function */
#define PROC_MAIN      0  
#define PROC_TIMER    -1  
#define PROC_RPC      -2  
#define PROC_FIFO      PROC_RPC  
#define PROC_TCP_MAIN -4  
#define PROC_UNIXSOCK -5  
#define PROC_ATTENDANT -10  
#define PROC_INIT     -127 
#define PROC_NOCHLDINIT -128 
#define PROC_SIPINIT      1  
#define PROC_SIPRPC       127  
#define PROC_MIN PROC_NOCHLDINIT 
#define DEFAULT_DLFLAGS 0 
#ifndef RTLD_NOW
/* for openbsd */
#define RTLD_NOW DL_LAZY
#endif

#define KAMAILIO_DLFLAGS        RTLD_NOW


#define MODULE_VERSION \
        char *module_version=SER_FULL_VERSION; \
        char *module_flags=SER_COMPILE_FLAGS; \
        unsigned int module_interface_ver=MODULE_INTERFACE_VER; 

struct ser_cmd_export_ {
        char* name;             
        cmd_function function;  
        int param_no;           
        fixup_function fixup;   
        int flags;              
};


struct kam_cmd_export_ {
        char* name;             
        cmd_function function;  
        int param_no;           
        fixup_function fixup;   
        free_fixup_function free_fixup; 
        int flags;              
};

struct sr31_cmd_export_ {
        char* name;             
        cmd_function function;  
        int param_no;           
        fixup_function fixup;   
        free_fixup_function free_fixup; 
        int flags;              
        int fixup_flags;
        void* module_exports; 
};


struct cmd_export_common_ {
        char* name;
        cmd_function function; 
        int param_no;
        fixup_function fixup;
};


struct param_export_ {
        char* name;             
        modparam_t type;        
        void* param_pointer;    
};


/*
 * Allowed parameter types, the types _must_ be in "fallback" order,
 * e.g. FPARAM_STR should be the last to allow fallback to it,
 * F_PARAM_PVS should be in front of F_PARAM_AVP (so that
 * for fix_param_types(FPARAM_AVP|FPARAM_PVS|FPARAM_STR, param) and $foo
 * the pvars will be checked first and only if no pvar is found the
 * param will be resolved to an avp)
 */
enum {
        FPARAM_UNSPEC = 0,
        FPARAM_INT    = (1 << 0),
        FPARAM_SELECT = (1 << 1),
        FPARAM_PVS    = (1 << 2),
        FPARAM_AVP    = (1 << 3),
        FPARAM_STRING = (1 << 4),
        FPARAM_STR    = (1 << 5),
        /* special types: no fallback between them possible */
        FPARAM_REGEX  = (1 << 6),
        FPARAM_SUBST  = (1 << 7),
        FPARAM_PVE    = (1 << 8)
};

typedef struct fparam {
        char* orig;                       
        int type;                         
        union {
                char* asciiz;             
                struct _str str;          
                int i;                    
                regex_t* regex;           
                avp_ident_t avp;          
                select_t* select;         
                struct subst_expr* subst; 
                pv_spec_t* pvs;    
                pv_elem_t* pve;    
        } v;
        void *fixed;
} fparam_t;


typedef struct param_export_ param_export_t;  
typedef struct ser_cmd_export_ ser_cmd_export_t;
typedef struct kam_cmd_export_ kam_cmd_export_t;
typedef struct cmd_export_common_ cmd_export_common_t;
typedef struct sr31_cmd_export_ sr31_cmd_export_t;


struct ser_module_exports {
        char* name;                     
        ser_cmd_export_t* cmds;         
        rpc_export_t* rpc_methods;      
        param_export_t* params;         
        init_function init_f;           
        response_function response_f;   
        destroy_function destroy_f;     
        onbreak_function onbreak_f;
        child_init_function init_child_f;  
};


typedef void (*mod_proc)(int no);

typedef int (*mod_proc_wrapper)(void);

struct proc_export_ {
        char *name;
        mod_proc_wrapper pre_fork_function;
        mod_proc_wrapper post_fork_function;
        mod_proc function;
        unsigned int no;
};

typedef struct proc_export_ proc_export_t;


struct kam_module_exports {
        char* name;                             
        unsigned int dlflags;                   
        kam_cmd_export_t* cmds;                 
        param_export_t* params;                 
        stat_export_t* stats;                   
        mi_export_t* mi_cmds;                   
        pv_export_t* items;                             
        proc_export_t* procs;                   
        init_function init_f;                   
        response_function response_f;           
        destroy_function destroy_f;                     
        child_init_function init_child_f;       
};



struct sr31_module_exports {
        char* name;                     
        sr31_cmd_export_t* cmds;        
        param_export_t* params;         
        init_function init_f;           
        response_function response_f;   
        destroy_function destroy_f;     
        onbreak_function onbreak_f;
        child_init_function init_child_f;
        unsigned int dlflags;           
        /* ser specific exports
           (to be obsoleted and replaced by register_...) */
        rpc_export_t* rpc_methods;      
        /* kamailio specific exports
           (to be obsoleted and replaced by register_...) */
        stat_export_t* stats;                   
        mi_export_t* mi_cmds;                   
        pv_export_t* items;                     
        proc_export_t* procs;                   
};



struct module_exports_common {
        char* name;
};


union module_exports_u {
                struct module_exports_common c; 
                struct ser_module_exports v0;
                struct kam_module_exports v1;
};


struct sr_module {
        char* path;
        void* handle;
        unsigned int orig_mod_interface_ver;
        struct sr31_module_exports exports;
        struct sr_module* next;
};


extern struct sr_module* modules; 
extern response_function* mod_response_cbks; 
extern int mod_response_cbk_no; 
int register_builtin_modules(void);
int load_module(char* path);
sr31_cmd_export_t* find_export_record(char* name, int param_no, int flags,
                                                                                unsigned *ver);
cmd_function find_export(char* name, int param_no, int flags);
cmd_function find_mod_export(char* mod, char* name, int param_no, int flags);
rpc_export_t* find_rpc_export(char* name, int flags);
void destroy_modules(void);
int init_child(int rank);
int init_modules(void);
struct sr_module* find_module_by_name(char* mod);

#define module_loaded(mod_name) (find_module_by_name(mod_name)!=0)


void* find_param_export(struct sr_module* mod, char* name, modparam_t type_mask, modparam_t *param_type);


action_u_t *fixup_get_param(void **cur_param, int cur_param_no, int required_param_no);
int fixup_get_param_count(void **cur_param, int cur_param_no);

int fix_flag( modparam_t type, void* val,
                                        char* mod_name, char* param_name, int* flag);


/*
 * Common function parameter fixups
 */

int fix_param(int type, void** param);
void fparam_free_contents(fparam_t* fp);

int fix_param_types(int types, void** param);

int fixup_var_str_12(void** param, int param_no);

int fixup_var_str_1(void** param, int param_no);

int fixup_var_str_2(void** param, int param_no);

int fixup_var_pve_12(void** param, int param_no);

int fixup_var_pve_str_12(void** param, int param_no);

int fixup_var_pve_str_1(void** param, int param_no);

int fixup_var_pve_str_2(void** param, int param_no);

int fixup_var_int_12(void** param, int param_no);

int fixup_var_int_1(void** param, int param_no);

int fixup_var_int_2(void** param, int param_no);

int fixup_regex_12(void** param, int param_no);

int fixup_regex_1(void** param, int param_no);

int fixup_regex_2(void** param, int param_no);

int fixup_int_12(void** param, int param_no);

int fixup_int_1(void** param, int param_no);

int fixup_int_2(void** param, int param_no);

int fixup_str_12(void** param, int param_no);

int fixup_str_1(void** param, int param_no);

int fixup_str_2(void** param, int param_no);

int get_str_fparam(str* dst, struct sip_msg* msg, fparam_t* param);

int get_int_fparam(int* dst, struct sip_msg* msg, fparam_t* param);

int get_regex_fparam(regex_t *dst, struct sip_msg* msg, fparam_t* param);


int is_fparam_rve_fixup(fixup_function f);

void fparam_free_restore(void** param);
int fixup_free_fparam_all(void** param, int param_no);
int fixup_free_fparam_1(void** param, int param_no);
int fixup_free_fparam_2(void** param, int param_no);

free_fixup_function get_fixup_free(fixup_function f);

void set_child_sip_rpc_mode(void);
void set_child_rpc_sip_mode(void);
int is_sip_worker(int rank);
int is_rpc_worker(int rank);

#endif /* sr_module_h */