1 #ifndef OBJECT_INTERFACES_H 2 #define OBJECT_INTERFACES_H 3 4 #include "qom/object.h" 5 #include "qapi/qmp/qdict.h" 6 #include "qapi/visitor.h" 7 8 #define TYPE_USER_CREATABLE "user-creatable" 9 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 21 typedef struct UserCreatable { 22 /* <private> */ 23 Object Parent; 24 } UserCreatable; 25 26 /** 27 * UserCreatableClass: 28 * @parent_class: the base class 29 * @complete: callback to be called after @obj's properties are set. 30 * @can_be_deleted: callback to be called before an object is removed 31 * to check if @obj can be removed safely. 32 * 33 * Interface is designed to work with -object/object-add/object_add 34 * commands. 35 * Interface is mandatory for objects that are designed to be user 36 * creatable (i.e. -object/object-add/object_add, will accept only 37 * objects that inherit this interface). 38 * 39 * Interface also provides an optional ability to do the second 40 * stage * initialization of the object after its properties were 41 * set. 42 * 43 * For objects created without using -object/object-add/object_add, 44 * @user_creatable_complete() wrapper should be called manually if 45 * object's type implements USER_CREATABLE interface and needs 46 * complete() callback to be called. 47 */ 48 typedef struct UserCreatableClass { 49 /* <private> */ 50 InterfaceClass parent_class; 51 52 /* <public> */ 53 void (*complete)(UserCreatable *uc, Error **errp); 54 bool (*can_be_deleted)(UserCreatable *uc); 55 } UserCreatableClass; 56 57 /** 58 * user_creatable_complete: 59 * @obj: the object whose complete() method is called if defined 60 * @errp: if an error occurs, a pointer to an area to store the error 61 * 62 * Wrapper to call complete() method if one of types it's inherited 63 * from implements USER_CREATABLE interface, otherwise the call does 64 * nothing. 65 */ 66 void user_creatable_complete(Object *obj, Error **errp); 67 68 /** 69 * user_creatable_can_be_deleted: 70 * @uc: the object whose can_be_deleted() method is called if implemented 71 * 72 * Wrapper to call can_be_deleted() method if one of types it's inherited 73 * from implements USER_CREATABLE interface. 74 */ 75 bool user_creatable_can_be_deleted(UserCreatable *uc); 76 77 /** 78 * user_creatable_add_type: 79 * @type: the object type name 80 * @id: the unique ID for the object 81 * @qdict: the object properties 82 * @v: the visitor 83 * @errp: if an error occurs, a pointer to an area to store the error 84 * 85 * Create an instance of the user creatable object @type, placing 86 * it in the object composition tree with name @id, initializing 87 * it with properties from @qdict 88 * 89 * Returns: the newly created object or NULL on error 90 */ 91 Object *user_creatable_add_type(const char *type, const char *id, 92 const QDict *qdict, 93 Visitor *v, Error **errp); 94 95 /** 96 * user_creatable_add_opts: 97 * @opts: the object definition 98 * @errp: if an error occurs, a pointer to an area to store the error 99 * 100 * Create an instance of the user creatable object whose type 101 * is defined in @opts by the 'qom-type' option, placing it 102 * in the object composition tree with name provided by the 103 * 'id' field. The remaining options in @opts are used to 104 * initialize the object properties. 105 * 106 * Returns: the newly created object or NULL on error 107 */ 108 Object *user_creatable_add_opts(QemuOpts *opts, Error **errp); 109 110 111 /** 112 * user_creatable_add_opts_predicate: 113 * @type: the QOM type to be added 114 * 115 * A callback function to determine whether an object 116 * of type @type should be created. Instances of this 117 * callback should be passed to user_creatable_add_opts_foreach 118 */ 119 typedef bool (*user_creatable_add_opts_predicate)(const char *type); 120 121 /** 122 * user_creatable_add_opts_foreach: 123 * @opaque: a user_creatable_add_opts_predicate callback or NULL 124 * @opts: options to create 125 * @errp: unused 126 * 127 * An iterator callback to be used in conjunction with 128 * the qemu_opts_foreach() method for creating a list of 129 * objects from a set of QemuOpts 130 * 131 * The @opaque parameter can be passed a user_creatable_add_opts_predicate 132 * callback to filter which types of object are created during iteration. 133 * When it fails, report the error. 134 * 135 * Returns: 0 on success, -1 when an error was reported. 136 */ 137 int user_creatable_add_opts_foreach(void *opaque, 138 QemuOpts *opts, Error **errp); 139 140 /** 141 * user_creatable_del: 142 * @id: the unique ID for the object 143 * @errp: if an error occurs, a pointer to an area to store the error 144 * 145 * Delete an instance of the user creatable object identified 146 * by @id. 147 */ 148 void user_creatable_del(const char *id, Error **errp); 149 150 #endif 151