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