qom: Make functions taking Error ** return bool, not void
[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 #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 * Returns: %true on success, %false on failure.
62 */
63 bool user_creatable_complete(UserCreatable *uc, Error **errp);
64
65 /**
66 * user_creatable_can_be_deleted:
67 * @uc: the object whose can_be_deleted() method is called if implemented
68 *
69 * Wrapper to call can_be_deleted() method if one of types it's inherited
70 * from implements USER_CREATABLE interface.
71 */
72 bool user_creatable_can_be_deleted(UserCreatable *uc);
73
74 /**
75 * user_creatable_add_type:
76 * @type: the object type name
77 * @id: the unique ID for the object
78 * @qdict: the object properties
79 * @v: the visitor
80 * @errp: if an error occurs, a pointer to an area to store the error
81 *
82 * Create an instance of the user creatable object @type, placing
83 * it in the object composition tree with name @id, initializing
84 * it with properties from @qdict
85 *
86 * Returns: the newly created object or NULL on error
87 */
88 Object *user_creatable_add_type(const char *type, const char *id,
89 const QDict *qdict,
90 Visitor *v, Error **errp);
91
92 /**
93 * user_creatable_add_dict:
94 * @qdict: the object definition
95 * @keyval: if true, use a keyval visitor for processing @qdict (i.e.
96 * assume that all @qdict values are strings); otherwise, use
97 * the normal QObject visitor (i.e. assume all @qdict values
98 * have the QType expected by the QOM object type)
99 * @errp: if an error occurs, a pointer to an area to store the error
100 *
101 * Create an instance of the user creatable object that is defined by
102 * @qdict. The object type is taken from the QDict key 'qom-type', its
103 * ID from the key 'id'. The remaining entries in @qdict are used to
104 * initialize the object properties.
105 *
106 * Returns: %true on success, %false on failure.
107 */
108 bool user_creatable_add_dict(QDict *qdict, bool keyval, Error **errp);
109
110 /**
111 * user_creatable_add_opts:
112 * @opts: the object definition
113 * @errp: if an error occurs, a pointer to an area to store the error
114 *
115 * Create an instance of the user creatable object whose type
116 * is defined in @opts by the 'qom-type' option, placing it
117 * in the object composition tree with name provided by the
118 * 'id' field. The remaining options in @opts are used to
119 * initialize the object properties.
120 *
121 * Returns: the newly created object or NULL on error
122 */
123 Object *user_creatable_add_opts(QemuOpts *opts, Error **errp);
124
125
126 /**
127 * user_creatable_add_opts_predicate:
128 * @type: the QOM type to be added
129 *
130 * A callback function to determine whether an object
131 * of type @type should be created. Instances of this
132 * callback should be passed to user_creatable_add_opts_foreach
133 */
134 typedef bool (*user_creatable_add_opts_predicate)(const char *type);
135
136 /**
137 * user_creatable_add_opts_foreach:
138 * @opaque: a user_creatable_add_opts_predicate callback or NULL
139 * @opts: options to create
140 * @errp: unused
141 *
142 * An iterator callback to be used in conjunction with
143 * the qemu_opts_foreach() method for creating a list of
144 * objects from a set of QemuOpts
145 *
146 * The @opaque parameter can be passed a user_creatable_add_opts_predicate
147 * callback to filter which types of object are created during iteration.
148 * When it fails, report the error.
149 *
150 * Returns: 0 on success, -1 when an error was reported.
151 */
152 int user_creatable_add_opts_foreach(void *opaque,
153 QemuOpts *opts, Error **errp);
154
155 /**
156 * user_creatable_print_help:
157 * @type: the QOM type to be added
158 * @opts: options to create
159 *
160 * Prints help if requested in @opts.
161 *
162 * Returns: true if @opts contained a help option and help was printed, false
163 * if no help option was found.
164 */
165 bool user_creatable_print_help(const char *type, QemuOpts *opts);
166
167 /**
168 * user_creatable_del:
169 * @id: the unique ID for the object
170 * @errp: if an error occurs, a pointer to an area to store the error
171 *
172 * Delete an instance of the user creatable object identified
173 * by @id.
174 *
175 * Returns: %true on success, %false on failure.
176 */
177 bool user_creatable_del(const char *id, Error **errp);
178
179 /**
180 * user_creatable_cleanup:
181 *
182 * Delete all user-creatable objects and the user-creatable
183 * objects container.
184 */
185 void user_creatable_cleanup(void);
186
187 /**
188 * qmp_object_add:
189 *
190 * QMP command handler for object-add. See the QAPI schema for documentation.
191 */
192 void qmp_object_add(QDict *qdict, QObject **ret_data, Error **errp);
193
194 #endif