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