Annotation of embedaddon/libpdel/config/app_config.h, revision 1.1.1.1
1.1 misho 1:
2: /*
3: * Copyright (c) 2001-2002 Packet Design, LLC.
4: * All rights reserved.
5: *
6: * Subject to the following obligations and disclaimer of warranty,
7: * use and redistribution of this software, in source or object code
8: * forms, with or without modifications are expressly permitted by
9: * Packet Design; provided, however, that:
10: *
11: * (i) Any and all reproductions of the source or object code
12: * must include the copyright notice above and the following
13: * disclaimer of warranties; and
14: * (ii) No rights are granted, in any manner or form, to use
15: * Packet Design trademarks, including the mark "PACKET DESIGN"
16: * on advertising, endorsements, or otherwise except as such
17: * appears in the above copyright notice or in the software.
18: *
19: * THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND
20: * TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO
21: * REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING
22: * THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED
23: * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
24: * OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE,
25: * OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS
26: * OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY,
27: * RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE
28: * LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE
29: * OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT,
30: * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL
31: * DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF
32: * USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF
33: * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
34: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
35: * THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF
36: * THE POSSIBILITY OF SUCH DAMAGE.
37: *
38: * Author: Archie Cobbs <archie@freebsd.org>
39: */
40:
41: #ifndef _PDEL_CONFIG_APP_CONFIG_H_
42: #define _PDEL_CONFIG_APP_CONFIG_H_
43:
44: /************************************************************************
45: DEFINITIONS
46: ************************************************************************/
47:
48: struct app_subsystem;
49: struct app_config_ctx;
50: struct pevent_ctx;
51:
52: /* XML document tag for app_config configurations */
53: #define APP_CONFIG_XML_TAG "config"
54:
55: /* Methods exported by a subsystem */
56: typedef int app_ss_startup_t(struct app_config_ctx *ctx,
57: const struct app_subsystem *ss, const void *config);
58: typedef void app_ss_shutdown_t(struct app_config_ctx *ctx,
59: const struct app_subsystem *ss, const void *config);
60: typedef int app_ss_willrun_t(struct app_config_ctx *ctx,
61: const struct app_subsystem *ss, const void *config);
62: typedef int app_ss_changed_t(struct app_config_ctx *ctx,
63: const struct app_subsystem *ss, const void *config1,
64: const void *config2);
65:
66: /* Descriptor for a subsystem */
67: struct app_subsystem {
68: const char *name; /* name, null to end list */
69: void *arg; /* opaque subsystem argument */
70: app_ss_startup_t *start; /* start subsystem */
71: app_ss_shutdown_t *stop; /* stop subsystem */
72: app_ss_willrun_t *willrun; /* will subsystem run? */
73: app_ss_changed_t *changed; /* subsystem config changed? */
74: const char **deplist; /* config items dependent on */
75: };
76:
77: /*
78: * Methods exported by an application:
79: *
80: * init Initialize a config structure. The structure will already
81: * be initialized with the values provided by the structs type.
82: * This method is so any other default values can be applied.
83: *
84: * getnew This is used when no existing configuration is found for
85: * the system (i.e., after a factory reset). The argument
86: * provided is a configuration structure already initialized
87: * using the "init" method. The "getnew" method should apply
88: * any further initialization needed for this specific system.
89: *
90: * checker This method is the gatekeeper for applying new configurations.
91: * If this method returns zero, the configuration is rejected.
92: * An appropriate error message may be put in "errbuf". Make
93: * sure your application does not automatically generate any
94: * configurations that fail to pass this method, otherwise
95: * you get into a stuck state.
96: *
97: * normalize Configurations may contain redundant and/or derived info.
98: * This method (if defined) can be used to normalize a config
99: * struture. This method is called before "checker".
100: *
101: * upgrade When the configuration structure changes, and you still
102: * want to be able to read in XML created from the older
103: * versions of the configuration structure, defining this
104: * method gives you a way to specify how to upgrade information
105: * the old format to the new one.
106: */
107: typedef int app_config_init_t(struct app_config_ctx *ctx, void *config);
108: typedef int app_config_getnew_t(struct app_config_ctx *ctx, void *config);
109: typedef int app_config_checker_t(struct app_config_ctx *ctx,
110: const void *config, char *errbuf, size_t ebufsize);
111: typedef void app_config_normalize_t(struct app_config_ctx *ctx,
112: void *config);
113: typedef int app_config_upgrade_t(struct app_config_ctx *ctx,
114: const void *old_conf, u_int old_version,
115: void *new_conf);
116:
117: /*
118: * Descriptor for an application's configuration information.
119: *
120: * Automatic configuration upgrade feature:
121: *
122: * types[version] is a structs type for the applications configuration
123: * information structure. All previous pointers in the types[] array point
124: * to types for older versions of the configuration structure. When an
125: * older version is encountered in an XML file, it is read in using the
126: * corresponding old structs type and converted to the current version
127: * using the "upgrade" method. So versions are numbered 0, 1, .... Each
128: * time the configuration structure is changed, "version" should be
129: * bumped and the new type added to the "types" array. Version numbers
130: * are not allowed to go backwards.
131: */
132: struct app_config {
133: u_int version;/* current config version # */
134: const struct structs_type **types;/* types for all versions */
135: const struct app_subsystem **slist;/* list of subsystems */
136: app_config_init_t *init; /* initialize config defaults */
137: app_config_getnew_t *getnew;/* generate new config */
138: app_config_checker_t *checker;/* validate a config struct */
139: app_config_normalize_t *normalize; /* normalize a config */
140: app_config_upgrade_t *upgrade;/* upgrade a config */
141: };
142:
143: /************************************************************************
144: BUILT-IN SUBSYSTEMS
145: ************************************************************************/
146:
147: __BEGIN_DECLS
148:
149: /*
150: * PID file subsystem template.
151: *
152: * Copy this structure and set arg to be a const char * pointing to the
153: * name of the item in the config structure containing the pathname to
154: * the PID file. If this pathname is NULL/empty, no PID file is created.
155: */
156: extern const struct app_subsystem app_config_pidfile_subsystem;
157:
158: /*
159: * Directory subsystem template.
160: *
161: * Copy this structure and set arg to be a const char * pointing to the
162: * name of the item in the config structure containing the directory to
163: * chdir(2) into. If this pathname is NULL/empty, no change is made.
164: */
165: extern const struct app_subsystem app_config_directory_subsystem;
166:
167: /*
168: * "Curconf" subsystem template.
169: *
170: * Copy this structure and set arg to be a 'struct my_config **' pointer
171: * pointing to the application's 'curconf' variable, which at all times
172: * points to a (read-only) copy of the currently active configuration object.
173: * This subsystem should usually be first in the subsystem list.
174: */
175: extern const struct app_subsystem app_config_curconf_subsystem;
176:
177: __END_DECLS
178:
179: /*
180: * Alog logging subsystem template.
181: *
182: * Copy this structure and set arg to be a pointer to an instance
183: * of the structure below.
184: */
185: struct app_config_alog_info {
186: const char *name; /* name of alog_channel_config_type */
187: int channel; /* alog channel */
188: };
189:
190: __BEGIN_DECLS
191: extern const struct app_subsystem app_config_alog_subsystem;
192: __END_DECLS
193:
194: /************************************************************************
195: FUNCTIONS
196: ************************************************************************/
197:
198: __BEGIN_DECLS
199:
200: /*
201: * Initialize the application's configuration type and list of subsystems.
202: * Also sets the XML tag for reading and writing the configuration and
203: * the user application cookie.
204: *
205: * This must be called first.
206: */
207: extern struct app_config_ctx *app_config_init(struct pevent_ctx *ctx,
208: const struct app_config *info, void *cookie);
209:
210: /*
211: * Reverse the effects of app_config_init().
212: *
213: * All subsystems must be shutdown and no new configurations
214: * may be pending.
215: */
216: extern int app_config_uninit(struct app_config_ctx **ctxp);
217:
218: /*
219: * Get application cookie.
220: */
221: extern void *app_config_get_cookie(struct app_config_ctx *ctx);
222:
223: /*
224: * Initialize application configuration from an XML file.
225: *
226: * This reads in the configuration and then calls app_config_set()
227: * with a delay of one millisecond.
228: *
229: * If "writeback" is zero, no writebacks will ever occur.
230: */
231: extern int app_config_load(struct app_config_ctx *ctx,
232: const char *path, int allow_writeback);
233:
234: /*
235: * Re-read the XML file passed to app_config_load() and reconfigure
236: * as appropriate.
237: *
238: * This reads in the configuration and then calls app_config_set()
239: * with a delay of one millisecond.
240: */
241: extern int app_config_reload(struct app_config_ctx *c);
242:
243: /*
244: * Function to create a configuration structure. This structure will
245: * have the application "default" values.
246: */
247: extern void *app_config_new(struct app_config_ctx *c);
248:
249: /*
250: * Change the application's current configuration to be a copy of "config"
251: * after a delay of at most "delay" milliseconds.
252: *
253: * A NULL configuration shuts everything down. Any configs passed to
254: * app_config_set() subsequent to passing a NULL config, but before
255: * the shutdown operation has completed, are ignored. This guarantees
256: * that a shutdown really does shut everything down.
257: *
258: * If an app_config_load() was previously called with "allow_writeback" true,
259: * then a non-NULL configuration will be written back out to the XML file.
260: *
261: * If the configuration is invalid, -1 is returned with errno == EINVAL
262: * and the buffer (if not NULL) is filled in with the reason.
263: */
264: extern int app_config_set(struct app_config_ctx *ctx,
265: const void *config, u_long delay, char *ebuf, int emax);
266:
267: /*
268: * Get a copy of the application's current or pending configuration.
269: */
270: extern void *app_config_get(struct app_config_ctx *ctx, int pending);
271:
272: /*
273: * Get the configuration object type.
274: */
275: extern const struct structs_type *app_config_get_type(
276: struct app_config_ctx *ctx);
277:
278: /*
279: * Get a copy of a configuration.
280: */
281: extern void *app_config_copy(struct app_config_ctx *ctx,
282: const void *config);
283:
284: /*
285: * Free a configuration.
286: */
287: extern void app_config_free(struct app_config_ctx *ctx, void **configp);
288:
289: __END_DECLS
290:
291: #endif /* _PDEL_CONFIG_APP_CONFIG_H_ */
292:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to app_config.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libpdel / config