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