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 void user_creatable_add_qapi(ObjectOptions *options, Error **errp); 99 100 /** 101 * user_creatable_parse_str: 102 * @str: the object definition string as passed on the command line 103 * @errp: if an error occurs, a pointer to an area to store the error 104 * 105 * Parses the option for the user creatable object with a keyval parser and 106 * implicit key 'qom-type', converting the result to ObjectOptions. 107 * 108 * If a help option is given, print help instead. 109 * 110 * Returns: ObjectOptions on success, NULL when an error occurred (*errp is set 111 * then) or help was printed (*errp is not set). 112 */ 113 ObjectOptions *user_creatable_parse_str(const char *str, Error **errp); 114 115 /** 116 * user_creatable_add_from_str: 117 * @str: the object definition string as passed on the command line 118 * @errp: if an error occurs, a pointer to an area to store the error 119 * 120 * Create an instance of the user creatable object by parsing @str 121 * with a keyval parser and implicit key 'qom-type', converting the 122 * result to ObjectOptions and calling into qmp_object_add(). 123 * 124 * If a help option is given, print help instead. 125 * 126 * Returns: true when an object was successfully created, false when an error 127 * occurred (*errp is set then) or help was printed (*errp is not set). 128 */ 129 bool user_creatable_add_from_str(const char *str, Error **errp); 130 131 /** 132 * user_creatable_process_cmdline: 133 * @cmdline: the object definition string as passed on the command line 134 * 135 * Create an instance of the user creatable object by parsing @cmdline 136 * with a keyval parser and implicit key 'qom-type', converting the 137 * result to ObjectOptions and calling into qmp_object_add(). 138 * 139 * If a help option is given, print help instead and exit. 140 * 141 * This function is only meant to be called during command line parsing. 142 * It exits the process on failure or after printing help. 143 */ 144 void user_creatable_process_cmdline(const char *cmdline); 145 146 /** 147 * user_creatable_print_help: 148 * @type: the QOM type to be added 149 * @opts: options to create 150 * 151 * Prints help if requested in @type or @opts. Note that if @type is neither 152 * "help"/"?" nor a valid user creatable type, no help will be printed 153 * regardless of @opts. 154 * 155 * Returns: true if a help option was found and help was printed, false 156 * otherwise. 157 */ 158 bool user_creatable_print_help(const char *type, QemuOpts *opts); 159 160 /** 161 * user_creatable_del: 162 * @id: the unique ID for the object 163 * @errp: if an error occurs, a pointer to an area to store the error 164 * 165 * Delete an instance of the user creatable object identified 166 * by @id. 167 * 168 * Returns: %true on success, %false on failure. 169 */ 170 bool user_creatable_del(const char *id, Error **errp); 171 172 /** 173 * user_creatable_cleanup: 174 * 175 * Delete all user-creatable objects and the user-creatable 176 * objects container. 177 */ 178 void user_creatable_cleanup(void); 179 180 #endif 181