]>
Commit | Line | Data |
---|---|---|
2345c77c MR |
1 | /* |
2 | * Core Definitions for QAPI Visitor Classes | |
3 | * | |
08f9541d | 4 | * Copyright (C) 2012-2016 Red Hat, Inc. |
2345c77c MR |
5 | * Copyright IBM, Corp. 2011 |
6 | * | |
7 | * Authors: | |
8 | * Anthony Liguori <aliguori@us.ibm.com> | |
9 | * | |
10 | * This work is licensed under the terms of the GNU LGPL, version 2.1 or later. | |
11 | * See the COPYING.LIB file in the top-level directory. | |
12 | * | |
13 | */ | |
121d0712 MA |
14 | |
15 | #ifndef QAPI_VISITOR_H | |
16 | #define QAPI_VISITOR_H | |
2345c77c | 17 | |
eb815e24 | 18 | #include "qapi/qapi-builtin-types.h" |
2345c77c | 19 | |
adfb264c EB |
20 | /* |
21 | * The QAPI schema defines both a set of C data types, and a QMP wire | |
22 | * format. QAPI objects can contain references to other QAPI objects, | |
23 | * resulting in a directed acyclic graph. QAPI also generates visitor | |
24 | * functions to walk these graphs. This file represents the interface | |
25 | * for doing work at each node of a QAPI graph; it can also be used | |
26 | * for a virtual walk, where there is no actual QAPI C struct. | |
27 | * | |
554d6586 MA |
28 | * There are four kinds of visitors: input visitors (QObject, string, |
29 | * and QemuOpts) parse an external representation and build the | |
30 | * corresponding QAPI object, output visitors (QObject and string) | |
31 | * take a QAPI object and generate an external representation, the | |
32 | * dealloc visitor takes a QAPI object (possibly partially | |
33 | * constructed) and recursively frees it, and the clone visitor | |
34 | * performs a deep clone of a QAPI object. | |
35 | * | |
36 | * While the dealloc and QObject input/output visitors are general, | |
37 | * the string, QemuOpts, and clone visitors have some implementation | |
38 | * limitations; see the documentation for each visitor for more | |
39 | * details on what it supports. Also, see visitor-impl.h for the | |
40 | * callback contracts implemented by each visitor, and | |
41 | * docs/devel/qapi-code-gen.txt for more about the QAPI code | |
42 | * generator. | |
adfb264c | 43 | * |
2c0ef9f4 EB |
44 | * All of the visitors are created via: |
45 | * | |
3b098d56 | 46 | * Visitor *subtype_visitor_new(parameters...); |
2c0ef9f4 EB |
47 | * |
48 | * A visitor should be used for exactly one top-level visit_type_FOO() | |
3b098d56 | 49 | * or virtual walk; if that is successful, the caller can optionally |
554d6586 MA |
50 | * call visit_complete() (useful only for output visits, but safe to |
51 | * call on all visits). Then, regardless of success or failure, the | |
52 | * user should call visit_free() to clean up resources. It is okay to | |
53 | * free the visitor without completing the visit, if some other error | |
54 | * is detected in the meantime. | |
55 | * | |
56 | * The clone and dealloc visitor should not be used directly outside | |
57 | * of QAPI code. Use the qapi_free_FOO() and QAPI_CLONE() instead, | |
58 | * described below. | |
2c0ef9f4 | 59 | * |
adfb264c EB |
60 | * All QAPI types have a corresponding function with a signature |
61 | * roughly compatible with this: | |
62 | * | |
63 | * void visit_type_FOO(Visitor *v, const char *name, T obj, Error **errp); | |
64 | * | |
65 | * where T is FOO for scalar types, and FOO * otherwise. The scalar | |
66 | * visitors are declared here; the remaining visitors are generated in | |
3777d36e | 67 | * qapi-visit-MODULE.h. |
adfb264c EB |
68 | * |
69 | * The @name parameter of visit_type_FOO() describes the relation | |
70 | * between this QAPI value and its parent container. When visiting | |
71 | * the root of a tree, @name is ignored; when visiting a member of an | |
ed0ba0f4 MA |
72 | * object, @name is the key associated with the value; when visiting a |
73 | * member of a list, @name is NULL; and when visiting the member of an | |
74 | * alternate, @name should equal the name used for visiting the | |
75 | * alternate. | |
adfb264c | 76 | * |
554d6586 MA |
77 | * The visit_type_FOO() functions take a non-null @obj argument; they |
78 | * allocate *@obj during input visits, leave it unchanged during | |
79 | * output and clone visits, and free it (recursively) during a dealloc | |
80 | * visit. | |
81 | * | |
82 | * Each function also takes the customary @errp argument (see | |
adfb264c EB |
83 | * qapi/error.h for details), for reporting any errors (such as if a |
84 | * member @name is not present, or is present but not the specified | |
1f584248 | 85 | * type). Only input visitors can fail. |
adfb264c | 86 | * |
68ab47e4 | 87 | * If an error is detected during visit_type_FOO() with an input |
554d6586 MA |
88 | * visitor, then *@obj will be set to NULL for pointer types, and left |
89 | * unchanged for scalar types. | |
90 | * | |
91 | * Using an output or clone visitor with an incomplete object has | |
92 | * undefined behavior (other than a special case for visit_type_str() | |
93 | * treating NULL like ""), while the dealloc visitor safely handles | |
94 | * incomplete objects. Since input visitors never produce an | |
95 | * incomplete object, such an object is possible only by manual | |
96 | * construction. | |
adfb264c EB |
97 | * |
98 | * For the QAPI object types (structs, unions, and alternates), there | |
3777d36e MA |
99 | * is an additional generated function in qapi-visit-MODULE.h |
100 | * compatible with: | |
adfb264c EB |
101 | * |
102 | * void visit_type_FOO_members(Visitor *v, FOO *obj, Error **errp); | |
103 | * | |
104 | * for visiting the members of a type without also allocating the QAPI | |
105 | * struct. | |
106 | * | |
3777d36e MA |
107 | * Additionally, QAPI pointer types (structs, unions, alternates, and |
108 | * lists) have a generated function in qapi-types-MODULE.h compatible | |
adfb264c EB |
109 | * with: |
110 | * | |
111 | * void qapi_free_FOO(FOO *obj); | |
112 | * | |
554d6586 MA |
113 | * Does nothing when @obj is NULL. |
114 | * | |
115 | * Such objects may also be used with macro | |
a15fcc3c EB |
116 | * |
117 | * Type *QAPI_CLONE(Type, src); | |
118 | * | |
554d6586 | 119 | * in order to perform a deep clone of @src. |
a15fcc3c | 120 | * |
554d6586 MA |
121 | * For QAPI types can that inherit from a base type, a function is |
122 | * generated for going from the derived type to the base type: | |
adfb264c EB |
123 | * |
124 | * BASE *qapi_CHILD_base(CHILD *obj); | |
125 | * | |
554d6586 | 126 | * Typical input visitor usage involves: |
adfb264c EB |
127 | * |
128 | * <example> | |
129 | * Foo *f; | |
130 | * Error *err = NULL; | |
131 | * Visitor *v; | |
132 | * | |
3b098d56 | 133 | * v = FOO_visitor_new(...); |
adfb264c EB |
134 | * visit_type_Foo(v, NULL, &f, &err); |
135 | * if (err) { | |
adfb264c EB |
136 | * ...handle error... |
137 | * } else { | |
138 | * ...use f... | |
139 | * } | |
3b098d56 | 140 | * visit_free(v); |
adfb264c EB |
141 | * qapi_free_Foo(f); |
142 | * </example> | |
143 | * | |
144 | * For a list, it is: | |
145 | * <example> | |
146 | * FooList *l; | |
147 | * Error *err = NULL; | |
148 | * Visitor *v; | |
149 | * | |
3b098d56 | 150 | * v = FOO_visitor_new(...); |
adfb264c EB |
151 | * visit_type_FooList(v, NULL, &l, &err); |
152 | * if (err) { | |
adfb264c EB |
153 | * ...handle error... |
154 | * } else { | |
155 | * for ( ; l; l = l->next) { | |
156 | * ...use l->value... | |
157 | * } | |
158 | * } | |
3b098d56 | 159 | * visit_free(v); |
adfb264c EB |
160 | * qapi_free_FooList(l); |
161 | * </example> | |
162 | * | |
554d6586 | 163 | * Typical output visitor usage: |
adfb264c EB |
164 | * |
165 | * <example> | |
166 | * Foo *f = ...obtain populated object... | |
adfb264c | 167 | * Visitor *v; |
3b098d56 | 168 | * Type *result; |
adfb264c | 169 | * |
3b098d56 | 170 | * v = FOO_visitor_new(..., &result); |
1f584248 MA |
171 | * visit_type_Foo(v, NULL, &f, &error_abort); |
172 | * visit_complete(v, &result); | |
3b098d56 | 173 | * visit_free(v); |
1f584248 | 174 | * ...use result... |
adfb264c EB |
175 | * </example> |
176 | * | |
adfb264c | 177 | * It is also possible to use the visitors to do a virtual walk, where |
554d6586 | 178 | * no actual QAPI object is present. In this situation, decisions |
adfb264c EB |
179 | * about what needs to be walked are made by the calling code, and |
180 | * structured visits are split between pairs of start and end methods | |
181 | * (where the end method must be called if the start function | |
182 | * succeeded, even if an intermediate visit encounters an error). | |
183 | * Thus, a virtual walk corresponding to '{ "list": [1, 2] }' looks | |
184 | * like: | |
185 | * | |
186 | * <example> | |
187 | * Visitor *v; | |
188 | * Error *err = NULL; | |
189 | * int value; | |
190 | * | |
3b098d56 | 191 | * v = FOO_visitor_new(...); |
adfb264c EB |
192 | * visit_start_struct(v, NULL, NULL, 0, &err); |
193 | * if (err) { | |
194 | * goto out; | |
195 | * } | |
d9f62dde | 196 | * visit_start_list(v, "list", NULL, 0, &err); |
adfb264c EB |
197 | * if (err) { |
198 | * goto outobj; | |
199 | * } | |
200 | * value = 1; | |
201 | * visit_type_int(v, NULL, &value, &err); | |
202 | * if (err) { | |
203 | * goto outlist; | |
204 | * } | |
205 | * value = 2; | |
206 | * visit_type_int(v, NULL, &value, &err); | |
207 | * if (err) { | |
208 | * goto outlist; | |
209 | * } | |
210 | * outlist: | |
294c9066 MA |
211 | * if (!err) { |
212 | * visit_check_list(v, &err); | |
213 | * } | |
1158bb2a | 214 | * visit_end_list(v, NULL); |
15c2f669 EB |
215 | * if (!err) { |
216 | * visit_check_struct(v, &err); | |
217 | * } | |
adfb264c | 218 | * outobj: |
1158bb2a | 219 | * visit_end_struct(v, NULL); |
adfb264c | 220 | * out: |
3b098d56 | 221 | * visit_free(v); |
adfb264c | 222 | * </example> |
554d6586 MA |
223 | * |
224 | * This file provides helpers for use by the generated | |
225 | * visit_type_FOO(): visit_optional() for the 'has_member' field | |
226 | * associated with optional 'member' in the C struct, | |
227 | * visit_next_list() for advancing through a FooList linked list, and | |
228 | * visit_is_input() for cleaning up on failure. | |
adfb264c EB |
229 | */ |
230 | ||
231 | /*** Useful types ***/ | |
232 | ||
e65d89bf | 233 | /* This struct is layout-compatible with all other *List structs |
adfb264c | 234 | * created by the QAPI generator. It is used as a typical |
e65d89bf EB |
235 | * singly-linked list. */ |
236 | typedef struct GenericList { | |
2345c77c | 237 | struct GenericList *next; |
e65d89bf | 238 | char padding[]; |
2345c77c MR |
239 | } GenericList; |
240 | ||
dbf11922 | 241 | /* This struct is layout-compatible with all Alternate types |
adfb264c | 242 | * created by the QAPI generator. */ |
dbf11922 EB |
243 | typedef struct GenericAlternate { |
244 | QType type; | |
245 | char padding[]; | |
246 | } GenericAlternate; | |
247 | ||
2c0ef9f4 EB |
248 | /*** Visitor cleanup ***/ |
249 | ||
3b098d56 EB |
250 | /* |
251 | * Complete the visit, collecting any output. | |
252 | * | |
253 | * May only be called only once after a successful top-level | |
254 | * visit_type_FOO() or visit_end_ITEM(), and marks the end of the | |
255 | * visit. The @opaque pointer should match the output parameter | |
256 | * passed to the subtype_visitor_new() used to create an output | |
257 | * visitor, or NULL for any other visitor. Needed for output | |
258 | * visitors, but may also be called with other visitors. | |
259 | */ | |
260 | void visit_complete(Visitor *v, void *opaque); | |
261 | ||
2c0ef9f4 EB |
262 | /* |
263 | * Free @v and any resources it has tied up. | |
264 | * | |
265 | * May be called whether or not the visit has been successfully | |
266 | * completed, but should not be called until a top-level | |
267 | * visit_type_FOO() or visit_start_ITEM() has been performed on the | |
268 | * visitor. Safe if @v is NULL. | |
269 | */ | |
270 | void visit_free(Visitor *v); | |
271 | ||
272 | ||
adfb264c EB |
273 | /*** Visiting structures ***/ |
274 | ||
275 | /* | |
276 | * Start visiting an object @obj (struct or union). | |
277 | * | |
278 | * @name expresses the relationship of this object to its parent | |
279 | * container; see the general description of @name above. | |
280 | * | |
281 | * @obj must be non-NULL for a real walk, in which case @size | |
a15fcc3c EB |
282 | * determines how much memory an input or clone visitor will allocate |
283 | * into *@obj. @obj may also be NULL for a virtual walk, in which | |
284 | * case @size is ignored. | |
adfb264c | 285 | * |
c5460d5e | 286 | * On failure, set *@obj to NULL and store an error through @errp. |
1f584248 | 287 | * Can happen only when @v is an input visitor. |
adfb264c EB |
288 | * |
289 | * After visit_start_struct() succeeds, the caller may visit its | |
290 | * members one after the other, passing the member's name and address | |
291 | * within the struct. Finally, visit_end_struct() needs to be called | |
1158bb2a EB |
292 | * with the same @obj to clean up, even if intermediate visits fail. |
293 | * See the examples above. | |
adfb264c EB |
294 | * |
295 | * FIXME Should this be named visit_start_object, since it is also | |
296 | * used for QAPI unions, and maps to JSON objects? | |
297 | */ | |
51e72bc1 | 298 | void visit_start_struct(Visitor *v, const char *name, void **obj, |
337283df | 299 | size_t size, Error **errp); |
adfb264c EB |
300 | |
301 | /* | |
15c2f669 | 302 | * Prepare for completing an object visit. |
adfb264c | 303 | * |
1f584248 MA |
304 | * On failure, store an error through @errp. Can happen only when @v |
305 | * is an input visitor. | |
adfb264c | 306 | * |
15c2f669 EB |
307 | * Should be called prior to visit_end_struct() if all other |
308 | * intermediate visit steps were successful, to allow the visitor one | |
309 | * last chance to report errors. May be skipped on a cleanup path, | |
310 | * where there is no need to check for further errors. | |
311 | */ | |
312 | void visit_check_struct(Visitor *v, Error **errp); | |
313 | ||
314 | /* | |
315 | * Complete an object visit started earlier. | |
316 | * | |
1158bb2a EB |
317 | * @obj must match what was passed to the paired visit_start_struct(). |
318 | * | |
adfb264c EB |
319 | * Must be called after any successful use of visit_start_struct(), |
320 | * even if intermediate processing was skipped due to errors, to allow | |
321 | * the backend to release any resources. Destroying the visitor early | |
2c0ef9f4 | 322 | * with visit_free() behaves as if this was implicitly called. |
adfb264c | 323 | */ |
1158bb2a | 324 | void visit_end_struct(Visitor *v, void **obj); |
08f9541d | 325 | |
adfb264c EB |
326 | |
327 | /*** Visiting lists ***/ | |
328 | ||
329 | /* | |
330 | * Start visiting a list. | |
331 | * | |
332 | * @name expresses the relationship of this list to its parent | |
333 | * container; see the general description of @name above. | |
334 | * | |
d9f62dde | 335 | * @list must be non-NULL for a real walk, in which case @size |
a15fcc3c EB |
336 | * determines how much memory an input or clone visitor will allocate |
337 | * into *@list (at least sizeof(GenericList)). Some visitors also | |
338 | * allow @list to be NULL for a virtual walk, in which case @size is | |
d9f62dde EB |
339 | * ignored. |
340 | * | |
c5460d5e | 341 | * On failure, set *@list to NULL and store an error through @errp. |
1f584248 | 342 | * Can happen only when @v is an input visitor. |
adfb264c EB |
343 | * |
344 | * After visit_start_list() succeeds, the caller may visit its members | |
782586c7 | 345 | * one after the other. A real visit (where @list is non-NULL) uses |
d9f62dde | 346 | * visit_next_list() for traversing the linked list, while a virtual |
782586c7 | 347 | * visit (where @list is NULL) uses other means. For each list |
d9f62dde EB |
348 | * element, call the appropriate visit_type_FOO() with name set to |
349 | * NULL and obj set to the address of the value member of the list | |
1158bb2a EB |
350 | * element. Finally, visit_end_list() needs to be called with the |
351 | * same @list to clean up, even if intermediate visits fail. See the | |
352 | * examples above. | |
adfb264c | 353 | */ |
d9f62dde EB |
354 | void visit_start_list(Visitor *v, const char *name, GenericList **list, |
355 | size_t size, Error **errp); | |
adfb264c EB |
356 | |
357 | /* | |
358 | * Iterate over a GenericList during a non-virtual list visit. | |
359 | * | |
360 | * @size represents the size of a linked list node (at least | |
361 | * sizeof(GenericList)). | |
362 | * | |
d9f62dde EB |
363 | * @tail must not be NULL; on the first call, @tail is the value of |
364 | * *list after visit_start_list(), and on subsequent calls @tail must | |
365 | * be the previously returned value. Should be called in a loop until | |
81b49004 MA |
366 | * a NULL return; for each non-NULL return, the caller then calls the |
367 | * appropriate visit_type_*() for the element type of the list, with | |
368 | * that function's name parameter set to NULL and obj set to the | |
369 | * address of @tail->value. | |
adfb264c | 370 | */ |
d9f62dde | 371 | GenericList *visit_next_list(Visitor *v, GenericList *tail, size_t size); |
adfb264c | 372 | |
a4a1c70d MA |
373 | /* |
374 | * Prepare for completing a list visit. | |
375 | * | |
1f584248 MA |
376 | * On failure, store an error through @errp. Can happen only when @v |
377 | * is an input visitor. | |
a4a1c70d MA |
378 | * |
379 | * Should be called prior to visit_end_list() if all other | |
380 | * intermediate visit steps were successful, to allow the visitor one | |
381 | * last chance to report errors. May be skipped on a cleanup path, | |
382 | * where there is no need to check for further errors. | |
383 | */ | |
384 | void visit_check_list(Visitor *v, Error **errp); | |
385 | ||
adfb264c EB |
386 | /* |
387 | * Complete a list visit started earlier. | |
388 | * | |
1158bb2a EB |
389 | * @list must match what was passed to the paired visit_start_list(). |
390 | * | |
adfb264c EB |
391 | * Must be called after any successful use of visit_start_list(), even |
392 | * if intermediate processing was skipped due to errors, to allow the | |
393 | * backend to release any resources. Destroying the visitor early | |
2c0ef9f4 | 394 | * with visit_free() behaves as if this was implicitly called. |
adfb264c | 395 | */ |
1158bb2a | 396 | void visit_end_list(Visitor *v, void **list); |
5cdc8831 | 397 | |
adfb264c EB |
398 | |
399 | /*** Visiting alternates ***/ | |
400 | ||
dbf11922 | 401 | /* |
adfb264c | 402 | * Start the visit of an alternate @obj. |
dbf11922 | 403 | * |
adfb264c EB |
404 | * @name expresses the relationship of this alternate to its parent |
405 | * container; see the general description of @name above. | |
dbf11922 | 406 | * |
a15fcc3c EB |
407 | * @obj must not be NULL. Input and clone visitors use @size to |
408 | * determine how much memory to allocate into *@obj, then determine | |
c5460d5e MA |
409 | * the qtype of the next thing to be visited, and store it in |
410 | * (*@obj)->type. Other visitors leave @obj unchanged. | |
411 | * | |
412 | * On failure, set *@obj to NULL and store an error through @errp. | |
1f584248 | 413 | * Can happen only when @v is an input visitor. |
dbf11922 | 414 | * |
1158bb2a EB |
415 | * If successful, this must be paired with visit_end_alternate() with |
416 | * the same @obj to clean up, even if visiting the contents of the | |
417 | * alternate fails. | |
dbf11922 EB |
418 | */ |
419 | void visit_start_alternate(Visitor *v, const char *name, | |
420 | GenericAlternate **obj, size_t size, | |
60390d2d | 421 | Error **errp); |
dbf11922 EB |
422 | |
423 | /* | |
424 | * Finish visiting an alternate type. | |
425 | * | |
1158bb2a EB |
426 | * @obj must match what was passed to the paired visit_start_alternate(). |
427 | * | |
adfb264c EB |
428 | * Must be called after any successful use of visit_start_alternate(), |
429 | * even if intermediate processing was skipped due to errors, to allow | |
430 | * the backend to release any resources. Destroying the visitor early | |
2c0ef9f4 | 431 | * with visit_free() behaves as if this was implicitly called. |
dbf11922 | 432 | * |
dbf11922 | 433 | */ |
1158bb2a | 434 | void visit_end_alternate(Visitor *v, void **obj); |
dbf11922 | 435 | |
adfb264c EB |
436 | |
437 | /*** Other helpers ***/ | |
438 | ||
439 | /* | |
440 | * Does optional struct member @name need visiting? | |
441 | * | |
442 | * @name must not be NULL. This function is only useful between | |
443 | * visit_start_struct() and visit_end_struct(), since only objects | |
444 | * have optional keys. | |
445 | * | |
446 | * @present points to the address of the optional member's has_ flag. | |
447 | * | |
448 | * Input visitors set *@present according to input; other visitors | |
449 | * leave it unchanged. In either case, return *@present for | |
450 | * convenience. | |
5cdc8831 | 451 | */ |
51e72bc1 | 452 | bool visit_optional(Visitor *v, const char *name, bool *present); |
0426d53c | 453 | |
983f52d4 EB |
454 | /* |
455 | * Visit an enum value. | |
456 | * | |
adfb264c EB |
457 | * @name expresses the relationship of this enum to its parent |
458 | * container; see the general description of @name above. | |
459 | * | |
460 | * @obj must be non-NULL. Input visitors parse input and set *@obj to | |
461 | * the enumeration value, leaving @obj unchanged on error; other | |
462 | * visitors use *@obj but leave it unchanged. | |
463 | * | |
464 | * Currently, all input visitors parse text input, and all output | |
465 | * visitors produce text output. The mapping between enumeration | |
c5460d5e MA |
466 | * values and strings is done by the visitor core, using @lookup. |
467 | * | |
1f584248 MA |
468 | * On failure, store an error through @errp. Can happen only when @v |
469 | * is an input visitor. | |
983f52d4 EB |
470 | * |
471 | * May call visit_type_str() under the hood, and the enum visit may | |
472 | * fail even if the corresponding string visit succeeded; this implies | |
1f584248 MA |
473 | * that an input visitor's visit_type_str() must have no unwelcome |
474 | * side effects. | |
983f52d4 | 475 | */ |
51e72bc1 | 476 | void visit_type_enum(Visitor *v, const char *name, int *obj, |
f7abe0ec | 477 | const QEnumLookup *lookup, Error **errp); |
983f52d4 | 478 | |
68ab47e4 EB |
479 | /* |
480 | * Check if visitor is an input visitor. | |
481 | */ | |
482 | bool visit_is_input(Visitor *v); | |
483 | ||
8e08bf4e MA |
484 | /* |
485 | * Check if visitor is a dealloc visitor. | |
486 | */ | |
487 | bool visit_is_dealloc(Visitor *v); | |
488 | ||
adfb264c EB |
489 | /*** Visiting built-in types ***/ |
490 | ||
491 | /* | |
492 | * Visit an integer value. | |
493 | * | |
494 | * @name expresses the relationship of this integer to its parent | |
495 | * container; see the general description of @name above. | |
496 | * | |
497 | * @obj must be non-NULL. Input visitors set *@obj to the value; | |
498 | * other visitors will leave *@obj unchanged. | |
c5460d5e | 499 | * |
1f584248 MA |
500 | * On failure, store an error through @errp. Can happen only when @v |
501 | * is an input visitor. | |
adfb264c | 502 | */ |
51e72bc1 | 503 | void visit_type_int(Visitor *v, const char *name, int64_t *obj, Error **errp); |
adfb264c EB |
504 | |
505 | /* | |
506 | * Visit a uint8_t value. | |
507 | * Like visit_type_int(), except clamps the value to uint8_t range. | |
508 | */ | |
51e72bc1 EB |
509 | void visit_type_uint8(Visitor *v, const char *name, uint8_t *obj, |
510 | Error **errp); | |
adfb264c EB |
511 | |
512 | /* | |
513 | * Visit a uint16_t value. | |
514 | * Like visit_type_int(), except clamps the value to uint16_t range. | |
515 | */ | |
51e72bc1 EB |
516 | void visit_type_uint16(Visitor *v, const char *name, uint16_t *obj, |
517 | Error **errp); | |
adfb264c EB |
518 | |
519 | /* | |
520 | * Visit a uint32_t value. | |
521 | * Like visit_type_int(), except clamps the value to uint32_t range. | |
522 | */ | |
51e72bc1 EB |
523 | void visit_type_uint32(Visitor *v, const char *name, uint32_t *obj, |
524 | Error **errp); | |
adfb264c EB |
525 | |
526 | /* | |
527 | * Visit a uint64_t value. | |
528 | * Like visit_type_int(), except clamps the value to uint64_t range, | |
529 | * that is, ensures it is unsigned. | |
530 | */ | |
51e72bc1 EB |
531 | void visit_type_uint64(Visitor *v, const char *name, uint64_t *obj, |
532 | Error **errp); | |
adfb264c EB |
533 | |
534 | /* | |
535 | * Visit an int8_t value. | |
536 | * Like visit_type_int(), except clamps the value to int8_t range. | |
537 | */ | |
51e72bc1 | 538 | void visit_type_int8(Visitor *v, const char *name, int8_t *obj, Error **errp); |
adfb264c EB |
539 | |
540 | /* | |
541 | * Visit an int16_t value. | |
542 | * Like visit_type_int(), except clamps the value to int16_t range. | |
543 | */ | |
51e72bc1 EB |
544 | void visit_type_int16(Visitor *v, const char *name, int16_t *obj, |
545 | Error **errp); | |
adfb264c EB |
546 | |
547 | /* | |
548 | * Visit an int32_t value. | |
549 | * Like visit_type_int(), except clamps the value to int32_t range. | |
550 | */ | |
51e72bc1 EB |
551 | void visit_type_int32(Visitor *v, const char *name, int32_t *obj, |
552 | Error **errp); | |
adfb264c EB |
553 | |
554 | /* | |
555 | * Visit an int64_t value. | |
556 | * Identical to visit_type_int(). | |
557 | */ | |
51e72bc1 EB |
558 | void visit_type_int64(Visitor *v, const char *name, int64_t *obj, |
559 | Error **errp); | |
adfb264c EB |
560 | |
561 | /* | |
562 | * Visit a uint64_t value. | |
563 | * Like visit_type_uint64(), except that some visitors may choose to | |
564 | * recognize additional syntax, such as suffixes for easily scaling | |
565 | * values. | |
566 | */ | |
51e72bc1 EB |
567 | void visit_type_size(Visitor *v, const char *name, uint64_t *obj, |
568 | Error **errp); | |
adfb264c EB |
569 | |
570 | /* | |
571 | * Visit a boolean value. | |
572 | * | |
573 | * @name expresses the relationship of this boolean to its parent | |
574 | * container; see the general description of @name above. | |
575 | * | |
576 | * @obj must be non-NULL. Input visitors set *@obj to the value; | |
577 | * other visitors will leave *@obj unchanged. | |
c5460d5e | 578 | * |
1f584248 MA |
579 | * On failure, store an error through @errp. Can happen only when @v |
580 | * is an input visitor. | |
adfb264c | 581 | */ |
51e72bc1 | 582 | void visit_type_bool(Visitor *v, const char *name, bool *obj, Error **errp); |
adfb264c EB |
583 | |
584 | /* | |
585 | * Visit a string value. | |
586 | * | |
587 | * @name expresses the relationship of this string to its parent | |
588 | * container; see the general description of @name above. | |
589 | * | |
a15fcc3c EB |
590 | * @obj must be non-NULL. Input and clone visitors set *@obj to the |
591 | * value (always using "" rather than NULL for an empty string). | |
592 | * Other visitors leave *@obj unchanged, and commonly treat NULL like | |
593 | * "". | |
adfb264c EB |
594 | * |
595 | * It is safe to cast away const when preparing a (const char *) value | |
596 | * into @obj for use by an output visitor. | |
597 | * | |
c5460d5e | 598 | * On failure, set *@obj to NULL and store an error through @errp. |
1f584248 | 599 | * Can happen only when @v is an input visitor. |
c5460d5e | 600 | * |
adfb264c EB |
601 | * FIXME: Callers that try to output NULL *obj should not be allowed. |
602 | */ | |
51e72bc1 | 603 | void visit_type_str(Visitor *v, const char *name, char **obj, Error **errp); |
adfb264c EB |
604 | |
605 | /* | |
606 | * Visit a number (i.e. double) value. | |
607 | * | |
608 | * @name expresses the relationship of this number to its parent | |
609 | * container; see the general description of @name above. | |
610 | * | |
611 | * @obj must be non-NULL. Input visitors set *@obj to the value; | |
612 | * other visitors will leave *@obj unchanged. Visitors should | |
613 | * document if infinity or NaN are not permitted. | |
c5460d5e | 614 | * |
1f584248 MA |
615 | * On failure, store an error through @errp. Can happen only when @v |
616 | * is an input visitor. | |
adfb264c | 617 | */ |
51e72bc1 EB |
618 | void visit_type_number(Visitor *v, const char *name, double *obj, |
619 | Error **errp); | |
adfb264c EB |
620 | |
621 | /* | |
622 | * Visit an arbitrary value. | |
623 | * | |
624 | * @name expresses the relationship of this value to its parent | |
625 | * container; see the general description of @name above. | |
626 | * | |
627 | * @obj must be non-NULL. Input visitors set *@obj to the value; | |
628 | * other visitors will leave *@obj unchanged. *@obj must be non-NULL | |
629 | * for output visitors. | |
8339fa26 | 630 | * |
c5460d5e | 631 | * On failure, set *@obj to NULL and store an error through @errp. |
1f584248 | 632 | * Can happen only when @v is an input visitor. |
c5460d5e | 633 | * |
8339fa26 MA |
634 | * Note that some kinds of input can't express arbitrary QObject. |
635 | * E.g. the visitor returned by qobject_input_visitor_new_keyval() | |
636 | * can't create numbers or booleans, only strings. | |
adfb264c | 637 | */ |
51e72bc1 | 638 | void visit_type_any(Visitor *v, const char *name, QObject **obj, Error **errp); |
2345c77c | 639 | |
3bc97fd5 EB |
640 | /* |
641 | * Visit a JSON null value. | |
642 | * | |
643 | * @name expresses the relationship of the null value to its parent | |
644 | * container; see the general description of @name above. | |
645 | * | |
d2f95f4d MA |
646 | * @obj must be non-NULL. Input visitors set *@obj to the value; |
647 | * other visitors ignore *@obj. | |
c5460d5e MA |
648 | * |
649 | * On failure, set *@obj to NULL and store an error through @errp. | |
1f584248 | 650 | * Can happen only when @v is an input visitor. |
3bc97fd5 | 651 | */ |
d2f95f4d MA |
652 | void visit_type_null(Visitor *v, const char *name, QNull **obj, |
653 | Error **errp); | |
3bc97fd5 | 654 | |
2345c77c | 655 | #endif |