123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202 |
- /* Copyright (c) 2001 Matej Pfajfar.
- * Copyright (c) 2001-2004, Roger Dingledine.
- * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
- * Copyright (c) 2007-2019, The Tor Project, Inc. */
- /* See LICENSE for licensing information */
- /**
- * @file conftypes.h
- * @brief Types used to specify configurable options.
- *
- * This header defines the types that different modules will use in order to
- * declare their configuration and state variables, and tell the configuration
- * management code about those variables. From the individual module's point
- * of view, its configuration and state are simply data structures.
- *
- * For defining new variable types, see var_type_def_st.h.
- *
- * For the code that manipulates variables defined via this module, see
- * lib/confmgt/, especially typedvar.h and (later) structvar.h. The
- * configuration manager is responsible for encoding, decoding, and
- * maintaining the configuration structures used by the various modules.
- *
- * STATUS NOTE: This is a work in process refactoring. It is not yet possible
- * for modules to define their own variables, and much of the configuration
- * management code is still in src/app/config/.
- **/
- #ifndef TOR_SRC_LIB_CONF_CONFTYPES_H
- #define TOR_SRC_LIB_CONF_CONFTYPES_H
- #include "lib/cc/torint.h"
- #ifdef TOR_UNIT_TESTS
- #include "lib/conf/conftesting.h"
- #endif
- #include <stddef.h>
- /** Enumeration of types which option values can take */
- typedef enum config_type_t {
- CONFIG_TYPE_STRING = 0, /**< An arbitrary string. */
- CONFIG_TYPE_FILENAME, /**< A filename: some prefixes get expanded. */
- CONFIG_TYPE_POSINT, /**< A non-negative integer less than MAX_INT */
- CONFIG_TYPE_INT, /**< Any integer. */
- CONFIG_TYPE_UINT64, /**< A value in range 0..UINT64_MAX */
- CONFIG_TYPE_INTERVAL, /**< A number of seconds, with optional units*/
- CONFIG_TYPE_MSEC_INTERVAL,/**< A number of milliseconds, with optional
- * units */
- CONFIG_TYPE_MEMUNIT, /**< A number of bytes, with optional units*/
- CONFIG_TYPE_DOUBLE, /**< A floating-point value */
- CONFIG_TYPE_BOOL, /**< A boolean value, expressed as 0 or 1. */
- CONFIG_TYPE_AUTOBOOL, /**< A boolean+auto value, expressed 0 for false,
- * 1 for true, and -1 for auto */
- CONFIG_TYPE_ISOTIME, /**< An ISO-formatted time relative to UTC. */
- CONFIG_TYPE_CSV, /**< A list of strings, separated by commas and
- * optional whitespace. */
- CONFIG_TYPE_CSV_INTERVAL, /**< A list of strings, separated by commas and
- * optional whitespace, representing intervals in
- * seconds, with optional units. We allow
- * multiple values here for legacy reasons, but
- * ignore every value after the first. */
- CONFIG_TYPE_LINELIST, /**< Uninterpreted config lines */
- CONFIG_TYPE_LINELIST_S, /**< Uninterpreted, context-sensitive config lines,
- * mixed with other keywords. */
- CONFIG_TYPE_LINELIST_V, /**< Catch-all "virtual" option to summarize
- * context-sensitive config lines when fetching.
- */
- CONFIG_TYPE_OBSOLETE, /**< Obsolete (ignored) option. */
- /**
- * Extended type: definition appears in the <b>type_def</b> pointer
- * of the corresponding struct_member_t.
- *
- * For some types, we cannot define them as particular values of this
- * enumeration, since those types are abstractions defined at a higher level
- * than this module. (For example, parsing a routerset_t is higher-level
- * than this module.) To handle this, we use CONFIG_TYPE_EXTENDED for those
- * types, and give a definition for them in the struct_member_t.type_def.
- **/
- CONFIG_TYPE_EXTENDED,
- } config_type_t;
- /* Forward delcaration for var_type_def_t, for extended types. */
- struct var_type_def_t;
- /** Structure to specify a named, typed member within a structure. */
- typedef struct struct_member_t {
- /** Name of the field. */
- const char *name;
- /**
- * Type of the field, according to the config_type_t enumeration.
- *
- * For any type not otherwise listed in config_type_t, this field's value
- * should be CONFIG_TYPE_EXTENDED. When it is, the <b>type_def</b> pointer
- * must be set.
- **/
- /*
- * NOTE: In future refactoring, we might remove this field entirely, along
- * with its corresponding enumeration. In that case, we will require that
- * type_def be set in all cases. If we do, we will also need a new mechanism
- * to enforce consistency between configuration variable types and their
- * corresponding structures, since our current design in
- * lib/conf/conftesting.h won't work any more.
- */
- config_type_t type;
- /**
- * Pointer to a type definition for the type of this field. Overrides
- * <b>type</b> if it is not NULL. Must be set when <b>type</b> is
- * CONFIG_TYPE_EXTENDED.
- **/
- const struct var_type_def_t *type_def;
- /**
- * Offset of this field within the structure. Compute this with
- * offsetof(structure, fieldname).
- **/
- ptrdiff_t offset;
- } struct_member_t;
- /**
- * Structure to describe the location and preferred value of a "magic number"
- * field within a structure.
- *
- * These 'magic numbers' are 32-bit values used to tag objects to make sure
- * that they have the correct type.
- */
- typedef struct struct_magic_decl_t {
- /** The name of the structure */
- const char *typename;
- /** A value used to recognize instances of this structure. */
- uint32_t magic_val;
- /** The location within the structure at which we expect to find
- * <b>magic_val</b>. */
- ptrdiff_t magic_offset;
- } struct_magic_decl_t;
- /**
- * Flag to indicate that an option or type is "undumpable". An
- * undumpable option is never saved to disk.
- *
- * For historical reasons its name is usually is prefixed with __.
- **/
- #define CFLG_NODUMP (1u<<0)
- /**
- * Flag to indicate that an option or type is "unlisted".
- *
- * We don't tell the controller about unlisted options when it asks for a
- * list of them.
- **/
- #define CFLG_NOLIST (1u<<1)
- /**
- * Flag to indicate that an option or type is "unsettable".
- *
- * An unsettable option can never be set directly by name.
- **/
- #define CFLG_NOSET (1u<<2)
- /**
- * Flag to indicate that an option or type does not need to be copied when
- * copying the structure that contains it.
- *
- * (Usually, if an option does not need to be copied, then either it contains
- * no data, or the data that it does contain is completely contained within
- * another option.)
- **/
- #define CFLG_NOCOPY (1u<<3)
- /**
- * Flag to indicate that an option or type does not need to be compared
- * when telling the controller about the differences between two
- * configurations.
- *
- * (Usually, if an option does not need to be compared, then either it
- * contains no data, or the data that it does contain is completely contained
- * within another option.)
- **/
- #define CFLG_NOCMP (1u<<4)
- /**
- * Flag to indicate that an option or type should not be replaced when setting
- * it.
- *
- * For most options, setting them replaces their old value. For some options,
- * however, setting them appends to their old value.
- */
- #define CFLG_NOREPLACE (1u<<5)
- /**
- * A group of flags that should be set on all obsolete options and types.
- **/
- #define CFLG_GROUP_OBSOLETE \
- (CFLG_NOCOPY|CFLG_NOCMP|CFLG_NODUMP|CFLG_NOSET|CFLG_NOLIST)
- /** A variable allowed in the configuration file or on the command line. */
- typedef struct config_var_t {
- struct_member_t member; /** A struct member corresponding to this
- * variable. */
- const char *initvalue; /**< String (or null) describing initial value. */
- uint32_t flags; /**< One or more flags describing special handling for this
- * variable */
- #ifdef TOR_UNIT_TESTS
- /** Used for compiler-magic to typecheck the corresponding field in the
- * corresponding struct. Only used in unit test mode, at compile-time. */
- confparse_dummy_values_t var_ptr_dummy;
- #endif
- } config_var_t;
- #endif /* !defined(TOR_SRC_LIB_CONF_CONFTYPES_H) */
|