1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright 2018, Olivier MATZ <zer0@droids-corp.org>
13 #ifndef EC_COUNT_OF //XXX
14 #define EC_COUNT_OF(x) ((sizeof(x)/sizeof(0[x])) / \
15 ((size_t)(!(sizeof(x) % sizeof(0[x])))))
22 * The type identifier for a config value.
25 EC_CONFIG_TYPE_NONE = 0,
28 EC_CONFIG_TYPE_UINT64,
29 EC_CONFIG_TYPE_STRING,
36 * Structure describing the format of a configuration value.
38 * This structure is used in a const array which is referenced by a
39 * struct ec_config. Each entry of the array represents a key/value
40 * storage of the configuration dictionary.
42 struct ec_config_schema {
43 const char *key; /**< The key string (NULL for list elts). */
44 const char *desc; /**< A description of the value. */
45 enum ec_config_type type; /**< Type of the value */
46 /* XXX flags: mandatory */
49 /** If type is dict or list, the schema of the dict or list
50 * elements. Else must be NULL. */
51 const struct ec_config_schema *subschema;
54 TAILQ_HEAD(ec_config_list, ec_config);
57 * Structure storing the configuration data.
60 /** type of value stored in the union */
61 enum ec_config_type type;
64 bool boolean; /** Boolean value */
65 int64_t i64; /** Signed integer value */
66 uint64_t u64; /** Unsigned integer value */
67 char *string; /** String value */
68 struct ec_node *node; /** Node value */
69 struct ec_keyval *dict; /** Hash table value */
70 struct ec_config_list list; /** List value */
74 * Next in list, only valid if type is list.
76 TAILQ_ENTRY(ec_config) next;
82 * Validate a configuration schema array.
85 * Pointer to the first element of the schema array. The array
86 * must be terminated by a sentinel entry (type == EC_CONFIG_TYPE_NONE).
88 * 0 if the schema is valid, or -1 on error (errno is set).
90 int ec_config_schema_validate(const struct ec_config_schema *schema);
93 * Dump a configuration schema array.
96 * Output stream on which the dump will be sent.
98 * Pointer to the first element of the schema array. The array
99 * must be terminated by a sentinel entry (type == EC_CONFIG_TYPE_NONE).
101 void ec_config_schema_dump(FILE *out, const struct ec_config_schema *schema);
104 * Find a schema entry matching the key.
106 * Browse the schema array and lookup for the given key.
109 * Pointer to the first element of the schema array. The array
110 * must be terminated by a sentinel entry (type == EC_CONFIG_TYPE_NONE).
112 * The schema entry if it matches a key, or NULL if not found.
114 const struct ec_config_schema *
115 ec_config_schema_lookup(const struct ec_config_schema *schema,
119 * Get the type of a schema entry.
122 * Pointer to an element of the schema array.
124 * The type of the schema entry.
127 ec_config_schema_type(const struct ec_config_schema *schema_elt);
130 * Get the subschema of a schema entry.
133 * Pointer to an element of the schema array.
135 * The subschema if any, or NULL.
137 const struct ec_config_schema *
138 ec_config_schema_sub(const struct ec_config_schema *schema_elt);
141 * Check if a key name is reserved in a config dict.
143 * Some key names are reserved and should not be used in configs.
146 * The name of the key to test.
148 * True if the key name is reserved and must not be used, else false.
150 bool ec_config_key_is_reserved(const char *name);
153 * Array of reserved key names.
155 extern const char *ec_config_reserved_keys[];
161 * Get the type of the configuration.
166 * The configuration type.
168 enum ec_config_type ec_config_get_type(const struct ec_config *config);
171 * Create a boolean configuration value.
174 * The boolean value to be set.
176 * The configuration object, or NULL on error (errno is set).
178 struct ec_config *ec_config_bool(bool boolean);
181 * Create a signed integer configuration value.
184 * The signed integer value to be set.
186 * The configuration object, or NULL on error (errno is set).
188 struct ec_config *ec_config_i64(int64_t i64);
191 * Create an unsigned configuration value.
194 * The unsigned integer value to be set.
196 * The configuration object, or NULL on error (errno is set).
198 struct ec_config *ec_config_u64(uint64_t u64);
201 * Create a string configuration value.
204 * The string value to be set. The string is copied into the
205 * configuration object.
207 * The configuration object, or NULL on error (errno is set).
209 struct ec_config *ec_config_string(const char *string);
212 * Create a node configuration value.
215 * The node pointer to be set. The node is "consumed" by
216 * the function and should not be used by the caller, even
217 * on error. The caller can use ec_node_clone() to keep a
218 * reference on the node.
220 * The configuration object, or NULL on error (errno is set).
222 struct ec_config *ec_config_node(struct ec_node *node);
225 * Create a hash table configuration value.
228 * A configuration object containing an empty hash table, or NULL on
229 * error (errno is set).
231 struct ec_config *ec_config_dict(void);
234 * Create a list configuration value.
237 * The configuration object containing an empty list, or NULL on
238 * error (errno is set).
240 struct ec_config *ec_config_list(void);
243 * Add a config object into a list.
246 * The list configuration in which the value will be added.
248 * The value configuration to add in the list. The value object
249 * will be freed when freeing the list object. On error, the
250 * value object is also freed.
252 * 0 on success, else -1 (errno is set).
254 int ec_config_list_add(struct ec_config *list, struct ec_config *value);
257 * Remove an element from a list.
259 * The element is freed and should not be accessed.
262 * The list configuration.
264 * The element to remove from the list.
266 * 0 on success, -1 on error (errno is set).
268 int ec_config_list_del(struct ec_config *list, struct ec_config *config);
271 * Count the number of elements in a list or dict.
274 * The configuration that must be a list or a dict.
276 * The number of elements, or -1 on error (errno is set).
278 ssize_t ec_config_count(const struct ec_config *config);
281 * Validate a configuration.
284 * A hash table configuration to validate.
286 * Pointer to the first element of the schema array. The array
287 * must be terminated by a sentinel entry (type == EC_CONFIG_TYPE_NONE).
289 * 0 on success, -1 on error (errno is set).
291 int ec_config_validate(const struct ec_config *dict,
292 const struct ec_config_schema *schema);
295 * Set a value in a hash table configuration
298 * A hash table configuration to validate.
302 * The value to set. The value object will be freed when freeing the
303 * dict object. On error, the value object is also freed.
305 * 0 on success, -1 on error (errno is set).
307 int ec_config_dict_set(struct ec_config *dict, const char *key,
308 struct ec_config *value);
311 * Remove an element from a hash table configuration.
313 * The element is freed and should not be accessed.
316 * A hash table configuration to validate.
318 * The key of the configuration to delete.
320 * 0 on success, -1 on error (errno is set).
322 int ec_config_dict_del(struct ec_config *config, const char *key);
325 * Compare two configurations.
327 int ec_config_cmp(const struct ec_config *config1,
328 const struct ec_config *config2);
331 * Get configuration value.
333 struct ec_config *ec_config_dict_get(const struct ec_config *config,
337 * Get the first element of a list.
340 * for (config = ec_config_list_iter(list);
342 * config = ec_config_list_next(list, config)) {
347 * The list configuration to iterate.
349 * The first configuration element, or NULL on error (errno is set).
351 struct ec_config *ec_config_list_first(struct ec_config *list);
354 * Get next element in list.
357 * The list configuration beeing iterated.
359 * The current configuration element.
361 * The next configuration element, or NULL if there is no more element.
364 ec_config_list_next(struct ec_config *list, struct ec_config *config);
367 * Free a configuration.
370 * The element to free.
372 void ec_config_free(struct ec_config *config);
375 * Compare two configurations.
378 * 0 if the configurations are equal, else -1.
380 int ec_config_cmp(const struct ec_config *value1,
381 const struct ec_config *value2);
384 * Duplicate a configuration.
387 * The configuration to duplicate.
389 * The duplicated configuration, or NULL on error (errno is set).
392 ec_config_dup(const struct ec_config *config);
395 * Dump a configuration.
398 * Output stream on which the dump will be sent.
400 * The configuration to dump.
402 void ec_config_dump(FILE *out, const struct ec_config *config);