shippable.yml: Remove the Debian9-based MinGW cross-compiler tests
[qemu.git] / include / qom / object_interfaces.h
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 typedef struct UserCreatableClass UserCreatableClass;
10 DECLARE_CLASS_CHECKERS(UserCreatableClass, USER_CREATABLE,
11 TYPE_USER_CREATABLE)
12 #define USER_CREATABLE(obj) \
13 INTERFACE_CHECK(UserCreatable, (obj), \
14 TYPE_USER_CREATABLE)
15
16 typedef struct UserCreatable UserCreatable;
17
18 /**
19 * UserCreatableClass:
20 * @parent_class: the base class
21 * @complete: callback to be called after @obj's properties are set.
22 * @can_be_deleted: callback to be called before an object is removed
23 * to check if @obj can be removed safely.
24 *
25 * Interface is designed to work with -object/object-add/object_add
26 * commands.
27 * Interface is mandatory for objects that are designed to be user
28 * creatable (i.e. -object/object-add/object_add, will accept only
29 * objects that inherit this interface).
30 *
31 * Interface also provides an optional ability to do the second
32 * stage * initialization of the object after its properties were
33 * set.
34 *
35 * For objects created without using -object/object-add/object_add,
36 * @user_creatable_complete() wrapper should be called manually if
37 * object's type implements USER_CREATABLE interface and needs
38 * complete() callback to be called.
39 */
40 struct UserCreatableClass {
41 /* <private> */
42 InterfaceClass parent_class;
43
44 /* <public> */
45 void (*complete)(UserCreatable *uc, Error **errp);
46 bool (*can_be_deleted)(UserCreatable *uc);
47 };
48
49 /**
50 * user_creatable_complete:
51 * @uc: the user-creatable object whose complete() method is called if defined
52 * @errp: if an error occurs, a pointer to an area to store the error
53 *
54 * Wrapper to call complete() method if one of types it's inherited
55 * from implements USER_CREATABLE interface, otherwise the call does
56 * nothing.
57 *
58 * Returns: %true on success, %false on failure.
59 */
60 bool user_creatable_complete(UserCreatable *uc, Error **errp);
61
62 /**
63 * user_creatable_can_be_deleted:
64 * @uc: the object whose can_be_deleted() method is called if implemented
65 *
66 * Wrapper to call can_be_deleted() method if one of types it's inherited
67 * from implements USER_CREATABLE interface.
68 */
69 bool user_creatable_can_be_deleted(UserCreatable *uc);
70
71 /**
72 * user_creatable_add_type:
73 * @type: the object type name
74 * @id: the unique ID for the object
75 * @qdict: the object properties
76 * @v: the visitor
77 * @errp: if an error occurs, a pointer to an area to store the error
78 *
79 * Create an instance of the user creatable object @type, placing
80 * it in the object composition tree with name @id, initializing
81 * it with properties from @qdict
82 *
83 * Returns: the newly created object or NULL on error
84 */
85 Object *user_creatable_add_type(const char *type, const char *id,
86 const QDict *qdict,
87 Visitor *v, Error **errp);
88
89 /**
90 * user_creatable_add_dict:
91 * @qdict: the object definition
92 * @keyval: if true, use a keyval visitor for processing @qdict (i.e.
93 * assume that all @qdict values are strings); otherwise, use
94 * the normal QObject visitor (i.e. assume all @qdict values
95 * have the QType expected by the QOM object type)
96 * @errp: if an error occurs, a pointer to an area to store the error
97 *
98 * Create an instance of the user creatable object that is defined by
99 * @qdict. The object type is taken from the QDict key 'qom-type', its
100 * ID from the key 'id'. The remaining entries in @qdict are used to
101 * initialize the object properties.
102 *
103 * Returns: %true on success, %false on failure.
104 */
105 bool user_creatable_add_dict(QDict *qdict, bool keyval, Error **errp);
106
107 /**
108 * user_creatable_add_opts:
109 * @opts: the object definition
110 * @errp: if an error occurs, a pointer to an area to store the error
111 *
112 * Create an instance of the user creatable object whose type
113 * is defined in @opts by the 'qom-type' option, placing it
114 * in the object composition tree with name provided by the
115 * 'id' field. The remaining options in @opts are used to
116 * initialize the object properties.
117 *
118 * Returns: the newly created object or NULL on error
119 */
120 Object *user_creatable_add_opts(QemuOpts *opts, Error **errp);
121
122
123 /**
124 * user_creatable_add_opts_predicate:
125 * @type: the QOM type to be added
126 *
127 * A callback function to determine whether an object
128 * of type @type should be created. Instances of this
129 * callback should be passed to user_creatable_add_opts_foreach
130 */
131 typedef bool (*user_creatable_add_opts_predicate)(const char *type);
132
133 /**
134 * user_creatable_add_opts_foreach:
135 * @opaque: a user_creatable_add_opts_predicate callback or NULL
136 * @opts: options to create
137 * @errp: unused
138 *
139 * An iterator callback to be used in conjunction with
140 * the qemu_opts_foreach() method for creating a list of
141 * objects from a set of QemuOpts
142 *
143 * The @opaque parameter can be passed a user_creatable_add_opts_predicate
144 * callback to filter which types of object are created during iteration.
145 * When it fails, report the error.
146 *
147 * Returns: 0 on success, -1 when an error was reported.
148 */
149 int user_creatable_add_opts_foreach(void *opaque,
150 QemuOpts *opts, Error **errp);
151
152 /**
153 * user_creatable_print_help:
154 * @type: the QOM type to be added
155 * @opts: options to create
156 *
157 * Prints help if requested in @opts.
158 *
159 * Returns: true if @opts contained a help option and help was printed, false
160 * if no help option was found.
161 */
162 bool user_creatable_print_help(const char *type, QemuOpts *opts);
163
164 /**
165 * user_creatable_del:
166 * @id: the unique ID for the object
167 * @errp: if an error occurs, a pointer to an area to store the error
168 *
169 * Delete an instance of the user creatable object identified
170 * by @id.
171 *
172 * Returns: %true on success, %false on failure.
173 */
174 bool user_creatable_del(const char *id, Error **errp);
175
176 /**
177 * user_creatable_cleanup:
178 *
179 * Delete all user-creatable objects and the user-creatable
180 * objects container.
181 */
182 void user_creatable_cleanup(void);
183
184 /**
185 * qmp_object_add:
186 *
187 * QMP command handler for object-add. See the QAPI schema for documentation.
188 */
189 void qmp_object_add(QDict *qdict, QObject **ret_data, Error **errp);
190
191 #endif