sr_module.h
3bf76e49
 /* $Id$
  *
53c7e0f1
  * modules/plug-in structures declarations
3bf76e49
  *
7dd0b342
  *
53c7e0f1
  * Copyright (C) 2001-2003 FhG Fokus
7dd0b342
  *
  * 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.
  *
fb851d7e
  * You should have received a copy of the GNU General Public License
  * along with this program; if not, write to the Free Software
7dd0b342
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
3bf76e49
  */
6419a43f
 /*
  * History:
  * --------
  *  2003-03-10  changed module exports interface: added struct cmd_export
  *               and param_export (andrei)
f9add4f7
  *  2003-03-16  Added flags field to cmd_export_ (janakj)
87405423
  *  2003-04-05  s/reply_route/failure_route, onreply_route introduced (jiri)
78878540
  *  2004-03-12  extra flag USE_FUNC_PARAM added to modparam type -
  *              instead of copying the param value, a func is called (bogdan)
dd0e65a8
  *  2004-09-19  switched to version.h for the module versions checks (andrei)
d7a3fdea
  *  2004-12-03  changed param_func_t to (modparam_t, void*), killed
  *               param_func_param_t   (andrei)
6419a43f
  */
3bf76e49
 
7dd0b342
 
4042f646
 #ifndef sr_module_h
 #define sr_module_h
3bf76e49
 
3881f12c
 #include "parser/msg_parser.h" /* for sip_msg */
dd0e65a8
 #include "version.h"
300b0f50
 #include "rpc.h"
f141bc93
 #include "route_struct.h"
c16e9887
 #include "str.h"
3bf76e49
 
404073d3
 typedef  struct module_exports* (*module_register)();
34fd2612
 typedef  int (*cmd_function)(struct sip_msg*, char*, char*);
 typedef  int (*fixup_function)(void** param, int param_no);
3bf76e49
 typedef  int (*response_function)(struct sip_msg*);
4bd1673d
 typedef  void (*onbreak_function)(struct sip_msg*);
bf08223a
 typedef void (*destroy_function)();
31309a3a
 typedef int (*init_function)(void);
192ac55b
 typedef int (*child_init_function)(int rank);
3bf76e49
 
31309a3a
 
fb851d7e
 #define PARAM_STRING     (1U<<0)  /* String (char *) parameter type */
 #define PARAM_INT        (1U<<1)  /* Integer parameter type */
 #define PARAM_STR        (1U<<2)  /* struct str parameter type */
 #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
78878540
 
d7a3fdea
 typedef unsigned int modparam_t;
78878540
 
d7a3fdea
 typedef int (*param_func_t)( modparam_t type, void* val);
31309a3a
 
87405423
 #define REQUEST_ROUTE 1  /* Function can be used in request route blocks */
 #define FAILURE_ROUTE 2  /* Function can be used in reply route blocks */
 #define ONREPLY_ROUTE 4  /* Function can be used in on_reply */
7662b2e7
 #define BRANCH_ROUTE  8  /* Function can be used in branch_route blocks */
0d88ce78
 #define ONSEND_ROUTE   16  /* Function can be used in onsend_route blocks */
f9add4f7
 
cb87691a
 /* Macros - used as rank in child_init function */
 #define PROC_MAIN      0  /* Main ser process */
 #define PROC_TIMER    -1  /* Timer attendant process */
 #define PROC_FIFO     -2  /* FIFO attendant process */
 #define PROC_TCP_MAIN -4  /* TCP main process */
300b0f50
 #define PROC_UNIXSOCK -5  /* Unix socket server */
37209e14
 #define PROC_NOCHLDINIT -128 /* no child init functions will be called
                                 if this rank is used in fork_process() */
cb87691a
 
bd52d9b9
 #define PROC_MIN PROC_UNIXSOCK /* Minimum process rank */
 
dd0e65a8
 #define MODULE_VERSION \
 	char *module_version=SER_FULL_VERSION; \
 	char *module_flags=SER_COMPILE_FLAGS;
2dcb8b67
 
6419a43f
 struct cmd_export_ {
 	char* name;             /* null terminated command name */
 	cmd_function function;  /* pointer to the corresponding function */
 	int param_no;           /* number of parameters used by the function */
 	fixup_function fixup;   /* pointer to the function called to "fix" the
 							   parameters */
f9add4f7
 	int flags;              /* Function flags */
6419a43f
 };
 
 
 struct param_export_ {
 	char* name;             /* null terminated param. name */
 	modparam_t type;        /* param. type */
 	void* param_pointer;    /* pointer to the param. memory location */
 };
 
 
b91364c6
 enum {
 	FPARAM_UNSPEC = 0,
2c511189
 	FPARAM_STRING = (1 << 0),
b91364c6
 	FPARAM_STR    = (1 << 1),
 	FPARAM_INT    = (1 << 2),
 	FPARAM_REGEX  = (1 << 3),
 	FPARAM_AVP    = (1 << 5),
c16e9887
 	FPARAM_SELECT = (1 << 6),
d0ce0ebd
 	FPARAM_SUBST  = (1 << 7)
b91364c6
 };
 
 /*
  * Function parameter
  */
 typedef struct fparam {
d0ce0ebd
         char* orig;                       /* The original value */
         int type;                         /* Type of parameter */
b91364c6
         union {
d0ce0ebd
 		char* asciiz;             /* Zero terminated ASCII string */
 		struct _str str;          /* pointer/len string */
 		int i;                    /* Integer value */
 		regex_t* regex;           /* Compiled regular expression */
 		avp_ident_t avp;          /* AVP identifier */
 	        select_t* select;         /* select structure */ 
 	        struct subst_expr* subst; /* Regex substitution */
b91364c6
 	} v;
 } fparam_t;
 
 
6419a43f
 typedef struct cmd_export_ cmd_export_t;
 typedef struct param_export_ param_export_t;
 
c16e9887
 struct module_exports {
31309a3a
 	char* name;                     /* null terminated module name */
fb851d7e
 
6419a43f
 	cmd_export_t* cmds;             /* null terminated array of the exported
 									   commands */
300b0f50
 	rpc_export_t* rpc_methods;      /* null terminated array of exported rpc methods */
6419a43f
 	param_export_t* params;         /* null terminated array of the exported
 									   module parameters */
 
53c7e0f1
 	init_function init_f;           /* Initialization function */
6419a43f
 	response_function response_f;   /* function used for responses,
 									   returns yes or no; can be null */
 	destroy_function destroy_f;     /* function called when the module should
 									   be "destroyed", e.g: on ser exit;
 									   can be null */
4bd1673d
 	onbreak_function onbreak_f;
e3fc93f4
 	child_init_function init_child_f;  /* function called by all processes
 										  after the fork */
3bf76e49
 };
 
6419a43f
 
3bf76e49
 struct sr_module{
 	char* path;
 	void* handle;
 	struct module_exports* exports;
 	struct sr_module* next;
 };
6419a43f
 
 
031e278e
 struct sr_module* modules; /* global module list*/
3bf76e49
 
31309a3a
 int register_builtin_modules();
 int register_module(struct module_exports*, char*,  void*);
3bf76e49
 int load_module(char* path);
f141bc93
 cmd_export_t* find_export_record(char* name, int param_no, int flags);
51c38611
 cmd_function find_export(char* name, int param_no, int flags);
49b28ea4
 cmd_function find_mod_export(char* mod, char* name, int param_no, int flags);
300b0f50
 rpc_export_t* find_rpc_export(char* name, int flags);
bf08223a
 void destroy_modules();
192ac55b
 int init_child(int rank);
31309a3a
 int init_modules(void);
fb851d7e
 struct sr_module* find_module_by_name(char* mod);
34fd2612
 
31309a3a
 /*
  * Find a parameter with given type and return it's
  * address in memory
  * If there is no such parameter, NULL is returned
  */
fb851d7e
 void* find_param_export(struct sr_module* mod, char* name, modparam_t type_mask, modparam_t *param_type);
3bf76e49
 
 /* modules function prototypes:
404073d3
  * struct module_exports* mod_register(); (type module_register)
3bf76e49
  * int   foo_cmd(struct sip_msg* msg, char* param);
  *  - returns >0 if ok , <0 on error, 0 to stop processing (==DROP)
  * int   response_f(struct sip_msg* msg)
  *  - returns >0 if ok, 0 to drop message
  */
 
 
d0ce0ebd
 /* API function to get other parameters from fixup */
 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);
 
 
bb6575cd
 /*
d0ce0ebd
  * Common function parameter fixups
bb6575cd
  */
 
d0ce0ebd
 /*
  * Generic parameter fixup function which creates
  * fparam_t structure. type parameter contains allowed
  * parameter types
  */
 int fix_param(int type, void** param);
bb6575cd
 
d0ce0ebd
 /*
  * Fixup variable string, the parameter can be
  * AVP, SELECT, or ordinary string. AVP and select
  * identifiers will be resolved to their values during
  * runtime
  *
  * The parameter value will be converted to fparam structure
  * This function returns -1 on an error
  */
 int fixup_var_str_12(void** param, int param_no);
bb6575cd
 
d0ce0ebd
 /* Same as fixup_var_str_12 but applies to the 1st parameter only */
 int fixup_var_str_1(void** param, int param_no);
bb6575cd
 
d0ce0ebd
 /* Same as fixup_var_str_12 but applies to the 2nd parameter only */
 int fixup_var_str_2(void** param, int param_no);
bb6575cd
 
d0ce0ebd
 /*
  * Fixup variable integer, the parameter can be
  * AVP, SELECT, or ordinary integer. AVP and select
  * identifiers will be resolved to their values and 
  * converted to int if necessary during runtime
  *
  * The parameter value will be converted to fparam structure
  * This function returns -1 on an error
  */
 int fixup_var_int_12(void** param, int param_no);
bb6575cd
 
d0ce0ebd
 /* Same as fixup_var_int_12 but applies to the 1st parameter only */
 int fixup_var_int_1(void** param, int param_no);
bb6575cd
 
d0ce0ebd
 /* Same as fixup_var_int_12 but applies to the 2nd parameter only */
 int fixup_var_int_2(void** param, int param_no);
 
 /*
  * The parameter must be a regular expression which must compile, the
  * parameter will be converted to compiled regex
  */
f6712967
 int fixup_regex_12(void** param, int param_no);
 
d0ce0ebd
 /* Same as fixup_regex_12 but applies to the 1st parameter only */
f6712967
 int fixup_regex_1(void** param, int param_no);
 
d0ce0ebd
 /* Same as fixup_regex_12 but applies to the 2nd parameter only */
f6712967
 int fixup_regex_2(void** param, int param_no);
 
b91364c6
 /*
d0ce0ebd
  * The string parameter will be converted to integer
b91364c6
  */
d0ce0ebd
 int fixup_int_12(void** param, int param_no);
 
 /* Same as fixup_int_12 but applies to the 1st parameter only */
 int fixup_int_1(void** param, int param_no);
 
 /* Same as fixup_int_12 but applies to the 2nd parameter only */
 int fixup_int_2(void** param, int param_no);
 
 /*
  * Parse the parameter as static string, do not resolve
  * AVPs or selects, convert the parameter to str structure
  */
 int fixup_str_12(void** param, int param_no);
 
 /* Same as fixup_str_12 but applies to the 1st parameter only */
 int fixup_str_1(void** param, int param_no);
 
 /* Same as fixup_str_12 but applies to the 2nd parameter only */
 int fixup_str_2(void** param, int param_no);
b91364c6
 
c16e9887
 /*
  * Get the function parameter value as string
  * Return values:  0 - Success
  *                -1 - Cannot get value
  */
 int get_str_fparam(str* dst, struct sip_msg* msg, fparam_t* param);
 
d0ce0ebd
 /*
  * Get the function parameter value as integer
  * Return values:  0 - Success
  *                -1 - Cannot get value
  */
 int get_int_fparam(int* dst, struct sip_msg* msg, fparam_t* param);
6d35d70e
 
bb6575cd
 #endif /* sr_module_h */