[Settings] copy_settings() should not fail if some settings are missing!
[people/mcb30/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_settings ( struct settings *dest, struct settings *source );
167 extern int fetch_setting_len ( struct settings *settings, unsigned int tag );
168 extern int fetch_string_setting ( struct settings *settings, unsigned int tag,
169                                   char *data, size_t len );
170 extern int fetch_ipv4_setting ( struct settings *settings, unsigned int tag,
171                                 struct in_addr *inp );
172 extern int fetch_int_setting ( struct settings *settings, unsigned int tag,
173                                long *value );
174 extern int fetch_uint_setting ( struct settings *settings, unsigned int tag,
175                                 unsigned long *value );
176 extern long fetch_intz_setting ( struct settings *settings, unsigned int tag );
177 extern unsigned long fetch_uintz_setting ( struct settings *settings,
178                                            unsigned int tag );
179 extern struct settings * find_child_settings ( struct settings *parent,
180                                                const char *name );
181 extern struct settings * find_settings ( const char *name );
182 extern int store_typed_setting ( struct settings *settings,
183                                  unsigned int tag, struct setting_type *type,
184                                  const char *value );
185 extern int store_named_setting ( const char *name, const char *value );
186 extern int fetch_named_setting ( const char *name, char *buf, size_t len );
187
188 extern struct setting_type setting_type_ __setting_type;
189 extern struct setting_type setting_type_string __setting_type;
190 extern struct setting_type setting_type_ipv4 __setting_type;
191 extern struct setting_type setting_type_int8 __setting_type;
192 extern struct setting_type setting_type_int16 __setting_type;
193 extern struct setting_type setting_type_int32 __setting_type;
194 extern struct setting_type setting_type_uint8 __setting_type;
195 extern struct setting_type setting_type_uint16 __setting_type;
196 extern struct setting_type setting_type_uint32 __setting_type;
197 extern struct setting_type setting_type_hex __setting_type;
198
199 /**
200  * Initialise a settings block
201  *
202  * @v settings          Settings block
203  * @v op                Settings block operations
204  * @v refcnt            Containing object reference counter, or NULL
205  * @v name              Settings block name
206  */
207 static inline void settings_init ( struct settings *settings,
208                                    struct settings_operations *op,
209                                    struct refcnt *refcnt,
210                                    const char *name ) {
211         INIT_LIST_HEAD ( &settings->siblings );
212         INIT_LIST_HEAD ( &settings->children );
213         settings->op = op;
214         settings->refcnt = refcnt;
215         settings->name = name;
216 }
217
218 /**
219  * Initialise a settings block
220  *
221  * @v simple            Simple settings block
222  * @v refcnt            Containing object reference counter, or NULL
223  * @v name              Settings block name
224  */
225 static inline void simple_settings_init ( struct simple_settings *simple,
226                                           struct refcnt *refcnt,
227                                           const char *name ) {
228         settings_init ( &simple->settings, &simple_settings_operations,
229                         refcnt, name );
230 }
231
232 /**
233  * Delete setting
234  *
235  * @v settings          Settings block
236  * @v tag               Setting tag number
237  * @ret rc              Return status code
238  */
239 static inline int delete_setting ( struct settings *settings,
240                                    unsigned int tag ) {
241         return store_setting ( settings, tag, NULL, 0 );
242 }
243
244 /**
245  * Fetch and format value of setting
246  *
247  * @v settings          Settings block, or NULL to search all blocks
248  * @v tag               Setting tag number
249  * @v type              Settings type
250  * @v buf               Buffer to contain formatted value
251  * @v len               Length of buffer
252  * @ret len             Length of formatted value, or negative error
253  */
254 static inline int fetch_typed_setting ( struct settings *settings,
255                                         unsigned int tag,
256                                         struct setting_type *type,
257                                         char *buf, size_t len ) {
258         return type->fetchf ( settings, tag, buf, len );
259 }
260
261 /**
262  * Delete named setting
263  *
264  * @v name              Name of setting
265  * @ret rc              Return status code
266  */
267 static inline int delete_named_setting ( const char *name ) {
268         return store_named_setting ( name, NULL );
269 }
270
271 #endif /* _GPXE_SETTINGS_H */