Tor 0.4.9.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
31struct 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)