LXR qemu/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 */
  37typedef enum VisitorType {
  38    VISITOR_INPUT = 1,
  39    VISITOR_OUTPUT = 2,
  40    VISITOR_CLONE = 3,
  41    VISITOR_DEALLOC = 4,
  42} VisitorType;
  43
  44struct Visitor
  45{
  46    /* Must be set to visit structs */
  47    void (*start_struct)(Visitor *v, const char *name, void **obj,
  48                         size_t size, Error **errp);
  49
  50    /* Optional; intended for input visitors */
  51    void (*check_struct)(Visitor *v, Error **errp);
  52
  53    /* Must be set to visit structs */
  54    void (*end_struct)(Visitor *v, void **obj);
  55
  56    /* Must be set; implementations may require @list to be non-null,
  57     * but must document it. */
  58    void (*start_list)(Visitor *v, const char *name, GenericList **list,
  59                       size_t size, Error **errp);
  60
  61    /* Must be set */
  62    GenericList *(*next_list)(Visitor *v, GenericList *tail, size_t size);
  63
  64    /* Optional; intended for input visitors */
  65    void (*check_list)(Visitor *v, Error **errp);
  66
  67    /* Must be set */
  68    void (*end_list)(Visitor *v, void **list);
  69
  70    /* Must be set by input and dealloc visitors to visit alternates;
  71     * optional for output visitors. */
  72    void (*start_alternate)(Visitor *v, const char *name,
  73                            GenericAlternate **obj, size_t size,
  74                            Error **errp);
  75
  76    /* Optional, needed for dealloc visitor */
  77    void (*end_alternate)(Visitor *v, void **obj);
  78
  79    /* Must be set */
  80    void (*type_int64)(Visitor *v, const char *name, int64_t *obj,
  81                       Error **errp);
  82
  83    /* Must be set */
  84    void (*type_uint64)(Visitor *v, const char *name, uint64_t *obj,
  85                        Error **errp);
  86
  87    /* Optional; fallback is type_uint64() */
  88    void (*type_size)(Visitor *v, const char *name, uint64_t *obj,
  89                      Error **errp);
  90
  91    /* Must be set */
  92    void (*type_bool)(Visitor *v, const char *name, bool *obj, Error **errp);
  93
  94    /* Must be set */
  95    void (*type_str)(Visitor *v, const char *name, char **obj, Error **errp);
  96
  97    /* Must be set to visit numbers */
  98    void (*type_number)(Visitor *v, const char *name, double *obj,
  99                        Error **errp);
 100
 101    /* Must be set to visit arbitrary QTypes */
 102    void (*type_any)(Visitor *v, const char *name, QObject **obj,
 103                     Error **errp);
 104
 105    /* Must be set to visit explicit null values.  */
 106    void (*type_null)(Visitor *v, const char *name, QNull **obj,
 107                      Error **errp);
 108
 109    /* Must be set for input visitors to visit structs, optional otherwise.
 110       The core takes care of the return type in the public interface. */
 111    void (*optional)(Visitor *v, const char *name, bool *present);
 112
 113    /* Must be set */
 114    VisitorType type;
 115
 116    /* Must be set for output visitors, optional otherwise. */
 117    void (*complete)(Visitor *v, void *opaque);
 118
 119    /* Must be set */
 120    void (*free)(Visitor *v);
 121};
 122
 123#endif
 124