modules/ims_qos: added patch for flow-description bug when request originates from...
[sip-router] / 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 */