blob: 5f3d5b5bf532cc3627df4f017356d3dd3b5cf603 [file] [log] [blame]
Anthony Liguori2f28d2f2011-12-03 17:10:08 -06001/*
2 * QEMU Object Model
3 *
4 * Copyright IBM, Corp. 2011
5 *
6 * Authors:
7 * Anthony Liguori <aliguori@us.ibm.com>
8 *
9 * This work is licensed under the terms of the GNU GPL, version 2 or later.
10 * See the COPYING file in the top-level directory.
11 *
12 */
13
14#ifndef QEMU_OBJECT_H
15#define QEMU_OBJECT_H
16
Markus Armbrustereb815e22018-02-11 10:36:05 +010017#include "qapi/qapi-builtin-types.h"
Markus Armbruster0b8fa322019-05-23 16:35:07 +020018#include "qemu/module.h"
Eduardo Habkostdb1015e2020-09-03 16:43:22 -040019#include "qom/object.h"
Anthony Liguori57c9faf2012-01-30 08:55:55 -060020
Anthony Liguori2f28d2f2011-12-03 17:10:08 -060021struct TypeImpl;
22typedef struct TypeImpl *Type;
23
Anthony Liguori2f28d2f2011-12-03 17:10:08 -060024typedef struct TypeInfo TypeInfo;
25
26typedef struct InterfaceClass InterfaceClass;
27typedef struct InterfaceInfo InterfaceInfo;
28
Paolo Bonzini745549c2012-03-31 16:45:54 +020029#define TYPE_OBJECT "object"
Anthony Liguori2f28d2f2011-12-03 17:10:08 -060030
Marc-André Lureau2a1be4b2020-01-10 19:30:19 +040031typedef struct ObjectProperty ObjectProperty;
32
Anthony Liguori57c9faf2012-01-30 08:55:55 -060033/**
Eduardo Habkostff597802020-10-02 22:41:21 -040034 * typedef ObjectPropertyAccessor:
Anthony Liguori57c9faf2012-01-30 08:55:55 -060035 * @obj: the object that owns the property
36 * @v: the visitor that contains the property data
Anthony Liguori57c9faf2012-01-30 08:55:55 -060037 * @name: the name of the property
Eric Blaked7bce992016-01-29 06:48:55 -070038 * @opaque: the object property opaque
Anthony Liguori57c9faf2012-01-30 08:55:55 -060039 * @errp: a pointer to an Error that is filled if getting/setting fails.
40 *
41 * Called when trying to get/set a property.
42 */
43typedef void (ObjectPropertyAccessor)(Object *obj,
Eric Blake4fa45492016-01-29 06:48:53 -070044 Visitor *v,
Anthony Liguori57c9faf2012-01-30 08:55:55 -060045 const char *name,
Eric Blaked7bce992016-01-29 06:48:55 -070046 void *opaque,
Michael S. Tsirkine82df242013-09-22 10:08:14 +030047 Error **errp);
Anthony Liguori57c9faf2012-01-30 08:55:55 -060048
49/**
Eduardo Habkostff597802020-10-02 22:41:21 -040050 * typedef ObjectPropertyResolve:
Paolo Bonzini64607d02014-06-05 13:11:51 +020051 * @obj: the object that owns the property
52 * @opaque: the opaque registered with the property
53 * @part: the name of the property
54 *
55 * Resolves the #Object corresponding to property @part.
56 *
57 * The returned object can also be used as a starting point
58 * to resolve a relative path starting with "@part".
59 *
60 * Returns: If @path is the path that led to @obj, the function
61 * returns the #Object corresponding to "@path/@part".
62 * If "@path/@part" is not a valid object path, it returns #NULL.
63 */
64typedef Object *(ObjectPropertyResolve)(Object *obj,
65 void *opaque,
66 const char *part);
67
68/**
Eduardo Habkostff597802020-10-02 22:41:21 -040069 * typedef ObjectPropertyRelease:
Anthony Liguori57c9faf2012-01-30 08:55:55 -060070 * @obj: the object that owns the property
71 * @name: the name of the property
72 * @opaque: the opaque registered with the property
73 *
74 * Called when a property is removed from a object.
75 */
76typedef void (ObjectPropertyRelease)(Object *obj,
77 const char *name,
78 void *opaque);
79
Marc-André Lureau2a1be4b2020-01-10 19:30:19 +040080/**
Eduardo Habkostff597802020-10-02 22:41:21 -040081 * typedef ObjectPropertyInit:
Marc-André Lureau2a1be4b2020-01-10 19:30:19 +040082 * @obj: the object that owns the property
83 * @prop: the property to set
84 *
85 * Called when a property is initialized.
86 */
87typedef void (ObjectPropertyInit)(Object *obj, ObjectProperty *prop);
88
89struct ObjectProperty
Anthony Liguori57c9faf2012-01-30 08:55:55 -060090{
Markus Armbrusterddfb0ba2020-05-05 17:29:10 +020091 char *name;
92 char *type;
93 char *description;
Anthony Liguori57c9faf2012-01-30 08:55:55 -060094 ObjectPropertyAccessor *get;
95 ObjectPropertyAccessor *set;
Paolo Bonzini64607d02014-06-05 13:11:51 +020096 ObjectPropertyResolve *resolve;
Anthony Liguori57c9faf2012-01-30 08:55:55 -060097 ObjectPropertyRelease *release;
Marc-André Lureau2a1be4b2020-01-10 19:30:19 +040098 ObjectPropertyInit *init;
Anthony Liguori57c9faf2012-01-30 08:55:55 -060099 void *opaque;
Marc-André Lureau0e76ed02020-01-10 19:30:23 +0400100 QObject *defval;
Marc-André Lureau2a1be4b2020-01-10 19:30:19 +0400101};
Anthony Liguori57c9faf2012-01-30 08:55:55 -0600102
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600103/**
Eduardo Habkostff597802020-10-02 22:41:21 -0400104 * typedef ObjectUnparent:
Paolo Bonzini667d22d2012-11-23 09:47:13 +0100105 * @obj: the object that is being removed from the composition tree
106 *
107 * Called when an object is being removed from the QOM composition tree.
108 * The function should remove any backlinks from children objects to @obj.
109 */
110typedef void (ObjectUnparent)(Object *obj);
111
112/**
Eduardo Habkostff597802020-10-02 22:41:21 -0400113 * typedef ObjectFree:
Paolo Bonzinifde9bf42012-11-23 09:47:14 +0100114 * @obj: the object being freed
115 *
116 * Called when an object's last reference is removed.
117 */
118typedef void (ObjectFree)(void *obj);
119
Anthony Liguori03587322013-05-13 15:22:24 -0500120#define OBJECT_CLASS_CAST_CACHE 4
121
Paolo Bonzinifde9bf42012-11-23 09:47:14 +0100122/**
Eduardo Habkostff597802020-10-02 22:41:21 -0400123 * struct ObjectClass:
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600124 *
125 * The base for all classes. The only thing that #ObjectClass contains is an
126 * integer type handle.
127 */
128struct ObjectClass
129{
Eduardo Habkost11e1c3a2020-09-10 18:15:19 -0400130 /* private: */
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600131 Type type;
Anthony Liguori33e95c62012-08-10 13:16:10 +1000132 GSList *interfaces;
Paolo Bonzini667d22d2012-11-23 09:47:13 +0100133
Peter Crosthwaite0ab4c942013-11-27 20:27:33 -0800134 const char *object_cast_cache[OBJECT_CLASS_CAST_CACHE];
135 const char *class_cast_cache[OBJECT_CLASS_CAST_CACHE];
Anthony Liguori03587322013-05-13 15:22:24 -0500136
Paolo Bonzini667d22d2012-11-23 09:47:13 +0100137 ObjectUnparent *unparent;
Daniel P. Berrange16bf7f52015-10-13 13:37:46 +0100138
139 GHashTable *properties;
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600140};
141
142/**
Eduardo Habkostff597802020-10-02 22:41:21 -0400143 * struct Object:
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600144 *
145 * The base for all objects. The first member of this object is a pointer to
146 * a #ObjectClass. Since C guarantees that the first member of a structure
147 * always begins at byte 0 of that structure, as long as any sub-object places
148 * its parent as the first member, we can cast directly to a #Object.
149 *
150 * As a result, #Object contains a reference to the objects type as its
151 * first member. This allows identification of the real type of the object at
152 * run time.
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600153 */
154struct Object
155{
Eduardo Habkost11e1c3a2020-09-10 18:15:19 -0400156 /* private: */
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600157 ObjectClass *class;
Paolo Bonzinifde9bf42012-11-23 09:47:14 +0100158 ObjectFree *free;
Pavel Fedinb604a852015-10-13 13:37:45 +0100159 GHashTable *properties;
Anthony Liguori57c9faf2012-01-30 08:55:55 -0600160 uint32_t ref;
161 Object *parent;
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600162};
163
164/**
Eduardo Habkost7808a282020-08-31 17:07:26 -0400165 * DECLARE_INSTANCE_CHECKER:
166 * @InstanceType: instance struct name
167 * @OBJ_NAME: the object name in uppercase with underscore separators
168 * @TYPENAME: type name
169 *
170 * Direct usage of this macro should be avoided, and the complete
171 * OBJECT_DECLARE_TYPE macro is recommended instead.
172 *
Eduardo Habkostd5b99592020-10-02 22:54:19 -0400173 * This macro will provide the instance type cast functions for a
Eduardo Habkost7808a282020-08-31 17:07:26 -0400174 * QOM type.
175 */
176#define DECLARE_INSTANCE_CHECKER(InstanceType, OBJ_NAME, TYPENAME) \
177 static inline G_GNUC_UNUSED InstanceType * \
Eduardo Habkostad09bed2020-08-31 17:07:27 -0400178 OBJ_NAME(const void *obj) \
Eduardo Habkost7808a282020-08-31 17:07:26 -0400179 { return OBJECT_CHECK(InstanceType, obj, TYPENAME); }
180
181/**
182 * DECLARE_CLASS_CHECKERS:
183 * @ClassType: class struct name
184 * @OBJ_NAME: the object name in uppercase with underscore separators
185 * @TYPENAME: type name
186 *
187 * Direct usage of this macro should be avoided, and the complete
188 * OBJECT_DECLARE_TYPE macro is recommended instead.
189 *
Eduardo Habkostd5b99592020-10-02 22:54:19 -0400190 * This macro will provide the class type cast functions for a
Eduardo Habkost7808a282020-08-31 17:07:26 -0400191 * QOM type.
192 */
193#define DECLARE_CLASS_CHECKERS(ClassType, OBJ_NAME, TYPENAME) \
194 static inline G_GNUC_UNUSED ClassType * \
Eduardo Habkostad09bed2020-08-31 17:07:27 -0400195 OBJ_NAME##_GET_CLASS(const void *obj) \
Eduardo Habkost7808a282020-08-31 17:07:26 -0400196 { return OBJECT_GET_CLASS(ClassType, obj, TYPENAME); } \
197 \
198 static inline G_GNUC_UNUSED ClassType * \
Eduardo Habkostad09bed2020-08-31 17:07:27 -0400199 OBJ_NAME##_CLASS(const void *klass) \
Eduardo Habkost7808a282020-08-31 17:07:26 -0400200 { return OBJECT_CLASS_CHECK(ClassType, klass, TYPENAME); }
201
202/**
203 * DECLARE_OBJ_CHECKERS:
204 * @InstanceType: instance struct name
205 * @ClassType: class struct name
206 * @OBJ_NAME: the object name in uppercase with underscore separators
207 * @TYPENAME: type name
208 *
209 * Direct usage of this macro should be avoided, and the complete
210 * OBJECT_DECLARE_TYPE macro is recommended instead.
211 *
212 * This macro will provide the three standard type cast functions for a
213 * QOM type.
214 */
215#define DECLARE_OBJ_CHECKERS(InstanceType, ClassType, OBJ_NAME, TYPENAME) \
216 DECLARE_INSTANCE_CHECKER(InstanceType, OBJ_NAME, TYPENAME) \
217 \
218 DECLARE_CLASS_CHECKERS(ClassType, OBJ_NAME, TYPENAME)
219
220/**
Daniel P. Berrangéf84203a2020-08-31 17:07:24 -0400221 * OBJECT_DECLARE_TYPE:
Eduardo Habkost4a5f0542020-08-31 17:07:25 -0400222 * @InstanceType: instance struct name
223 * @ClassType: class struct name
Daniel P. Berrangéf84203a2020-08-31 17:07:24 -0400224 * @MODULE_OBJ_NAME: the object name in uppercase with underscore separators
225 *
226 * This macro is typically used in a header file, and will:
227 *
228 * - create the typedefs for the object and class structs
229 * - register the type for use with g_autoptr
230 * - provide three standard type cast functions
231 *
232 * The object struct and class struct need to be declared manually.
233 */
Eduardo Habkost30b57072020-09-16 14:25:17 -0400234#define OBJECT_DECLARE_TYPE(InstanceType, ClassType, MODULE_OBJ_NAME) \
Eduardo Habkost4a5f0542020-08-31 17:07:25 -0400235 typedef struct InstanceType InstanceType; \
236 typedef struct ClassType ClassType; \
Daniel P. Berrangéf84203a2020-08-31 17:07:24 -0400237 \
Eduardo Habkost4a5f0542020-08-31 17:07:25 -0400238 G_DEFINE_AUTOPTR_CLEANUP_FUNC(InstanceType, object_unref) \
Daniel P. Berrangéf84203a2020-08-31 17:07:24 -0400239 \
Eduardo Habkost7808a282020-08-31 17:07:26 -0400240 DECLARE_OBJ_CHECKERS(InstanceType, ClassType, \
241 MODULE_OBJ_NAME, TYPE_##MODULE_OBJ_NAME)
Daniel P. Berrangéf84203a2020-08-31 17:07:24 -0400242
243/**
244 * OBJECT_DECLARE_SIMPLE_TYPE:
Eduardo Habkost4a5f0542020-08-31 17:07:25 -0400245 * @InstanceType: instance struct name
Daniel P. Berrangéf84203a2020-08-31 17:07:24 -0400246 * @MODULE_OBJ_NAME: the object name in uppercase with underscore separators
Daniel P. Berrangéf84203a2020-08-31 17:07:24 -0400247 *
Eduardo Habkostc734cd42020-09-16 14:25:16 -0400248 * This does the same as OBJECT_DECLARE_TYPE(), but with no class struct
249 * declared.
Daniel P. Berrangéf84203a2020-08-31 17:07:24 -0400250 *
251 * This macro should be used unless the class struct needs to have
252 * virtual methods declared.
253 */
Eduardo Habkost30b57072020-09-16 14:25:17 -0400254#define OBJECT_DECLARE_SIMPLE_TYPE(InstanceType, MODULE_OBJ_NAME) \
Eduardo Habkostc734cd42020-09-16 14:25:16 -0400255 typedef struct InstanceType InstanceType; \
256 \
257 G_DEFINE_AUTOPTR_CLEANUP_FUNC(InstanceType, object_unref) \
258 \
259 DECLARE_INSTANCE_CHECKER(InstanceType, MODULE_OBJ_NAME, TYPE_##MODULE_OBJ_NAME)
Daniel P. Berrangéf84203a2020-08-31 17:07:24 -0400260
261
262/**
263 * OBJECT_DEFINE_TYPE_EXTENDED:
264 * @ModuleObjName: the object name with initial caps
265 * @module_obj_name: the object name in lowercase with underscore separators
266 * @MODULE_OBJ_NAME: the object name in uppercase with underscore separators
267 * @PARENT_MODULE_OBJ_NAME: the parent object name in uppercase with underscore
268 * separators
269 * @ABSTRACT: boolean flag to indicate whether the object can be instantiated
270 * @...: list of initializers for "InterfaceInfo" to declare implemented interfaces
271 *
272 * This macro is typically used in a source file, and will:
273 *
274 * - declare prototypes for _finalize, _class_init and _init methods
275 * - declare the TypeInfo struct instance
276 * - provide the constructor to register the type
277 *
278 * After using this macro, implementations of the _finalize, _class_init,
279 * and _init methods need to be written. Any of these can be zero-line
280 * no-op impls if no special logic is required for a given type.
281 *
282 * This macro should rarely be used, instead one of the more specialized
283 * macros is usually a better choice.
284 */
285#define OBJECT_DEFINE_TYPE_EXTENDED(ModuleObjName, module_obj_name, \
286 MODULE_OBJ_NAME, PARENT_MODULE_OBJ_NAME, \
287 ABSTRACT, ...) \
288 static void \
289 module_obj_name##_finalize(Object *obj); \
290 static void \
291 module_obj_name##_class_init(ObjectClass *oc, void *data); \
292 static void \
293 module_obj_name##_init(Object *obj); \
294 \
295 static const TypeInfo module_obj_name##_info = { \
296 .parent = TYPE_##PARENT_MODULE_OBJ_NAME, \
297 .name = TYPE_##MODULE_OBJ_NAME, \
298 .instance_size = sizeof(ModuleObjName), \
Richard Henderson4c880f32020-09-15 17:46:34 -0700299 .instance_align = __alignof__(ModuleObjName), \
Daniel P. Berrangéf84203a2020-08-31 17:07:24 -0400300 .instance_init = module_obj_name##_init, \
301 .instance_finalize = module_obj_name##_finalize, \
302 .class_size = sizeof(ModuleObjName##Class), \
303 .class_init = module_obj_name##_class_init, \
304 .abstract = ABSTRACT, \
305 .interfaces = (InterfaceInfo[]) { __VA_ARGS__ } , \
306 }; \
307 \
308 static void \
309 module_obj_name##_register_types(void) \
310 { \
311 type_register_static(&module_obj_name##_info); \
312 } \
313 type_init(module_obj_name##_register_types);
314
315/**
316 * OBJECT_DEFINE_TYPE:
317 * @ModuleObjName: the object name with initial caps
318 * @module_obj_name: the object name in lowercase with underscore separators
319 * @MODULE_OBJ_NAME: the object name in uppercase with underscore separators
320 * @PARENT_MODULE_OBJ_NAME: the parent object name in uppercase with underscore
321 * separators
322 *
323 * This is a specialization of OBJECT_DEFINE_TYPE_EXTENDED, which is suitable
324 * for the common case of a non-abstract type, without any interfaces.
325 */
326#define OBJECT_DEFINE_TYPE(ModuleObjName, module_obj_name, MODULE_OBJ_NAME, \
327 PARENT_MODULE_OBJ_NAME) \
328 OBJECT_DEFINE_TYPE_EXTENDED(ModuleObjName, module_obj_name, \
329 MODULE_OBJ_NAME, PARENT_MODULE_OBJ_NAME, \
330 false, { NULL })
331
332/**
333 * OBJECT_DEFINE_TYPE_WITH_INTERFACES:
334 * @ModuleObjName: the object name with initial caps
335 * @module_obj_name: the object name in lowercase with underscore separators
336 * @MODULE_OBJ_NAME: the object name in uppercase with underscore separators
337 * @PARENT_MODULE_OBJ_NAME: the parent object name in uppercase with underscore
338 * separators
339 * @...: list of initializers for "InterfaceInfo" to declare implemented interfaces
340 *
341 * This is a specialization of OBJECT_DEFINE_TYPE_EXTENDED, which is suitable
342 * for the common case of a non-abstract type, with one or more implemented
343 * interfaces.
344 *
345 * Note when passing the list of interfaces, be sure to include the final
346 * NULL entry, e.g. { TYPE_USER_CREATABLE }, { NULL }
347 */
348#define OBJECT_DEFINE_TYPE_WITH_INTERFACES(ModuleObjName, module_obj_name, \
349 MODULE_OBJ_NAME, \
350 PARENT_MODULE_OBJ_NAME, ...) \
351 OBJECT_DEFINE_TYPE_EXTENDED(ModuleObjName, module_obj_name, \
352 MODULE_OBJ_NAME, PARENT_MODULE_OBJ_NAME, \
353 false, __VA_ARGS__)
354
355/**
356 * OBJECT_DEFINE_ABSTRACT_TYPE:
357 * @ModuleObjName: the object name with initial caps
358 * @module_obj_name: the object name in lowercase with underscore separators
359 * @MODULE_OBJ_NAME: the object name in uppercase with underscore separators
360 * @PARENT_MODULE_OBJ_NAME: the parent object name in uppercase with underscore
361 * separators
362 *
363 * This is a specialization of OBJECT_DEFINE_TYPE_EXTENDED, which is suitable
364 * for defining an abstract type, without any interfaces.
365 */
366#define OBJECT_DEFINE_ABSTRACT_TYPE(ModuleObjName, module_obj_name, \
367 MODULE_OBJ_NAME, PARENT_MODULE_OBJ_NAME) \
368 OBJECT_DEFINE_TYPE_EXTENDED(ModuleObjName, module_obj_name, \
369 MODULE_OBJ_NAME, PARENT_MODULE_OBJ_NAME, \
370 true, { NULL })
371
372/**
Eduardo Habkostff597802020-10-02 22:41:21 -0400373 * struct TypeInfo:
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600374 * @name: The name of the type.
375 * @parent: The name of the parent type.
376 * @instance_size: The size of the object (derivative of #Object). If
377 * @instance_size is 0, then the size of the object will be the size of the
378 * parent object.
Richard Henderson4c880f32020-09-15 17:46:34 -0700379 * @instance_align: The required alignment of the object. If @instance_align
380 * is 0, then normal malloc alignment is sufficient; if non-zero, then we
381 * must use qemu_memalign for allocation.
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600382 * @instance_init: This function is called to initialize an object. The parent
383 * class will have already been initialized so the type is only responsible
384 * for initializing its own members.
Eduardo Habkost8231c2d2013-07-10 17:08:41 -0300385 * @instance_post_init: This function is called to finish initialization of
386 * an object, after all @instance_init functions were called.
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600387 * @instance_finalize: This function is called during object destruction. This
388 * is called before the parent @instance_finalize function has been called.
389 * An object should only free the members that are unique to its type in this
390 * function.
391 * @abstract: If this field is true, then the class is considered abstract and
392 * cannot be directly instantiated.
393 * @class_size: The size of the class object (derivative of #ObjectClass)
394 * for this object. If @class_size is 0, then the size of the class will be
395 * assumed to be the size of the parent class. This allows a type to avoid
396 * implementing an explicit class type if they are not adding additional
397 * virtual functions.
398 * @class_init: This function is called after all parent class initialization
Stefan Weil441dd5e2012-02-25 13:47:09 +0100399 * has occurred to allow a class to set its default virtual method pointers.
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600400 * This is also the function to use to override virtual methods from a parent
401 * class.
Paolo Bonzini3b50e312012-05-02 13:30:55 +0200402 * @class_base_init: This function is called for all base classes after all
403 * parent class initialization has occurred, but before the class itself
404 * is initialized. This is the function to use to undo the effects of
Marc-André Lureau39a10752016-12-12 20:31:49 +0300405 * memcpy from the parent class to the descendants.
Marc-André Lureau37fdb2c2018-12-04 18:20:10 +0400406 * @class_data: Data to pass to the @class_init,
407 * @class_base_init. This can be useful when building dynamic
Paolo Bonzini3b50e312012-05-02 13:30:55 +0200408 * classes.
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600409 * @interfaces: The list of interfaces associated with this type. This
410 * should point to a static array that's terminated with a zero filled
411 * element.
412 */
413struct TypeInfo
414{
415 const char *name;
416 const char *parent;
417
418 size_t instance_size;
Richard Henderson4c880f32020-09-15 17:46:34 -0700419 size_t instance_align;
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600420 void (*instance_init)(Object *obj);
Eduardo Habkost8231c2d2013-07-10 17:08:41 -0300421 void (*instance_post_init)(Object *obj);
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600422 void (*instance_finalize)(Object *obj);
423
424 bool abstract;
425 size_t class_size;
426
427 void (*class_init)(ObjectClass *klass, void *data);
Paolo Bonzini3b50e312012-05-02 13:30:55 +0200428 void (*class_base_init)(ObjectClass *klass, void *data);
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600429 void *class_data;
430
431 InterfaceInfo *interfaces;
432};
433
434/**
435 * OBJECT:
436 * @obj: A derivative of #Object
437 *
438 * Converts an object to a #Object. Since all objects are #Objects,
439 * this function will always succeed.
440 */
441#define OBJECT(obj) \
442 ((Object *)(obj))
443
444/**
Paolo Bonzini1ed5b912012-02-03 11:48:11 +0100445 * OBJECT_CLASS:
Andreas Färbera0dbf402012-02-16 18:03:18 +0100446 * @class: A derivative of #ObjectClass.
Paolo Bonzini1ed5b912012-02-03 11:48:11 +0100447 *
448 * Converts a class to an #ObjectClass. Since all objects are #Objects,
449 * this function will always succeed.
450 */
451#define OBJECT_CLASS(class) \
452 ((ObjectClass *)(class))
453
454/**
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600455 * OBJECT_CHECK:
456 * @type: The C type to use for the return value.
457 * @obj: A derivative of @type to cast.
458 * @name: The QOM typename of @type
459 *
460 * A type safe version of @object_dynamic_cast_assert. Typically each class
461 * will define a macro based on this type to perform type safe dynamic_casts to
462 * this object type.
463 *
464 * If an invalid object is passed to this function, a run time assert will be
465 * generated.
466 */
467#define OBJECT_CHECK(type, obj, name) \
Paolo Bonzinibe17f182013-05-10 14:16:38 +0200468 ((type *)object_dynamic_cast_assert(OBJECT(obj), (name), \
469 __FILE__, __LINE__, __func__))
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600470
471/**
472 * OBJECT_CLASS_CHECK:
Cao jinb30d8052015-11-03 10:36:42 +0800473 * @class_type: The C type to use for the return value.
474 * @class: A derivative class of @class_type to cast.
475 * @name: the QOM typename of @class_type.
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600476 *
Paolo Bonzini1ed5b912012-02-03 11:48:11 +0100477 * A type safe version of @object_class_dynamic_cast_assert. This macro is
478 * typically wrapped by each type to perform type safe casts of a class to a
479 * specific class type.
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600480 */
Cao jinb30d8052015-11-03 10:36:42 +0800481#define OBJECT_CLASS_CHECK(class_type, class, name) \
482 ((class_type *)object_class_dynamic_cast_assert(OBJECT_CLASS(class), (name), \
Paolo Bonzinibe17f182013-05-10 14:16:38 +0200483 __FILE__, __LINE__, __func__))
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600484
485/**
486 * OBJECT_GET_CLASS:
487 * @class: The C type to use for the return value.
488 * @obj: The object to obtain the class for.
489 * @name: The QOM typename of @obj.
490 *
491 * This function will return a specific class for a given object. Its generally
492 * used by each type to provide a type safe macro to get a specific class type
493 * from an object.
494 */
495#define OBJECT_GET_CLASS(class, obj, name) \
496 OBJECT_CLASS_CHECK(class, object_get_class(OBJECT(obj)), name)
497
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600498/**
Eduardo Habkostff597802020-10-02 22:41:21 -0400499 * struct InterfaceInfo:
Anthony Liguori33e95c62012-08-10 13:16:10 +1000500 * @type: The name of the interface.
501 *
502 * The information associated with an interface.
503 */
504struct InterfaceInfo {
505 const char *type;
506};
507
508/**
Eduardo Habkostff597802020-10-02 22:41:21 -0400509 * struct InterfaceClass:
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600510 * @parent_class: the base class
511 *
512 * The class for all interfaces. Subclasses of this class should only add
513 * virtual methods.
514 */
515struct InterfaceClass
516{
517 ObjectClass parent_class;
Eduardo Habkost11e1c3a2020-09-10 18:15:19 -0400518 /* private: */
Anthony Liguori33e95c62012-08-10 13:16:10 +1000519 ObjectClass *concrete_class;
Paolo Bonzinib061dc42013-12-03 16:41:59 +0100520 Type interface_type;
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600521};
522
523#define TYPE_INTERFACE "interface"
524
525/**
Anthony Liguori33e95c62012-08-10 13:16:10 +1000526 * INTERFACE_CLASS:
527 * @klass: class to cast from
528 * Returns: An #InterfaceClass or raise an error if cast is invalid
529 */
530#define INTERFACE_CLASS(klass) \
531 OBJECT_CLASS_CHECK(InterfaceClass, klass, TYPE_INTERFACE)
532
533/**
534 * INTERFACE_CHECK:
535 * @interface: the type to return
536 * @obj: the object to convert to an interface
537 * @name: the interface type name
538 *
539 * Returns: @obj casted to @interface if cast is valid, otherwise raise error.
540 */
541#define INTERFACE_CHECK(interface, obj, name) \
Paolo Bonzinibe17f182013-05-10 14:16:38 +0200542 ((interface *)object_dynamic_cast_assert(OBJECT((obj)), (name), \
543 __FILE__, __LINE__, __func__))
Anthony Liguori33e95c62012-08-10 13:16:10 +1000544
545/**
Paolo Bonzini3c75e122019-11-13 13:57:55 +0100546 * object_new_with_class:
547 * @klass: The class to instantiate.
548 *
549 * This function will initialize a new object using heap allocated memory.
550 * The returned object has a reference count of 1, and will be freed when
551 * the last reference is dropped.
552 *
553 * Returns: The newly allocated and instantiated object.
554 */
555Object *object_new_with_class(ObjectClass *klass);
556
557/**
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600558 * object_new:
559 * @typename: The name of the type of the object to instantiate.
560 *
Paolo Bonzinib76facc2013-01-25 14:12:39 +0100561 * This function will initialize a new object using heap allocated memory.
562 * The returned object has a reference count of 1, and will be freed when
563 * the last reference is dropped.
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600564 *
565 * Returns: The newly allocated and instantiated object.
566 */
567Object *object_new(const char *typename);
568
569/**
Daniel P. Berrangea31bdae2015-05-13 17:14:06 +0100570 * object_new_with_props:
571 * @typename: The name of the type of the object to instantiate.
572 * @parent: the parent object
573 * @id: The unique ID of the object
574 * @errp: pointer to error object
575 * @...: list of property names and values
576 *
577 * This function will initialize a new object using heap allocated memory.
578 * The returned object has a reference count of 1, and will be freed when
579 * the last reference is dropped.
580 *
581 * The @id parameter will be used when registering the object as a
582 * child of @parent in the composition tree.
583 *
584 * The variadic parameters are a list of pairs of (propname, propvalue)
585 * strings. The propname of %NULL indicates the end of the property
586 * list. If the object implements the user creatable interface, the
587 * object will be marked complete once all the properties have been
588 * processed.
589 *
Eduardo Habkost6cf164c2020-09-10 18:15:24 -0400590 * .. code-block:: c
591 * :caption: Creating an object with properties
592 *
Eduardo Habkost9bbfd242020-09-10 18:15:23 -0400593 * Error *err = NULL;
594 * Object *obj;
Daniel P. Berrangea31bdae2015-05-13 17:14:06 +0100595 *
Eduardo Habkost9bbfd242020-09-10 18:15:23 -0400596 * obj = object_new_with_props(TYPE_MEMORY_BACKEND_FILE,
597 * object_get_objects_root(),
598 * "hostmem0",
599 * &err,
600 * "share", "yes",
601 * "mem-path", "/dev/shm/somefile",
602 * "prealloc", "yes",
603 * "size", "1048576",
604 * NULL);
Daniel P. Berrangea31bdae2015-05-13 17:14:06 +0100605 *
Eduardo Habkost9bbfd242020-09-10 18:15:23 -0400606 * if (!obj) {
607 * error_reportf_err(err, "Cannot create memory backend: ");
608 * }
Daniel P. Berrangea31bdae2015-05-13 17:14:06 +0100609 *
610 * The returned object will have one stable reference maintained
611 * for as long as it is present in the object hierarchy.
612 *
613 * Returns: The newly allocated, instantiated & initialized object.
614 */
615Object *object_new_with_props(const char *typename,
616 Object *parent,
617 const char *id,
618 Error **errp,
Marc-André Lureau887ce502022-02-24 00:58:22 +0400619 ...) G_GNUC_NULL_TERMINATED;
Daniel P. Berrangea31bdae2015-05-13 17:14:06 +0100620
621/**
622 * object_new_with_propv:
623 * @typename: The name of the type of the object to instantiate.
624 * @parent: the parent object
625 * @id: The unique ID of the object
626 * @errp: pointer to error object
627 * @vargs: list of property names and values
628 *
629 * See object_new_with_props() for documentation.
630 */
631Object *object_new_with_propv(const char *typename,
632 Object *parent,
633 const char *id,
634 Error **errp,
635 va_list vargs);
636
Markus Armbruster6fd5bef2020-07-07 18:05:55 +0200637bool object_apply_global_props(Object *obj, const GPtrArray *props,
Marc-André Lureauea9ce892018-11-26 22:04:32 +0400638 Error **errp);
Markus Armbruster617902a2019-03-08 14:14:35 +0100639void object_set_machine_compat_props(GPtrArray *compat_props);
640void object_set_accelerator_compat_props(GPtrArray *compat_props);
Greg Kurza8dc82c2020-08-14 09:24:50 +0200641void object_register_sugar_prop(const char *driver, const char *prop,
642 const char *value, bool optional);
Markus Armbruster617902a2019-03-08 14:14:35 +0100643void object_apply_compat_props(Object *obj);
Marc-André Lureauea9ce892018-11-26 22:04:32 +0400644
Daniel P. Berrangea31bdae2015-05-13 17:14:06 +0100645/**
646 * object_set_props:
647 * @obj: the object instance to set properties on
648 * @errp: pointer to error object
649 * @...: list of property names and values
650 *
651 * This function will set a list of properties on an existing object
652 * instance.
653 *
654 * The variadic parameters are a list of pairs of (propname, propvalue)
655 * strings. The propname of %NULL indicates the end of the property
656 * list.
657 *
Eduardo Habkost6cf164c2020-09-10 18:15:24 -0400658 * .. code-block:: c
659 * :caption: Update an object's properties
660 *
Eduardo Habkost9bbfd242020-09-10 18:15:23 -0400661 * Error *err = NULL;
662 * Object *obj = ...get / create object...;
Daniel P. Berrangea31bdae2015-05-13 17:14:06 +0100663 *
Eduardo Habkost9bbfd242020-09-10 18:15:23 -0400664 * if (!object_set_props(obj,
665 * &err,
666 * "share", "yes",
667 * "mem-path", "/dev/shm/somefile",
668 * "prealloc", "yes",
669 * "size", "1048576",
670 * NULL)) {
671 * error_reportf_err(err, "Cannot set properties: ");
672 * }
Daniel P. Berrangea31bdae2015-05-13 17:14:06 +0100673 *
674 * The returned object will have one stable reference maintained
675 * for as long as it is present in the object hierarchy.
676 *
Markus Armbrusterb783f542020-07-07 18:05:58 +0200677 * Returns: %true on success, %false on error.
Daniel P. Berrangea31bdae2015-05-13 17:14:06 +0100678 */
Marc-André Lureau887ce502022-02-24 00:58:22 +0400679bool object_set_props(Object *obj, Error **errp, ...) G_GNUC_NULL_TERMINATED;
Daniel P. Berrangea31bdae2015-05-13 17:14:06 +0100680
681/**
682 * object_set_propv:
683 * @obj: the object instance to set properties on
684 * @errp: pointer to error object
685 * @vargs: list of property names and values
686 *
687 * See object_set_props() for documentation.
688 *
Markus Armbrusterb783f542020-07-07 18:05:58 +0200689 * Returns: %true on success, %false on error.
Daniel P. Berrangea31bdae2015-05-13 17:14:06 +0100690 */
Markus Armbrusterb783f542020-07-07 18:05:58 +0200691bool object_set_propv(Object *obj, Error **errp, va_list vargs);
Daniel P. Berrangea31bdae2015-05-13 17:14:06 +0100692
693/**
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600694 * object_initialize:
695 * @obj: A pointer to the memory to be used for the object.
Andreas Färber213f0c42013-08-23 19:37:12 +0200696 * @size: The maximum size available at @obj for the object.
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600697 * @typename: The name of the type of the object to instantiate.
698 *
699 * This function will initialize an object. The memory for the object should
Paolo Bonzinib76facc2013-01-25 14:12:39 +0100700 * have already been allocated. The returned object has a reference count of 1,
701 * and will be finalized when the last reference is dropped.
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600702 */
Andreas Färber213f0c42013-08-23 19:37:12 +0200703void object_initialize(void *obj, size_t size, const char *typename);
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600704
705/**
Markus Armbruster9fc7fc42020-06-10 07:32:25 +0200706 * object_initialize_child_with_props:
Thomas Huth0210b392018-07-16 14:59:18 +0200707 * @parentobj: The parent object to add a property to
708 * @propname: The name of the property
709 * @childobj: A pointer to the memory to be used for the object.
710 * @size: The maximum size available at @childobj for the object.
711 * @type: The name of the type of the object to instantiate.
712 * @errp: If an error occurs, a pointer to an area to store the error
713 * @...: list of property names and values
714 *
715 * This function will initialize an object. The memory for the object should
716 * have already been allocated. The object will then be added as child property
717 * to a parent with object_property_add_child() function. The returned object
718 * has a reference count of 1 (for the "child<...>" property from the parent),
719 * so the object will be finalized automatically when the parent gets removed.
720 *
721 * The variadic parameters are a list of pairs of (propname, propvalue)
722 * strings. The propname of %NULL indicates the end of the property list.
723 * If the object implements the user creatable interface, the object will
724 * be marked complete once all the properties have been processed.
Markus Armbruster6fd5bef2020-07-07 18:05:55 +0200725 *
726 * Returns: %true on success, %false on failure.
Thomas Huth0210b392018-07-16 14:59:18 +0200727 */
Markus Armbruster6fd5bef2020-07-07 18:05:55 +0200728bool object_initialize_child_with_props(Object *parentobj,
Markus Armbruster9fc7fc42020-06-10 07:32:25 +0200729 const char *propname,
Thomas Huth0210b392018-07-16 14:59:18 +0200730 void *childobj, size_t size, const char *type,
Marc-André Lureau887ce502022-02-24 00:58:22 +0400731 Error **errp, ...) G_GNUC_NULL_TERMINATED;
Thomas Huth0210b392018-07-16 14:59:18 +0200732
733/**
Markus Armbruster9fc7fc42020-06-10 07:32:25 +0200734 * object_initialize_child_with_propsv:
Thomas Huth0210b392018-07-16 14:59:18 +0200735 * @parentobj: The parent object to add a property to
736 * @propname: The name of the property
737 * @childobj: A pointer to the memory to be used for the object.
738 * @size: The maximum size available at @childobj for the object.
739 * @type: The name of the type of the object to instantiate.
740 * @errp: If an error occurs, a pointer to an area to store the error
741 * @vargs: list of property names and values
742 *
743 * See object_initialize_child() for documentation.
Markus Armbruster6fd5bef2020-07-07 18:05:55 +0200744 *
745 * Returns: %true on success, %false on failure.
Thomas Huth0210b392018-07-16 14:59:18 +0200746 */
Markus Armbruster6fd5bef2020-07-07 18:05:55 +0200747bool object_initialize_child_with_propsv(Object *parentobj,
Markus Armbruster9fc7fc42020-06-10 07:32:25 +0200748 const char *propname,
Thomas Huth0210b392018-07-16 14:59:18 +0200749 void *childobj, size_t size, const char *type,
750 Error **errp, va_list vargs);
751
752/**
Markus Armbruster9fc7fc42020-06-10 07:32:25 +0200753 * object_initialize_child:
754 * @parent: The parent object to add a property to
755 * @propname: The name of the property
756 * @child: A precisely typed pointer to the memory to be used for the
757 * object.
758 * @type: The name of the type of the object to instantiate.
759 *
Eduardo Habkost6cf164c2020-09-10 18:15:24 -0400760 * This is like::
761 *
762 * object_initialize_child_with_props(parent, propname,
763 * child, sizeof(*child), type,
764 * &error_abort, NULL)
Markus Armbruster9fc7fc42020-06-10 07:32:25 +0200765 */
766#define object_initialize_child(parent, propname, child, type) \
767 object_initialize_child_internal((parent), (propname), \
768 (child), sizeof(*(child)), (type))
769void object_initialize_child_internal(Object *parent, const char *propname,
770 void *child, size_t size,
771 const char *type);
772
773/**
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600774 * object_dynamic_cast:
775 * @obj: The object to cast.
776 * @typename: The @typename to cast to.
777 *
778 * This function will determine if @obj is-a @typename. @obj can refer to an
779 * object or an interface associated with an object.
780 *
781 * Returns: This function returns @obj on success or #NULL on failure.
782 */
783Object *object_dynamic_cast(Object *obj, const char *typename);
784
785/**
Andreas Färber438e1c72012-02-16 18:03:19 +0100786 * object_dynamic_cast_assert:
Eduardo Habkost1827c352020-09-10 18:15:18 -0400787 * @obj: The object to cast.
788 * @typename: The @typename to cast to.
789 * @file: Source code file where function was called
790 * @line: Source code line where function was called
791 * @func: Name of function where this function was called
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600792 *
793 * See object_dynamic_cast() for a description of the parameters of this
794 * function. The only difference in behavior is that this function asserts
Paolo Bonzini3556c232013-05-10 14:16:40 +0200795 * instead of returning #NULL on failure if QOM cast debugging is enabled.
796 * This function is not meant to be called directly, but only through
797 * the wrapper macro OBJECT_CHECK.
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600798 */
Paolo Bonzinibe17f182013-05-10 14:16:38 +0200799Object *object_dynamic_cast_assert(Object *obj, const char *typename,
800 const char *file, int line, const char *func);
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600801
802/**
803 * object_get_class:
804 * @obj: A derivative of #Object
805 *
806 * Returns: The #ObjectClass of the type associated with @obj.
807 */
808ObjectClass *object_get_class(Object *obj);
809
810/**
811 * object_get_typename:
812 * @obj: A derivative of #Object.
813 *
814 * Returns: The QOM typename of @obj.
815 */
Igor Mammedov8f5d58e2017-07-14 10:14:50 +0800816const char *object_get_typename(const Object *obj);
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600817
818/**
819 * type_register_static:
820 * @info: The #TypeInfo of the new type.
821 *
822 * @info and all of the strings it points to should exist for the life time
823 * that the type is registered.
824 *
Igor Mammedov31b93522017-10-04 12:08:00 +0200825 * Returns: the new #Type.
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600826 */
827Type type_register_static(const TypeInfo *info);
828
829/**
830 * type_register:
831 * @info: The #TypeInfo of the new type
832 *
Stefan Weil93148aa2012-02-26 18:46:12 +0100833 * Unlike type_register_static(), this call does not require @info or its
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600834 * string members to continue to exist after the call returns.
835 *
Igor Mammedov31b93522017-10-04 12:08:00 +0200836 * Returns: the new #Type.
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600837 */
838Type type_register(const TypeInfo *info);
839
840/**
Igor Mammedovaa04c9d22017-10-09 21:50:49 +0200841 * type_register_static_array:
842 * @infos: The array of the new type #TypeInfo structures.
843 * @nr_infos: number of entries in @infos
844 *
845 * @infos and all of the strings it points to should exist for the life time
846 * that the type is registered.
847 */
848void type_register_static_array(const TypeInfo *infos, int nr_infos);
849
850/**
Igor Mammedov38b5d792017-10-09 21:50:50 +0200851 * DEFINE_TYPES:
852 * @type_array: The array containing #TypeInfo structures to register
853 *
854 * @type_array should be static constant that exists for the life time
855 * that the type is registered.
856 */
857#define DEFINE_TYPES(type_array) \
858static void do_qemu_init_ ## type_array(void) \
859{ \
860 type_register_static_array(type_array, ARRAY_SIZE(type_array)); \
861} \
862type_init(do_qemu_init_ ## type_array)
863
864/**
Paolo Bonzini3bb69442020-11-02 11:08:07 -0500865 * type_print_class_properties:
866 * @type: a QOM class name
867 *
868 * Print the object's class properties to stdout or the monitor.
869 * Return whether an object was found.
870 */
871bool type_print_class_properties(const char *type);
872
873/**
874 * object_set_properties_from_keyval:
875 * @obj: a QOM object
876 * @qdict: a dictionary with the properties to be set
877 * @from_json: true if leaf values of @qdict are typed, false if they
878 * are strings
879 * @errp: pointer to error object
880 *
881 * For each key in the dictionary, parse the value string if needed,
882 * then set the corresponding property in @obj.
883 */
884void object_set_properties_from_keyval(Object *obj, const QDict *qdict,
885 bool from_json, Error **errp);
886
887/**
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600888 * object_class_dynamic_cast_assert:
889 * @klass: The #ObjectClass to attempt to cast.
890 * @typename: The QOM typename of the class to cast to.
Eduardo Habkost1827c352020-09-10 18:15:18 -0400891 * @file: Source code file where function was called
892 * @line: Source code line where function was called
893 * @func: Name of function where this function was called
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600894 *
Paolo Bonzini33bc94e2013-05-10 14:16:35 +0200895 * See object_class_dynamic_cast() for a description of the parameters
896 * of this function. The only difference in behavior is that this function
Paolo Bonzini3556c232013-05-10 14:16:40 +0200897 * asserts instead of returning #NULL on failure if QOM cast debugging is
898 * enabled. This function is not meant to be called directly, but only through
Eduardo Habkost04dcf4b2020-09-16 15:30:59 -0400899 * the wrapper macro OBJECT_CLASS_CHECK.
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600900 */
901ObjectClass *object_class_dynamic_cast_assert(ObjectClass *klass,
Paolo Bonzinibe17f182013-05-10 14:16:38 +0200902 const char *typename,
903 const char *file, int line,
904 const char *func);
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600905
Paolo Bonzini33bc94e2013-05-10 14:16:35 +0200906/**
907 * object_class_dynamic_cast:
908 * @klass: The #ObjectClass to attempt to cast.
909 * @typename: The QOM typename of the class to cast to.
910 *
911 * Returns: If @typename is a class, this function returns @klass if
912 * @typename is a subtype of @klass, else returns #NULL.
913 *
914 * If @typename is an interface, this function returns the interface
915 * definition for @klass if @klass implements it unambiguously; #NULL
916 * is returned if @klass does not implement the interface or if multiple
917 * classes or interfaces on the hierarchy leading to @klass implement
918 * it. (FIXME: perhaps this can be detected at type definition time?)
919 */
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600920ObjectClass *object_class_dynamic_cast(ObjectClass *klass,
921 const char *typename);
922
923/**
Paolo Bonzinie7cce672012-05-02 13:30:54 +0200924 * object_class_get_parent:
925 * @klass: The class to obtain the parent for.
926 *
927 * Returns: The parent for @klass or %NULL if none.
928 */
929ObjectClass *object_class_get_parent(ObjectClass *klass);
930
931/**
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600932 * object_class_get_name:
933 * @klass: The class to obtain the QOM typename for.
934 *
935 * Returns: The QOM typename for @klass.
936 */
937const char *object_class_get_name(ObjectClass *klass);
938
Paolo Bonzini0466e452012-05-02 13:30:53 +0200939/**
Andreas Färber17862372013-01-23 12:20:18 +0100940 * object_class_is_abstract:
941 * @klass: The class to obtain the abstractness for.
942 *
943 * Returns: %true if @klass is abstract, %false otherwise.
944 */
945bool object_class_is_abstract(ObjectClass *klass);
946
947/**
Paolo Bonzini0466e452012-05-02 13:30:53 +0200948 * object_class_by_name:
949 * @typename: The QOM typename to obtain the class for.
950 *
951 * Returns: The class for @typename or %NULL if not found.
952 */
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600953ObjectClass *object_class_by_name(const char *typename);
954
Gerd Hoffmann0f8198f2020-06-24 15:10:37 +0200955/**
956 * module_object_class_by_name:
957 * @typename: The QOM typename to obtain the class for.
958 *
959 * For objects which might be provided by a module. Behaves like
960 * object_class_by_name, but additionally tries to load the module
961 * needed in case the class is not available.
962 *
963 * Returns: The class for @typename or %NULL if not found.
964 */
965ObjectClass *module_object_class_by_name(const char *typename);
966
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600967void object_class_foreach(void (*fn)(ObjectClass *klass, void *opaque),
Anthony Liguori93c511a2011-12-22 14:11:53 -0600968 const char *implements_type, bool include_abstract,
Anthony Liguori2f28d2f2011-12-03 17:10:08 -0600969 void *opaque);
Andreas Färber418ba9e2012-02-25 23:07:34 +0100970
971/**
972 * object_class_get_list:
973 * @implements_type: The type to filter for, including its derivatives.
974 * @include_abstract: Whether to include abstract classes.
975 *
976 * Returns: A singly-linked list of the classes in reverse hashtable order.
977 */
978GSList *object_class_get_list(const char *implements_type,
979 bool include_abstract);
980
Anthony Liguori57c9faf2012-01-30 08:55:55 -0600981/**
Paolo Bonzini47c66002018-03-03 08:33:10 +0100982 * object_class_get_list_sorted:
983 * @implements_type: The type to filter for, including its derivatives.
984 * @include_abstract: Whether to include abstract classes.
985 *
986 * Returns: A singly-linked list of the classes in alphabetical
987 * case-insensitive order.
988 */
989GSList *object_class_get_list_sorted(const char *implements_type,
990 bool include_abstract);
991
992/**
Anthony Liguori57c9faf2012-01-30 08:55:55 -0600993 * object_ref:
994 * @obj: the object
995 *
996 * Increase the reference count of a object. A object cannot be freed as long
997 * as its reference count is greater than zero.
Marc-André Lureaub77ade92020-01-10 19:30:31 +0400998 * Returns: @obj
Anthony Liguori57c9faf2012-01-30 08:55:55 -0600999 */
Daniel P. Berrangéc5a61e52020-08-31 17:07:23 -04001000Object *object_ref(void *obj);
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001001
1002/**
Changlong Xieada03a02016-06-14 15:27:49 +08001003 * object_unref:
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001004 * @obj: the object
1005 *
1006 * Decrease the reference count of a object. A object cannot be freed as long
1007 * as its reference count is greater than zero.
1008 */
Daniel P. Berrangéc5a61e52020-08-31 17:07:23 -04001009void object_unref(void *obj);
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001010
1011/**
Eric Augerdb57fef2020-06-29 21:34:22 +02001012 * object_property_try_add:
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001013 * @obj: the object to add a property to
1014 * @name: the name of the property. This can contain any character except for
1015 * a forward slash. In general, you should use hyphens '-' instead of
1016 * underscores '_' when naming properties.
1017 * @type: the type name of the property. This namespace is pretty loosely
1018 * defined. Sub namespaces are constructed by using a prefix and then
1019 * to angle brackets. For instance, the type 'virtio-net-pci' in the
1020 * 'link' namespace would be 'link<virtio-net-pci>'.
1021 * @get: The getter to be called to read a property. If this is NULL, then
1022 * the property cannot be read.
1023 * @set: the setter to be called to write a property. If this is NULL,
1024 * then the property cannot be written.
1025 * @release: called when the property is removed from the object. This is
1026 * meant to allow a property to free its opaque upon object
1027 * destruction. This may be NULL.
1028 * @opaque: an opaque pointer to pass to the callbacks for the property
Eric Augerdb57fef2020-06-29 21:34:22 +02001029 * @errp: pointer to error object
Paolo Bonzini64607d02014-06-05 13:11:51 +02001030 *
1031 * Returns: The #ObjectProperty; this can be used to set the @resolve
1032 * callback for child and link properties.
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001033 */
Eric Augerdb57fef2020-06-29 21:34:22 +02001034ObjectProperty *object_property_try_add(Object *obj, const char *name,
1035 const char *type,
1036 ObjectPropertyAccessor *get,
1037 ObjectPropertyAccessor *set,
1038 ObjectPropertyRelease *release,
1039 void *opaque, Error **errp);
1040
1041/**
1042 * object_property_add:
1043 * Same as object_property_try_add() with @errp hardcoded to
1044 * &error_abort.
Eduardo Habkost1827c352020-09-10 18:15:18 -04001045 *
1046 * @obj: the object to add a property to
1047 * @name: the name of the property. This can contain any character except for
1048 * a forward slash. In general, you should use hyphens '-' instead of
1049 * underscores '_' when naming properties.
1050 * @type: the type name of the property. This namespace is pretty loosely
1051 * defined. Sub namespaces are constructed by using a prefix and then
1052 * to angle brackets. For instance, the type 'virtio-net-pci' in the
1053 * 'link' namespace would be 'link<virtio-net-pci>'.
1054 * @get: The getter to be called to read a property. If this is NULL, then
1055 * the property cannot be read.
1056 * @set: the setter to be called to write a property. If this is NULL,
1057 * then the property cannot be written.
1058 * @release: called when the property is removed from the object. This is
1059 * meant to allow a property to free its opaque upon object
1060 * destruction. This may be NULL.
1061 * @opaque: an opaque pointer to pass to the callbacks for the property
Eric Augerdb57fef2020-06-29 21:34:22 +02001062 */
Paolo Bonzini64607d02014-06-05 13:11:51 +02001063ObjectProperty *object_property_add(Object *obj, const char *name,
1064 const char *type,
1065 ObjectPropertyAccessor *get,
1066 ObjectPropertyAccessor *set,
1067 ObjectPropertyRelease *release,
Markus Armbrusterd2623122020-05-05 17:29:22 +02001068 void *opaque);
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001069
Markus Armbrusterdf4fe0b2020-05-05 17:29:26 +02001070void object_property_del(Object *obj, const char *name);
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001071
Daniel P. Berrange16bf7f52015-10-13 13:37:46 +01001072ObjectProperty *object_class_property_add(ObjectClass *klass, const char *name,
1073 const char *type,
1074 ObjectPropertyAccessor *get,
1075 ObjectPropertyAccessor *set,
1076 ObjectPropertyRelease *release,
Markus Armbrusterd2623122020-05-05 17:29:22 +02001077 void *opaque);
Daniel P. Berrange16bf7f52015-10-13 13:37:46 +01001078
Paolo Bonzini8cb67892012-03-30 14:54:31 +02001079/**
Marc-André Lureau0e76ed02020-01-10 19:30:23 +04001080 * object_property_set_default_bool:
1081 * @prop: the property to set
1082 * @value: the value to be written to the property
1083 *
1084 * Set the property default value.
1085 */
1086void object_property_set_default_bool(ObjectProperty *prop, bool value);
1087
1088/**
1089 * object_property_set_default_str:
1090 * @prop: the property to set
1091 * @value: the value to be written to the property
1092 *
1093 * Set the property default value.
1094 */
1095void object_property_set_default_str(ObjectProperty *prop, const char *value);
1096
1097/**
1098 * object_property_set_default_int:
1099 * @prop: the property to set
1100 * @value: the value to be written to the property
1101 *
1102 * Set the property default value.
1103 */
1104void object_property_set_default_int(ObjectProperty *prop, int64_t value);
1105
1106/**
1107 * object_property_set_default_uint:
1108 * @prop: the property to set
1109 * @value: the value to be written to the property
1110 *
1111 * Set the property default value.
1112 */
1113void object_property_set_default_uint(ObjectProperty *prop, uint64_t value);
1114
1115/**
Paolo Bonzini8cb67892012-03-30 14:54:31 +02001116 * object_property_find:
1117 * @obj: the object
1118 * @name: the name of the property
Daniel P. Berrangéefba1592020-09-14 14:56:17 +01001119 *
1120 * Look up a property for an object.
1121 *
1122 * Return its #ObjectProperty if found, or NULL.
1123 */
1124ObjectProperty *object_property_find(Object *obj, const char *name);
1125
1126/**
1127 * object_property_find_err:
1128 * @obj: the object
1129 * @name: the name of the property
Paolo Bonzini89bfe002012-04-12 18:00:18 +02001130 * @errp: returns an error if this function fails
Paolo Bonzini8cb67892012-03-30 14:54:31 +02001131 *
Daniel P. Berrangéefba1592020-09-14 14:56:17 +01001132 * Look up a property for an object.
1133 *
1134 * Return its #ObjectProperty if found, or NULL.
Paolo Bonzini8cb67892012-03-30 14:54:31 +02001135 */
Daniel P. Berrangéefba1592020-09-14 14:56:17 +01001136ObjectProperty *object_property_find_err(Object *obj,
1137 const char *name,
1138 Error **errp);
1139
1140/**
1141 * object_class_property_find:
1142 * @klass: the object class
1143 * @name: the name of the property
1144 *
1145 * Look up a property for an object class.
1146 *
1147 * Return its #ObjectProperty if found, or NULL.
1148 */
1149ObjectProperty *object_class_property_find(ObjectClass *klass,
1150 const char *name);
1151
1152/**
1153 * object_class_property_find_err:
1154 * @klass: the object class
1155 * @name: the name of the property
1156 * @errp: returns an error if this function fails
1157 *
1158 * Look up a property for an object class.
1159 *
1160 * Return its #ObjectProperty if found, or NULL.
1161 */
1162ObjectProperty *object_class_property_find_err(ObjectClass *klass,
1163 const char *name,
1164 Error **errp);
Paolo Bonzini8cb67892012-03-30 14:54:31 +02001165
Daniel P. Berrange7746abd2015-12-09 12:34:02 +00001166typedef struct ObjectPropertyIterator {
1167 ObjectClass *nextclass;
1168 GHashTableIter iter;
1169} ObjectPropertyIterator;
Daniel P. Berrangea00c9482015-10-13 13:37:40 +01001170
1171/**
1172 * object_property_iter_init:
Eduardo Habkost1827c352020-09-10 18:15:18 -04001173 * @iter: the iterator instance
Daniel P. Berrangea00c9482015-10-13 13:37:40 +01001174 * @obj: the object
1175 *
1176 * Initializes an iterator for traversing all properties
Daniel P. Berrange16bf7f52015-10-13 13:37:46 +01001177 * registered against an object instance, its class and all parent classes.
Daniel P. Berrangea00c9482015-10-13 13:37:40 +01001178 *
1179 * It is forbidden to modify the property list while iterating,
1180 * whether removing or adding properties.
1181 *
1182 * Typical usage pattern would be
1183 *
Eduardo Habkost6cf164c2020-09-10 18:15:24 -04001184 * .. code-block:: c
1185 * :caption: Using object property iterators
1186 *
Eduardo Habkost9bbfd242020-09-10 18:15:23 -04001187 * ObjectProperty *prop;
1188 * ObjectPropertyIterator iter;
Daniel P. Berrangea00c9482015-10-13 13:37:40 +01001189 *
Eduardo Habkost9bbfd242020-09-10 18:15:23 -04001190 * object_property_iter_init(&iter, obj);
1191 * while ((prop = object_property_iter_next(&iter))) {
1192 * ... do something with prop ...
1193 * }
Daniel P. Berrangea00c9482015-10-13 13:37:40 +01001194 */
Daniel P. Berrange7746abd2015-12-09 12:34:02 +00001195void object_property_iter_init(ObjectPropertyIterator *iter,
1196 Object *obj);
Daniel P. Berrangea00c9482015-10-13 13:37:40 +01001197
1198/**
Alexey Kardashevskiy961c47b2018-03-02 00:09:39 +11001199 * object_class_property_iter_init:
Eduardo Habkost1827c352020-09-10 18:15:18 -04001200 * @iter: the iterator instance
Alexey Kardashevskiy961c47b2018-03-02 00:09:39 +11001201 * @klass: the class
1202 *
1203 * Initializes an iterator for traversing all properties
1204 * registered against an object class and all parent classes.
1205 *
1206 * It is forbidden to modify the property list while iterating,
1207 * whether removing or adding properties.
1208 *
1209 * This can be used on abstract classes as it does not create a temporary
1210 * instance.
1211 */
1212void object_class_property_iter_init(ObjectPropertyIterator *iter,
1213 ObjectClass *klass);
1214
1215/**
Daniel P. Berrangea00c9482015-10-13 13:37:40 +01001216 * object_property_iter_next:
1217 * @iter: the iterator instance
1218 *
Daniel P. Berrange7746abd2015-12-09 12:34:02 +00001219 * Return the next available property. If no further properties
1220 * are available, a %NULL value will be returned and the @iter
1221 * pointer should not be used again after this point without
1222 * re-initializing it.
1223 *
Daniel P. Berrangea00c9482015-10-13 13:37:40 +01001224 * Returns: the next property, or %NULL when all properties
1225 * have been traversed.
1226 */
1227ObjectProperty *object_property_iter_next(ObjectPropertyIterator *iter);
1228
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001229void object_unparent(Object *obj);
1230
1231/**
1232 * object_property_get:
1233 * @obj: the object
Markus Armbruster5325cc32020-07-07 18:05:54 +02001234 * @name: the name of the property
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001235 * @v: the visitor that will receive the property value. This should be an
1236 * Output visitor and the data will be written with @name as the name.
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001237 * @errp: returns an error if this function fails
1238 *
1239 * Reads a property from a object.
Markus Armbruster6fd5bef2020-07-07 18:05:55 +02001240 *
1241 * Returns: %true on success, %false on failure.
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001242 */
Markus Armbruster6fd5bef2020-07-07 18:05:55 +02001243bool object_property_get(Object *obj, const char *name, Visitor *v,
Michael S. Tsirkine82df242013-09-22 10:08:14 +03001244 Error **errp);
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001245
1246/**
Paolo Bonzini7b7b7d12012-02-01 17:16:22 +01001247 * object_property_set_str:
Eduardo Habkost1827c352020-09-10 18:15:18 -04001248 * @obj: the object
Paolo Bonzini7b7b7d12012-02-01 17:16:22 +01001249 * @name: the name of the property
Markus Armbruster5325cc32020-07-07 18:05:54 +02001250 * @value: the value to be written to the property
Paolo Bonzini7b7b7d12012-02-01 17:16:22 +01001251 * @errp: returns an error if this function fails
1252 *
1253 * Writes a string value to a property.
Markus Armbruster6fd5bef2020-07-07 18:05:55 +02001254 *
1255 * Returns: %true on success, %false on failure.
Paolo Bonzini7b7b7d12012-02-01 17:16:22 +01001256 */
Markus Armbruster6fd5bef2020-07-07 18:05:55 +02001257bool object_property_set_str(Object *obj, const char *name,
Markus Armbruster5325cc32020-07-07 18:05:54 +02001258 const char *value, Error **errp);
Paolo Bonzini7b7b7d12012-02-01 17:16:22 +01001259
1260/**
1261 * object_property_get_str:
1262 * @obj: the object
1263 * @name: the name of the property
1264 * @errp: returns an error if this function fails
1265 *
1266 * Returns: the value of the property, converted to a C string, or NULL if
1267 * an error occurs (including when the property value is not a string).
1268 * The caller should free the string.
1269 */
1270char *object_property_get_str(Object *obj, const char *name,
Michael S. Tsirkine82df242013-09-22 10:08:14 +03001271 Error **errp);
Paolo Bonzini7b7b7d12012-02-01 17:16:22 +01001272
1273/**
Paolo Bonzini1d9c5a12012-02-02 10:51:57 +01001274 * object_property_set_link:
Eduardo Habkost1827c352020-09-10 18:15:18 -04001275 * @obj: the object
Paolo Bonzini1d9c5a12012-02-02 10:51:57 +01001276 * @name: the name of the property
Markus Armbruster5325cc32020-07-07 18:05:54 +02001277 * @value: the value to be written to the property
Paolo Bonzini1d9c5a12012-02-02 10:51:57 +01001278 * @errp: returns an error if this function fails
1279 *
1280 * Writes an object's canonical path to a property.
Marc-André Lureau265b5782018-05-31 21:51:17 +02001281 *
1282 * If the link property was created with
Eduardo Habkostb99e80c2020-10-02 22:54:23 -04001283 * %OBJ_PROP_LINK_STRONG bit, the old target object is
Marc-André Lureau265b5782018-05-31 21:51:17 +02001284 * unreferenced, and a reference is added to the new target object.
1285 *
Markus Armbruster6fd5bef2020-07-07 18:05:55 +02001286 * Returns: %true on success, %false on failure.
Paolo Bonzini1d9c5a12012-02-02 10:51:57 +01001287 */
Markus Armbruster6fd5bef2020-07-07 18:05:55 +02001288bool object_property_set_link(Object *obj, const char *name,
Markus Armbruster5325cc32020-07-07 18:05:54 +02001289 Object *value, Error **errp);
Paolo Bonzini1d9c5a12012-02-02 10:51:57 +01001290
1291/**
1292 * object_property_get_link:
1293 * @obj: the object
1294 * @name: the name of the property
1295 * @errp: returns an error if this function fails
1296 *
1297 * Returns: the value of the property, resolved from a path to an Object,
1298 * or NULL if an error occurs (including when the property value is not a
1299 * string or not a valid object path).
1300 */
1301Object *object_property_get_link(Object *obj, const char *name,
Michael S. Tsirkine82df242013-09-22 10:08:14 +03001302 Error **errp);
Paolo Bonzini1d9c5a12012-02-02 10:51:57 +01001303
1304/**
Paolo Bonzini7b7b7d12012-02-01 17:16:22 +01001305 * object_property_set_bool:
Eduardo Habkost1827c352020-09-10 18:15:18 -04001306 * @obj: the object
Paolo Bonzini7b7b7d12012-02-01 17:16:22 +01001307 * @name: the name of the property
Markus Armbruster5325cc32020-07-07 18:05:54 +02001308 * @value: the value to be written to the property
Paolo Bonzini7b7b7d12012-02-01 17:16:22 +01001309 * @errp: returns an error if this function fails
1310 *
1311 * Writes a bool value to a property.
Markus Armbruster6fd5bef2020-07-07 18:05:55 +02001312 *
1313 * Returns: %true on success, %false on failure.
Paolo Bonzini7b7b7d12012-02-01 17:16:22 +01001314 */
Markus Armbruster6fd5bef2020-07-07 18:05:55 +02001315bool object_property_set_bool(Object *obj, const char *name,
Markus Armbruster5325cc32020-07-07 18:05:54 +02001316 bool value, Error **errp);
Paolo Bonzini7b7b7d12012-02-01 17:16:22 +01001317
1318/**
1319 * object_property_get_bool:
1320 * @obj: the object
1321 * @name: the name of the property
1322 * @errp: returns an error if this function fails
1323 *
Markus Armbrustera21e6602020-09-17 14:55:40 +02001324 * Returns: the value of the property, converted to a boolean, or false if
Paolo Bonzini7b7b7d12012-02-01 17:16:22 +01001325 * an error occurs (including when the property value is not a bool).
1326 */
1327bool object_property_get_bool(Object *obj, const char *name,
Michael S. Tsirkine82df242013-09-22 10:08:14 +03001328 Error **errp);
Paolo Bonzini7b7b7d12012-02-01 17:16:22 +01001329
1330/**
1331 * object_property_set_int:
Eduardo Habkost1827c352020-09-10 18:15:18 -04001332 * @obj: the object
Paolo Bonzini7b7b7d12012-02-01 17:16:22 +01001333 * @name: the name of the property
Markus Armbruster5325cc32020-07-07 18:05:54 +02001334 * @value: the value to be written to the property
Paolo Bonzini7b7b7d12012-02-01 17:16:22 +01001335 * @errp: returns an error if this function fails
1336 *
1337 * Writes an integer value to a property.
Markus Armbruster6fd5bef2020-07-07 18:05:55 +02001338 *
1339 * Returns: %true on success, %false on failure.
Paolo Bonzini7b7b7d12012-02-01 17:16:22 +01001340 */
Markus Armbruster6fd5bef2020-07-07 18:05:55 +02001341bool object_property_set_int(Object *obj, const char *name,
Markus Armbruster5325cc32020-07-07 18:05:54 +02001342 int64_t value, Error **errp);
Paolo Bonzini7b7b7d12012-02-01 17:16:22 +01001343
1344/**
1345 * object_property_get_int:
1346 * @obj: the object
1347 * @name: the name of the property
1348 * @errp: returns an error if this function fails
1349 *
Markus Armbrustera21e6602020-09-17 14:55:40 +02001350 * Returns: the value of the property, converted to an integer, or -1 if
Paolo Bonzini7b7b7d12012-02-01 17:16:22 +01001351 * an error occurs (including when the property value is not an integer).
1352 */
1353int64_t object_property_get_int(Object *obj, const char *name,
Michael S. Tsirkine82df242013-09-22 10:08:14 +03001354 Error **errp);
Paolo Bonzini7b7b7d12012-02-01 17:16:22 +01001355
1356/**
Marc-André Lureau31527792017-06-07 20:36:04 +04001357 * object_property_set_uint:
Eduardo Habkost1827c352020-09-10 18:15:18 -04001358 * @obj: the object
Marc-André Lureau31527792017-06-07 20:36:04 +04001359 * @name: the name of the property
Markus Armbruster5325cc32020-07-07 18:05:54 +02001360 * @value: the value to be written to the property
Marc-André Lureau31527792017-06-07 20:36:04 +04001361 * @errp: returns an error if this function fails
1362 *
1363 * Writes an unsigned integer value to a property.
Markus Armbruster6fd5bef2020-07-07 18:05:55 +02001364 *
1365 * Returns: %true on success, %false on failure.
Marc-André Lureau31527792017-06-07 20:36:04 +04001366 */
Markus Armbruster6fd5bef2020-07-07 18:05:55 +02001367bool object_property_set_uint(Object *obj, const char *name,
Markus Armbruster5325cc32020-07-07 18:05:54 +02001368 uint64_t value, Error **errp);
Marc-André Lureau31527792017-06-07 20:36:04 +04001369
1370/**
1371 * object_property_get_uint:
1372 * @obj: the object
1373 * @name: the name of the property
1374 * @errp: returns an error if this function fails
1375 *
1376 * Returns: the value of the property, converted to an unsigned integer, or 0
1377 * an error occurs (including when the property value is not an integer).
1378 */
1379uint64_t object_property_get_uint(Object *obj, const char *name,
1380 Error **errp);
1381
1382/**
Hu Tao1f217722014-05-14 17:43:33 +08001383 * object_property_get_enum:
1384 * @obj: the object
1385 * @name: the name of the property
Daniel P. Berrangea3590da2015-05-27 16:07:56 +01001386 * @typename: the name of the enum data type
Hu Tao1f217722014-05-14 17:43:33 +08001387 * @errp: returns an error if this function fails
1388 *
Markus Armbrusterd20f6162020-09-17 14:55:39 +02001389 * Returns: the value of the property, converted to an integer (which
1390 * can't be negative), or -1 on error (including when the property
1391 * value is not an enum).
Hu Tao1f217722014-05-14 17:43:33 +08001392 */
1393int object_property_get_enum(Object *obj, const char *name,
Daniel P. Berrangea3590da2015-05-27 16:07:56 +01001394 const char *typename, Error **errp);
Hu Tao1f217722014-05-14 17:43:33 +08001395
1396/**
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001397 * object_property_set:
1398 * @obj: the object
Markus Armbruster5325cc32020-07-07 18:05:54 +02001399 * @name: the name of the property
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001400 * @v: the visitor that will be used to write the property value. This should
1401 * be an Input visitor and the data will be first read with @name as the
1402 * name and then written as the property value.
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001403 * @errp: returns an error if this function fails
1404 *
1405 * Writes a property to a object.
Markus Armbruster6fd5bef2020-07-07 18:05:55 +02001406 *
1407 * Returns: %true on success, %false on failure.
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001408 */
Markus Armbruster6fd5bef2020-07-07 18:05:55 +02001409bool object_property_set(Object *obj, const char *name, Visitor *v,
Michael S. Tsirkine82df242013-09-22 10:08:14 +03001410 Error **errp);
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001411
1412/**
Paolo Bonzinib2cd7de2012-02-09 09:52:59 +01001413 * object_property_parse:
1414 * @obj: the object
Paolo Bonzinib2cd7de2012-02-09 09:52:59 +01001415 * @name: the name of the property
Markus Armbruster5325cc32020-07-07 18:05:54 +02001416 * @string: the string that will be used to parse the property value.
Paolo Bonzinib2cd7de2012-02-09 09:52:59 +01001417 * @errp: returns an error if this function fails
1418 *
1419 * Parses a string and writes the result into a property of an object.
Markus Armbruster6fd5bef2020-07-07 18:05:55 +02001420 *
1421 * Returns: %true on success, %false on failure.
Paolo Bonzinib2cd7de2012-02-09 09:52:59 +01001422 */
Markus Armbruster6fd5bef2020-07-07 18:05:55 +02001423bool object_property_parse(Object *obj, const char *name,
Markus Armbruster5325cc32020-07-07 18:05:54 +02001424 const char *string, Error **errp);
Paolo Bonzinib2cd7de2012-02-09 09:52:59 +01001425
1426/**
1427 * object_property_print:
1428 * @obj: the object
1429 * @name: the name of the property
Paolo Bonzini0b7593e2014-02-08 11:01:50 +01001430 * @human: if true, print for human consumption
Paolo Bonzinib2cd7de2012-02-09 09:52:59 +01001431 * @errp: returns an error if this function fails
1432 *
1433 * Returns a string representation of the value of the property. The
1434 * caller shall free the string.
1435 */
Paolo Bonzini0b7593e2014-02-08 11:01:50 +01001436char *object_property_print(Object *obj, const char *name, bool human,
Michael S. Tsirkine82df242013-09-22 10:08:14 +03001437 Error **errp);
Paolo Bonzinib2cd7de2012-02-09 09:52:59 +01001438
1439/**
Andreas Färber438e1c72012-02-16 18:03:19 +01001440 * object_property_get_type:
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001441 * @obj: the object
1442 * @name: the name of the property
1443 * @errp: returns an error if this function fails
1444 *
1445 * Returns: The type name of the property.
1446 */
1447const char *object_property_get_type(Object *obj, const char *name,
Michael S. Tsirkine82df242013-09-22 10:08:14 +03001448 Error **errp);
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001449
1450/**
1451 * object_get_root:
1452 *
1453 * Returns: the root object of the composition tree
1454 */
1455Object *object_get_root(void);
1456
Daniel P. Berrangebc2256c2015-05-13 17:14:05 +01001457
1458/**
1459 * object_get_objects_root:
1460 *
1461 * Get the container object that holds user created
1462 * object instances. This is the object at path
1463 * "/objects"
1464 *
1465 * Returns: the user object container
1466 */
1467Object *object_get_objects_root(void);
1468
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001469/**
Peter Xu7c47c4e2017-09-28 10:59:54 +08001470 * object_get_internal_root:
1471 *
1472 * Get the container object that holds internally used object
1473 * instances. Any object which is put into this container must not be
1474 * user visible, and it will not be exposed in the QOM tree.
1475 *
1476 * Returns: the internal object container
1477 */
1478Object *object_get_internal_root(void);
1479
1480/**
Stefan Hajnoczi11f590b2014-03-03 11:30:02 +01001481 * object_get_canonical_path_component:
Eduardo Habkost1827c352020-09-10 18:15:18 -04001482 * @obj: the object
Stefan Hajnoczi11f590b2014-03-03 11:30:02 +01001483 *
1484 * Returns: The final component in the object's canonical path. The canonical
1485 * path is the path within the composition tree starting from the root.
Paolo Bonzini770dec22018-04-30 11:44:17 +02001486 * %NULL if the object doesn't have a parent (and thus a canonical path).
Stefan Hajnoczi11f590b2014-03-03 11:30:02 +01001487 */
Markus Armbruster7a309cc2020-07-14 18:02:00 +02001488const char *object_get_canonical_path_component(const Object *obj);
Stefan Hajnoczi11f590b2014-03-03 11:30:02 +01001489
1490/**
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001491 * object_get_canonical_path:
Eduardo Habkost1827c352020-09-10 18:15:18 -04001492 * @obj: the object
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001493 *
Markus Armbruster5bd929d2020-07-14 18:02:01 +02001494 * Returns: The canonical path for a object, newly allocated. This is
1495 * the path within the composition tree starting from the root. Use
1496 * g_free() to free it.
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001497 */
Markus Armbrustere8512df2020-05-27 10:47:53 +02001498char *object_get_canonical_path(const Object *obj);
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001499
1500/**
1501 * object_resolve_path:
1502 * @path: the path to resolve
1503 * @ambiguous: returns true if the path resolution failed because of an
1504 * ambiguous match
1505 *
1506 * There are two types of supported paths--absolute paths and partial paths.
1507 *
1508 * Absolute paths are derived from the root object and can follow child<> or
1509 * link<> properties. Since they can follow link<> properties, they can be
1510 * arbitrarily long. Absolute paths look like absolute filenames and are
1511 * prefixed with a leading slash.
1512 *
1513 * Partial paths look like relative filenames. They do not begin with a
1514 * prefix. The matching rules for partial paths are subtle but designed to make
1515 * specifying objects easy. At each level of the composition tree, the partial
1516 * path is matched as an absolute path. The first match is not returned. At
1517 * least two matches are searched for. A successful result is only returned if
Paolo Bonzini02fe2db2012-02-03 11:21:01 +01001518 * only one match is found. If more than one match is found, a flag is
1519 * returned to indicate that the match was ambiguous.
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001520 *
1521 * Returns: The matched object or NULL on path lookup failure.
1522 */
1523Object *object_resolve_path(const char *path, bool *ambiguous);
1524
1525/**
Paolo Bonzini02fe2db2012-02-03 11:21:01 +01001526 * object_resolve_path_type:
1527 * @path: the path to resolve
1528 * @typename: the type to look for.
1529 * @ambiguous: returns true if the path resolution failed because of an
1530 * ambiguous match
1531 *
1532 * This is similar to object_resolve_path. However, when looking for a
1533 * partial path only matches that implement the given type are considered.
1534 * This restricts the search and avoids spuriously flagging matches as
1535 * ambiguous.
1536 *
1537 * For both partial and absolute paths, the return value goes through
1538 * a dynamic cast to @typename. This is important if either the link,
1539 * or the typename itself are of interface types.
1540 *
1541 * Returns: The matched object or NULL on path lookup failure.
1542 */
1543Object *object_resolve_path_type(const char *path, const char *typename,
1544 bool *ambiguous);
1545
1546/**
Markus Armbruster1bf4d322021-10-19 10:57:11 +02001547 * object_resolve_path_at:
1548 * @parent: the object in which to resolve the path
1549 * @path: the path to resolve
1550 *
1551 * This is like object_resolve_path(), except paths not starting with
1552 * a slash are relative to @parent.
1553 *
1554 * Returns: The resolved object or NULL on path lookup failure.
1555 */
1556Object *object_resolve_path_at(Object *parent, const char *path);
1557
1558/**
Paolo Bonzinia612b2a2012-03-27 18:38:45 +02001559 * object_resolve_path_component:
1560 * @parent: the object in which to resolve the path
1561 * @part: the component to resolve.
1562 *
1563 * This is similar to object_resolve_path with an absolute path, but it
1564 * only resolves one element (@part) and takes the others from @parent.
1565 *
1566 * Returns: The resolved object or NULL on path lookup failure.
1567 */
Markus Armbrusterddfb0ba2020-05-05 17:29:10 +02001568Object *object_resolve_path_component(Object *parent, const char *part);
Paolo Bonzinia612b2a2012-03-27 18:38:45 +02001569
1570/**
Eric Augerdb57fef2020-06-29 21:34:22 +02001571 * object_property_try_add_child:
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001572 * @obj: the object to add a property to
1573 * @name: the name of the property
1574 * @child: the child object
Eric Augerdb57fef2020-06-29 21:34:22 +02001575 * @errp: pointer to error object
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001576 *
1577 * Child properties form the composition tree. All objects need to be a child
1578 * of another object. Objects can only be a child of one object.
1579 *
1580 * There is no way for a child to determine what its parent is. It is not
1581 * a bidirectional relationship. This is by design.
Alexander Barabash358b5462012-02-21 12:14:22 +02001582 *
1583 * The value of a child property as a C string will be the child object's
1584 * canonical path. It can be retrieved using object_property_get_str().
1585 * The child object itself can be retrieved using object_property_get_link().
Markus Armbruster70251882020-05-05 17:29:14 +02001586 *
1587 * Returns: The newly added property on success, or %NULL on failure.
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001588 */
Eric Augerdb57fef2020-06-29 21:34:22 +02001589ObjectProperty *object_property_try_add_child(Object *obj, const char *name,
1590 Object *child, Error **errp);
1591
1592/**
1593 * object_property_add_child:
Eduardo Habkost1827c352020-09-10 18:15:18 -04001594 * @obj: the object to add a property to
1595 * @name: the name of the property
1596 * @child: the child object
1597 *
Eric Augerdb57fef2020-06-29 21:34:22 +02001598 * Same as object_property_try_add_child() with @errp hardcoded to
1599 * &error_abort
1600 */
Markus Armbruster70251882020-05-05 17:29:14 +02001601ObjectProperty *object_property_add_child(Object *obj, const char *name,
Markus Armbrusterd2623122020-05-05 17:29:22 +02001602 Object *child);
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001603
Stefan Hajnoczi9561fda2014-03-19 08:58:55 +01001604typedef enum {
1605 /* Unref the link pointer when the property is deleted */
Marc-André Lureau265b5782018-05-31 21:51:17 +02001606 OBJ_PROP_LINK_STRONG = 0x1,
Marc-André Lureau9941d372020-01-10 19:30:27 +04001607
1608 /* private */
1609 OBJ_PROP_LINK_DIRECT = 0x2,
Marc-André Lureau840ecdf2020-01-10 19:30:29 +04001610 OBJ_PROP_LINK_CLASS = 0x4,
Stefan Hajnoczi9561fda2014-03-19 08:58:55 +01001611} ObjectPropertyLinkFlags;
1612
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001613/**
Stefan Hajnoczi39f72ef2014-03-19 08:58:56 +01001614 * object_property_allow_set_link:
Eduardo Habkost1827c352020-09-10 18:15:18 -04001615 * @obj: the object to add a property to
1616 * @name: the name of the property
1617 * @child: the child object
1618 * @errp: pointer to error object
Stefan Hajnoczi39f72ef2014-03-19 08:58:56 +01001619 *
1620 * The default implementation of the object_property_add_link() check()
1621 * callback function. It allows the link property to be set and never returns
1622 * an error.
1623 */
Eduardo Habkost1827c352020-09-10 18:15:18 -04001624void object_property_allow_set_link(const Object *obj, const char *name,
1625 Object *child, Error **errp);
Stefan Hajnoczi39f72ef2014-03-19 08:58:56 +01001626
1627/**
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001628 * object_property_add_link:
1629 * @obj: the object to add a property to
1630 * @name: the name of the property
1631 * @type: the qobj type of the link
Marc-André Lureau36854202020-01-10 19:30:26 +04001632 * @targetp: a pointer to where the link object reference is stored
Stefan Hajnoczi39f72ef2014-03-19 08:58:56 +01001633 * @check: callback to veto setting or NULL if the property is read-only
Stefan Hajnoczi9561fda2014-03-19 08:58:55 +01001634 * @flags: additional options for the link
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001635 *
1636 * Links establish relationships between objects. Links are unidirectional
1637 * although two links can be combined to form a bidirectional relationship
1638 * between objects.
1639 *
1640 * Links form the graph in the object model.
Paolo Bonzini6c232d22013-01-25 14:12:31 +01001641 *
Eduardo Habkostb99e80c2020-10-02 22:54:23 -04001642 * The @check() callback is invoked when
Stefan Hajnoczi39f72ef2014-03-19 08:58:56 +01001643 * object_property_set_link() is called and can raise an error to prevent the
Eduardo Habkostb99e80c2020-10-02 22:54:23 -04001644 * link being set. If @check is NULL, the property is read-only
Stefan Hajnoczi39f72ef2014-03-19 08:58:56 +01001645 * and cannot be set.
1646 *
Paolo Bonzini6c232d22013-01-25 14:12:31 +01001647 * Ownership of the pointer that @child points to is transferred to the
Eduardo Habkostb99e80c2020-10-02 22:54:23 -04001648 * link property. The reference count for *@child is
Paolo Bonzini6c232d22013-01-25 14:12:31 +01001649 * managed by the property from after the function returns till the
Stefan Hajnoczi9561fda2014-03-19 08:58:55 +01001650 * property is deleted with object_property_del(). If the
Eduardo Habkostb99e80c2020-10-02 22:54:23 -04001651 * @flags %OBJ_PROP_LINK_STRONG bit is set,
Marc-André Lureau265b5782018-05-31 21:51:17 +02001652 * the reference count is decremented when the property is deleted or
1653 * modified.
Markus Armbruster70251882020-05-05 17:29:14 +02001654 *
1655 * Returns: The newly added property on success, or %NULL on failure.
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001656 */
Markus Armbruster70251882020-05-05 17:29:14 +02001657ObjectProperty *object_property_add_link(Object *obj, const char *name,
Marc-André Lureau36854202020-01-10 19:30:26 +04001658 const char *type, Object **targetp,
Igor Mammedov8f5d58e2017-07-14 10:14:50 +08001659 void (*check)(const Object *obj, const char *name,
Stefan Hajnoczi39f72ef2014-03-19 08:58:56 +01001660 Object *val, Error **errp),
Markus Armbrusterd2623122020-05-05 17:29:22 +02001661 ObjectPropertyLinkFlags flags);
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001662
Marc-André Lureau840ecdf2020-01-10 19:30:29 +04001663ObjectProperty *object_class_property_add_link(ObjectClass *oc,
1664 const char *name,
1665 const char *type, ptrdiff_t offset,
1666 void (*check)(const Object *obj, const char *name,
1667 Object *val, Error **errp),
Markus Armbrusterd2623122020-05-05 17:29:22 +02001668 ObjectPropertyLinkFlags flags);
Marc-André Lureau840ecdf2020-01-10 19:30:29 +04001669
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001670/**
1671 * object_property_add_str:
1672 * @obj: the object to add a property to
1673 * @name: the name of the property
1674 * @get: the getter or NULL if the property is write-only. This function must
1675 * return a string to be freed by g_free().
1676 * @set: the setter or NULL if the property is read-only
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001677 *
1678 * Add a string property using getters/setters. This function will add a
1679 * property of type 'string'.
Markus Armbruster70251882020-05-05 17:29:14 +02001680 *
1681 * Returns: The newly added property on success, or %NULL on failure.
Anthony Liguori57c9faf2012-01-30 08:55:55 -06001682 */
Markus Armbruster70251882020-05-05 17:29:14 +02001683ObjectProperty *object_property_add_str(Object *obj, const char *name,
Michael S. Tsirkine82df242013-09-22 10:08:14 +03001684 char *(*get)(Object *, Error **),
Markus Armbrusterd2623122020-05-05 17:29:22 +02001685 void (*set)(Object *, const char *, Error **));
Anthony Liguori2f28d2f2011-12-03 17:10:08 -06001686
Marc-André Lureaua3a16212020-01-10 19:30:21 +04001687ObjectProperty *object_class_property_add_str(ObjectClass *klass,
1688 const char *name,
Daniel P. Berrange16bf7f52015-10-13 13:37:46 +01001689 char *(*get)(Object *, Error **),
1690 void (*set)(Object *, const char *,
Markus Armbrusterd2623122020-05-05 17:29:22 +02001691 Error **));
Daniel P. Berrange16bf7f52015-10-13 13:37:46 +01001692
Paolo Bonzinia612b2a2012-03-27 18:38:45 +02001693/**
Anthony Liguori0e558842012-06-25 10:32:46 -05001694 * object_property_add_bool:
1695 * @obj: the object to add a property to
1696 * @name: the name of the property
1697 * @get: the getter or NULL if the property is write-only.
1698 * @set: the setter or NULL if the property is read-only
Anthony Liguori0e558842012-06-25 10:32:46 -05001699 *
1700 * Add a bool property using getters/setters. This function will add a
1701 * property of type 'bool'.
Markus Armbruster70251882020-05-05 17:29:14 +02001702 *
1703 * Returns: The newly added property on success, or %NULL on failure.
Anthony Liguori0e558842012-06-25 10:32:46 -05001704 */
Markus Armbruster70251882020-05-05 17:29:14 +02001705ObjectProperty *object_property_add_bool(Object *obj, const char *name,
Michael S. Tsirkine82df242013-09-22 10:08:14 +03001706 bool (*get)(Object *, Error **),
Markus Armbrusterd2623122020-05-05 17:29:22 +02001707 void (*set)(Object *, bool, Error **));
Anthony Liguori0e558842012-06-25 10:32:46 -05001708
Marc-André Lureaua3a16212020-01-10 19:30:21 +04001709ObjectProperty *object_class_property_add_bool(ObjectClass *klass,
1710 const char *name,
Daniel P. Berrange16bf7f52015-10-13 13:37:46 +01001711 bool (*get)(Object *, Error **),
Markus Armbrusterd2623122020-05-05 17:29:22 +02001712 void (*set)(Object *, bool, Error **));
Daniel P. Berrange16bf7f52015-10-13 13:37:46 +01001713
Anthony Liguori0e558842012-06-25 10:32:46 -05001714/**
Daniel P. Berrangea8e3fbe2015-05-13 17:14:08 +01001715 * object_property_add_enum:
1716 * @obj: the object to add a property to
1717 * @name: the name of the property
1718 * @typename: the name of the enum data type
Eduardo Habkost1827c352020-09-10 18:15:18 -04001719 * @lookup: enum value namelookup table
Daniel P. Berrangea8e3fbe2015-05-13 17:14:08 +01001720 * @get: the getter or %NULL if the property is write-only.
1721 * @set: the setter or %NULL if the property is read-only
Daniel P. Berrangea8e3fbe2015-05-13 17:14:08 +01001722 *
1723 * Add an enum property using getters/setters. This function will add a
1724 * property of type '@typename'.
Markus Armbruster70251882020-05-05 17:29:14 +02001725 *
1726 * Returns: The newly added property on success, or %NULL on failure.
Daniel P. Berrangea8e3fbe2015-05-13 17:14:08 +01001727 */
Markus Armbruster70251882020-05-05 17:29:14 +02001728ObjectProperty *object_property_add_enum(Object *obj, const char *name,
Daniel P. Berrangea8e3fbe2015-05-13 17:14:08 +01001729 const char *typename,
Marc-André Lureauf7abe0e2017-08-24 10:46:10 +02001730 const QEnumLookup *lookup,
Daniel P. Berrangea8e3fbe2015-05-13 17:14:08 +01001731 int (*get)(Object *, Error **),
Markus Armbrusterd2623122020-05-05 17:29:22 +02001732 void (*set)(Object *, int, Error **));
Daniel P. Berrangea8e3fbe2015-05-13 17:14:08 +01001733
Marc-André Lureaua3a16212020-01-10 19:30:21 +04001734ObjectProperty *object_class_property_add_enum(ObjectClass *klass,
1735 const char *name,
Daniel P. Berrange16bf7f52015-10-13 13:37:46 +01001736 const char *typename,
Marc-André Lureauf7abe0e2017-08-24 10:46:10 +02001737 const QEnumLookup *lookup,
Daniel P. Berrange16bf7f52015-10-13 13:37:46 +01001738 int (*get)(Object *, Error **),
Markus Armbrusterd2623122020-05-05 17:29:22 +02001739 void (*set)(Object *, int, Error **));
Daniel P. Berrange16bf7f52015-10-13 13:37:46 +01001740
Daniel P. Berrangea8e3fbe2015-05-13 17:14:08 +01001741/**
David Gibson8e099d12015-02-06 14:55:45 +11001742 * object_property_add_tm:
1743 * @obj: the object to add a property to
1744 * @name: the name of the property
1745 * @get: the getter or NULL if the property is write-only.
David Gibson8e099d12015-02-06 14:55:45 +11001746 *
1747 * Add a read-only struct tm valued property using a getter function.
1748 * This function will add a property of type 'struct tm'.
Markus Armbruster70251882020-05-05 17:29:14 +02001749 *
1750 * Returns: The newly added property on success, or %NULL on failure.
David Gibson8e099d12015-02-06 14:55:45 +11001751 */
Markus Armbruster70251882020-05-05 17:29:14 +02001752ObjectProperty *object_property_add_tm(Object *obj, const char *name,
Markus Armbrusterd2623122020-05-05 17:29:22 +02001753 void (*get)(Object *, struct tm *, Error **));
David Gibson8e099d12015-02-06 14:55:45 +11001754
Marc-André Lureaua3a16212020-01-10 19:30:21 +04001755ObjectProperty *object_class_property_add_tm(ObjectClass *klass,
Markus Armbrusterd2623122020-05-05 17:29:22 +02001756 const char *name,
1757 void (*get)(Object *, struct tm *, Error **));
Daniel P. Berrange16bf7f52015-10-13 13:37:46 +01001758
Felipe Franciosi836e1b32020-02-04 13:15:58 +00001759typedef enum {
1760 /* Automatically add a getter to the property */
1761 OBJ_PROP_FLAG_READ = 1 << 0,
1762 /* Automatically add a setter to the property */
1763 OBJ_PROP_FLAG_WRITE = 1 << 1,
1764 /* Automatically add a getter and a setter to the property */
1765 OBJ_PROP_FLAG_READWRITE = (OBJ_PROP_FLAG_READ | OBJ_PROP_FLAG_WRITE),
1766} ObjectPropertyFlags;
1767
David Gibson8e099d12015-02-06 14:55:45 +11001768/**
Michael S. Tsirkina25ebca2013-10-07 12:35:01 +03001769 * object_property_add_uint8_ptr:
1770 * @obj: the object to add a property to
1771 * @name: the name of the property
1772 * @v: pointer to value
Felipe Franciosi836e1b32020-02-04 13:15:58 +00001773 * @flags: bitwise-or'd ObjectPropertyFlags
Michael S. Tsirkina25ebca2013-10-07 12:35:01 +03001774 *
1775 * Add an integer property in memory. This function will add a
1776 * property of type 'uint8'.
Markus Armbruster70251882020-05-05 17:29:14 +02001777 *
1778 * Returns: The newly added property on success, or %NULL on failure.
Michael S. Tsirkina25ebca2013-10-07 12:35:01 +03001779 */
Markus Armbruster70251882020-05-05 17:29:14 +02001780ObjectProperty *object_property_add_uint8_ptr(Object *obj, const char *name,
Markus Armbrusterd2623122020-05-05 17:29:22 +02001781 const uint8_t *v,
1782 ObjectPropertyFlags flags);
Felipe Franciosi836e1b32020-02-04 13:15:58 +00001783
Marc-André Lureaua3a16212020-01-10 19:30:21 +04001784ObjectProperty *object_class_property_add_uint8_ptr(ObjectClass *klass,
1785 const char *name,
Felipe Franciosi836e1b32020-02-04 13:15:58 +00001786 const uint8_t *v,
Markus Armbrusterd2623122020-05-05 17:29:22 +02001787 ObjectPropertyFlags flags);
Michael S. Tsirkina25ebca2013-10-07 12:35:01 +03001788
1789/**
1790 * object_property_add_uint16_ptr:
1791 * @obj: the object to add a property to
1792 * @name: the name of the property
1793 * @v: pointer to value
Felipe Franciosi836e1b32020-02-04 13:15:58 +00001794 * @flags: bitwise-or'd ObjectPropertyFlags
Michael S. Tsirkina25ebca2013-10-07 12:35:01 +03001795 *
1796 * Add an integer property in memory. This function will add a
1797 * property of type 'uint16'.
Markus Armbruster70251882020-05-05 17:29:14 +02001798 *
1799 * Returns: The newly added property on success, or %NULL on failure.
Michael S. Tsirkina25ebca2013-10-07 12:35:01 +03001800 */
Markus Armbruster70251882020-05-05 17:29:14 +02001801ObjectProperty *object_property_add_uint16_ptr(Object *obj, const char *name,
Felipe Franciosi836e1b32020-02-04 13:15:58 +00001802 const uint16_t *v,
Markus Armbrusterd2623122020-05-05 17:29:22 +02001803 ObjectPropertyFlags flags);
Felipe Franciosi836e1b32020-02-04 13:15:58 +00001804
Marc-André Lureaua3a16212020-01-10 19:30:21 +04001805ObjectProperty *object_class_property_add_uint16_ptr(ObjectClass *klass,
1806 const char *name,
Felipe Franciosi836e1b32020-02-04 13:15:58 +00001807 const uint16_t *v,
Markus Armbrusterd2623122020-05-05 17:29:22 +02001808 ObjectPropertyFlags flags);
Michael S. Tsirkina25ebca2013-10-07 12:35:01 +03001809
1810/**
1811 * object_property_add_uint32_ptr:
1812 * @obj: the object to add a property to
1813 * @name: the name of the property
1814 * @v: pointer to value
Felipe Franciosi836e1b32020-02-04 13:15:58 +00001815 * @flags: bitwise-or'd ObjectPropertyFlags
Michael S. Tsirkina25ebca2013-10-07 12:35:01 +03001816 *
1817 * Add an integer property in memory. This function will add a
1818 * property of type 'uint32'.
Markus Armbruster70251882020-05-05 17:29:14 +02001819 *
1820 * Returns: The newly added property on success, or %NULL on failure.
Michael S. Tsirkina25ebca2013-10-07 12:35:01 +03001821 */
Markus Armbruster70251882020-05-05 17:29:14 +02001822ObjectProperty *object_property_add_uint32_ptr(Object *obj, const char *name,
Felipe Franciosi836e1b32020-02-04 13:15:58 +00001823 const uint32_t *v,
Markus Armbrusterd2623122020-05-05 17:29:22 +02001824 ObjectPropertyFlags flags);
Felipe Franciosi836e1b32020-02-04 13:15:58 +00001825
Marc-André Lureaua3a16212020-01-10 19:30:21 +04001826ObjectProperty *object_class_property_add_uint32_ptr(ObjectClass *klass,
1827 const char *name,
Felipe Franciosi836e1b32020-02-04 13:15:58 +00001828 const uint32_t *v,
Markus Armbrusterd2623122020-05-05 17:29:22 +02001829 ObjectPropertyFlags flags);
Michael S. Tsirkina25ebca2013-10-07 12:35:01 +03001830
1831/**
1832 * object_property_add_uint64_ptr:
1833 * @obj: the object to add a property to
1834 * @name: the name of the property
1835 * @v: pointer to value
Felipe Franciosi836e1b32020-02-04 13:15:58 +00001836 * @flags: bitwise-or'd ObjectPropertyFlags
Michael S. Tsirkina25ebca2013-10-07 12:35:01 +03001837 *
1838 * Add an integer property in memory. This function will add a
1839 * property of type 'uint64'.
Markus Armbruster70251882020-05-05 17:29:14 +02001840 *
1841 * Returns: The newly added property on success, or %NULL on failure.
Michael S. Tsirkina25ebca2013-10-07 12:35:01 +03001842 */
Markus Armbruster70251882020-05-05 17:29:14 +02001843ObjectProperty *object_property_add_uint64_ptr(Object *obj, const char *name,
Felipe Franciosi836e1b32020-02-04 13:15:58 +00001844 const uint64_t *v,
Markus Armbrusterd2623122020-05-05 17:29:22 +02001845 ObjectPropertyFlags flags);
Felipe Franciosi836e1b32020-02-04 13:15:58 +00001846
Marc-André Lureaua3a16212020-01-10 19:30:21 +04001847ObjectProperty *object_class_property_add_uint64_ptr(ObjectClass *klass,
1848 const char *name,
Felipe Franciosi836e1b32020-02-04 13:15:58 +00001849 const uint64_t *v,
Markus Armbrusterd2623122020-05-05 17:29:22 +02001850 ObjectPropertyFlags flags);
Michael S. Tsirkina25ebca2013-10-07 12:35:01 +03001851
1852/**
Stefan Hajnoczief7c7ff2014-06-18 17:58:28 +08001853 * object_property_add_alias:
1854 * @obj: the object to add a property to
1855 * @name: the name of the property
1856 * @target_obj: the object to forward property access to
1857 * @target_name: the name of the property on the forwarded object
Stefan Hajnoczief7c7ff2014-06-18 17:58:28 +08001858 *
1859 * Add an alias for a property on an object. This function will add a property
1860 * of the same type as the forwarded property.
1861 *
Eduardo Habkostb99e80c2020-10-02 22:54:23 -04001862 * The caller must ensure that @target_obj stays alive as long as
Stefan Hajnoczief7c7ff2014-06-18 17:58:28 +08001863 * this property exists. In the case of a child object or an alias on the same
1864 * object this will be the case. For aliases to other objects the caller is
1865 * responsible for taking a reference.
Markus Armbruster70251882020-05-05 17:29:14 +02001866 *
1867 * Returns: The newly added property on success, or %NULL on failure.
Stefan Hajnoczief7c7ff2014-06-18 17:58:28 +08001868 */
Markus Armbruster70251882020-05-05 17:29:14 +02001869ObjectProperty *object_property_add_alias(Object *obj, const char *name,
Markus Armbrusterd2623122020-05-05 17:29:22 +02001870 Object *target_obj, const char *target_name);
Stefan Hajnoczief7c7ff2014-06-18 17:58:28 +08001871
1872/**
Paolo Bonzinifb9e7e32015-05-05 18:29:00 +02001873 * object_property_add_const_link:
1874 * @obj: the object to add a property to
1875 * @name: the name of the property
1876 * @target: the object to be referred by the link
Paolo Bonzinifb9e7e32015-05-05 18:29:00 +02001877 *
1878 * Add an unmodifiable link for a property on an object. This function will
1879 * add a property of type link<TYPE> where TYPE is the type of @target.
1880 *
1881 * The caller must ensure that @target stays alive as long as
1882 * this property exists. In the case @target is a child of @obj,
1883 * this will be the case. Otherwise, the caller is responsible for
1884 * taking a reference.
Markus Armbruster70251882020-05-05 17:29:14 +02001885 *
1886 * Returns: The newly added property on success, or %NULL on failure.
Paolo Bonzinifb9e7e32015-05-05 18:29:00 +02001887 */
Markus Armbruster70251882020-05-05 17:29:14 +02001888ObjectProperty *object_property_add_const_link(Object *obj, const char *name,
Markus Armbrusterd2623122020-05-05 17:29:22 +02001889 Object *target);
Paolo Bonzinifb9e7e32015-05-05 18:29:00 +02001890
1891/**
Gonglei80742642014-10-07 14:33:21 +08001892 * object_property_set_description:
1893 * @obj: the object owning the property
1894 * @name: the name of the property
1895 * @description: the description of the property on the object
Gonglei80742642014-10-07 14:33:21 +08001896 *
1897 * Set an object property's description.
1898 *
Markus Armbruster6fd5bef2020-07-07 18:05:55 +02001899 * Returns: %true on success, %false on failure.
Gonglei80742642014-10-07 14:33:21 +08001900 */
1901void object_property_set_description(Object *obj, const char *name,
Markus Armbruster7eecec72020-05-05 17:29:15 +02001902 const char *description);
Daniel P. Berrange16bf7f52015-10-13 13:37:46 +01001903void object_class_property_set_description(ObjectClass *klass, const char *name,
Markus Armbruster7eecec72020-05-05 17:29:15 +02001904 const char *description);
Gonglei80742642014-10-07 14:33:21 +08001905
1906/**
Paolo Bonzini32efc532012-04-11 23:30:20 +02001907 * object_child_foreach:
1908 * @obj: the object whose children will be navigated
1909 * @fn: the iterator function to be called
1910 * @opaque: an opaque value that will be passed to the iterator
1911 *
1912 * Call @fn passing each child of @obj and @opaque to it, until @fn returns
1913 * non-zero.
1914 *
Pavel Fedinb604a852015-10-13 13:37:45 +01001915 * It is forbidden to add or remove children from @obj from the @fn
1916 * callback.
1917 *
Paolo Bonzini32efc532012-04-11 23:30:20 +02001918 * Returns: The last value returned by @fn, or 0 if there is no child.
1919 */
1920int object_child_foreach(Object *obj, int (*fn)(Object *child, void *opaque),
1921 void *opaque);
1922
1923/**
Peter Crosthwaited714b8d2015-09-08 17:38:43 +01001924 * object_child_foreach_recursive:
1925 * @obj: the object whose children will be navigated
1926 * @fn: the iterator function to be called
1927 * @opaque: an opaque value that will be passed to the iterator
1928 *
1929 * Call @fn passing each child of @obj and @opaque to it, until @fn returns
1930 * non-zero. Calls recursively, all child nodes of @obj will also be passed
1931 * all the way down to the leaf nodes of the tree. Depth first ordering.
1932 *
Pavel Fedinb604a852015-10-13 13:37:45 +01001933 * It is forbidden to add or remove children from @obj (or its
1934 * child nodes) from the @fn callback.
1935 *
Peter Crosthwaited714b8d2015-09-08 17:38:43 +01001936 * Returns: The last value returned by @fn, or 0 if there is no child.
1937 */
1938int object_child_foreach_recursive(Object *obj,
1939 int (*fn)(Object *child, void *opaque),
1940 void *opaque);
1941/**
Paolo Bonzinia612b2a2012-03-27 18:38:45 +02001942 * container_get:
Andreas Färberdfe47e72012-04-05 13:21:46 +02001943 * @root: root of the #path, e.g., object_get_root()
Paolo Bonzinia612b2a2012-03-27 18:38:45 +02001944 * @path: path to the container
1945 *
1946 * Return a container object whose path is @path. Create more containers
1947 * along the path if necessary.
1948 *
1949 * Returns: the container object.
1950 */
Andreas Färberdfe47e72012-04-05 13:21:46 +02001951Object *container_get(Object *root, const char *path);
Paolo Bonzinia612b2a2012-03-27 18:38:45 +02001952
Bharata B Rao3f97b532016-06-10 06:29:00 +05301953/**
1954 * object_type_get_instance_size:
1955 * @typename: Name of the Type whose instance_size is required
1956 *
1957 * Returns the instance_size of the given @typename.
1958 */
1959size_t object_type_get_instance_size(const char *typename);
Marc-André Lureauf60a1cd2019-11-08 18:02:25 +04001960
Marc-André Lureau4df81612020-01-10 19:30:37 +04001961/**
1962 * object_property_help:
1963 * @name: the name of the property
1964 * @type: the type of the property
1965 * @defval: the default value
1966 * @description: description of the property
1967 *
1968 * Returns: a user-friendly formatted string describing the property
1969 * for help purposes.
1970 */
1971char *object_property_help(const char *name, const char *type,
1972 QObject *defval, const char *description);
1973
Marc-André Lureauf60a1cd2019-11-08 18:02:25 +04001974G_DEFINE_AUTOPTR_CLEANUP_FUNC(Object, object_unref)
1975
Anthony Liguori2f28d2f2011-12-03 17:10:08 -06001976#endif