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 | /* 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 | |