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