1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright 2018, Olivier MATZ <zer0@droids-corp.org>
6 * @defgroup config Node configuration
9 * @brief Configure nodes behavior through generic API.
15 #include <sys/queue.h>
20 #ifndef EC_COUNT_OF //XXX
21 #define EC_COUNT_OF(x) ((sizeof(x)/sizeof(0[x])) / \
22 ((size_t)(!(sizeof(x) % sizeof(0[x])))))
29 * The type identifier for a config value.
32 EC_CONFIG_TYPE_NONE = 0,
35 EC_CONFIG_TYPE_UINT64,
36 EC_CONFIG_TYPE_STRING,
43 * Structure describing the format of a configuration value.
45 * This structure is used in a const array which is referenced by a
46 * struct ec_config. Each entry of the array represents a key/value
47 * storage of the configuration dictionary.
49 struct ec_config_schema {
50 const char *key; /**< The key string (NULL for list elts). */
51 const char *desc; /**< A description of the value. */
52 enum ec_config_type type; /**< Type of the value */
53 /* XXX flags: mandatory */
56 /** If type is dict or list, the schema of the dict or list
57 * elements. Else must be NULL. */
58 const struct ec_config_schema *subschema;
61 TAILQ_HEAD(ec_config_list, ec_config);
64 * Structure storing the configuration data.
67 /** type of value stored in the union */
68 enum ec_config_type type;
71 bool boolean; /** Boolean value */
72 int64_t i64; /** Signed integer value */
73 uint64_t u64; /** Unsigned integer value */
74 char *string; /** String value */
75 struct ec_node *node; /** Node value */
76 struct ec_dict *dict; /** Hash table value */
77 struct ec_config_list list; /** List value */
81 * Next in list, only valid if type is list.
83 TAILQ_ENTRY(ec_config) next;
89 * Validate a configuration schema array.
92 * Pointer to the first element of the schema array. The array
93 * must be terminated by a sentinel entry (type == EC_CONFIG_TYPE_NONE).
95 * 0 if the schema is valid, or -1 on error (errno is set).
97 int ec_config_schema_validate(const struct ec_config_schema *schema);
100 * Dump a configuration schema array.
103 * Output stream on which the dump will be sent.
105 * Pointer to the first element of the schema array. The array
106 * must be terminated by a sentinel entry (type == EC_CONFIG_TYPE_NONE).
108 void ec_config_schema_dump(FILE *out, const struct ec_config_schema *schema);
111 * Find a schema entry matching the key.
113 * Browse the schema array and lookup for the given key.
116 * Pointer to the first element of the schema array. The array
117 * must be terminated by a sentinel entry (type == EC_CONFIG_TYPE_NONE).
119 * The schema entry if it matches a key, or NULL if not found.
121 const struct ec_config_schema *
122 ec_config_schema_lookup(const struct ec_config_schema *schema,
126 * Get the type of a schema entry.
129 * Pointer to an element of the schema array.
131 * The type of the schema entry.
134 ec_config_schema_type(const struct ec_config_schema *schema_elt);
137 * Get the subschema of a schema entry.
140 * Pointer to an element of the schema array.
142 * The subschema if any, or NULL.
144 const struct ec_config_schema *
145 ec_config_schema_sub(const struct ec_config_schema *schema_elt);
148 * Check if a key name is reserved in a config dict.
150 * Some key names are reserved and should not be used in configs.
153 * The name of the key to test.
155 * True if the key name is reserved and must not be used, else false.
157 bool ec_config_key_is_reserved(const char *name);
160 * Array of reserved key names.
162 extern const char *ec_config_reserved_keys[];
168 * Get the type of the configuration.
173 * The configuration type.
175 enum ec_config_type ec_config_get_type(const struct ec_config *config);
178 * Create a boolean configuration value.
181 * The boolean value to be set.
183 * The configuration object, or NULL on error (errno is set).
185 struct ec_config *ec_config_bool(bool boolean);
188 * Create a signed integer configuration value.
191 * The signed integer value to be set.
193 * The configuration object, or NULL on error (errno is set).
195 struct ec_config *ec_config_i64(int64_t i64);
198 * Create an unsigned configuration value.
201 * The unsigned integer value to be set.
203 * The configuration object, or NULL on error (errno is set).
205 struct ec_config *ec_config_u64(uint64_t u64);
208 * Create a string configuration value.
211 * The string value to be set. The string is copied into the
212 * configuration object.
214 * The configuration object, or NULL on error (errno is set).
216 struct ec_config *ec_config_string(const char *string);
219 * Create a node configuration value.
222 * The node pointer to be set. The node is "consumed" by
223 * the function and should not be used by the caller, even
224 * on error. The caller can use ec_node_clone() to keep a
225 * reference on the node.
227 * The configuration object, or NULL on error (errno is set).
229 struct ec_config *ec_config_node(struct ec_node *node);
232 * Create a hash table configuration value.
235 * A configuration object containing an empty hash table, or NULL on
236 * error (errno is set).
238 struct ec_config *ec_config_dict(void);
241 * Create a list configuration value.
244 * The configuration object containing an empty list, or NULL on
245 * error (errno is set).
247 struct ec_config *ec_config_list(void);
250 * Add a config object into a list.
253 * The list configuration in which the value will be added.
255 * The value configuration to add in the list. The value object
256 * will be freed when freeing the list object. On error, the
257 * value object is also freed.
259 * 0 on success, else -1 (errno is set).
261 int ec_config_list_add(struct ec_config *list, struct ec_config *value);
264 * Remove an element from a list.
266 * The element is freed and should not be accessed.
269 * The list configuration.
271 * The element to remove from the list.
273 * 0 on success, -1 on error (errno is set).
275 int ec_config_list_del(struct ec_config *list, struct ec_config *config);
278 * Count the number of elements in a list or dict.
281 * The configuration that must be a list or a dict.
283 * The number of elements, or -1 on error (errno is set).
285 ssize_t ec_config_count(const struct ec_config *config);
288 * Validate a configuration.
291 * A hash table configuration to validate.
293 * Pointer to the first element of the schema array. The array
294 * must be terminated by a sentinel entry (type == EC_CONFIG_TYPE_NONE).
296 * 0 on success, -1 on error (errno is set).
298 int ec_config_validate(const struct ec_config *dict,
299 const struct ec_config_schema *schema);
302 * Set a value in a hash table configuration
305 * A hash table configuration to validate.
309 * The value to set. The value object will be freed when freeing the
310 * dict object. On error, the value object is also freed.
312 * 0 on success, -1 on error (errno is set).
314 int ec_config_dict_set(struct ec_config *dict, const char *key,
315 struct ec_config *value);
318 * Remove an element from a hash table configuration.
320 * The element is freed and should not be accessed.
323 * A hash table configuration to validate.
325 * The key of the configuration to delete.
327 * 0 on success, -1 on error (errno is set).
329 int ec_config_dict_del(struct ec_config *config, const char *key);
332 * Compare two configurations.
334 int ec_config_cmp(const struct ec_config *config1,
335 const struct ec_config *config2);
338 * Get configuration value.
340 struct ec_config *ec_config_dict_get(const struct ec_config *config,
344 * Get the first element of a list.
347 * for (config = ec_config_list_iter(list);
349 * config = ec_config_list_next(list, config)) {
354 * The list configuration to iterate.
356 * The first configuration element, or NULL on error (errno is set).
358 struct ec_config *ec_config_list_first(struct ec_config *list);
361 * Get next element in list.
364 * The list configuration beeing iterated.
366 * The current configuration element.
368 * The next configuration element, or NULL if there is no more element.
371 ec_config_list_next(struct ec_config *list, struct ec_config *config);
374 * Free a configuration.
377 * The element to free.
379 void ec_config_free(struct ec_config *config);
382 * Compare two configurations.
385 * 0 if the configurations are equal, else -1.
387 int ec_config_cmp(const struct ec_config *value1,
388 const struct ec_config *value2);
391 * Duplicate a configuration.
394 * The configuration to duplicate.
396 * The duplicated configuration, or NULL on error (errno is set).
399 ec_config_dup(const struct ec_config *config);
402 * Dump a configuration.
405 * Output stream on which the dump will be sent.
407 * The configuration to dump.
409 void ec_config_dump(FILE *out, const struct ec_config *config);