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 three classes of visitors; setting the class determines
  31  * how QAPI enums are visited, as well as what additional restrictions
  32  * can be asserted.
  33  */
  34 typedef enum VisitorType {
  35     VISITOR_INPUT,
  36     VISITOR_OUTPUT,
  37     VISITOR_DEALLOC,
  38 } VisitorType;
  39
  40 struct Visitor
  41 {
  42     /* Must be set to visit structs */
  43     void (*start_struct)(Visitor *v, const char *name, void **obj,
  44                          size_t size, Error **errp);
  45
  46     /* Optional; intended for input visitors */
  47     void (*check_struct)(Visitor *v, Error **errp);
  48
  49     /* Must be set to visit structs */
  50     void (*end_struct)(Visitor *v);
  51
  52     /* Must be set; implementations may require @list to be non-null,
  53      * but must document it. */
  54     void (*start_list)(Visitor *v, const char *name, GenericList **list,
  55                        size_t size, Error **errp);
  56
  57     /* Must be set */
  58     GenericList *(*next_list)(Visitor *v, GenericList *tail, size_t size);
  59
  60     /* Must be set */
  61     void (*end_list)(Visitor *v);
  62
  63     /* Must be set by input and dealloc visitors to visit alternates;
  64      * optional for output visitors. */
  65     void (*start_alternate)(Visitor *v, const char *name,
  66                             GenericAlternate **obj, size_t size,
  67                             bool promote_int, Error **errp);
  68
  69     /* Optional, needed for dealloc visitor */
  70     void (*end_alternate)(Visitor *v);
  71
  72     /* Must be set */
  73     void (*type_int64)(Visitor *v, const char *name, int64_t *obj,
  74                        Error **errp);
  75
  76     /* Must be set */
  77     void (*type_uint64)(Visitor *v, const char *name, uint64_t *obj,
  78                         Error **errp);
  79
  80     /* Optional; fallback is type_uint64() */
  81     void (*type_size)(Visitor *v, const char *name, uint64_t *obj,
  82                       Error **errp);
  83
  84     /* Must be set */
  85     void (*type_bool)(Visitor *v, const char *name, bool *obj, Error **errp);
  86
  87     /* Must be set */
  88     void (*type_str)(Visitor *v, const char *name, char **obj, Error **errp);
  89
  90     /* Must be set to visit numbers */
  91     void (*type_number)(Visitor *v, const char *name, double *obj,
  92                         Error **errp);
  93
  94     /* Must be set to visit arbitrary QTypes */
  95     void (*type_any)(Visitor *v, const char *name, QObject **obj,
  96                      Error **errp);
  97
  98     /* Must be set to visit explicit null values.  */
  99     void (*type_null)(Visitor *v, const char *name, Error **errp);
 100
 101     /* Must be set for input visitors, optional otherwise.  The core
 102      * takes care of the return type in the public interface. */
 103     void (*optional)(Visitor *v, const char *name, bool *present);
 104
 105     /* Must be set */
 106     VisitorType type;
 107 };
 108
 109 #endif