Annotation of embedaddon/libpdel/config/app_config.h, revision 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