/*
* Core Definitions for QAPI Visitor implementations
*
- * Copyright (C) 2012 Red Hat, Inc.
+ * Copyright (C) 2012-2016 Red Hat, Inc.
*
* Author: Paolo Bonizni <pbonzini@redhat.com>
*
#ifndef QAPI_VISITOR_IMPL_H
#define QAPI_VISITOR_IMPL_H
-#include "qapi/error.h"
#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 four classes of visitors; setting the class determines
+ * how QAPI enums are visited, as well as what additional restrictions
+ * can be asserted. The values are intentionally chosen so as to
+ * permit some assertions based on whether a given bit is set (that
+ * is, some assertions apply to input and clone visitors, some
+ * assertions apply to output and clone visitors).
+ */
+typedef enum VisitorType {
+ VISITOR_INPUT = 1,
+ VISITOR_OUTPUT = 2,
+ VISITOR_CLONE = 3,
+ VISITOR_DEALLOC = 4,
+} VisitorType;
+
struct Visitor
{
+ /* Must be set to visit structs */
+ void (*start_struct)(Visitor *v, const char *name, void **obj,
+ size_t size, Error **errp);
+
+ /* Optional; intended for input visitors */
+ void (*check_struct)(Visitor *v, Error **errp);
+
+ /* Must be set to visit structs */
+ void (*end_struct)(Visitor *v, void **obj);
+
+ /* Must be set; implementations may require @list to be non-null,
+ * but must document it. */
+ void (*start_list)(Visitor *v, const char *name, GenericList **list,
+ size_t size, Error **errp);
+
+ /* Must be set */
+ GenericList *(*next_list)(Visitor *v, GenericList *tail, size_t size);
+
+ /* Optional; intended for input visitors */
+ void (*check_list)(Visitor *v, Error **errp);
+
+ /* Must be set */
+ void (*end_list)(Visitor *v, void **list);
+
+ /* 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 */
+ void (*end_alternate)(Visitor *v, void **obj);
+
/* Must be set */
- void (*start_struct)(Visitor *v, void **obj, const char *kind,
- const char *name, size_t size, Error **errp);
- void (*end_struct)(Visitor *v, Error **errp);
-
- void (*start_implicit_struct)(Visitor *v, void **obj, size_t size,
- Error **errp);
- void (*end_implicit_struct)(Visitor *v, Error **errp);
-
- void (*start_list)(Visitor *v, const char *name, Error **errp);
- GenericList *(*next_list)(Visitor *v, GenericList **list, Error **errp);
- void (*end_list)(Visitor *v, Error **errp);
-
- void (*type_enum)(Visitor *v, int *obj, const char * const strings[],
- const char *kind, const char *name, Error **errp);
- /* May be NULL; only needed for input visitors. */
- void (*get_next_type)(Visitor *v, QType *type, bool promote_int,
- const char *name, Error **errp);
-
- void (*type_int)(Visitor *v, int64_t *obj, const char *name, Error **errp);
- void (*type_bool)(Visitor *v, bool *obj, const char *name, Error **errp);
- void (*type_str)(Visitor *v, char **obj, const char *name, Error **errp);
- void (*type_number)(Visitor *v, double *obj, const char *name,
+ void (*type_int64)(Visitor *v, const char *name, int64_t *obj,
+ Error **errp);
+
+ /* Must be set */
+ void (*type_uint64)(Visitor *v, const char *name, uint64_t *obj,
+ Error **errp);
+
+ /* Optional; fallback is type_uint64() */
+ void (*type_size)(Visitor *v, const char *name, uint64_t *obj,
+ Error **errp);
+
+ /* 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);
- void (*type_any)(Visitor *v, QObject **obj, const char *name,
+
+ /* 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. */
- void (*optional)(Visitor *v, bool *present, const char *name);
-
- void (*type_uint8)(Visitor *v, uint8_t *obj, const char *name, Error **errp);
- void (*type_uint16)(Visitor *v, uint16_t *obj, const char *name, Error **errp);
- void (*type_uint32)(Visitor *v, uint32_t *obj, const char *name, Error **errp);
- void (*type_uint64)(Visitor *v, uint64_t *obj, const char *name, Error **errp);
- void (*type_int8)(Visitor *v, int8_t *obj, const char *name, Error **errp);
- void (*type_int16)(Visitor *v, int16_t *obj, const char *name, Error **errp);
- void (*type_int32)(Visitor *v, int32_t *obj, const char *name, Error **errp);
- void (*type_int64)(Visitor *v, int64_t *obj, const char *name, Error **errp);
- /* visit_type_size() falls back to (*type_uint64)() if type_size is unset */
- void (*type_size)(Visitor *v, uint64_t *obj, const char *name, Error **errp);
- bool (*start_union)(Visitor *v, bool data_present, Error **errp);
- void (*end_union)(Visitor *v, bool data_present, Error **errp);
-};
+ /* Must be set to visit explicit null values. */
+ void (*type_null)(Visitor *v, const char *name, Error **errp);
+
+ /* Must be set for input visitors to visit structs, 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 */
+ VisitorType type;
+
+ /* Must be set for output visitors, optional otherwise. */
+ void (*complete)(Visitor *v, void *opaque);
-void input_type_enum(Visitor *v, int *obj, const char * const strings[],
- const char *kind, const char *name, Error **errp);
-void output_type_enum(Visitor *v, int *obj, const char * const strings[],
- const char *kind, const char *name, Error **errp);
+ /* Must be set */
+ void (*free)(Visitor *v);
+};
#endif
projects / mirror_qemu.git / blobdiff