tools/cfzy/libconfizery/cfzy_conftree.h

   1 /*
   2  * Copyright (c) 2013, Olivier MATZ <zer0@droids-corp.org>
   3  * All rights reserved.
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions are met:
   6  *
   7  *     * Redistributions of source code must retain the above copyright
   8  *       notice, this list of conditions and the following disclaimer.
   9  *     * Redistributions in binary form must reproduce the above copyright
  10  *       notice, this list of conditions and the following disclaimer in the
  11  *       documentation and/or other materials provided with the distribution.
  12  *     * Neither the name of the University of California, Berkeley nor the
  13  *       names of its contributors may be used to endorse or promote products
  14  *       derived from this software without specific prior written permission.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
  17  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  18  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  19  * DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY
  20  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  21  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  22  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  23  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  25  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26  */
  27
  28 /**
  29  * @file
  30  * Confizery configuration tree
  31  *
  32  * This module defines a structure cfzy_conftree that stores the full
  33  * configuration tree (composed of cfzy_confnode structures), and some
  34  * meta data like the number of nodes in the tree, a hash table used
  35  * to do a node lookup by its name, the path of the configuration tree
  36  * file, ...
  37  */
  38
  39 #ifndef _CFZY_CONFTREE_H_
  40 #define _CFZY_CONFTREE_H_
  41
  42 #include "cfzy_confnode.h"
  43
  44 struct cfzy_htable;
  45
  46 /**
  47  * Structure storing the config tree
  48  */
  49 struct cfzy_conftree {
  50         char *path;                       /**< path of conftree file */
  51         struct cfzy_confnode *root;       /**< pointer to root node */
  52         int count;                        /**< number of nodes */
  53         struct cfzy_htable *nodes_htable; /**< htable of nodes, indexed by name */
  54         struct cfzy_confnode_list prio_list; /**< ordered list of nodes */
  55 };
  56
  57 /**
  58  * Create a new configuration tree
  59  *
  60  * Parse a configuration tree and allocate a new conftree
  61  * structure. The structure must be freed with cfzy_conftree_free().
  62  *
  63  * @param filename
  64  *   name of the configuration tree file
  65  * @return
  66  *   the allocated conftree structure, or NULL on error
  67  */
  68 struct cfzy_conftree *cfzy_conftree_new(const char *filename);
  69
  70 /**
  71  * Free a configuration tree structure
  72  *
  73  * Free a configuration tree structure previously allocated with
  74  * cfzy_conftree_new().
  75  *
  76  * @param conftree
  77  *   the configuration tree structure to be freed
  78  */
  79 void cfzy_conftree_free(struct cfzy_conftree *conftree);
  80
  81 /**
  82  * Dump a configuration tree structure in a file
  83  *
  84  * @param conftree
  85  *   the configuration tree structure to be freed
  86  * @param filename
  87  *   file where conf should be dumped
  88  * @return
  89  *   0 on success, negative on error
  90  */
  91 int cfzy_conftree_dump(const struct cfzy_conftree *conftree,
  92                        const char *filename);
  93
  94 /**
  95  * Evaluate a configuration tree structure
  96  *
  97  * Parse all nodes following priority list and set the effective_value
  98  * field by calling cfzy_confnode_evaluate() which takes care of
  99  * default values, user values, and dependencies.
 100  *
 101  * @param conftree
 102  *   the configuration tree structure
 103  * @return
 104  *   0 on success, negative on error
 105  */
 106 int cfzy_conftree_evaluate(struct cfzy_conftree *conftree);
 107
 108 /**
 109  * Save values of configuration tree
 110  *
 111  * For each node, copy the effective_value field in
 112  * old_effective_value and the user_value field in old_user_value.
 113  * These values can be used later with cfzy_conftree_filter() to
 114  * compare the old values with the new ones.
 115  *
 116  * @param conftree
 117  *   the configuration tree structure
 118  * @return
 119  *   0 on success, negative on error
 120  */
 121 int cfzy_conftree_save_values(struct cfzy_conftree *conftree);
 122
 123 /* flags to be used with cfzy_conftree_filter() */
 124 #define CFZY_FILTER_F_USR_UNSET     0x01
 125 #define CFZY_FILTER_F_EFF_UNSET     0x02
 126 #define CFZY_FILTER_F_USR_CHANGED   0x04
 127 #define CFZY_FILTER_F_EFF_CHANGED   0x08
 128
 129 /**
 130  * Get a list of nodes matching conditions
 131  *
 132  * Return the list of nodes in configuration tree that match
 133  * conditions. Example: cfzy_conftree_filter(contree,
 134  * CFZY_FILTER_F_USR_UNSET) will return all nodes that have no user
 135  * value (set to NULL).
 136  *
 137  * @param conftree
 138  *   the configuration tree structure
 139  * @param flags
 140  *   list of conditions (CFZY_FILTER_F_*)
 141  * @return
 142  *   0 on success, negative on error
 143  */
 144 struct cfzy_list_head *
 145 cfzy_conftree_filter(struct cfzy_conftree *conftree, int flags);
 146
 147 #endif /* _CFZY_CONFTREE_H_ */