Merge remote branch 'origin/andrei/pointer_alias_warnings'
[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., 59 Temple Place, Suite 330, Boston, MA  02111-1307  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         /* blob that contains the new value */
53         union cfg_var_value new_val; /* variable size */
54 } cfg_changed_var_t;
55
56 /*! \brief callback that is called when a new group is declared */
57 typedef void (*cfg_on_declare)(str *, cfg_def_t *);
58
59 /*! \brief linked list of registered contexts */
60 typedef struct _cfg_ctx {
61         /* variables that are already changed
62         but have not been committed yet */
63         cfg_changed_var_t       *changed_first;
64         cfg_changed_var_t       *changed_last;
65         /* lock protecting the linked-list of
66         changed variables */
67         gen_lock_t              lock;
68
69         /* callback that is called when a new
70         group is registered */
71         cfg_on_declare          on_declare_cb;
72
73         struct _cfg_ctx *next;
74 } cfg_ctx_t;
75
76 #define CFG_CTX_LOCK(ctx)       lock_get(&(ctx)->lock)
77 #define CFG_CTX_UNLOCK(ctx)     lock_release(&(ctx)->lock)
78
79 /*! \brief creates a new config context that is an interface to the
80  * cfg variables with write permission */
81 int cfg_register_ctx(cfg_ctx_t **handle, cfg_on_declare on_declare_cb);
82
83 /*! \brief free the memory allocated for the contexts */
84 void cfg_ctx_destroy(void);
85
86 /*! \brief set the value of a variable without the need of explicit commit */
87 int cfg_set_now(cfg_ctx_t *ctx, str *group_name, str *var_name,
88                         void *val, unsigned int val_type);
89 int cfg_set_now_int(cfg_ctx_t *ctx, str *group_name, str *var_name, int val);
90 int cfg_set_now_string(cfg_ctx_t *ctx, str *group_name, str *var_name, char *val);
91 int cfg_set_now_str(cfg_ctx_t *ctx, str *group_name, str *var_name, str *val);
92
93 /* sets the value of a variable but does not commit the change */
94 int cfg_set_delayed(cfg_ctx_t *ctx, str *group_name, str *var_name,
95                         void *val, unsigned int val_type);
96 int cfg_set_delayed_int(cfg_ctx_t *ctx, str *group_name, str *var_name, int val);
97 int cfg_set_delayed_string(cfg_ctx_t *ctx, str *group_name, str *var_name, char *val);
98 int cfg_set_delayed_str(cfg_ctx_t *ctx, str *group_name, str *var_name, str *val);
99
100 /*! \brief commits the previously prepared changes within the context */
101 int cfg_commit(cfg_ctx_t *ctx);
102
103 /*! \brief drops the not yet committed changes within the context */
104 int cfg_rollback(cfg_ctx_t *ctx);
105
106 /*! \brief returns the value of a variable */
107 int cfg_get_by_name(cfg_ctx_t *ctx, str *group_name, str *var_name,
108                         void **val, unsigned int *val_type);
109
110 /*! \brief returns the description of a variable */
111 int cfg_help(cfg_ctx_t *ctx, str *group_name, str *var_name,
112                         char **ch, unsigned int *input_type);
113
114 /*! \brief notify the drivers about the new config definition */
115 void cfg_notify_drivers(char *group_name, int group_name_len, cfg_def_t *def);
116
117 /*! \brief convert the value to the requested type */
118 int convert_val(unsigned int val_type, void *val,
119                         unsigned int var_type, void **new_val);
120
121 /*! \brief initialize the handle for cfg_get_group_next() */
122 #define cfg_get_group_init(handle) \
123         (*(handle)) = (void *)cfg_group
124
125 /*! \brief returns the group name and the cfg structure definition,
126  * and moves the handle to the next group
127  *
128  * Return value:
129  *      0: no more group
130  *      1: group exists
131  *
132  * can be used as follows:
133  *
134  * void *handle;
135  * cfg_get_group_init(&handle)
136  * while (cfg_get_group_next(&handle, &name, &def)) {
137  *      ...
138  * }
139  */
140 int cfg_get_group_next(void **h,
141                         str *gname, cfg_def_t **def);
142
143 /*! \brief Initialize the handle for cfg_diff_next()
144  * WARNING: keeps the context lock held, do not forget
145  * to release it with cfg_diff_release()
146  */
147 int cfg_diff_init(cfg_ctx_t *ctx,
148                 void **h);
149
150 /*! \brief return the pending changes that have not been
151  * committed yet
152  *
153  * can be used as follows:
154  *
155  * void *handle;
156  * if (cfg_diff_init(ctx, &handle)) return -1
157  * while (cfg_diff_next(&handle
158  *                      &group_name, &var_name,
159  *                      &old_val, &new_val
160  *                      &val_type)
161  * ) {
162  *              ...
163  * }
164  * cfg_diff_release(ctx);
165  */
166 int cfg_diff_next(void **h,
167                         str *gname, str *vname,
168                         void **old_val, void **new_val,
169                         unsigned int *val_type);
170
171 /*! \brief destroy the handle of cfg_diff_next() */
172 void cfg_diff_release(cfg_ctx_t *ctx);
173
174 #endif /* _CFG_CTX_H */