BadVPN – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 1 /**
2 * @file NCDObject.h
3 * @author Ambroz Bizjak <ambrop7@gmail.com>
4 *
5 * @section LICENSE
6 *
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions are met:
9 * 1. Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 * 2. Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
14 * 3. Neither the name of the author nor the
15 * names of its contributors may be used to endorse or promote products
16 * derived from this software without specific prior written permission.
17 *
18 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
19 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
20 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
21 * DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
22 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
23 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
24 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
25 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
27 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28 */
29  
30 #ifndef BADVPN_NCDOBJECT_H
31 #define BADVPN_NCDOBJECT_H
32  
33 #include <stddef.h>
34  
35 #include <misc/debug.h>
36 #include <structure/LinkedList0.h>
37 #include <ncd/NCDVal_types.h>
38 #include <ncd/NCDStringIndex.h>
39 #include <ncd/static_strings.h>
40  
41 /**
42 * Represents an NCD object.
43 * Objects expose the following functionalities:
44 * - resolving variables by name,
45 * - resolving objects by name,
46 * - provide information for calling method-like statements.
47 *
48 * The NCDObject structure must not be stored persistently; it is only
49 * valid at the time it was obtained, and any change of state in the
50 * execution of the NCD program may render the object invalid.
51 * However, the structure does not contain any resources, and can freely
52 * be passed around by value.
53 */
54 typedef struct NCDObject_s NCDObject;
55  
56 /**
57 * Serves as an anchor point for NCDObjRef weak references.
58 * A callback produces the temporary NCDObject values on demand.
59 */
60 typedef struct NCDPersistentObj_s NCDPersistentObj;
61  
62 /**
63 * A weak reference to an NCDPersistentObj.
64 * This means that the existence of a reference does not prevent
65 * the NCDPersistentObj from going away, rather when it goes away
66 * the NCDObjRef becomes a broken reference - any further
67 * dereference operations will fail "gracefully".
68 */
69 typedef struct NCDObjRef_s NCDObjRef;
70  
71 /**
72 * Callback function for variable resolution requests.
73 *
74 * @param obj const pointer to the NCDObject this is being called for.
75 * {@link NCDObject_DataPtr} and {@link NCDObject_DataInt} can be
76 * used to retrieve state information which was passed to
77 * {@link NCDObject_Build} or {@link NCDObject_BuildFull}.
78 * @param name name of the variable being resolved, in form of an {@link NCDStringIndex}
79 * string identifier
80 * @param mem pointer to the memory object where the resulting value should be
81 * constructed
82 * @param out_value If the variable exists, *out_value should be set to the value
83 * reference to the result value. If the variable exists but there
84 * was an error constructing the value, should be set to an
85 * invalid value reference. Can be modified even if the variable
86 * does not exist.
87 * @return 1 if the variable exists, 0 if not
88 */
89 typedef int (*NCDObject_func_getvar) (const NCDObject *obj, NCD_string_id_t name, NCDValMem *mem, NCDValRef *out_value);
90  
91 /**
92 * Callback function for object resolution requests.
93 *
94 * @param obj const pointer to the NCDObject this is being called for.
95 * {@link NCDObject_DataPtr} and {@link NCDObject_DataInt} can be
96 * used to retrieve state information which was passed to
97 * {@link NCDObject_Build} or {@link NCDObject_BuildFull}.
98 * @param name name of the object being resolved, in form of an {@link NCDStringIndex}
99 * string identifier
100 * @param out_object If the object exists, *out_object should be set to the result
101 * object. Can be modified even if the object does not exist.
102 * @return 1 if the object exists, 0 if not
103 */
104 typedef int (*NCDObject_func_getobj) (const NCDObject *obj, NCD_string_id_t name, NCDObject *out_object);
105  
106 /**
107 * A callback of NCDPersistentObj which produces the corresponding temporary
108 * NCDObject value.
109 */
110 typedef NCDObject (*NCDPersistentObj_func_retobj) (NCDPersistentObj const *pobj);
111  
112 struct NCDObject_s {
113 NCD_string_id_t type;
114 int data_int;
115 void *data_ptr;
116 void *method_user;
117 NCDObject_func_getvar func_getvar;
118 NCDObject_func_getobj func_getobj;
119 NCDPersistentObj *pobj;
120 };
121  
122 struct NCDPersistentObj_s {
123 NCDPersistentObj_func_retobj func_retobj;
124 LinkedList0 refs_list;
125 };
126  
127 struct NCDObjRef_s {
128 NCDPersistentObj *pobj;
129 LinkedList0Node refs_list_node;
130 };
131  
132 /**
133 * Basic object construction function.
134 * This is equivalent to calling {@link NCDObject_BuildFull} with data_int=0,
135 * method_user=data_ptr and pobj=NULL. See that function for detailed documentation.
136 */
137 NCDObject NCDObject_Build (NCD_string_id_t type, void *data_ptr, NCDObject_func_getvar func_getvar, NCDObject_func_getobj func_getobj);
138  
139 /**
140 * Constructs an {@link NCDObject} structure.
141 * This is the full version where all supported parameters have to be provided.
142 * In most cases, {@link NCDObject_Build} will suffice.
143 *
144 * @param type type of the object for the purpose of calling method-like statements
145 * on the object, in form of an {@link NCDStringIndex} string identifier.
146 * May be set to -1 if the object has no methods.
147 * @param data_ptr state-keeping pointer which can be restored from callbacks using
148 * {@link NCDObject_DataPtr}
149 * @param data_int state-keeping integer which can be restored from callbacks using
150 * {@link NCDObject_DataInt}
151 * @param method_user state-keeping pointer to be passed to new method-like statements
152 * created using this object. The value of this argument will be
153 * available as params->method_user within the {@link NCDModule_func_new2}
154 * module backend callback.
155 * @param func_getvar callback for resolving variables within the object. This must not
156 * be NULL; if the object exposes no variables, pass {@link NCDObject_no_getvar}.
157 * @param func_getobj callback for resolving objects within the object. This must not
158 * be NULL; if the object exposes no objects, pass {@link NCDObject_no_getobj}.
159 * @param pobj pointer to an NCDPersistentObj, serving as a reference anchor for this
160 * object. NULL if references are not supported by the object.
161 * @return an NCDObject structure encapsulating the information given
162 */
163 NCDObject NCDObject_BuildFull (NCD_string_id_t type, void *data_ptr, int data_int, void *method_user, NCDObject_func_getvar func_getvar, NCDObject_func_getobj func_getobj, NCDPersistentObj *pobj);
164  
165 /**
166 * Returns the 'type' attribute; see {@link NCDObject_BuildFull}.
167 */
168 NCD_string_id_t NCDObject_Type (const NCDObject *o);
169  
170 /**
171 * Returns the 'data_ptr' attribute; see {@link NCDObject_BuildFull}.
172 */
173 void * NCDObject_DataPtr (const NCDObject *o);
174  
175 /**
176 * Returns the 'data_int' attribute; see {@link NCDObject_BuildFull}.
177 */
178 int NCDObject_DataInt (const NCDObject *o);
179  
180 /**
181 * Returns the 'method_user' attribute; see {@link NCDObject_BuildFull}.
182 */
183 void * NCDObject_MethodUser (const NCDObject *o);
184  
185 /**
186 * Attempts to resolve a variable within the object.
187 * This just calls {@link NCDObject_func_getvar}, but also has some assertions to detect
188 * incorrect behavior of the callback.
189 */
190 int NCDObject_GetVar (const NCDObject *o, NCD_string_id_t name, NCDValMem *mem, NCDValRef *out_value) WARN_UNUSED;
191  
192 /**
193 * Attempts to resolve an object within the object.
194 * This just calls {@link NCDObject_func_getobj}, but also has some assertions to detect
195 * incorrect behavior of the callback.
196 */
197 int NCDObject_GetObj (const NCDObject *o, NCD_string_id_t name, NCDObject *out_object) WARN_UNUSED;
198  
199 /**
200 * Returns a pointer to the NCDPersistentObj pointer for this
201 * object (if any).
202 */
203 NCDPersistentObj * NCDObject_Pobj (const NCDObject *o);
204  
205 /**
206 * Resolves a variable expression starting with this object.
207 * A variable expression is usually represented in dotted form,
208 * e.g. object1.object2.variable (for a named variable) or object1.object2.object3
209 * (for an empty string variable). This function however receives the expression
210 * as an array of string identifiers.
211 *
212 * Consult the implementation for exact semantics of variable expression resolution.
213 *
214 * @param o object to start the resolution with
215 * @param names pointer to an array of names for the resolution. May be NULL if num_names is 0.
216 * @param num_names number in names in the array
217 * @param mem pointer to the memory object where the resulting value
218 * should be constructed
219 * @param out_value If the variable exists, *out_value will be set to the value
220 * reference to the result value. If the variable exists but there
221 * was an error constructing the value, will be set to an
222 * invalid value reference. May be modified even if the variable
223 * does not exist.
224 * @return 1 if the variable exists, 0 if not
225 */
226 int NCDObject_ResolveVarExprCompact (const NCDObject *o, const NCD_string_id_t *names, size_t num_names, NCDValMem *mem, NCDValRef *out_value) WARN_UNUSED;
227  
228 /**
229 * Resolves an object expression starting with this object.
230 * An object expression is usually represented in dotted form,
231 * e.g. object1.object2.object3. This function however receives the expression
232 * as an array of string identifiers.
233 *
234 * Consult the implementation for exact semantics of object expression resolution.
235 *
236 * @param o object to start the resolution with
237 * @param names pointer to an array of names for the resolution. May be NULL if num_names is 0.
238 * @param num_names number in names in the array
239 * @param out_object If the object exists, *out_object will be set to the result
240 * object. May be modified even if the object does not exist.
241 * @return 1 if the object exists, 0 if not
242 */
243 int NCDObject_ResolveObjExprCompact (const NCDObject *o, const NCD_string_id_t *names, size_t num_names, NCDObject *out_object) WARN_UNUSED;
244  
245 /**
246 * Returns 0. This can be used as a dummy variable resolution callback.
247 */
248 int NCDObject_no_getvar (const NCDObject *obj, NCD_string_id_t name, NCDValMem *mem, NCDValRef *out_value);
249  
250 /**
251 * Returns 0. This can be used as a dummy object resolution callback.
252 */
253 int NCDObject_no_getobj (const NCDObject *obj, NCD_string_id_t name, NCDObject *out_object);
254  
255 /**
256 * Initializes an NCDPersistentObj, an anchor point for NCDObjRef
257 * refrences.
258 *
259 * @param func_retobj callback for producing NCDObject temporary objects
260 */
261 void NCDPersistentObj_Init (NCDPersistentObj *o, NCDPersistentObj_func_retobj func_retobj);
262  
263 /**
264 * Frees the NCDPersistentObj.
265 * This breaks any NCDObjRef references referencing this object.
266 * This means that any further NCDObjRef_Deref calls on those
267 * references will fail.
268 */
269 void NCDPersistentObj_Free (NCDPersistentObj *o);
270  
271 /**
272 * Initializes an object reference.
273 *
274 * @param pobj the NCDPersistentObj for the reference, or NULL to make
275 * a broken reference
276 */
277 void NCDObjRef_Init (NCDObjRef *o, NCDPersistentObj *pobj);
278  
279 /**
280 * Frees the object reference.
281 */
282 void NCDObjRef_Free (NCDObjRef *o);
283  
284 /**
285 * Dereferences the object reference.
286 * Note that the refernce will be broken if the originally
287 * reference NCDPersistentObj was freed.
288 *
289 * @param res on success, *res will be set to the resulting NCDObject
290 * @return 1 on success, 0 on failure (broken reference)
291 */
292 int NCDObjRef_Deref (NCDObjRef *o, NCDObject *res) WARN_UNUSED;
293  
294 #endif