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 * Returns: %true on success, %false on failure. 62 */ 63 bool user_creatable_complete(UserCreatable *uc, Error **errp); 64 65 /** 66 * user_creatable_can_be_deleted: 67 * @uc: the object whose can_be_deleted() method is called if implemented 68 * 69 * Wrapper to call can_be_deleted() method if one of types it's inherited 70 * from implements USER_CREATABLE interface. 71 */ 72 bool user_creatable_can_be_deleted(UserCreatable *uc); 73 74 /** 75 * user_creatable_add_type: 76 * @type: the object type name 77 * @id: the unique ID for the object 78 * @qdict: the object properties 79 * @v: the visitor 80 * @errp: if an error occurs, a pointer to an area to store the error 81 * 82 * Create an instance of the user creatable object @type, placing 83 * it in the object composition tree with name @id, initializing 84 * it with properties from @qdict 85 * 86 * Returns: the newly created object or NULL on error 87 */ 88 Object *user_creatable_add_type(const char *type, const char *id, 89 const QDict *qdict, 90 Visitor *v, Error **errp); 91 92 /** 93 * user_creatable_add_dict: 94 * @qdict: the object definition 95 * @keyval: if true, use a keyval visitor for processing @qdict (i.e. 96 * assume that all @qdict values are strings); otherwise, use 97 * the normal QObject visitor (i.e. assume all @qdict values 98 * have the QType expected by the QOM object type) 99 * @errp: if an error occurs, a pointer to an area to store the error 100 * 101 * Create an instance of the user creatable object that is defined by 102 * @qdict. The object type is taken from the QDict key 'qom-type', its 103 * ID from the key 'id'. The remaining entries in @qdict are used to 104 * initialize the object properties. 105 * 106 * Returns: %true on success, %false on failure. 107 */ 108 bool user_creatable_add_dict(QDict *qdict, bool keyval, Error **errp); 109 110 /** 111 * user_creatable_add_opts: 112 * @opts: the object definition 113 * @errp: if an error occurs, a pointer to an area to store the error 114 * 115 * Create an instance of the user creatable object whose type 116 * is defined in @opts by the 'qom-type' option, placing it 117 * in the object composition tree with name provided by the 118 * 'id' field. The remaining options in @opts are used to 119 * initialize the object properties. 120 * 121 * Returns: the newly created object or NULL on error 122 */ 123 Object *user_creatable_add_opts(QemuOpts *opts, Error **errp); 124 125 126 /** 127 * user_creatable_add_opts_predicate: 128 * @type: the QOM type to be added 129 * 130 * A callback function to determine whether an object 131 * of type @type should be created. Instances of this 132 * callback should be passed to user_creatable_add_opts_foreach 133 */ 134 typedef bool (*user_creatable_add_opts_predicate)(const char *type); 135 136 /** 137 * user_creatable_add_opts_foreach: 138 * @opaque: a user_creatable_add_opts_predicate callback or NULL 139 * @opts: options to create 140 * @errp: unused 141 * 142 * An iterator callback to be used in conjunction with 143 * the qemu_opts_foreach() method for creating a list of 144 * objects from a set of QemuOpts 145 * 146 * The @opaque parameter can be passed a user_creatable_add_opts_predicate 147 * callback to filter which types of object are created during iteration. 148 * When it fails, report the error. 149 * 150 * Returns: 0 on success, -1 when an error was reported. 151 */ 152 int user_creatable_add_opts_foreach(void *opaque, 153 QemuOpts *opts, Error **errp); 154 155 /** 156 * user_creatable_print_help: 157 * @type: the QOM type to be added 158 * @opts: options to create 159 * 160 * Prints help if requested in @opts. 161 * 162 * Returns: true if @opts contained a help option and help was printed, false 163 * if no help option was found. 164 */ 165 bool user_creatable_print_help(const char *type, QemuOpts *opts); 166 167 /** 168 * user_creatable_del: 169 * @id: the unique ID for the object 170 * @errp: if an error occurs, a pointer to an area to store the error 171 * 172 * Delete an instance of the user creatable object identified 173 * by @id. 174 * 175 * Returns: %true on success, %false on failure. 176 */ 177 bool user_creatable_del(const char *id, Error **errp); 178 179 /** 180 * user_creatable_cleanup: 181 * 182 * Delete all user-creatable objects and the user-creatable 183 * objects container. 184 */ 185 void user_creatable_cleanup(void); 186 187 /** 188 * qmp_object_add: 189 * 190 * QMP command handler for object-add. See the QAPI schema for documentation. 191 */ 192 void qmp_object_add(QDict *qdict, QObject **ret_data, Error **errp); 193 194 #endif 195