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