include/qapi/visitor.h

23  * format.  QAPI objects can contain references to other QAPI objects,
25  * functions to walk these graphs.  This file represents the interface
51  * call visit_complete() (useful only for output visits, but safe to
53  * user should call visit_free() to clean up resources.  It is okay to
89  * visitor, then *@obj will be set to NULL for pointer types, and left
122  * in order to perform a deep clone of @src.
125  * generated for going from the derived type to the base type:
178  * It is also possible to use the visitors to do a virtual walk, where
180  * about what needs to be walked are made by the calling code, and
184  * Thus, a virtual walk corresponding to '{ "list": [1, 2] }' looks
255  * passed to the subtype_visitor_new() used to create an output
277  * @name expresses the relationship of this object to its parent
285  * On failure, set *@obj to NULL and store an error through @errp.
292  * within the struct.  Finally, visit_end_struct() needs to be called
293  * with the same @obj to clean up, even if intermediate visits fail.
297  * used for QAPI unions, and maps to JSON objects?
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.
320  * @obj must match what was passed to the paired 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
335  * @name expresses the relationship of this list to its parent
341  * allow @list to be NULL for a virtual walk, in which case @size is
344  * On failure, set *@list to NULL and store an error through @errp.
353  * element, call the appropriate visit_type_FOO() with name set to
354  * NULL and obj set to the address of the value member of the list
355  * element.  Finally, visit_end_list() needs to be called with the
356  * same @list to clean up, even if intermediate visits fail.  See the
373  * that function's name parameter set to NULL and obj set to the
386  * Should be called prior to visit_end_list() if all other
387  * intermediate visit steps were successful, to allow the visitor one
388  * last chance to report errors.  May be skipped on a cleanup path,
389  * where there is no need to check for further errors.
396  * @list must match what was passed to the paired visit_start_list().
399  * if intermediate processing was skipped due to errors, to allow the
400  * backend to release any resources.  Destroying the visitor early
411  * @name expresses the relationship of this alternate to its parent
414  * @obj must not be NULL. Input and clone visitors use @size to
415  * determine how much memory to allocate into *@obj, then determine
416  * the qtype of the next thing to be visited, and store it in
419  * On failure, set *@obj to NULL and store an error through @errp.
425  * the same @obj to clean up, even if visiting the contents of the
435  * @obj must match what was passed to the paired visit_start_alternate().
438  * even if intermediate processing was skipped due to errors, to allow
439  * the backend to release any resources.  Destroying the visitor early
455  * @present points to the address of the optional member's has_ flag.
457  * Input visitors set *@present according to input; other visitors
464  * Should we reject member @name due to policy?
478  * Should we skip member @name due to policy?
501  * @name expresses the relationship of this enum to its parent
504  * @obj must be non-NULL.  Input visitors parse input and set *@obj to
540  * @name expresses the relationship of this integer to its parent
543  * @obj must be non-NULL.  Input visitors set *@obj to the value;
555  * Like visit_type_int(), except clamps the value to uint8_t range.
562  * Like visit_type_int(), except clamps the value to uint16_t range.
569  * Like visit_type_int(), except clamps the value to uint32_t range.
576  * Like visit_type_int(), except clamps the value to uint64_t range,
584  * Like visit_type_int(), except clamps the value to int8_t range.
590  * Like visit_type_int(), except clamps the value to int16_t range.
597  * Like visit_type_int(), except clamps the value to int32_t range.
604  * Identical to visit_type_int().
611  * Like visit_type_uint64(), except that some visitors may choose to
621  * @name expresses the relationship of this boolean to its parent
624  * @obj must be non-NULL.  Input visitors set *@obj to the value;
637  * @name expresses the relationship of this string to its parent
640  * @obj must be non-NULL.  Input and clone visitors set *@obj to the
645  * It is safe to cast away const when preparing a (const char *) value
648  * On failure, set *@obj to NULL and store an error through @errp.
653  * FIXME: Callers that try to output NULL *obj should not be allowed.
660  * @name expresses the relationship of this number to its parent
663  * @obj must be non-NULL.  Input visitors set *@obj to the value;
678  * @name expresses the relationship of this value to its parent
681  * @obj must be non-NULL.  Input visitors set *@obj to the value;
685  * On failure, set *@obj to NULL and store an error through @errp.
699  * @name expresses the relationship of the null value to its parent
702  * @obj must be non-NULL.  Input visitors set *@obj to the value;
705  * On failure, set *@obj to NULL and store an error through @errp.