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 void user_creatable_complete(UserCreatable *uc, Error **errp); 62 63 /** 64 * user_creatable_can_be_deleted: 65 * @uc: the object whose can_be_deleted() method is called if implemented 66 * 67 * Wrapper to call can_be_deleted() method if one of types it's inherited 68 * from implements USER_CREATABLE interface. 69 */ 70 bool user_creatable_can_be_deleted(UserCreatable *uc); 71 72 /** 73 * user_creatable_add_type: 74 * @type: the object type name 75 * @id: the unique ID for the object 76 * @qdict: the object properties 77 * @v: the visitor 78 * @errp: if an error occurs, a pointer to an area to store the error 79 * 80 * Create an instance of the user creatable object @type, placing 81 * it in the object composition tree with name @id, initializing 82 * it with properties from @qdict 83 * 84 * Returns: the newly created object or NULL on error 85 */ 86 Object *user_creatable_add_type(const char *type, const char *id, 87 const QDict *qdict, 88 Visitor *v, Error **errp); 89 90 /** 91 * user_creatable_add_opts: 92 * @opts: the object definition 93 * @errp: if an error occurs, a pointer to an area to store the error 94 * 95 * Create an instance of the user creatable object whose type 96 * is defined in @opts by the 'qom-type' option, placing it 97 * in the object composition tree with name provided by the 98 * 'id' field. The remaining options in @opts are used to 99 * initialize the object properties. 100 * 101 * Returns: the newly created object or NULL on error 102 */ 103 Object *user_creatable_add_opts(QemuOpts *opts, Error **errp); 104 105 106 /** 107 * user_creatable_add_opts_predicate: 108 * @type: the QOM type to be added 109 * 110 * A callback function to determine whether an object 111 * of type @type should be created. Instances of this 112 * callback should be passed to user_creatable_add_opts_foreach 113 */ 114 typedef bool (*user_creatable_add_opts_predicate)(const char *type); 115 116 /** 117 * user_creatable_add_opts_foreach: 118 * @opaque: a user_creatable_add_opts_predicate callback or NULL 119 * @opts: options to create 120 * @errp: unused 121 * 122 * An iterator callback to be used in conjunction with 123 * the qemu_opts_foreach() method for creating a list of 124 * objects from a set of QemuOpts 125 * 126 * The @opaque parameter can be passed a user_creatable_add_opts_predicate 127 * callback to filter which types of object are created during iteration. 128 * When it fails, report the error. 129 * 130 * Returns: 0 on success, -1 when an error was reported. 131 */ 132 int user_creatable_add_opts_foreach(void *opaque, 133 QemuOpts *opts, Error **errp); 134 135 /** 136 * user_creatable_del: 137 * @id: the unique ID for the object 138 * @errp: if an error occurs, a pointer to an area to store the error 139 * 140 * Delete an instance of the user creatable object identified 141 * by @id. 142 */ 143 void user_creatable_del(const char *id, Error **errp); 144 145 /** 146 * user_creatable_cleanup: 147 * 148 * Delete all user-creatable objects and the user-creatable 149 * objects container. 150 */ 151 void user_creatable_cleanup(void); 152 153 #endif 154