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