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 three classes of visitors; setting the class determines 31 * how QAPI enums are visited, as well as what additional restrictions 32 * can be asserted. 33 */ 34 typedef enum VisitorType { 35 VISITOR_INPUT, 36 VISITOR_OUTPUT, 37 VISITOR_DEALLOC, 38 } VisitorType; 39 40 struct Visitor 41 { 42 /* Must be set to visit structs */ 43 void (*start_struct)(Visitor *v, const char *name, void **obj, 44 size_t size, Error **errp); 45 46 /* Optional; intended for input visitors */ 47 void (*check_struct)(Visitor *v, Error **errp); 48 49 /* Must be set to visit structs */ 50 void (*end_struct)(Visitor *v); 51 52 /* Must be set; implementations may require @list to be non-null, 53 * but must document it. */ 54 void (*start_list)(Visitor *v, const char *name, GenericList **list, 55 size_t size, Error **errp); 56 57 /* Must be set */ 58 GenericList *(*next_list)(Visitor *v, GenericList *tail, size_t size); 59 60 /* Must be set */ 61 void (*end_list)(Visitor *v); 62 63 /* Must be set by input and dealloc visitors to visit alternates; 64 * optional for output visitors. */ 65 void (*start_alternate)(Visitor *v, const char *name, 66 GenericAlternate **obj, size_t size, 67 bool promote_int, Error **errp); 68 69 /* Optional, needed for dealloc visitor */ 70 void (*end_alternate)(Visitor *v); 71 72 /* Must be set */ 73 void (*type_int64)(Visitor *v, const char *name, int64_t *obj, 74 Error **errp); 75 76 /* Must be set */ 77 void (*type_uint64)(Visitor *v, const char *name, uint64_t *obj, 78 Error **errp); 79 80 /* Optional; fallback is type_uint64() */ 81 void (*type_size)(Visitor *v, const char *name, uint64_t *obj, 82 Error **errp); 83 84 /* Must be set */ 85 void (*type_bool)(Visitor *v, const char *name, bool *obj, Error **errp); 86 87 /* Must be set */ 88 void (*type_str)(Visitor *v, const char *name, char **obj, Error **errp); 89 90 /* Must be set to visit numbers */ 91 void (*type_number)(Visitor *v, const char *name, double *obj, 92 Error **errp); 93 94 /* Must be set to visit arbitrary QTypes */ 95 void (*type_any)(Visitor *v, const char *name, QObject **obj, 96 Error **errp); 97 98 /* Must be set to visit explicit null values. */ 99 void (*type_null)(Visitor *v, const char *name, Error **errp); 100 101 /* Must be set for input visitors, optional otherwise. The core 102 * takes care of the return type in the public interface. */ 103 void (*optional)(Visitor *v, const char *name, bool *present); 104 105 /* Must be set */ 106 VisitorType type; 107 }; 108 109 #endif 110