git.sip-router.org Git - sip-router/blob - cfg/cfg_ctx.h

   1 /*
   2  * Copyright (C) 2007 iptelorg GmbH
   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 #ifndef _CFG_CTX_H
  23 #define _CFG_CTX_H
  24
  25 #include "../str.h"
  26 #include "../locking.h"
  27 #include "cfg.h"
  28 #include "cfg_struct.h"
  29
  30
  31 /* variable values */
  32 union cfg_var_value{
  33         void* vp;
  34         long vlong;
  35         int vint;
  36         str vstr;
  37         unsigned char   vraw[1]; /* variable length */
  38 };
  39
  40
  41 /** linked list of variables with their new values. */
  42 typedef struct _cfg_changed_var {
  43         cfg_group_t     *group;
  44         cfg_mapping_t   *var;
  45         struct _cfg_changed_var *next;
  46
  47         unsigned int    group_id; /* valid only if group_id_set==1 */
  48         unsigned char   group_id_set;
  49         unsigned char   del_value;      /* delete the value instead of setting it */
  50
  51         /* blob that contains the new value */
  52         union cfg_var_value new_val; /* variable size */
  53 } cfg_changed_var_t;
  54
  55 /*! \brief callback that is called when a new group is declared */
  56 typedef void (*cfg_on_declare)(str *, cfg_def_t *);
  57
  58 /*! \brief linked list of registered contexts */
  59 typedef struct _cfg_ctx {
  60         /* variables that are already changed
  61         but have not been committed yet */
  62         cfg_changed_var_t       *changed_first;
  63         /* lock protecting the linked-list of
  64         changed variables */
  65         gen_lock_t              lock;
  66
  67         /* callback that is called when a new
  68         group is registered */
  69         cfg_on_declare          on_declare_cb;
  70
  71         struct _cfg_ctx *next;
  72 } cfg_ctx_t;
  73
  74 #define CFG_CTX_LOCK(ctx)       lock_get(&(ctx)->lock)
  75 #define CFG_CTX_UNLOCK(ctx)     lock_release(&(ctx)->lock)
  76
  77 /*! \brief creates a new config context that is an interface to the
  78  * cfg variables with write permission */
  79 int cfg_register_ctx(cfg_ctx_t **handle, cfg_on_declare on_declare_cb);
  80
  81 /*! \brief free the memory allocated for the contexts */
  82 void cfg_ctx_destroy(void);
  83
  84 /*! \brief set the value of a variable without the need of explicit commit */
  85 int cfg_set_now(cfg_ctx_t *ctx, str *group_name, unsigned int *group_id, str *var_name,
  86                         void *val, unsigned int val_type);
  87 int cfg_set_now_int(cfg_ctx_t *ctx, str *group_name, unsigned int *group_id, str *var_name,
  88                         int val);
  89 int cfg_set_now_string(cfg_ctx_t *ctx, str *group_name, unsigned int *group_id, str *var_name,
  90                         char *val);
  91 int cfg_set_now_str(cfg_ctx_t *ctx, str *group_name, unsigned int *group_id, str *var_name,
  92                         str *val);
  93
  94 /*! \brief Delete a variable from the group instance.
  95  * wrapper function for cfg_set_now */
  96 int cfg_del_now(cfg_ctx_t *ctx, str *group_name, unsigned int *group_id, str *var_name);
  97
  98 /* sets the value of a variable but does not commit the change */
  99 int cfg_set_delayed(cfg_ctx_t *ctx, str *group_name, unsigned int *group_id, str *var_name,
 100                         void *val, unsigned int val_type);
 101 int cfg_set_delayed_int(cfg_ctx_t *ctx, str *group_name, unsigned int *group_id, str *var_name,
 102                         int val);
 103 int cfg_set_delayed_string(cfg_ctx_t *ctx, str *group_name, unsigned int *group_id, str *var_name,
 104                         char *val);
 105 int cfg_set_delayed_str(cfg_ctx_t *ctx, str *group_name, unsigned int *group_id, str *var_name,
 106                         str *val);
 107
 108 /*! \brief Delete a variable from the group instance.
 109  * wrapper function for cfg_set_delayed */
 110 int cfg_del_delayed(cfg_ctx_t *ctx, str *group_name, unsigned int *group_id, str *var_name);
 111
 112 /*! \brief commits the previously prepared changes within the context */
 113 int cfg_commit(cfg_ctx_t *ctx);
 114
 115 /*! \brief drops the not yet committed changes within the context */
 116 int cfg_rollback(cfg_ctx_t *ctx);
 117
 118 /*! \brief returns the value of a variable */
 119 int cfg_get_by_name(cfg_ctx_t *ctx, str *group_name, unsigned int *group_id, str *var_name,
 120                         void **val, unsigned int *val_type);
 121
 122 /*! \brief returns the description of a variable */
 123 int cfg_help(cfg_ctx_t *ctx, str *group_name, str *var_name,
 124                         char **ch, unsigned int *input_type);
 125
 126 /*! \brief notify the drivers about the new config definition */
 127 void cfg_notify_drivers(char *group_name, int group_name_len, cfg_def_t *def);
 128
 129 /*! \brief convert the value to the requested type.
 130  * Do not forget the call convert_val_cleaup afterwards. */
 131 int convert_val(unsigned int val_type, void *val,
 132                         unsigned int var_type, void **new_val);
 133
 134 /*! \brief cleanup function for convert_val() */
 135 void convert_val_cleanup(void);
 136
 137 /*! \brief initialize the handle for cfg_get_group_next() */
 138 #define cfg_get_group_init(handle) \
 139         (*(handle)) = (void *)cfg_group
 140
 141 /*! \brief returns the group name and the cfg structure definition,
 142  * and moves the handle to the next group
 143  *
 144  * Return value:
 145  *      0: no more group
 146  *      1: group exists
 147  *
 148  * can be used as follows:
 149  *
 150  * void *handle;
 151  * cfg_get_group_init(&handle)
 152  * while (cfg_get_group_next(&handle, &name, &def)) {
 153  *      ...
 154  * }
 155  */
 156 int cfg_get_group_next(void **h,
 157                         str *gname, cfg_def_t **def);
 158
 159 /*! \brief Initialize the handle for cfg_diff_next()
 160  * WARNING: keeps the context lock held, do not forget
 161  * to release it with cfg_diff_release()
 162  */
 163 int cfg_diff_init(cfg_ctx_t *ctx,
 164                 void **h);
 165
 166 /*! \brief return the pending changes that have not been
 167  * committed yet
 168  * return value:
 169  *      1: valid value is found
 170  *      0: no more changed value found
 171  *      -1: error occurred
 172  *
 173  *
 174  * can be used as follows:
 175  *
 176  * void *handle;
 177  * if (cfg_diff_init(ctx, &handle)) return -1
 178  * while ((err = cfg_diff_next(&handle
 179  *                      &group_name, &group_id, &var_name,
 180  *                      &old_val, &new_val
 181  *                      &val_type)) > 0
 182  * ) {
 183  *              ...
 184  * }
 185  * cfg_diff_release(ctx);
 186  * if (err) {
 187  *      error occurred, the changes cannot be retrieved
 188  *      ...
 189  * }
 190  */
 191 int cfg_diff_next(void **h,
 192                         str *gname, unsigned int **gid, str *vname,
 193                         void **old_val, void **new_val,
 194                         unsigned int *val_type);
 195
 196 /*! \brief destroy the handle of cfg_diff_next() */
 197 void cfg_diff_release(cfg_ctx_t *ctx);
 198
 199 /* Add a new instance to an existing group */
 200 int cfg_add_group_inst(cfg_ctx_t *ctx, str *group_name, unsigned int group_id);
 201
 202 /* Delete an instance of a group */
 203 int cfg_del_group_inst(cfg_ctx_t *ctx, str *group_name, unsigned int group_id);
 204
 205 /* Check the existance of a group instance.
 206  * return value:
 207  *      1: exists
 208  *      0: does not exist
 209  */
 210 int cfg_group_inst_exists(cfg_ctx_t *ctx, str *group_name, unsigned int group_id);
 211
 212 /* Apply the changes to a group instance as long as the additional variable
 213  * belongs to the specified group_id. *add_var_p is moved to the next additional
 214  * variable, and all the consumed variables are freed.
 215  */
 216 int cfg_apply_list(cfg_group_inst_t *ginst, cfg_group_t *group,
 217                         unsigned int group_id, cfg_add_var_t **add_var_p);
 218
 219 #endif /* _CFG_CTX_H */