File: config.h

package info (click to toggle)
janus 0.7.3-2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, sid
  • size: 15,360 kB
  • sloc: ansic: 130,260; makefile: 554; sh: 153; lisp: 9
file content (170 lines) | stat: -rw-r--r-- 9,252 bytes parent folder | download
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
/*! \file    config.h
 * \author   Lorenzo Miniero <lorenzo@meetecho.com>
 * \copyright GNU General Public License v3
 * \brief    Configuration files parsing (headers)
 * \details  Implementation of a parser of INI and libconfig configuration files.
 *
 * \ingroup core
 * \ref core
 */

#ifndef _JANUS_CONFIG_H
#define _JANUS_CONFIG_H

#include <glib.h>

/*! \brief Configuration element type */
typedef enum janus_config_type {
	/*! \brief Anything (just for searches) */
	janus_config_type_any = 1,
	/*! \brief Plain item */
	janus_config_type_item,
	/*! \brief Category */
	janus_config_type_category,
	/*! \brief Array */
	janus_config_type_array,
} janus_config_type;

/*! \brief Generic configuration container (can be an item, a category or an array) */
typedef struct janus_config_container {
	/*! \brief Whether this is a category, an item or an array */
	janus_config_type type;
	/*! \brief Name of the item/category/array */
	const char *name;
	/*! \brief Value of the item (item only) */
	const char *value;
	/*! \brief Linked list of contained items/categories/arrays (category and array only) */
	GList *list;
} janus_config_container;

/*! \brief Configuration item (defined for backwards compatibility) */
typedef struct janus_config_container janus_config_item;

/*! \brief Configuration category (defined for backwards compatibility) */
typedef struct janus_config_container janus_config_category;

/*! \brief Configuration array */
typedef struct janus_config_container janus_config_array;

/*! \brief Configuration container */
typedef struct janus_config {
	/*! \brief Whether this is a libconfig (jcfg for us) or an INI config */
	gboolean is_jcfg;
	/*! \brief Name of the configuration */
	const char *name;
	/*! \brief Linked list of items/categories/arrays */
	GList *list;
} janus_config;


/*! \brief Method to parse an INI configuration file
 * @param[in] config_file Path to the configuration file
 * @returns A pointer to a valid janus_config instance if successful, NULL otherwise */
janus_config *janus_config_parse(const char *config_file);
/*! \brief Method to create a new, empty, configuration
 * @param[in] name Name to give to the configuration
 * @returns A pointer to a valid janus_config instance if successful, NULL otherwise */
janus_config *janus_config_create(const char *name);
/*! \brief Helper method to print a configuration on the standard output
 * @note This prints with LOG_VERB: if you need the configuration to be visible at
 * a different debugging level, use janus_config_print_as instead
 * @param[in] config The configuration to print */
void janus_config_print(janus_config *config);
/*! \brief Helper method to print a configuration on the standard output
 * using a different logging level than LOG_VERB
 * @param[in] config The configuration to print
 * @param[in] level The debugging level to use */
void janus_config_print_as(janus_config *config, int level);
/*! \brief Helper method to save a configuration to a file
 * @param[in] config The configuration to sav
 * @param[in] folder The folder the file should be saved to
 * @param[in] filename The file name, extension included (should be .jcfg, or .cfg for legacy INI files)
 * @returns 0 if successful, a negative integer otherwise */
int janus_config_save(janus_config *config, const char *folder, const char *filename);
/*! \brief Destroy a configuration container instance
 * @param[in] config The configuration to destroy */
void janus_config_destroy(janus_config *config);

/*! \brief Method to create a new janus_config_item instance from name and value
 * @param[in] name Name to give to the item
 * @param[in] value Value of the item (optional)
 * @returns A valid janus_config_item instance if successful, NULL otherwise */
janus_config_item *janus_config_item_create(const char *name, const char *value);
/*! \brief Method to create a new janus_config_category instance
 * @param[in] name Name to give to the category
 * @returns A pointer to a valid janus_config_category instance if successful, NULL otherwise */
janus_config_category *janus_config_category_create(const char *name);
/*! \brief Method to create a new janus_config_array instance
 * @param[in] name Name to give to the array
 * @returns A valid janus_config_array instance if successful, NULL otherwise */
janus_config_array *janus_config_array_create(const char *name);
/*! \brief Helper method to quickly destroy an item, category or array
 * @note This method also destroys anything it contains, if it's a category or
 * array, but will not unlink the object from its parent: this is up to the caller
 * @param[in] container The item/category/array to destroy */
void janus_config_container_destroy(janus_config_container *container);

/*! \brief Helper method to quickly get an item, category, or array
 * @note If the parent container is NULL, the lookup is done at the root. If something is found
 * but type doesn't match (name is an array but we're looking for a category), NULL is returned.
 * @param[in] config The configuration instance
 * @param[in] parent The parent container (category or array), if any
 * @param[in] type The type of container to look for
 * @param[in] name The name of the item/category/array to look for
 * @returns A pointer to a valid janus_config_container instance if successful, NULL otherwise */
janus_config_container *janus_config_get(janus_config *config,
	janus_config_container *parent, janus_config_type type, const char *name);
/*! \brief Same as janus_config_get, but creates the element if it doesn't exist
 * @note Nothing is created if type is janus_config_type_any.
 * @param[in] config The configuration instance
 * @param[in] parent The parent container (category or array), if any
 * @param[in] type The type of container to look for
 * @param[in] name The name of the item/category/array to look for
 * @returns A pointer to a valid janus_config_container instance if successful, NULL otherwise */
janus_config_container *janus_config_get_create(janus_config *config,
	janus_config_container *parent, janus_config_type type, const char *name);
/*! \brief Helper method to quickly lookup an item, category, or array
 * @note If something is found but type doesn't match (name is an array
 * but we're looking for a category), NULL is returned.
 * @param[in] config The configuration instance
 * @returns A pointer to a valid janus_config_container instance if successful, NULL otherwise */
janus_config_container *janus_config_search(janus_config *config, ...);

/*! \brief Add an item/category/array instance to a category or array
 * \note If adding to a category and the item/category/array already exists, it is replaced;
 * it is appended if the target is an array instead, where duplicates are accepted.
 * @param[in] config The configuration instance
 * @param[in] parent The category or array to add the item to, if any
 * @param[in] item The item/category/array to add
 * @returns 0 if successful, a negative integer otherwise */
int janus_config_add(janus_config *config, janus_config_container *parent, janus_config_container *item);
/*! \brief Remove an existing item with the specific name from a category/array
 * @param[in] config The configuration instance
 * @param[in] parent The category/array to remove the item from, if any
 * @param[in] name The name of the item/category/array to remove
 * @returns 0 if successful, a negative integer otherwise */
int janus_config_remove(janus_config *config, janus_config_container *parent, const char *name);

/*! \brief Helper method to return the list of plain items, either in root or from a parent
 * @note The method returns a new GList: it's up to the caller to free it. The values
 * of the list data must NOT be freed, though, as it's just linked from the configuration.
 * @param[in] config The configuration instance
 * @param[in] parent The parent container (category or array), if any
 * @returns A pointer to the categories GLib linked list of items if successful, NULL otherwise */
GList *janus_config_get_items(janus_config *config, janus_config_container *parent);
/*! \brief Helper method to return the list of categories, either in root or from a parent
 * @note The method returns a new GList: it's up to the caller to free it. The values
 * of the list data must NOT be freed, though, as it's just linked from the configuration.
 * @param[in] config The configuration instance
 * @param[in] parent The parent container (category or array), if any
 * @returns A pointer to the categories GLib linked list of categories if successful, NULL otherwise */
GList *janus_config_get_categories(janus_config *config, janus_config_container *parent);
/*! \brief Helper method to return the list of arrays, either in root or from a parent
 * @note The method returns a new GList: it's up to the caller to free it. The values
 * of the list data must NOT be freed, though, as it's just linked from the configuration.
 * @param[in] config The configuration instance
 * @param[in] parent The parent container (category or array), if any
 * @returns A pointer to the categories GLib linked list of arrays if successful, NULL otherwise */
GList *janus_config_get_arrays(janus_config *config, janus_config_container *parent);

#endif