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