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 | |