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