include/qapi/visitor-impl.h

   1 /*
   2  * Core Definitions for QAPI Visitor implementations
   3  *
   4  * Copyright (C) 2012-2016 Red Hat, Inc.
   5  *
   6  * Author: Paolo Bonizni <pbonzini@redhat.com>
   7  *
   8  * This work is licensed under the terms of the GNU LGPL, version 2.1 or later.
   9  * See the COPYING.LIB file in the top-level directory.
  10  *
  11  */
  12 #ifndef QAPI_VISITOR_IMPL_H
  13 #define QAPI_VISITOR_IMPL_H
  14
  15 #include "qapi/visitor.h"
  16
  17 /*
  18  * This file describes the callback interface for implementing a QAPI
  19  * visitor.  For the client interface, see visitor.h.  When
  20  * implementing the callbacks, it is easiest to declare a struct with
  21  * 'Visitor visitor;' as the first member.  A callback's contract
  22  * matches the corresponding public functions' contract unless stated
  23  * otherwise.  In the comments below, some callbacks are marked "must
  24  * be set for $TYPE visits to work"; if a visitor implementation omits
  25  * that callback, it should also document that it is only useful for a
  26  * subset of QAPI.
  27  */
  28
  29 /*
  30  * There are four classes of visitors; setting the class determines
  31  * how QAPI enums are visited, as well as what additional restrictions
  32  * can be asserted.  The values are intentionally chosen so as to
  33  * permit some assertions based on whether a given bit is set (that
  34  * is, some assertions apply to input and clone visitors, some
  35  * assertions apply to output and clone visitors).
  36  */
  37 typedef enum VisitorType {
  38     VISITOR_INPUT = 1,
  39     VISITOR_OUTPUT = 2,
  40     VISITOR_CLONE = 3,
  41     VISITOR_DEALLOC = 4,
  42 } VisitorType;
  43
  44 struct Visitor
  45 {
  46     /*
  47      * Only input visitors may fail!
  48      */
  49
  50     /* Must be set to visit structs */
  51     bool (*start_struct)(Visitor *v, const char *name, void **obj,
  52                          size_t size, Error **errp);
  53
  54     /* Optional; intended for input visitors */
  55     bool (*check_struct)(Visitor *v, Error **errp);
  56
  57     /* Must be set to visit structs */
  58     void (*end_struct)(Visitor *v, void **obj);
  59
  60     /* Must be set; implementations may require @list to be non-null,
  61      * but must document it. */
  62     bool (*start_list)(Visitor *v, const char *name, GenericList **list,
  63                        size_t size, Error **errp);
  64
  65     /* Must be set */
  66     GenericList *(*next_list)(Visitor *v, GenericList *tail, size_t size);
  67
  68     /* Optional; intended for input visitors */
  69     bool (*check_list)(Visitor *v, Error **errp);
  70
  71     /* Must be set */
  72     void (*end_list)(Visitor *v, void **list);
  73
  74     /* Must be set by input and clone visitors to visit alternates */
  75     bool (*start_alternate)(Visitor *v, const char *name,
  76                             GenericAlternate **obj, size_t size,
  77                             Error **errp);
  78
  79     /* Optional */
  80     void (*end_alternate)(Visitor *v, void **obj);
  81
  82     /* Must be set */
  83     bool (*type_int64)(Visitor *v, const char *name, int64_t *obj,
  84                        Error **errp);
  85
  86     /* Must be set */
  87     bool (*type_uint64)(Visitor *v, const char *name, uint64_t *obj,
  88                         Error **errp);
  89
  90     /* Optional; fallback is type_uint64() */
  91     bool (*type_size)(Visitor *v, const char *name, uint64_t *obj,
  92                       Error **errp);
  93
  94     /* Must be set */
  95     bool (*type_bool)(Visitor *v, const char *name, bool *obj, Error **errp);
  96
  97     /* Must be set */
  98     bool (*type_str)(Visitor *v, const char *name, char **obj, Error **errp);
  99
 100     /* Must be set to visit numbers */
 101     bool (*type_number)(Visitor *v, const char *name, double *obj,
 102                         Error **errp);
 103
 104     /* Must be set to visit arbitrary QTypes */
 105     bool (*type_any)(Visitor *v, const char *name, QObject **obj,
 106                      Error **errp);
 107
 108     /* Must be set to visit explicit null values.  */
 109     bool (*type_null)(Visitor *v, const char *name, QNull **obj,
 110                       Error **errp);
 111
 112     /* Must be set for input visitors to visit structs, optional otherwise.
 113        The core takes care of the return type in the public interface. */
 114     void (*optional)(Visitor *v, const char *name, bool *present);
 115
 116     /* Optional */
 117     bool (*policy_reject)(Visitor *v, const char *name,
 118                           unsigned special_features, Error **errp);
 119
 120     /* Optional */
 121     bool (*policy_skip)(Visitor *v, const char *name,
 122                         unsigned special_features);
 123
 124     /* Must be set */
 125     VisitorType type;
 126
 127     /* Optional */
 128     struct CompatPolicy compat_policy;
 129
 130     /* Must be set for output visitors, optional otherwise. */
 131     void (*complete)(Visitor *v, void *opaque);
 132
 133     /* Must be set */
 134     void (*free)(Visitor *v);
 135 };
 136
 137 #endif