aboutsummaryrefslogtreecommitdiffstats
path: root/include/asterisk/config.h
blob: 17fe05ec4b863cf6a268cbbae2fd2efaf31b94ed (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
/*
 * Asterisk -- A telephony toolkit for Linux.
 *
 * Configuration File Parser
 * 
 * Copyright (C) 1999-2005, Mark Spencer
 *
 * Mark Spencer <markster@digium.com>
 *
 * This program is free software, distributed under the terms of
 * the GNU General Public License
 */

#ifndef _ASTERISK_CONFIG_H
#define _ASTERISK_CONFIG_H

#if defined(__cplusplus) || defined(c_plusplus)
extern "C" {
#endif

#include <stdarg.h>

struct ast_config;

struct ast_category;

struct ast_variable {
	char *name;
	char *value;
	int lineno;
	int object;		/* 0 for variable, 1 for object */
	int blanklines; 	/* Number of blanklines following entry */
	struct ast_comment *precomments;
	struct ast_comment *sameline;
	struct ast_variable *next;
	char stuff[0];
};

#include "asterisk/config_old.h"

typedef struct ast_config *config_load_func(const char *database, const char *table, const char *configfile, struct ast_config *config);
typedef struct ast_variable *realtime_var_get(const char *database, const char *table, va_list ap);
typedef struct ast_config *realtime_multi_get(const char *database, const char *table, va_list ap);
typedef int realtime_update(const char *database, const char *table, const char *keyfield, const char *entity, va_list ap);

struct ast_config_engine {
	char *name;
	config_load_func *load_func;
	realtime_var_get *realtime_func;
	realtime_multi_get *realtime_multi_func;
	realtime_update *update_func;
	struct ast_config_engine *next;
};

/*! Load a config file */
/*! 
 * \param configfile path of file to open.  If no preceding '/' character, path is considered relative to AST_CONFIG_DIR
 * Create a config structure from a given configuration file.
 *
 * Returns NULL on error, or an ast_config data structure on success
 */
struct ast_config *ast_config_load(const char *filename);

/*! Destroys a config */
/*!
 * \param config pointer to config data structure
 * Free memory associated with a given config
 *
 */
void ast_config_destroy(struct ast_config *config);

/*! Goes through categories */
/*!
 * \param config Which config structure you wish to "browse"
 * \param prev A pointer to a previous category.
 * 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.
 *
 * Returns a category on success, or NULL on failure/no-more-categories
 */
char *ast_category_browse(struct ast_config *config, const char *prev);

/*! Goes through variables */
/*!
 * Somewhat similar in intent as the ast_category_browse.
 * List variables of config file category
 *
 * Returns ast_variable list on success, or NULL on failure
 */
struct ast_variable *ast_variable_browse(const struct ast_config *config, const char *category);

/*! Gets a variable */
/*!
 * \param config which (opened) config to use
 * \param category category under which the variable lies
 * \param value which variable you wish to get the data for
 * Goes through a given config file in the given category and searches for the given variable
 *
 * Returns the variable value on success, or NULL if unable to find it.
 */
char *ast_variable_retrieve(const struct ast_config *config, const char *category, const char *variable);

/*! Make sure something is true */
/*!
 * Determine if a string containing a boolean value is "true".
 * 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".  
 *
 * Returns 0 if val is a NULL pointer, -1 if "true", and 0 otherwise.
 */
int ast_true(const char *val);

/*! Make sure something is false */
/*!
 * Determine if a string containing a boolean value is "false".
 * 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".  
 *
 * Returns 0 if val is a NULL pointer, -1 if "false", and 0 otherwise.
 */
int ast_false(const char *val);

/*! Retrieve a category if it exists */
/*!
 * \param config which config to use
 * \param category_name name of the category you're looking for
 * This will search through the categories within a given config file for a match.
 *
 * Returns pointer to category if found, NULL if not.
 */
struct ast_category *ast_category_get(const struct ast_config *config, const char *category_name);

/*! Check for category duplicates */
/*!
 * \param config which config to use
 * \param category_name name of the category you're looking for
 * This will search through the categories within a given config file for a match.
 *
 * Return non-zero if found
 */
int ast_category_exist(const struct ast_config *config, const char *category_name);

/*! Retrieve realtime configuration */
/*!
 * \param family which family/config to lookup
 * \param keyfield which field to use as the key
 * \param lookup which value to look for in the key field to match the entry.
 * This will use builtin configuration backends to look up a particular 
 * entity in realtime and return a variable list of its parameters.  Note
 * that unlike the variables in ast_config, the resulting list of variables
 * MUST be fred with ast_free_runtime() as there is no container.
 */
struct ast_variable *ast_load_realtime(const char *family, ...);

/*! Retrieve realtime configuration */
/*!
 * \param family which family/config to lookup
 * \param keyfield which field to use as the key
 * \param lookup which value to look for in the key field to match the entry.
 * This will use builtin configuration backends to look up a particular 
 * entity in realtime and return a variable list of its parameters. Unlike
 * the ast_load_realtime, this function can return more than one entry and
 * is thus stored inside a taditional ast_config structure rather than 
 * just returning a linked list of variables.
 */
struct ast_config *ast_load_realtime_multientry(const char *family, ...);

/*! Update realtime configuration */
/*!
 * \param family which family/config to be updated
 * \param keyfield which field to use as the key
 * \param lookup which value to look for in the key field to match the entry.
 * \param variable which variable should be updated in the config, NULL to end list
 * \param value the value to be assigned to that variable in the given entity.
 * This function is used to update a parameter in realtime configuration space.
 *
 */
int ast_update_realtime(const char *family, const char *keyfield, const char *lookup, ...);

/*! Free variable list */
/*!
 * \param var the linked list of variables to free
 * This function frees a list of variables.
 */
void ast_variables_destroy(struct ast_variable *var);

int ast_config_engine_register(struct ast_config_engine *newconfig);
int ast_config_engine_deregister(struct ast_config_engine *del);
int register_config_cli(void);
void read_config_maps(void);

struct ast_config *ast_config_new(void);
struct ast_category *ast_config_get_current_category(const struct ast_config *cfg);
void ast_config_set_current_category(struct ast_config *cfg, const struct ast_category *cat);

struct ast_category *ast_category_new(const char *name);
void ast_category_append(struct ast_config *config, struct ast_category *cat);
int ast_category_delete(struct ast_config *cfg, char *category);
void ast_category_destroy(struct ast_category *cat);
struct ast_variable *ast_category_detach_variables(struct ast_category *cat);
void ast_category_rename(struct ast_category *cat, const char *name);

struct ast_variable *ast_variable_new(const char *name, const char *value);
void ast_variable_append(struct ast_category *category, struct ast_variable *variable);
int ast_variable_delete(struct ast_config *cfg, char *category, char *variable, char *value);

int config_text_file_save(const char *filename, const struct ast_config *cfg, const char *generator);

struct ast_config *ast_config_internal_load(const char *configfile, struct ast_config *cfg);

#if defined(__cplusplus) || defined(c_plusplus)
}
#endif

#endif