Merge remote-tracking branch 'remotes/vivier2/tags/trivial-branch-for-5.2-pull-reques...
[qemu.git] / 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 /* Must be set */
117 VisitorType type;
118
119 /* Must be set for output visitors, optional otherwise. */
120 void (*complete)(Visitor *v, void *opaque);
121
122 /* Must be set */
123 void (*free)(Visitor *v);
124 };
125
126 #endif