1 #ifndef OBJECT_INTERFACES_H 2 #define OBJECT_INTERFACES_H 3 4 #include "qom/object.h" 5 #include "qapi/visitor.h" 6 7 #define TYPE_USER_CREATABLE "user-creatable" 8 9 #define USER_CREATABLE_CLASS(klass) \ 10 OBJECT_CLASS_CHECK(UserCreatableClass, (klass), \ 11 TYPE_USER_CREATABLE) 12 #define USER_CREATABLE_GET_CLASS(obj) \ 13 OBJECT_GET_CLASS(UserCreatableClass, (obj), \ 14 TYPE_USER_CREATABLE) 15 #define USER_CREATABLE(obj) \ 16 INTERFACE_CHECK(UserCreatable, (obj), \ 17 TYPE_USER_CREATABLE) 18 19 typedef struct UserCreatable UserCreatable; 20 21 /** 22 * UserCreatableClass: 23 * @parent_class: the base class 24 * @complete: callback to be called after @obj's properties are set. 25 * @can_be_deleted: callback to be called before an object is removed 26 * to check if @obj can be removed safely. 27 * 28 * Interface is designed to work with -object/object-add/object_add 29 * commands. 30 * Interface is mandatory for objects that are designed to be user 31 * creatable (i.e. -object/object-add/object_add, will accept only 32 * objects that inherit this interface). 33 * 34 * Interface also provides an optional ability to do the second 35 * stage * initialization of the object after its properties were 36 * set. 37 * 38 * For objects created without using -object/object-add/object_add, 39 * @user_creatable_complete() wrapper should be called manually if 40 * object's type implements USER_CREATABLE interface and needs 41 * complete() callback to be called. 42 */ 43 typedef struct UserCreatableClass { 44 /* <private> */ 45 InterfaceClass parent_class; 46 47 /* <public> */ 48 void (*complete)(UserCreatable *uc, Error **errp); 49 bool (*can_be_deleted)(UserCreatable *uc); 50 } UserCreatableClass; 51 52 /** 53 * user_creatable_complete: 54 * @uc: the user-creatable object whose complete() method is called if defined 55 * @errp: if an error occurs, a pointer to an area to store the error 56 * 57 * Wrapper to call complete() method if one of types it's inherited 58 * from implements USER_CREATABLE interface, otherwise the call does 59 * nothing. 60 */ 61 void user_creatable_complete(UserCreatable *uc, Error **errp); 62 63 /** 64 * user_creatable_can_be_deleted: 65 * @uc: the object whose can_be_deleted() method is called if implemented 66 * 67 * Wrapper to call can_be_deleted() method if one of types it's inherited 68 * from implements USER_CREATABLE interface. 69 */ 70 bool user_creatable_can_be_deleted(UserCreatable *uc); 71 72 /** 73 * user_creatable_add_type: 74 * @type: the object type name 75 * @id: the unique ID for the object 76 * @qdict: the object properties 77 * @v: the visitor 78 * @errp: if an error occurs, a pointer to an area to store the error 79 * 80 * Create an instance of the user creatable object @type, placing 81 * it in the object composition tree with name @id, initializing 82 * it with properties from @qdict 83 * 84 * Returns: the newly created object or NULL on error 85 */ 86 Object *user_creatable_add_type(const char *type, const char *id, 87 const QDict *qdict, 88 Visitor *v, Error **errp); 89 90 /** 91 * user_creatable_add_dict: 92 * @qdict: the object definition 93 * @keyval: if true, use a keyval visitor for processing @qdict (i.e. 94 * assume that all @qdict values are strings); otherwise, use 95 * the normal QObject visitor (i.e. assume all @qdict values 96 * have the QType expected by the QOM object type) 97 * @errp: if an error occurs, a pointer to an area to store the error 98 * 99 * Create an instance of the user creatable object that is defined by 100 * @qdict. The object type is taken from the QDict key 'qom-type', its 101 * ID from the key 'id'. The remaining entries in @qdict are used to 102 * initialize the object properties. 103 */ 104 void user_creatable_add_dict(QDict *qdict, bool keyval, Error **errp); 105 106 /** 107 * user_creatable_add_opts: 108 * @opts: the object definition 109 * @errp: if an error occurs, a pointer to an area to store the error 110 * 111 * Create an instance of the user creatable object whose type 112 * is defined in @opts by the 'qom-type' option, placing it 113 * in the object composition tree with name provided by the 114 * 'id' field. The remaining options in @opts are used to 115 * initialize the object properties. 116 * 117 * Returns: the newly created object or NULL on error 118 */ 119 Object *user_creatable_add_opts(QemuOpts *opts, Error **errp); 120 121 122 /** 123 * user_creatable_add_opts_predicate: 124 * @type: the QOM type to be added 125 * 126 * A callback function to determine whether an object 127 * of type @type should be created. Instances of this 128 * callback should be passed to user_creatable_add_opts_foreach 129 */ 130 typedef bool (*user_creatable_add_opts_predicate)(const char *type); 131 132 /** 133 * user_creatable_add_opts_foreach: 134 * @opaque: a user_creatable_add_opts_predicate callback or NULL 135 * @opts: options to create 136 * @errp: unused 137 * 138 * An iterator callback to be used in conjunction with 139 * the qemu_opts_foreach() method for creating a list of 140 * objects from a set of QemuOpts 141 * 142 * The @opaque parameter can be passed a user_creatable_add_opts_predicate 143 * callback to filter which types of object are created during iteration. 144 * When it fails, report the error. 145 * 146 * Returns: 0 on success, -1 when an error was reported. 147 */ 148 int user_creatable_add_opts_foreach(void *opaque, 149 QemuOpts *opts, Error **errp); 150 151 /** 152 * user_creatable_print_help: 153 * @type: the QOM type to be added 154 * @opts: options to create 155 * 156 * Prints help if requested in @opts. 157 * 158 * Returns: true if @opts contained a help option and help was printed, false 159 * if no help option was found. 160 */ 161 bool user_creatable_print_help(const char *type, QemuOpts *opts); 162 163 /** 164 * user_creatable_del: 165 * @id: the unique ID for the object 166 * @errp: if an error occurs, a pointer to an area to store the error 167 * 168 * Delete an instance of the user creatable object identified 169 * by @id. 170 */ 171 void user_creatable_del(const char *id, Error **errp); 172 173 /** 174 * user_creatable_cleanup: 175 * 176 * Delete all user-creatable objects and the user-creatable 177 * objects container. 178 */ 179 void user_creatable_cleanup(void); 180 181 /** 182 * qmp_object_add: 183 * 184 * QMP command handler for object-add. See the QAPI schema for documentation. 185 */ 186 void qmp_object_add(QDict *qdict, QObject **ret_data, Error **errp); 187 188 #endif 189