[Settings] Introduce settings applicators.
[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
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 /**
126  * A settings applicator
127  *
128  */
129 struct settings_applicator {
130         /** Apply updated settings
131          *
132          * @ret rc              Return status code
133          */
134         int ( * apply ) ( void );
135 };
136
137 /** Declare a settings applicator */
138 #define __settings_applicator \
139         __table ( struct settings_applicator, settings_applicators, 01 )
140
141 extern int simple_settings_store ( struct settings *settings, unsigned int tag,
142                                    const void *data, size_t len );
143 extern int simple_settings_fetch ( struct settings *settings, unsigned int tag,
144                                    void *data, size_t len );
145 extern struct settings_operations simple_settings_operations;
146
147 extern int register_settings ( struct settings *settings,
148                                struct settings *parent );
149 extern void unregister_settings ( struct settings *settings );
150 extern int store_setting ( struct settings *settings, unsigned int tag,
151                            const void *data, size_t len );
152 extern int fetch_setting ( struct settings *settings, unsigned int tag,
153                            void *data, size_t len );
154 extern int fetch_setting_len ( struct settings *settings, unsigned int tag );
155 extern int fetch_string_setting ( struct settings *settings, unsigned int tag,
156                                   char *data, size_t len );
157 extern int fetch_ipv4_setting ( struct settings *settings, unsigned int tag,
158                                 struct in_addr *inp );
159 extern int fetch_int_setting ( struct settings *settings, unsigned int tag,
160                                long *value );
161 extern int fetch_uint_setting ( struct settings *settings, unsigned int tag,
162                                 unsigned long *value );
163 extern struct settings * find_settings ( const char *name );
164 extern int store_typed_setting ( struct settings *settings,
165                                  unsigned int tag, struct setting_type *type,
166                                  const char *value );
167 extern int store_named_setting ( const char *name, const char *value );
168 extern int fetch_named_setting ( const char *name, char *buf, size_t len );
169
170 extern struct setting_type setting_type_ __setting_type;
171 extern struct setting_type setting_type_string __setting_type;
172 extern struct setting_type setting_type_ipv4 __setting_type;
173 extern struct setting_type setting_type_int8 __setting_type;
174 extern struct setting_type setting_type_int16 __setting_type;
175 extern struct setting_type setting_type_int32 __setting_type;
176 extern struct setting_type setting_type_uint8 __setting_type;
177 extern struct setting_type setting_type_uint16 __setting_type;
178 extern struct setting_type setting_type_uint32 __setting_type;
179 extern struct setting_type setting_type_hex __setting_type;
180
181 /**
182  * Initialise a settings block
183  *
184  * @v settings          Settings block
185  * @v op                Settings block operations
186  * @v refcnt            Containing object reference counter, or NULL
187  * @v name              Settings block name
188  */
189 static inline void settings_init ( struct settings *settings,
190                                    struct settings_operations *op,
191                                    struct refcnt *refcnt,
192                                    const char *name ) {
193         INIT_LIST_HEAD ( &settings->siblings );
194         INIT_LIST_HEAD ( &settings->children );
195         settings->op = op;
196         settings->refcnt = refcnt;
197         settings->name = name;
198 }
199
200 /**
201  * Delete setting
202  *
203  * @v settings          Settings block
204  * @v tag               Setting tag number
205  * @ret rc              Return status code
206  */
207 static inline int delete_setting ( struct settings *settings,
208                                    unsigned int tag ) {
209         return store_setting ( settings, tag, NULL, 0 );
210 }
211
212 /**
213  * Fetch and format value of setting
214  *
215  * @v settings          Settings block, or NULL to search all blocks
216  * @v tag               Setting tag number
217  * @v type              Settings type
218  * @v buf               Buffer to contain formatted value
219  * @v len               Length of buffer
220  * @ret len             Length of formatted value, or negative error
221  */
222 static inline int fetch_typed_setting ( struct settings *settings,
223                                         unsigned int tag,
224                                         struct setting_type *type,
225                                         char *buf, size_t len ) {
226         return type->fetchf ( settings, tag, buf, len );
227 }
228
229 /**
230  * Delete named setting
231  *
232  * @v name              Name of setting
233  * @ret rc              Return status code
234  */
235 static inline int delete_named_setting ( const char *name ) {
236         return store_named_setting ( name, NULL );
237 }
238
239 #endif /* _GPXE_SETTINGS_H */