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 /* Optional */ 117 bool (*policy_reject)(Visitor *v, const char *name, 118 unsigned special_features, Error **errp); 119 120 /* Optional */ 121 bool (*policy_skip)(Visitor *v, const char *name, 122 unsigned special_features); 123 124 /* Must be set */ 125 VisitorType type; 126 127 /* Optional */ 128 struct CompatPolicy compat_policy; 129 130 /* Must be set for output visitors, optional otherwise. */ 131 void (*complete)(Visitor *v, void *opaque); 132 133 /* Must be set */ 134 void (*free)(Visitor *v); 135 }; 136 137 #endif 138