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 bool promote_int, 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, Error **errp); 107 108 /* Must be set for input visitors to visit structs, optional otherwise. 109 The core takes care of the return type in the public interface. */ 110 void (*optional)(Visitor *v, const char *name, bool *present); 111 112 /* Must be set */ 113 VisitorType type; 114 115 /* Must be set for output visitors, optional otherwise. */ 116 void (*complete)(Visitor *v, void *opaque); 117 118 /* Must be set */ 119 void (*free)(Visitor *v); 120 }; 121 122 #endif 123