b8be39bf7ccc7813b7d00a682eb906634c7c5ce7
[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, Mark Spencer
7  *
8  * Mark Spencer <markster@linux-support.net>
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 struct ast_config;
22
23 struct ast_comment {
24         struct ast_comment *next;
25         char cmt[0];
26 };
27
28 struct ast_variable {
29         char *name;
30         char *value;
31         int lineno;
32         int object;             /* 0 for variable, 1 for object */
33         int blanklines;         /* Number of blanklines following entry */
34         struct ast_comment *precomments;
35         struct ast_comment *sameline;
36         struct ast_variable *next;
37         char stuff[0];
38 };
39
40 /*! Load a config file */
41 /*! 
42  * \param configfile path of file to open.  If no preceding '/' character, path is considered relative to AST_CONFIG_DIR
43  * Create a config structure from a given configuration file.
44  * Returns NULL on error, or an ast_config data structure on success
45  */
46 struct ast_config *ast_load(char *configfile);
47
48 /*! Removes a config */
49 /*!
50  * \param config config data structure associated with the config.
51  * Free memory associated with a given config
52  * Returns nothing
53  */
54 void ast_destroy(struct ast_config *config);
55
56 /*! Goes through categories */
57 /*!
58  * \param config Which config file you wish to "browse"
59  * \param prev A pointer to a previous category.
60  * 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.  Note:  If you manually strcpy a string into a character array and pass it thinking it will return your category, it will not; the comparisons are not done doing strcmp, they are done by checking whether the value of the string POINTER is the same.
61  * Returns a category on success, or NULL on failure/no-more-categories
62  */
63 char *ast_category_browse(struct ast_config *config, char *prev);
64
65 /*! Goes through variables */
66 /*!
67  * Somewhat similar in intent as the ast_category_browse.  The category MUST be an actual pointer to an actual category (such as one obtained by using ast_category_browse()).
68  * List variables of config file
69  * Returns ast_variable list on success, or NULL on failure
70  */
71 struct ast_variable *ast_variable_browse(const struct ast_config *config, const char *category);
72
73 /*! Gets a variable */
74 /*!
75  * \param config which (opened) config to use
76  * \param category category under which the variable lies (must be a pointer to the category, such as one given by ast_category_browse)
77  * \param value which variable you wish to get the data for
78  * Goes through a given config file in the given category and searches for the given variable
79  * Returns the variable value on success, or NULL if unable to find it.
80  * Retrieve a specific variable */
81 char *ast_variable_retrieve(const struct ast_config *config, const char *category, const char *value);
82
83 /*! Make sure something is true */
84 /*!
85  * Determine affermativeness of a boolean value.
86  * This function checks to see whether a string passed to it is an indication of an affirmitave value.  It checks to see if the string is "yes", "true", "y", "t", and "1".  
87  * Returns 0 if the value of s is a NULL pointer, 0 on "truth", and -1 on falsehood.
88  */
89 int ast_true(const char *val);
90
91 /*! Make sure something is false */
92 /*!
93  * Determine falseness of a boolean value.
94  * This function checks to see whether a string passed to it is an indication of a negatirve value.  It checks to see if the string is "no", "false", "n", "f", and "0".  
95  * Returns 0 if the value of s is a NULL pointer, 0 on "truth", and -1 on falsehood.
96  */
97 int ast_false(const char *val);
98
99 /*! Retrieve a category if it exists
100  * \param config which config to use
101  * \param category_name name of the category you're looking for
102  * This will search through the categories within a given config file and search for a match.  The passed category_name can be a regular string.
103  * Returns pointer to category if found, NULL if not. */
104 struct ast_category *ast_category_get(const struct ast_config *config, const char *category_name);
105
106 /*! Check for category duplicates */
107 /*!
108  * \param config which config to use
109  * \param category_name name of the category you're looking for
110  * This will search through the categories within a given config file and search for a match.  The passed category_name can be a regular string (as opposed to a pointer of an existent string, lol)
111  * Browse config structure and check for category duplicity Return non-zero if found */
112 int ast_category_exist(struct ast_config *config, char *category_name);
113
114 /*! Retrieve realtime configuration */
115 /*!
116  * \param family which family/config to lookup
117  * \param keyfield which field to use as the key
118  * \param lookup which value to look for in the key field to match the entry.
119  * This will use builtin configuration backends to look up a particular 
120  * entity in realtime and return a variable list of its parameters.  Note
121  * that unlike the variables in ast_config, the resulting list of variables
122  * MUST be fred with ast_free_runtime() as there is no container.
123  */
124 struct ast_variable *ast_load_realtime(const char *family, ...);
125
126 /*! Retrieve realtime configuration */
127 /*!
128  * \param family which family/config to lookup
129  * \param keyfield which field to use as the key
130  * \param lookup which value to look for in the key field to match the entry.
131  * This will use builtin configuration backends to look up a particular 
132  * entity in realtime and return a variable list of its parameters. Unlike
133  * the ast_load_realtime, this function can return more than one entry and
134  * is thus stored inside a taditional ast_config structure rather than 
135  * just returning a linked list of variables.
136  */
137 struct ast_config *ast_load_realtime_multientry(const char *family, ...);
138
139 /*! Update realtime configuration */
140 /*!
141  * \param family which family/config to be updated
142  * \param keyfield which field to use as the key
143  * \param lookup which value to look for in the key field to match the entry.
144  * \param variable which variable should be updated in the config, NULL to end list
145  * \param value the value to be assigned to that variable in the given entity.
146  * This function is used to update a parameter in realtime configuration space.
147  *
148  */
149 int ast_update_realtime(const char *family, const char *keyfield, const char *lookup, ...);
150
151 /*! Free realtime configuration */
152 /*!
153  * \param var the linked list of variables to free
154  * This command free's a list of variables and should ONLY be used
155  * in conjunction with ast_load_realtime and not with the regular ast_load.
156  */
157 void ast_destroy_realtime(struct ast_variable *var);
158
159 #if defined(__cplusplus) || defined(c_plusplus)
160 }
161 #endif
162
163
164
165 #endif