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 /* Must be set */ 65 void (*end_list)(Visitor *v, void **list); 66 67 /* Must be set by input and dealloc visitors to visit alternates; 68 * optional for output visitors. */ 69 void (*start_alternate)(Visitor *v, const char *name, 70 GenericAlternate **obj, size_t size, 71 bool promote_int, Error **errp); 72 73 /* Optional, needed for dealloc visitor */ 74 void (*end_alternate)(Visitor *v, void **obj); 75 76 /* Must be set */ 77 void (*type_int64)(Visitor *v, const char *name, int64_t *obj, 78 Error **errp); 79 80 /* Must be set */ 81 void (*type_uint64)(Visitor *v, const char *name, uint64_t *obj, 82 Error **errp); 83 84 /* Optional; fallback is type_uint64() */ 85 void (*type_size)(Visitor *v, const char *name, uint64_t *obj, 86 Error **errp); 87 88 /* Must be set */ 89 void (*type_bool)(Visitor *v, const char *name, bool *obj, Error **errp); 90 91 /* Must be set */ 92 void (*type_str)(Visitor *v, const char *name, char **obj, Error **errp); 93 94 /* Must be set to visit numbers */ 95 void (*type_number)(Visitor *v, const char *name, double *obj, 96 Error **errp); 97 98 /* Must be set to visit arbitrary QTypes */ 99 void (*type_any)(Visitor *v, const char *name, QObject **obj, 100 Error **errp); 101 102 /* Must be set to visit explicit null values. */ 103 void (*type_null)(Visitor *v, const char *name, Error **errp); 104 105 /* Must be set for input visitors, optional otherwise. The core 106 * takes care of the return type in the public interface. */ 107 void (*optional)(Visitor *v, const char *name, bool *present); 108 109 /* Must be set */ 110 VisitorType type; 111 112 /* Must be set for output visitors, optional otherwise. */ 113 void (*complete)(Visitor *v, void *opaque); 114 115 /* Must be set */ 116 void (*free)(Visitor *v); 117 }; 118 119 #endif 120