src/include/gpxe/settings.h

   1 #ifndef _GPXE_SETTINGS_H
   2 #define _GPXE_SETTINGS_H
   3
   4 /** @file
   5  *
   6  * Configuration settings
   7  *
   8  */
   9
  10 #include <stdint.h>
  11 #include <gpxe/tables.h>
  12 #include <gpxe/list.h>
  13 #include <gpxe/refcnt.h>
  14
  15 struct settings;
  16 struct in_addr;
  17
  18 /** Settings block operations */
  19 struct settings_operations {
  20         /** Store value of setting
  21          *
  22          * @v settings          Settings block
  23          * @v tag               Setting tag number
  24          * @v data              Setting data, or NULL to clear setting
  25          * @v len               Length of setting data
  26          * @ret rc              Return status code
  27          */
  28         int ( * store ) ( struct settings *settings, unsigned int tag,
  29                           const void *data, size_t len );
  30         /** Fetch value of setting
  31          *
  32          * @v settings          Settings block
  33          * @v tag               Setting tag number
  34          * @v data              Buffer to fill with setting data
  35          * @v len               Length of buffer
  36          * @ret len             Length of setting data, or negative error
  37          *
  38          * The actual length of the setting will be returned even if
  39          * the buffer was too small.
  40          */
  41         int ( * fetch ) ( struct settings *settings, unsigned int tag,
  42                           void *data, size_t len );
  43 };
  44
  45 /** A settings block */
  46 struct settings {
  47         /** Reference counter */
  48         struct refcnt *refcnt;
  49         /** Name */
  50         const char *name;
  51         /** Parent settings block */
  52         struct settings *parent;
  53         /** Sibling settings blocks */
  54         struct list_head siblings;
  55         /** Child settings blocks */
  56         struct list_head children;
  57         /** Settings block operations */
  58         struct settings_operations *op;
  59 };
  60
  61 /**
  62  * A setting type
  63  *
  64  * This represents a type of setting (e.g. string, IPv4 address,
  65  * etc.).
  66  */
  67 struct setting_type {
  68         /** Name
  69          *
  70          * This is the name exposed to the user (e.g. "string").
  71          */
  72         const char *name;
  73         /** Parse and set value of setting
  74          *
  75          * @v settings          Settings block
  76          * @v tag               Setting tag number
  77          * @v value             Formatted setting data
  78          * @ret rc              Return status code
  79          */
  80         int ( * storef ) ( struct settings *settings, unsigned int tag,
  81                            const char *value );
  82         /** Fetch and format value of setting
  83          *
  84          * @v settings          Settings block, or NULL to search all blocks
  85          * @v tag               Setting tag number
  86          * @v buf               Buffer to contain formatted value
  87          * @v len               Length of buffer
  88          * @ret len             Length of formatted value, or negative error
  89          */
  90         int ( * fetchf ) ( struct settings *settings, unsigned int tag,
  91                            char *buf, size_t len );
  92 };
  93
  94 /** Declare a configuration setting type */
  95 #define __setting_type \
  96         __table ( struct setting_type, setting_types, 01 )
  97
  98 /**
  99  * A named setting
 100  *
 101  * This represents a single setting (e.g. "hostname"), encapsulating
 102  * the information about the setting's tag number and type.
 103  */
 104 struct named_setting {
 105         /** Name
 106          *
 107          * This is the human-readable name for the setting.
 108          */
 109         const char *name;
 110         /** Description */
 111         const char *description;
 112         /** Setting tag number */
 113         unsigned int tag;
 114         /** Setting type
 115          *
 116          * This identifies the type of setting (e.g. string, IPv4
 117          * address, etc.).
 118          */
 119         struct setting_type *type;
 120 };
 121
 122 /** Declare a configuration setting */
 123 #define __named_setting __table ( struct named_setting, named_settings, 01 )
 124
 125 extern int simple_settings_store ( struct settings *settings, unsigned int tag,
 126                                    const void *data, size_t len );
 127 extern int simple_settings_fetch ( struct settings *settings, unsigned int tag,
 128                                    void *data, size_t len );
 129 extern struct settings_operations simple_settings_operations;
 130
 131 extern int register_settings ( struct settings *settings,
 132                                struct settings *parent );
 133 extern void unregister_settings ( struct settings *settings );
 134 extern int fetch_setting ( struct settings *settings, unsigned int tag,
 135                            void *data, size_t len );
 136 extern int fetch_setting_len ( struct settings *settings, unsigned int tag );
 137 extern int fetch_string_setting ( struct settings *settings, unsigned int tag,
 138                                   char *data, size_t len );
 139 extern int fetch_ipv4_setting ( struct settings *settings, unsigned int tag,
 140                                 struct in_addr *inp );
 141 extern int fetch_int_setting ( struct settings *settings, unsigned int tag,
 142                                long *value );
 143 extern int fetch_uint_setting ( struct settings *settings, unsigned int tag,
 144                                 unsigned long *value );
 145 extern struct settings * find_settings ( const char *name );
 146 extern int store_typed_setting ( struct settings *settings,
 147                                  unsigned int tag, struct setting_type *type,
 148                                  const char *value );
 149 extern int store_named_setting ( const char *name, const char *value );
 150 extern int fetch_named_setting ( const char *name, char *buf, size_t len );
 151
 152 extern struct setting_type setting_type_ __setting_type;
 153 extern struct setting_type setting_type_string __setting_type;
 154 extern struct setting_type setting_type_ipv4 __setting_type;
 155 extern struct setting_type setting_type_int8 __setting_type;
 156 extern struct setting_type setting_type_int16 __setting_type;
 157 extern struct setting_type setting_type_int32 __setting_type;
 158 extern struct setting_type setting_type_uint8 __setting_type;
 159 extern struct setting_type setting_type_uint16 __setting_type;
 160 extern struct setting_type setting_type_uint32 __setting_type;
 161 extern struct setting_type setting_type_hex __setting_type;
 162
 163 /**
 164  * Initialise a settings block
 165  *
 166  * @v settings          Settings block
 167  * @v op                Settings block operations
 168  * @v refcnt            Containing object reference counter, or NULL
 169  * @v name              Settings block name
 170  */
 171 static inline void settings_init ( struct settings *settings,
 172                                    struct settings_operations *op,
 173                                    struct refcnt *refcnt,
 174                                    const char *name ) {
 175         INIT_LIST_HEAD ( &settings->siblings );
 176         INIT_LIST_HEAD ( &settings->children );
 177         settings->op = op;
 178         settings->refcnt = refcnt;
 179         settings->name = name;
 180 }
 181
 182 /**
 183  * Store value of setting
 184  *
 185  * @v settings          Settings block
 186  * @v tag               Setting tag number
 187  * @v data              Setting data, or NULL to clear setting
 188  * @v len               Length of setting data
 189  * @ret rc              Return status code
 190  */
 191 static inline int store_setting ( struct settings *settings, unsigned int tag,
 192                                   const void *data, size_t len ) {
 193         return settings->op->store ( settings, tag, data, len );
 194 }
 195
 196 /**
 197  * Delete setting
 198  *
 199  * @v settings          Settings block
 200  * @v tag               Setting tag number
 201  * @ret rc              Return status code
 202  */
 203 static inline int delete_setting ( struct settings *settings,
 204                                    unsigned int tag ) {
 205         return store_setting ( settings, tag, NULL, 0 );
 206 }
 207
 208 /**
 209  * Fetch and format value of setting
 210  *
 211  * @v settings          Settings block, or NULL to search all blocks
 212  * @v tag               Setting tag number
 213  * @v type              Settings type
 214  * @v buf               Buffer to contain formatted value
 215  * @v len               Length of buffer
 216  * @ret len             Length of formatted value, or negative error
 217  */
 218 static inline int fetch_typed_setting ( struct settings *settings,
 219                                         unsigned int tag,
 220                                         struct setting_type *type,
 221                                         char *buf, size_t len ) {
 222         return type->fetchf ( settings, tag, buf, len );
 223 }
 224
 225 /**
 226  * Delete named setting
 227  *
 228  * @v name              Name of setting
 229  * @ret rc              Return status code
 230  */
 231 static inline int delete_named_setting ( const char *name ) {
 232         return store_named_setting ( name, NULL );
 233 }
 234
 235 #endif /* _GPXE_SETTINGS_H */