Added descriptive text for settings and setting types, and display it in
[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/dhcp.h>
12 #include <gpxe/tables.h>
13
14 struct config_setting;
15
16 /**
17  * A configuration context
18  *
19  * This identifies the context within which settings are inspected and
20  * changed.  For example, the context might be global, or might be
21  * restricted to the settings stored in NVS on a particular device.
22  */
23 struct config_context {
24         /** DHCP options block, or NULL
25          *
26          * If NULL, all registered DHCP options blocks will be used.
27          */
28         struct dhcp_option_block *options;
29 };
30
31 /**
32  * A configuration setting type
33  *
34  * This represents a type of configuration setting (e.g. string, IPv4
35  * address, etc.).
36  */
37 struct config_setting_type {
38         /** Name
39          *
40          * This is the name exposed to the user (e.g. "string").
41          */
42         const char *name;
43         /** Description */
44         const char *description;
45         /** Show value of setting
46          *
47          * @v context           Configuration context
48          * @v setting           Configuration setting
49          * @v buf               Buffer to contain value
50          * @v len               Length of buffer
51          * @ret rc              Return status code
52          */
53         int ( * show ) ( struct config_context *context,
54                          struct config_setting *setting,
55                          char *buf, size_t len );
56         /** Set value of setting
57          *
58          * @v context           Configuration context
59          * @v setting           Configuration setting
60          * @v value             Setting value (as a string)
61          * @ret rc              Return status code
62          */ 
63         int ( * set ) ( struct config_context *context,
64                         struct config_setting *setting,
65                         const char *value );
66 };
67
68 /** Declare a configuration setting type */
69 #define __config_setting_type __table ( config_setting_types, 01 )
70
71 /**
72  * A configuration setting
73  *
74  * This represents a single configuration setting (e.g. "hostname").
75  */
76 struct config_setting {
77         /** Name
78          *
79          * This is the human-readable name for the setting.  Where
80          * possible, it should match the name used in dhcpd.conf (see
81          * dhcp-options(5)).
82          */
83         const char *name;
84         /** Description */
85         const char *description;
86         /** DHCP option tag
87          *
88          * This is the DHCP tag used to identify the option in DHCP
89          * packets and stored option blocks.
90          */
91         unsigned int tag;
92         /** Configuration setting type
93          *
94          * This identifies the type of setting (e.g. string, IPv4
95          * address, etc.).
96          */
97         struct config_setting_type *type;
98 };
99
100 /** Declare a configuration setting */
101 #define __config_setting __table ( config_settings, 01 )
102
103 /**
104  * Show value of setting
105  *
106  * @v context           Configuration context
107  * @v setting           Configuration setting
108  * @v buf               Buffer to contain value
109  * @v len               Length of buffer
110  * @ret rc              Return status code
111  */
112 static inline int show_setting ( struct config_context *context,
113                                  struct config_setting *setting,
114                                  char *buf, size_t len ) {
115         return setting->type->show ( context, setting, buf, len );
116 }
117
118 extern int set_setting ( struct config_context *context,
119                          struct config_setting *setting,
120                          const char *value );
121
122 /**
123  * Clear setting
124  *
125  * @v context           Configuration context
126  * @v setting           Configuration setting
127  * @ret rc              Return status code
128  */
129 static inline int clear_setting ( struct config_context *context,
130                                   struct config_setting *setting ) {
131         delete_dhcp_option ( context->options, setting->tag );
132         return 0;
133 }
134
135 /* Function prototypes */
136 extern int show_named_setting ( struct config_context *context,
137                                 const char *name, char *buf, size_t len );
138 extern int set_named_setting ( struct config_context *context,
139                                const char *name, const char *value );
140
141 /**
142  * Clear named setting
143  *
144  * @v context           Configuration context
145  * @v name              Configuration setting name
146  * @ret rc              Return status code
147  */
148 static inline int clear_named_setting ( struct config_context *context,
149                                         const char *name ) {
150         return set_named_setting ( context, name, NULL );
151 }
152
153 #endif /* _GPXE_SETTINGS_H */