diff options
Diffstat (limited to 'include/qapi/visitor-impl.h')
| -rw-r--r-- | include/qapi/visitor-impl.h | 44 |
1 files changed, 36 insertions, 8 deletions
diff --git a/include/qapi/visitor-impl.h b/include/qapi/visitor-impl.h index 51c338a43d..796d1800d4 100644 --- a/include/qapi/visitor-impl.h +++ b/include/qapi/visitor-impl.h @@ -15,6 +15,18 @@ #include "qapi/visitor.h" /* + * This file describes the callback interface for implementing a QAPI + * visitor. For the client interface, see visitor.h. When + * implementing the callbacks, it is easiest to declare a struct with + * 'Visitor visitor;' as the first member. A callback's contract + * matches the corresponding public functions' contract unless stated + * otherwise. In the comments below, some callbacks are marked "must + * be set for $TYPE visits to work"; if a visitor implementation omits + * that callback, it should also document that it is only useful for a + * subset of QAPI. + */ + +/* * There are three classes of visitors; setting the class determines * how QAPI enums are visited, as well as what additional restrictions * can be asserted. @@ -27,43 +39,59 @@ typedef enum VisitorType { struct Visitor { - /* Must be set */ + /* Must be set to visit structs */ void (*start_struct)(Visitor *v, const char *name, void **obj, size_t size, Error **errp); + + /* Must be set to visit structs */ void (*end_struct)(Visitor *v, Error **errp); + /* Must be set */ void (*start_list)(Visitor *v, const char *name, Error **errp); + /* Must be set */ GenericList *(*next_list)(Visitor *v, GenericList **list, size_t size); + /* Must be set */ void (*end_list)(Visitor *v); - /* Optional, needed for input and dealloc visitors. */ + /* Must be set by input and dealloc visitors to visit alternates; + * optional for output visitors. */ void (*start_alternate)(Visitor *v, const char *name, GenericAlternate **obj, size_t size, bool promote_int, Error **errp); - /* Optional, needed for dealloc visitor. */ + /* Optional, needed for dealloc visitor */ void (*end_alternate)(Visitor *v); - /* Must be set. */ + /* Must be set */ void (*type_int64)(Visitor *v, const char *name, int64_t *obj, Error **errp); - /* Must be set. */ + + /* Must be set */ void (*type_uint64)(Visitor *v, const char *name, uint64_t *obj, Error **errp); - /* Optional; fallback is type_uint64(). */ + + /* Optional; fallback is type_uint64() */ void (*type_size)(Visitor *v, const char *name, uint64_t *obj, Error **errp); - /* Must be set. */ + + /* Must be set */ void (*type_bool)(Visitor *v, const char *name, bool *obj, Error **errp); + + /* Must be set */ void (*type_str)(Visitor *v, const char *name, char **obj, Error **errp); + + /* Must be set to visit numbers */ void (*type_number)(Visitor *v, const char *name, double *obj, Error **errp); + + /* Must be set to visit arbitrary QTypes */ void (*type_any)(Visitor *v, const char *name, QObject **obj, Error **errp); - /* May be NULL; most useful for input visitors. */ + /* Must be set for input visitors, optional otherwise. The core + * takes care of the return type in the public interface. */ void (*optional)(Visitor *v, const char *name, bool *present); /* Must be set */ |