1 #ifndef OBJECT_INTERFACES_H 2 #define OBJECT_INTERFACES_H 3 4 #include "qom/object.h" 5 #include "qapi/qapi-types-qom.h" 6 #include "qapi/visitor.h" 7 8 #define TYPE_USER_CREATABLE "user-creatable" 9 10 typedef struct UserCreatableClass UserCreatableClass; 11 DECLARE_CLASS_CHECKERS(UserCreatableClass, USER_CREATABLE, 12 TYPE_USER_CREATABLE) 13 #define USER_CREATABLE(obj) \ 14 INTERFACE_CHECK(UserCreatable, (obj), \ 15 TYPE_USER_CREATABLE) 16 17 typedef struct UserCreatable UserCreatable; 18 19 /** 20 * UserCreatableClass: 21 * @parent_class: the base class 22 * @complete: callback to be called after @obj's properties are set. 23 * @can_be_deleted: callback to be called before an object is removed 24 * to check if @obj can be removed safely. 25 * 26 * Interface is designed to work with -object/object-add/object_add 27 * commands. 28 * Interface is mandatory for objects that are designed to be user 29 * creatable (i.e. -object/object-add/object_add, will accept only 30 * objects that inherit this interface). 31 * 32 * Interface also provides an optional ability to do the second 33 * stage * initialization of the object after its properties were 34 * set. 35 * 36 * For objects created without using -object/object-add/object_add, 37 * @user_creatable_complete() wrapper should be called manually if 38 * object's type implements USER_CREATABLE interface and needs 39 * complete() callback to be called. 40 */ 41 struct UserCreatableClass { 42 /* <private> */ 43 InterfaceClass parent_class; 44 45 /* <public> */ 46 void (*complete)(UserCreatable *uc, Error **errp); 47 bool (*can_be_deleted)(UserCreatable *uc); 48 }; 49 50 /** 51 * user_creatable_complete: 52 * @uc: the user-creatable object whose complete() method is called if defined 53 * @errp: if an error occurs, a pointer to an area to store the error 54 * 55 * Wrapper to call complete() method if one of types it's inherited 56 * from implements USER_CREATABLE interface, otherwise the call does 57 * nothing. 58 * 59 * Returns: %true on success, %false on failure. 60 */ 61 bool 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_qapi: 92 * @options: the object definition 93 * @errp: if an error occurs, a pointer to an area to store the error 94 * 95 * Create an instance of the user creatable object according to the 96 * options passed in @opts as described in the QAPI schema documentation. 97 * 98 * Returns: the newly created object or NULL on error 99 */ 100 void user_creatable_add_qapi(ObjectOptions *options, Error **errp); 101 102 /** 103 * user_creatable_add_opts: 104 * @opts: the object definition 105 * @errp: if an error occurs, a pointer to an area to store the error 106 * 107 * Create an instance of the user creatable object whose type 108 * is defined in @opts by the 'qom-type' option, placing it 109 * in the object composition tree with name provided by the 110 * 'id' field. The remaining options in @opts are used to 111 * initialize the object properties. 112 * 113 * Returns: the newly created object or NULL on error 114 */ 115 Object *user_creatable_add_opts(QemuOpts *opts, Error **errp); 116 117 118 /** 119 * user_creatable_add_opts_predicate: 120 * @type: the QOM type to be added 121 * 122 * A callback function to determine whether an object 123 * of type @type should be created. Instances of this 124 * callback should be passed to user_creatable_add_opts_foreach 125 */ 126 typedef bool (*user_creatable_add_opts_predicate)(const char *type); 127 128 /** 129 * user_creatable_add_opts_foreach: 130 * @opaque: a user_creatable_add_opts_predicate callback or NULL 131 * @opts: options to create 132 * @errp: unused 133 * 134 * An iterator callback to be used in conjunction with 135 * the qemu_opts_foreach() method for creating a list of 136 * objects from a set of QemuOpts 137 * 138 * The @opaque parameter can be passed a user_creatable_add_opts_predicate 139 * callback to filter which types of object are created during iteration. 140 * When it fails, report the error. 141 * 142 * Returns: 0 on success, -1 when an error was reported. 143 */ 144 int user_creatable_add_opts_foreach(void *opaque, 145 QemuOpts *opts, Error **errp); 146 147 /** 148 * user_creatable_parse_str: 149 * @optarg: the object definition string as passed on the command line 150 * @errp: if an error occurs, a pointer to an area to store the error 151 * 152 * Parses the option for the user creatable object with a keyval parser and 153 * implicit key 'qom-type', converting the result to ObjectOptions. 154 * 155 * If a help option is given, print help instead. 156 * 157 * Returns: ObjectOptions on success, NULL when an error occurred (*errp is set 158 * then) or help was printed (*errp is not set). 159 */ 160 ObjectOptions *user_creatable_parse_str(const char *optarg, Error **errp); 161 162 /** 163 * user_creatable_add_from_str: 164 * @optarg: the object definition string as passed on the command line 165 * @errp: if an error occurs, a pointer to an area to store the error 166 * 167 * Create an instance of the user creatable object by parsing optarg 168 * with a keyval parser and implicit key 'qom-type', converting the 169 * result to ObjectOptions and calling into qmp_object_add(). 170 * 171 * If a help option is given, print help instead. 172 * 173 * Returns: true when an object was successfully created, false when an error 174 * occurred (*errp is set then) or help was printed (*errp is not set). 175 */ 176 bool user_creatable_add_from_str(const char *optarg, Error **errp); 177 178 /** 179 * user_creatable_process_cmdline: 180 * @optarg: the object definition string as passed on the command line 181 * 182 * Create an instance of the user creatable object by parsing optarg 183 * with a keyval parser and implicit key 'qom-type', converting the 184 * result to ObjectOptions and calling into qmp_object_add(). 185 * 186 * If a help option is given, print help instead and exit. 187 * 188 * This function is only meant to be called during command line parsing. 189 * It exits the process on failure or after printing help. 190 */ 191 void user_creatable_process_cmdline(const char *optarg); 192 193 /** 194 * user_creatable_print_help: 195 * @type: the QOM type to be added 196 * @opts: options to create 197 * 198 * Prints help if requested in @type or @opts. Note that if @type is neither 199 * "help"/"?" nor a valid user creatable type, no help will be printed 200 * regardless of @opts. 201 * 202 * Returns: true if a help option was found and help was printed, false 203 * otherwise. 204 */ 205 bool user_creatable_print_help(const char *type, QemuOpts *opts); 206 207 /** 208 * user_creatable_del: 209 * @id: the unique ID for the object 210 * @errp: if an error occurs, a pointer to an area to store the error 211 * 212 * Delete an instance of the user creatable object identified 213 * by @id. 214 * 215 * Returns: %true on success, %false on failure. 216 */ 217 bool user_creatable_del(const char *id, Error **errp); 218 219 /** 220 * user_creatable_cleanup: 221 * 222 * Delete all user-creatable objects and the user-creatable 223 * objects container. 224 */ 225 void user_creatable_cleanup(void); 226 227 #endif 228