Merge config updates (bug #3406)
[asterisk/asterisk.git] / include / asterisk / config.h
1 /*
2  * Asterisk -- A telephony toolkit for Linux.
3  *
4  * Configuration File Parser
5  * 
6  * Copyright (C) 1999-2005, Mark Spencer
7  *
8  * Mark Spencer <markster@digium.com>
9  *
10  * This program is free software, distributed under the terms of
11  * the GNU General Public License
12  */
13
14 #ifndef _ASTERISK_CONFIG_H
15 #define _ASTERISK_CONFIG_H
16
17 #if defined(__cplusplus) || defined(c_plusplus)
18 extern "C" {
19 #endif
20
21 #include <stdarg.h>
22
23 struct ast_config;
24
25 struct ast_category;
26
27 struct ast_variable {
28         char *name;
29         char *value;
30         int lineno;
31         int object;             /* 0 for variable, 1 for object */
32         int blanklines;         /* Number of blanklines following entry */
33         struct ast_comment *precomments;
34         struct ast_comment *sameline;
35         struct ast_variable *next;
36         char stuff[0];
37 };
38
39 #include <asterisk/config_old.h>
40
41 typedef struct ast_config *config_load_func(const char *database, const char *table, const char *configfile, struct ast_config *config);
42 typedef struct ast_variable *realtime_var_get(const char *database, const char *table, va_list ap);
43 typedef struct ast_config *realtime_multi_get(const char *database, const char *table, va_list ap);
44 typedef int realtime_update(const char *database, const char *table, const char *keyfield, const char *entity, va_list ap);
45
46 struct ast_config_engine {
47         char *name;
48         config_load_func *load_func;
49         realtime_var_get *realtime_func;
50         realtime_multi_get *realtime_multi_func;
51         realtime_update *update_func;
52         struct ast_config_engine *next;
53 };
54
55 /*! Load a config file */
56 /*! 
57  * \param configfile path of file to open.  If no preceding '/' character, path is considered relative to AST_CONFIG_DIR
58  * Create a config structure from a given configuration file.
59  *
60  * Returns NULL on error, or an ast_config data structure on success
61  */
62 struct ast_config *ast_config_load(const char *filename);
63
64 /*! Destroys a config */
65 /*!
66  * \param config pointer to config data structure
67  * Free memory associated with a given config
68  *
69  */
70 void ast_config_destroy(struct ast_config *config);
71
72 /*! Goes through categories */
73 /*!
74  * \param config Which config structure you wish to "browse"
75  * \param prev A pointer to a previous category.
76  * This funtion is kind of non-intuitive in it's use.  To begin, one passes NULL as the second arguement.  It will return a pointer to the string of the first category in the file.  From here on after, one must then pass the previous usage's return value as the second pointer, and it will return a pointer to the category name afterwards.
77  *
78  * Returns a category on success, or NULL on failure/no-more-categories
79  */
80 char *ast_category_browse(struct ast_config *config, const char *prev);
81
82 /*! Goes through variables */
83 /*!
84  * Somewhat similar in intent as the ast_category_browse.
85  * List variables of config file category
86  *
87  * Returns ast_variable list on success, or NULL on failure
88  */
89 struct ast_variable *ast_variable_browse(const struct ast_config *config, const char *category);
90
91 /*! Gets a variable */
92 /*!
93  * \param config which (opened) config to use
94  * \param category category under which the variable lies
95  * \param value which variable you wish to get the data for
96  * Goes through a given config file in the given category and searches for the given variable
97  *
98  * Returns the variable value on success, or NULL if unable to find it.
99  */
100 char *ast_variable_retrieve(const struct ast_config *config, const char *category, const char *variable);
101
102 /*! Make sure something is true */
103 /*!
104  * Determine if a string containing a boolean value is "true".
105  * This function checks to see whether a string passed to it is an indication of an "true" value.  It checks to see if the string is "yes", "true", "y", "t", "on" or "1".  
106  *
107  * Returns 0 if val is a NULL pointer, -1 if "true", and 0 otherwise.
108  */
109 int ast_true(const char *val);
110
111 /*! Make sure something is false */
112 /*!
113  * Determine if a string containing a boolean value is "false".
114  * This function checks to see whether a string passed to it is an indication of an "false" value.  It checks to see if the string is "no", "false", "n", "f", "off" or "0".  
115  *
116  * Returns 0 if val is a NULL pointer, -1 if "false", and 0 otherwise.
117  */
118 int ast_false(const char *val);
119
120 /*! Retrieve a category if it exists */
121 /*!
122  * \param config which config to use
123  * \param category_name name of the category you're looking for
124  * This will search through the categories within a given config file for a match.
125  *
126  * Returns pointer to category if found, NULL if not.
127  */
128 struct ast_category *ast_category_get(const struct ast_config *config, const char *category_name);
129
130 /*! Check for category duplicates */
131 /*!
132  * \param config which config to use
133  * \param category_name name of the category you're looking for
134  * This will search through the categories within a given config file for a match.
135  *
136  * Return non-zero if found
137  */
138 int ast_category_exist(const struct ast_config *config, const char *category_name);
139
140 /*! Retrieve realtime configuration */
141 /*!
142  * \param family which family/config to lookup
143  * \param keyfield which field to use as the key
144  * \param lookup which value to look for in the key field to match the entry.
145  * This will use builtin configuration backends to look up a particular 
146  * entity in realtime and return a variable list of its parameters.  Note
147  * that unlike the variables in ast_config, the resulting list of variables
148  * MUST be fred with ast_free_runtime() as there is no container.
149  */
150 struct ast_variable *ast_load_realtime(const char *family, ...);
151
152 /*! Retrieve realtime configuration */
153 /*!
154  * \param family which family/config to lookup
155  * \param keyfield which field to use as the key
156  * \param lookup which value to look for in the key field to match the entry.
157  * This will use builtin configuration backends to look up a particular 
158  * entity in realtime and return a variable list of its parameters. Unlike
159  * the ast_load_realtime, this function can return more than one entry and
160  * is thus stored inside a taditional ast_config structure rather than 
161  * just returning a linked list of variables.
162  */
163 struct ast_config *ast_load_realtime_multientry(const char *family, ...);
164
165 /*! Update realtime configuration */
166 /*!
167  * \param family which family/config to be updated
168  * \param keyfield which field to use as the key
169  * \param lookup which value to look for in the key field to match the entry.
170  * \param variable which variable should be updated in the config, NULL to end list
171  * \param value the value to be assigned to that variable in the given entity.
172  * This function is used to update a parameter in realtime configuration space.
173  *
174  */
175 int ast_update_realtime(const char *family, const char *keyfield, const char *lookup, ...);
176
177 /*! Free variable list */
178 /*!
179  * \param var the linked list of variables to free
180  * This function frees a list of variables.
181  */
182 void ast_variables_destroy(struct ast_variable *var);
183
184 int ast_config_engine_register(struct ast_config_engine *new);
185 int ast_config_engine_deregister(struct ast_config_engine *del);
186 int register_config_cli(void);
187 void read_config_maps(void);
188
189 struct ast_config *ast_config_new(void);
190 struct ast_category *ast_config_get_current_category(const struct ast_config *cfg);
191 void ast_config_set_current_category(struct ast_config *cfg, const struct ast_category *cat);
192
193 struct ast_category *ast_category_new(const char *name);
194 void ast_category_append(struct ast_config *config, struct ast_category *cat);
195 int ast_category_delete(struct ast_config *cfg, char *category);
196 void ast_category_destroy(struct ast_category *cat);
197 struct ast_variable *ast_category_detach_variables(struct ast_category *cat);
198 void ast_category_rename(struct ast_category *cat, const char *name);
199
200 struct ast_variable *ast_variable_new(const char *name, const char *value);
201 void ast_variable_append(struct ast_category *category, struct ast_variable *variable);
202 int ast_variable_delete(struct ast_config *cfg, char *category, char *variable, char *value);
203
204 int config_text_file_save(const char *filename, const struct ast_config *cfg, const char *generator);
205
206 struct ast_config *ast_config_internal_load(const char *configfile, struct ast_config *cfg);
207
208 #if defined(__cplusplus) || defined(c_plusplus)
209 }
210 #endif
211
212 #endif