Tor  0.4.7.0-alpha-dev
var_type_def_st.h
Go to the documentation of this file.
1 /* Copyright (c) 2001 Matej Pfajfar.
2  * Copyright (c) 2001-2004, Roger Dingledine.
3  * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
4  * Copyright (c) 2007-2021, The Tor Project, Inc. */
5 /* See LICENSE for licensing information */
6 
7 /**
8  * @file var_type_def_st.h
9  * @brief Structure declarations for typedvar type definitions.
10  *
11  * This structure is used for defining new variable types. If you are not
12  * defining a new variable type for use by the configuration management
13  * system, you don't need this structure.
14  *
15  * For defining new variables, see the types in conftypes.h.
16  *
17  * For data-driven access to configuration variables, see the other members of
18  * lib/confmgt/.
19  *
20  * STATUS NOTE: It is not yet possible to actually define new variables
21  * outside of config.c, and many of the types that will eventually be used
22  * to do so are not yet moved. This will change as more of #29211 is
23  * completed.
24  **/
25 
26 #ifndef TOR_LIB_CONFMGT_VAR_TYPE_DEF_ST_H
27 #define TOR_LIB_CONFMGT_VAR_TYPE_DEF_ST_H
28 
29 #include <stdbool.h>
30 
31 struct config_line_t;
32 
33 /**
34  * A structure full of functions pointers to implement a variable type.
35  *
36  * Every type MUST implement parse or kv_parse and encode or kv_encode;
37  * the other functions pointers MAY be NULL.
38  *
39  * All functions here take a <b>params</b> argument, whose value
40  * is determined by the type definition. Two types may have the
41  * same functions, but differ only in parameters.
42  *
43  * Implementation considerations: If "" encodes a valid value for a type, try
44  * to make sure that it encodes the same thing as the default value for the
45  * type (that is, the value that is set by config_clear() or memset(0)). If
46  * this is not the case, you need to make extra certain that your parse/encode
47  * implementations preserve the NULL/"" distinction.
48  **/
50  /**
51  * Try to parse a string in <b>value</b> that encodes an object of this
52  * type. On success, adjust the lvalue pointed to by <b>target</b> to hold
53  * that value, and return 0. On failure, set *<b>errmsg</b> to a newly
54  * allocated string holding an error message, and return -1.
55  **/
56  int (*parse)(void *target, const char *value, char **errmsg,
57  const void *params);
58  /**
59  * Try to parse a single line from the head of<b>line</b> that encodes
60  * an object of this type. On success and failure, behave as in the parse()
61  * function.
62  *
63  * If this function is absent, it is implemented in terms of parse().
64  *
65  * All types for which keys are significant should use this method. For
66  * example, a "linelist" type records the actual keys that are given
67  * for each line, and so should use this method.
68  *
69  * Note that although multiple lines may be provided in <b>line</b>,
70  * only the first one should be handled by this function.
71  **/
72  int (*kv_parse)(void *target, const struct config_line_t *line,
73  char **errmsg, const void *params);
74  /**
75  * Encode a value pointed to by <b>value</b> and return its result
76  * in a newly allocated string. The string may need to be escaped.
77  *
78  * If this function is absent, it is implemented in terms of kv_encode().
79  *
80  * Returns NULL if this option has a NULL value, or on internal error.
81  *
82  * Requirement: all strings generated by encode() should produce a
83  * semantically equivalent value when given to parse().
84  **/
85  char *(*encode)(const void *value, const void *params);
86  /**
87  * As encode(), but returns a newly allocated config_line_t object. The
88  * provided <b>key</b> is used as the key of the lines, unless the type is
89  * one that encodes its own keys.
90  *
91  * Unlike kv_parse(), this function will return a list of multiple lines,
92  * if <b>value</b> is such that it must be encoded by multiple lines.
93  *
94  * Returns NULL if there are no lines to encode, or on internal error.
95  *
96  * If this function is absent, it is implemented in terms of encode().
97  **/
98  struct config_line_t *(*kv_encode)(const char *key, const void *value,
99  const void *params);
100  /**
101  * Free all storage held in <b>arg</b>, and set <b>arg</b> to a default
102  * value -- usually zero or NULL.
103  *
104  * If this function is absent, the default implementation does nothing.
105  **/
106  void (*clear)(void *arg, const void *params);
107  /**
108  * Return true if <b>a</b> and <b>b</b> hold the same value, and false
109  * otherwise.
110  *
111  * If this function is absent, it is implemented by encoding both a and
112  * b and comparing their encoded strings for equality.
113  **/
114  bool (*eq)(const void *a, const void *b, const void *params);
115  /**
116  * Try to copy the value from <b>value</b> into <b>target</b>.
117  * On success return 0; on failure return -1.
118  *
119  * If this function is absent, it is implemented by encoding the value
120  * into a string, and then parsing it into the target.
121  **/
122  int (*copy)(void *target, const void *value, const void *params);
123  /**
124  * Check whether <b>value</b> holds a valid value according to the
125  * rules of this type; return true if it does and false if it doesn't.
126  *
127  * The default implementation for this function assumes that all
128  * values are valid.
129  **/
130  bool (*ok)(const void *value, const void *params);
131  /**
132  * Mark a value of this variable as "fragile", so that future attempts to
133  * assign to this variable will replace rather than extending it.
134  *
135  * The default implementation for this function does nothing.
136  *
137  * Only meaningful for types with is_cumulative set.
138  **/
139  void (*mark_fragile)(void *value, const void *params);
140 };
141 
142 /**
143  * A structure describing a type that can be manipulated with the typedvar_*
144  * functions.
145  **/
147  /**
148  * The name of this type. Should not include spaces. Used for
149  * debugging, log messages, and the controller API. */
150  const char *name;
151  /**
152  * A function table for this type.
153  */
154  const struct var_type_fns_t *fns;
155  /**
156  * A pointer to a value that should be passed as the 'params' argument when
157  * calling the functions in this type's function table.
158  */
159  const void *params;
160  /**
161  * A bitwise OR of one or more VTFLAG_* values, describing properties
162  * for all values of this type.
163  **/
164  uint32_t flags;
165 };
166 
167 #endif /* !defined(TOR_LIB_CONFMGT_VAR_TYPE_DEF_ST_H) */
const void * params
const char * name
const struct var_type_fns_t * fns
bool(* eq)(const void *a, const void *b, const void *params)
int(* copy)(void *target, const void *value, const void *params)
int(* parse)(void *target, const char *value, char **errmsg, const void *params)
bool(* ok)(const void *value, const void *params)
int(* kv_parse)(void *target, const struct config_line_t *line, char **errmsg, const void *params)
void(* mark_fragile)(void *value, const void *params)
void(* clear)(void *arg, const void *params)