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