xref: /openbmc/qemu/include/qom/object.h (revision e54c2433)
1 /*
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 
17 #include "qapi/qapi-builtin-types.h"
18 #include "qemu/module.h"
19 
20 struct TypeImpl;
21 typedef struct TypeImpl *Type;
22 
23 typedef struct TypeInfo TypeInfo;
24 
25 typedef struct InterfaceClass InterfaceClass;
26 typedef struct InterfaceInfo InterfaceInfo;
27 
28 #define TYPE_OBJECT "object"
29 
30 typedef struct ObjectProperty ObjectProperty;
31 
32 /**
33  * typedef ObjectPropertyAccessor:
34  * @obj: the object that owns the property
35  * @v: the visitor that contains the property data
36  * @name: the name of the property
37  * @opaque: the object property opaque
38  * @errp: a pointer to an Error that is filled if getting/setting fails.
39  *
40  * Called when trying to get/set a property.
41  */
42 typedef void (ObjectPropertyAccessor)(Object *obj,
43                                       Visitor *v,
44                                       const char *name,
45                                       void *opaque,
46                                       Error **errp);
47 
48 /**
49  * typedef ObjectPropertyResolve:
50  * @obj: the object that owns the property
51  * @opaque: the opaque registered with the property
52  * @part: the name of the property
53  *
54  * Resolves the #Object corresponding to property @part.
55  *
56  * The returned object can also be used as a starting point
57  * to resolve a relative path starting with "@part".
58  *
59  * Returns: If @path is the path that led to @obj, the function
60  * returns the #Object corresponding to "@path/@part".
61  * If "@path/@part" is not a valid object path, it returns #NULL.
62  */
63 typedef Object *(ObjectPropertyResolve)(Object *obj,
64                                         void *opaque,
65                                         const char *part);
66 
67 /**
68  * typedef ObjectPropertyRelease:
69  * @obj: the object that owns the property
70  * @name: the name of the property
71  * @opaque: the opaque registered with the property
72  *
73  * Called when a property is removed from a object.
74  */
75 typedef void (ObjectPropertyRelease)(Object *obj,
76                                      const char *name,
77                                      void *opaque);
78 
79 /**
80  * typedef ObjectPropertyInit:
81  * @obj: the object that owns the property
82  * @prop: the property to set
83  *
84  * Called when a property is initialized.
85  */
86 typedef void (ObjectPropertyInit)(Object *obj, ObjectProperty *prop);
87 
88 struct ObjectProperty
89 {
90     char *name;
91     char *type;
92     char *description;
93     ObjectPropertyAccessor *get;
94     ObjectPropertyAccessor *set;
95     ObjectPropertyResolve *resolve;
96     ObjectPropertyRelease *release;
97     ObjectPropertyInit *init;
98     void *opaque;
99     QObject *defval;
100 };
101 
102 /**
103  * typedef ObjectUnparent:
104  * @obj: the object that is being removed from the composition tree
105  *
106  * Called when an object is being removed from the QOM composition tree.
107  * The function should remove any backlinks from children objects to @obj.
108  */
109 typedef void (ObjectUnparent)(Object *obj);
110 
111 /**
112  * typedef ObjectFree:
113  * @obj: the object being freed
114  *
115  * Called when an object's last reference is removed.
116  */
117 typedef void (ObjectFree)(void *obj);
118 
119 #define OBJECT_CLASS_CAST_CACHE 4
120 
121 /**
122  * struct ObjectClass:
123  *
124  * The base for all classes.  The only thing that #ObjectClass contains is an
125  * integer type handle.
126  */
127 struct ObjectClass
128 {
129     /* private: */
130     Type type;
131     GSList *interfaces;
132 
133     const char *object_cast_cache[OBJECT_CLASS_CAST_CACHE];
134     const char *class_cast_cache[OBJECT_CLASS_CAST_CACHE];
135 
136     ObjectUnparent *unparent;
137 
138     GHashTable *properties;
139 };
140 
141 /**
142  * struct Object:
143  *
144  * The base for all objects.  The first member of this object is a pointer to
145  * a #ObjectClass.  Since C guarantees that the first member of a structure
146  * always begins at byte 0 of that structure, as long as any sub-object places
147  * its parent as the first member, we can cast directly to a #Object.
148  *
149  * As a result, #Object contains a reference to the objects type as its
150  * first member.  This allows identification of the real type of the object at
151  * run time.
152  */
153 struct Object
154 {
155     /* private: */
156     ObjectClass *class;
157     ObjectFree *free;
158     GHashTable *properties;
159     uint32_t ref;
160     Object *parent;
161 };
162 
163 /**
164  * DECLARE_INSTANCE_CHECKER:
165  * @InstanceType: instance struct name
166  * @OBJ_NAME: the object name in uppercase with underscore separators
167  * @TYPENAME: type name
168  *
169  * Direct usage of this macro should be avoided, and the complete
170  * OBJECT_DECLARE_TYPE macro is recommended instead.
171  *
172  * This macro will provide the instance type cast functions for a
173  * QOM type.
174  */
175 #define DECLARE_INSTANCE_CHECKER(InstanceType, OBJ_NAME, TYPENAME) \
176     static inline G_GNUC_UNUSED InstanceType * \
177     OBJ_NAME(const void *obj) \
178     { return OBJECT_CHECK(InstanceType, obj, TYPENAME); }
179 
180 /**
181  * DECLARE_CLASS_CHECKERS:
182  * @ClassType: class struct name
183  * @OBJ_NAME: the object name in uppercase with underscore separators
184  * @TYPENAME: type name
185  *
186  * Direct usage of this macro should be avoided, and the complete
187  * OBJECT_DECLARE_TYPE macro is recommended instead.
188  *
189  * This macro will provide the class type cast functions for a
190  * QOM type.
191  */
192 #define DECLARE_CLASS_CHECKERS(ClassType, OBJ_NAME, TYPENAME) \
193     static inline G_GNUC_UNUSED ClassType * \
194     OBJ_NAME##_GET_CLASS(const void *obj) \
195     { return OBJECT_GET_CLASS(ClassType, obj, TYPENAME); } \
196     \
197     static inline G_GNUC_UNUSED ClassType * \
198     OBJ_NAME##_CLASS(const void *klass) \
199     { return OBJECT_CLASS_CHECK(ClassType, klass, TYPENAME); }
200 
201 /**
202  * DECLARE_OBJ_CHECKERS:
203  * @InstanceType: instance struct name
204  * @ClassType: class struct name
205  * @OBJ_NAME: the object name in uppercase with underscore separators
206  * @TYPENAME: type name
207  *
208  * Direct usage of this macro should be avoided, and the complete
209  * OBJECT_DECLARE_TYPE macro is recommended instead.
210  *
211  * This macro will provide the three standard type cast functions for a
212  * QOM type.
213  */
214 #define DECLARE_OBJ_CHECKERS(InstanceType, ClassType, OBJ_NAME, TYPENAME) \
215     DECLARE_INSTANCE_CHECKER(InstanceType, OBJ_NAME, TYPENAME) \
216     \
217     DECLARE_CLASS_CHECKERS(ClassType, OBJ_NAME, TYPENAME)
218 
219 /**
220  * OBJECT_DECLARE_TYPE:
221  * @InstanceType: instance struct name
222  * @ClassType: class struct name
223  * @MODULE_OBJ_NAME: the object name in uppercase with underscore separators
224  *
225  * This macro is typically used in a header file, and will:
226  *
227  *   - create the typedefs for the object and class structs
228  *   - register the type for use with g_autoptr
229  *   - provide three standard type cast functions
230  *
231  * The object struct and class struct need to be declared manually.
232  */
233 #define OBJECT_DECLARE_TYPE(InstanceType, ClassType, MODULE_OBJ_NAME) \
234     typedef struct InstanceType InstanceType; \
235     typedef struct ClassType ClassType; \
236     \
237     G_DEFINE_AUTOPTR_CLEANUP_FUNC(InstanceType, object_unref) \
238     \
239     DECLARE_OBJ_CHECKERS(InstanceType, ClassType, \
240                          MODULE_OBJ_NAME, TYPE_##MODULE_OBJ_NAME)
241 
242 /**
243  * OBJECT_DECLARE_SIMPLE_TYPE:
244  * @InstanceType: instance struct name
245  * @MODULE_OBJ_NAME: the object name in uppercase with underscore separators
246  *
247  * This does the same as OBJECT_DECLARE_TYPE(), but with no class struct
248  * declared.
249  *
250  * This macro should be used unless the class struct needs to have
251  * virtual methods declared.
252  */
253 #define OBJECT_DECLARE_SIMPLE_TYPE(InstanceType, MODULE_OBJ_NAME) \
254     typedef struct InstanceType InstanceType; \
255     \
256     G_DEFINE_AUTOPTR_CLEANUP_FUNC(InstanceType, object_unref) \
257     \
258     DECLARE_INSTANCE_CHECKER(InstanceType, MODULE_OBJ_NAME, TYPE_##MODULE_OBJ_NAME)
259 
260 
261 /**
262  * DO_OBJECT_DEFINE_TYPE_EXTENDED:
263  * @ModuleObjName: the object name with initial caps
264  * @module_obj_name: the object name in lowercase with underscore separators
265  * @MODULE_OBJ_NAME: the object name in uppercase with underscore separators
266  * @PARENT_MODULE_OBJ_NAME: the parent object name in uppercase with underscore
267  *                          separators
268  * @ABSTRACT: boolean flag to indicate whether the object can be instantiated
269  * @CLASS_SIZE: size of the type's class
270  * @...: list of initializers for "InterfaceInfo" to declare implemented interfaces
271  *
272  * This is the base macro used to implement all the OBJECT_DEFINE_*
273  * macros. It should never be used directly in a source file.
274  */
275 #define DO_OBJECT_DEFINE_TYPE_EXTENDED(ModuleObjName, module_obj_name, \
276                                        MODULE_OBJ_NAME, \
277                                        PARENT_MODULE_OBJ_NAME, \
278                                        ABSTRACT, CLASS_SIZE, ...) \
279     static void \
280     module_obj_name##_finalize(Object *obj); \
281     static void \
282     module_obj_name##_class_init(ObjectClass *oc, void *data); \
283     static void \
284     module_obj_name##_init(Object *obj); \
285     \
286     static const TypeInfo module_obj_name##_info = { \
287         .parent = TYPE_##PARENT_MODULE_OBJ_NAME, \
288         .name = TYPE_##MODULE_OBJ_NAME, \
289         .instance_size = sizeof(ModuleObjName), \
290         .instance_align = __alignof__(ModuleObjName), \
291         .instance_init = module_obj_name##_init, \
292         .instance_finalize = module_obj_name##_finalize, \
293         .class_size = CLASS_SIZE, \
294         .class_init = module_obj_name##_class_init, \
295         .abstract = ABSTRACT, \
296         .interfaces = (InterfaceInfo[]) { __VA_ARGS__ } , \
297     }; \
298     \
299     static void \
300     module_obj_name##_register_types(void) \
301     { \
302         type_register_static(&module_obj_name##_info); \
303     } \
304     type_init(module_obj_name##_register_types);
305 
306 /**
307  * OBJECT_DEFINE_TYPE_EXTENDED:
308  * @ModuleObjName: the object name with initial caps
309  * @module_obj_name: the object name in lowercase with underscore separators
310  * @MODULE_OBJ_NAME: the object name in uppercase with underscore separators
311  * @PARENT_MODULE_OBJ_NAME: the parent object name in uppercase with underscore
312  *                          separators
313  * @ABSTRACT: boolean flag to indicate whether the object can be instantiated
314  * @...: list of initializers for "InterfaceInfo" to declare implemented interfaces
315  *
316  * This macro is typically used in a source file, and will:
317  *
318  *   - declare prototypes for _finalize, _class_init and _init methods
319  *   - declare the TypeInfo struct instance
320  *   - provide the constructor to register the type
321  *
322  * After using this macro, implementations of the _finalize, _class_init,
323  * and _init methods need to be written. Any of these can be zero-line
324  * no-op impls if no special logic is required for a given type.
325  *
326  * This macro should rarely be used, instead one of the more specialized
327  * macros is usually a better choice.
328  */
329 #define OBJECT_DEFINE_TYPE_EXTENDED(ModuleObjName, module_obj_name, \
330                                     MODULE_OBJ_NAME, PARENT_MODULE_OBJ_NAME, \
331                                     ABSTRACT, ...) \
332     DO_OBJECT_DEFINE_TYPE_EXTENDED(ModuleObjName, module_obj_name, \
333                                    MODULE_OBJ_NAME, PARENT_MODULE_OBJ_NAME, \
334                                    ABSTRACT, sizeof(ModuleObjName##Class), \
335                                    __VA_ARGS__)
336 
337 /**
338  * OBJECT_DEFINE_TYPE:
339  * @ModuleObjName: the object name with initial caps
340  * @module_obj_name: the object name in lowercase with underscore separators
341  * @MODULE_OBJ_NAME: the object name in uppercase with underscore separators
342  * @PARENT_MODULE_OBJ_NAME: the parent object name in uppercase with underscore
343  *                          separators
344  *
345  * This is a specialization of OBJECT_DEFINE_TYPE_EXTENDED, which is suitable
346  * for the common case of a non-abstract type, without any interfaces.
347  */
348 #define OBJECT_DEFINE_TYPE(ModuleObjName, module_obj_name, MODULE_OBJ_NAME, \
349                            PARENT_MODULE_OBJ_NAME) \
350     OBJECT_DEFINE_TYPE_EXTENDED(ModuleObjName, module_obj_name, \
351                                 MODULE_OBJ_NAME, PARENT_MODULE_OBJ_NAME, \
352                                 false, { NULL })
353 
354 /**
355  * OBJECT_DEFINE_TYPE_WITH_INTERFACES:
356  * @ModuleObjName: the object name with initial caps
357  * @module_obj_name: the object name in lowercase with underscore separators
358  * @MODULE_OBJ_NAME: the object name in uppercase with underscore separators
359  * @PARENT_MODULE_OBJ_NAME: the parent object name in uppercase with underscore
360  *                          separators
361  * @...: list of initializers for "InterfaceInfo" to declare implemented interfaces
362  *
363  * This is a specialization of OBJECT_DEFINE_TYPE_EXTENDED, which is suitable
364  * for the common case of a non-abstract type, with one or more implemented
365  * interfaces.
366  *
367  * Note when passing the list of interfaces, be sure to include the final
368  * NULL entry, e.g.  { TYPE_USER_CREATABLE }, { NULL }
369  */
370 #define OBJECT_DEFINE_TYPE_WITH_INTERFACES(ModuleObjName, module_obj_name, \
371                                            MODULE_OBJ_NAME, \
372                                            PARENT_MODULE_OBJ_NAME, ...) \
373     OBJECT_DEFINE_TYPE_EXTENDED(ModuleObjName, module_obj_name, \
374                                 MODULE_OBJ_NAME, PARENT_MODULE_OBJ_NAME, \
375                                 false, __VA_ARGS__)
376 
377 /**
378  * OBJECT_DEFINE_ABSTRACT_TYPE:
379  * @ModuleObjName: the object name with initial caps
380  * @module_obj_name: the object name in lowercase with underscore separators
381  * @MODULE_OBJ_NAME: the object name in uppercase with underscore separators
382  * @PARENT_MODULE_OBJ_NAME: the parent object name in uppercase with underscore
383  *                          separators
384  *
385  * This is a specialization of OBJECT_DEFINE_TYPE_EXTENDED, which is suitable
386  * for defining an abstract type, without any interfaces.
387  */
388 #define OBJECT_DEFINE_ABSTRACT_TYPE(ModuleObjName, module_obj_name, \
389                                     MODULE_OBJ_NAME, PARENT_MODULE_OBJ_NAME) \
390     OBJECT_DEFINE_TYPE_EXTENDED(ModuleObjName, module_obj_name, \
391                                 MODULE_OBJ_NAME, PARENT_MODULE_OBJ_NAME, \
392                                 true, { NULL })
393 
394 /**
395  * OBJECT_DEFINE_SIMPLE_TYPE_WITH_INTERFACES:
396  * @ModuleObjName: the object name with initial caps
397  * @module_obj_name: the object name in lowercase with underscore separators
398  * @MODULE_OBJ_NAME: the object name in uppercase with underscore separators
399  * @PARENT_MODULE_OBJ_NAME: the parent object name in uppercase with underscore
400  *                          separators
401  *
402  * This is a variant of OBJECT_DEFINE_TYPE_EXTENDED, which is suitable for
403  * the case of a non-abstract type, with interfaces, and with no requirement
404  * for a class struct.
405  */
406 #define OBJECT_DEFINE_SIMPLE_TYPE_WITH_INTERFACES(ModuleObjName, \
407                                                   module_obj_name, \
408                                                   MODULE_OBJ_NAME, \
409                                                   PARENT_MODULE_OBJ_NAME, ...) \
410     DO_OBJECT_DEFINE_TYPE_EXTENDED(ModuleObjName, module_obj_name, \
411                                    MODULE_OBJ_NAME, PARENT_MODULE_OBJ_NAME, \
412                                    false, 0, __VA_ARGS__)
413 
414 /**
415  * OBJECT_DEFINE_SIMPLE_TYPE:
416  * @ModuleObjName: the object name with initial caps
417  * @module_obj_name: the object name in lowercase with underscore separators
418  * @MODULE_OBJ_NAME: the object name in uppercase with underscore separators
419  * @PARENT_MODULE_OBJ_NAME: the parent object name in uppercase with underscore
420  *                          separators
421  *
422  * This is a variant of OBJECT_DEFINE_TYPE_EXTENDED, which is suitable for
423  * the common case of a non-abstract type, without any interfaces, and with
424  * no requirement for a class struct. If you declared your type with
425  * OBJECT_DECLARE_SIMPLE_TYPE then this is probably the right choice for
426  * defining it.
427  */
428 #define OBJECT_DEFINE_SIMPLE_TYPE(ModuleObjName, module_obj_name, \
429                                   MODULE_OBJ_NAME, PARENT_MODULE_OBJ_NAME) \
430     OBJECT_DEFINE_SIMPLE_TYPE_WITH_INTERFACES(ModuleObjName, module_obj_name, \
431         MODULE_OBJ_NAME, PARENT_MODULE_OBJ_NAME, { NULL })
432 
433 /**
434  * struct TypeInfo:
435  * @name: The name of the type.
436  * @parent: The name of the parent type.
437  * @instance_size: The size of the object (derivative of #Object).  If
438  *   @instance_size is 0, then the size of the object will be the size of the
439  *   parent object.
440  * @instance_align: The required alignment of the object.  If @instance_align
441  *   is 0, then normal malloc alignment is sufficient; if non-zero, then we
442  *   must use qemu_memalign for allocation.
443  * @instance_init: This function is called to initialize an object.  The parent
444  *   class will have already been initialized so the type is only responsible
445  *   for initializing its own members.
446  * @instance_post_init: This function is called to finish initialization of
447  *   an object, after all @instance_init functions were called.
448  * @instance_finalize: This function is called during object destruction.  This
449  *   is called before the parent @instance_finalize function has been called.
450  *   An object should only free the members that are unique to its type in this
451  *   function.
452  * @abstract: If this field is true, then the class is considered abstract and
453  *   cannot be directly instantiated.
454  * @class_size: The size of the class object (derivative of #ObjectClass)
455  *   for this object.  If @class_size is 0, then the size of the class will be
456  *   assumed to be the size of the parent class.  This allows a type to avoid
457  *   implementing an explicit class type if they are not adding additional
458  *   virtual functions.
459  * @class_init: This function is called after all parent class initialization
460  *   has occurred to allow a class to set its default virtual method pointers.
461  *   This is also the function to use to override virtual methods from a parent
462  *   class.
463  * @class_base_init: This function is called for all base classes after all
464  *   parent class initialization has occurred, but before the class itself
465  *   is initialized.  This is the function to use to undo the effects of
466  *   memcpy from the parent class to the descendants.
467  * @class_data: Data to pass to the @class_init,
468  *   @class_base_init. This can be useful when building dynamic
469  *   classes.
470  * @interfaces: The list of interfaces associated with this type.  This
471  *   should point to a static array that's terminated with a zero filled
472  *   element.
473  */
474 struct TypeInfo
475 {
476     const char *name;
477     const char *parent;
478 
479     size_t instance_size;
480     size_t instance_align;
481     void (*instance_init)(Object *obj);
482     void (*instance_post_init)(Object *obj);
483     void (*instance_finalize)(Object *obj);
484 
485     bool abstract;
486     size_t class_size;
487 
488     void (*class_init)(ObjectClass *klass, void *data);
489     void (*class_base_init)(ObjectClass *klass, void *data);
490     void *class_data;
491 
492     InterfaceInfo *interfaces;
493 };
494 
495 /**
496  * OBJECT:
497  * @obj: A derivative of #Object
498  *
499  * Converts an object to a #Object.  Since all objects are #Objects,
500  * this function will always succeed.
501  */
502 #define OBJECT(obj) \
503     ((Object *)(obj))
504 
505 /**
506  * OBJECT_CLASS:
507  * @class: A derivative of #ObjectClass.
508  *
509  * Converts a class to an #ObjectClass.  Since all objects are #Objects,
510  * this function will always succeed.
511  */
512 #define OBJECT_CLASS(class) \
513     ((ObjectClass *)(class))
514 
515 /**
516  * OBJECT_CHECK:
517  * @type: The C type to use for the return value.
518  * @obj: A derivative of @type to cast.
519  * @name: The QOM typename of @type
520  *
521  * A type safe version of @object_dynamic_cast_assert.  Typically each class
522  * will define a macro based on this type to perform type safe dynamic_casts to
523  * this object type.
524  *
525  * If an invalid object is passed to this function, a run time assert will be
526  * generated.
527  */
528 #define OBJECT_CHECK(type, obj, name) \
529     ((type *)object_dynamic_cast_assert(OBJECT(obj), (name), \
530                                         __FILE__, __LINE__, __func__))
531 
532 /**
533  * OBJECT_CLASS_CHECK:
534  * @class_type: The C type to use for the return value.
535  * @class: A derivative class of @class_type to cast.
536  * @name: the QOM typename of @class_type.
537  *
538  * A type safe version of @object_class_dynamic_cast_assert.  This macro is
539  * typically wrapped by each type to perform type safe casts of a class to a
540  * specific class type.
541  */
542 #define OBJECT_CLASS_CHECK(class_type, class, name) \
543     ((class_type *)object_class_dynamic_cast_assert(OBJECT_CLASS(class), (name), \
544                                                __FILE__, __LINE__, __func__))
545 
546 /**
547  * OBJECT_GET_CLASS:
548  * @class: The C type to use for the return value.
549  * @obj: The object to obtain the class for.
550  * @name: The QOM typename of @obj.
551  *
552  * This function will return a specific class for a given object.  Its generally
553  * used by each type to provide a type safe macro to get a specific class type
554  * from an object.
555  */
556 #define OBJECT_GET_CLASS(class, obj, name) \
557     OBJECT_CLASS_CHECK(class, object_get_class(OBJECT(obj)), name)
558 
559 /**
560  * struct InterfaceInfo:
561  * @type: The name of the interface.
562  *
563  * The information associated with an interface.
564  */
565 struct InterfaceInfo {
566     const char *type;
567 };
568 
569 /**
570  * struct InterfaceClass:
571  * @parent_class: the base class
572  *
573  * The class for all interfaces.  Subclasses of this class should only add
574  * virtual methods.
575  */
576 struct InterfaceClass
577 {
578     ObjectClass parent_class;
579     /* private: */
580     ObjectClass *concrete_class;
581     Type interface_type;
582 };
583 
584 #define TYPE_INTERFACE "interface"
585 
586 /**
587  * INTERFACE_CLASS:
588  * @klass: class to cast from
589  * Returns: An #InterfaceClass or raise an error if cast is invalid
590  */
591 #define INTERFACE_CLASS(klass) \
592     OBJECT_CLASS_CHECK(InterfaceClass, klass, TYPE_INTERFACE)
593 
594 /**
595  * INTERFACE_CHECK:
596  * @interface: the type to return
597  * @obj: the object to convert to an interface
598  * @name: the interface type name
599  *
600  * Returns: @obj casted to @interface if cast is valid, otherwise raise error.
601  */
602 #define INTERFACE_CHECK(interface, obj, name) \
603     ((interface *)object_dynamic_cast_assert(OBJECT((obj)), (name), \
604                                              __FILE__, __LINE__, __func__))
605 
606 /**
607  * object_new_with_class:
608  * @klass: The class to instantiate.
609  *
610  * This function will initialize a new object using heap allocated memory.
611  * The returned object has a reference count of 1, and will be freed when
612  * the last reference is dropped.
613  *
614  * Returns: The newly allocated and instantiated object.
615  */
616 Object *object_new_with_class(ObjectClass *klass);
617 
618 /**
619  * object_new:
620  * @typename: The name of the type of the object to instantiate.
621  *
622  * This function will initialize a new object using heap allocated memory.
623  * The returned object has a reference count of 1, and will be freed when
624  * the last reference is dropped.
625  *
626  * Returns: The newly allocated and instantiated object.
627  */
628 Object *object_new(const char *typename);
629 
630 /**
631  * object_new_with_props:
632  * @typename:  The name of the type of the object to instantiate.
633  * @parent: the parent object
634  * @id: The unique ID of the object
635  * @errp: pointer to error object
636  * @...: list of property names and values
637  *
638  * This function will initialize a new object using heap allocated memory.
639  * The returned object has a reference count of 1, and will be freed when
640  * the last reference is dropped.
641  *
642  * The @id parameter will be used when registering the object as a
643  * child of @parent in the composition tree.
644  *
645  * The variadic parameters are a list of pairs of (propname, propvalue)
646  * strings. The propname of %NULL indicates the end of the property
647  * list. If the object implements the user creatable interface, the
648  * object will be marked complete once all the properties have been
649  * processed.
650  *
651  * .. code-block:: c
652  *    :caption: Creating an object with properties
653  *
654  *      Error *err = NULL;
655  *      Object *obj;
656  *
657  *      obj = object_new_with_props(TYPE_MEMORY_BACKEND_FILE,
658  *                                  object_get_objects_root(),
659  *                                  "hostmem0",
660  *                                  &err,
661  *                                  "share", "yes",
662  *                                  "mem-path", "/dev/shm/somefile",
663  *                                  "prealloc", "yes",
664  *                                  "size", "1048576",
665  *                                  NULL);
666  *
667  *      if (!obj) {
668  *        error_reportf_err(err, "Cannot create memory backend: ");
669  *      }
670  *
671  * The returned object will have one stable reference maintained
672  * for as long as it is present in the object hierarchy.
673  *
674  * Returns: The newly allocated, instantiated & initialized object.
675  */
676 Object *object_new_with_props(const char *typename,
677                               Object *parent,
678                               const char *id,
679                               Error **errp,
680                               ...) G_GNUC_NULL_TERMINATED;
681 
682 /**
683  * object_new_with_propv:
684  * @typename:  The name of the type of the object to instantiate.
685  * @parent: the parent object
686  * @id: The unique ID of the object
687  * @errp: pointer to error object
688  * @vargs: list of property names and values
689  *
690  * See object_new_with_props() for documentation.
691  */
692 Object *object_new_with_propv(const char *typename,
693                               Object *parent,
694                               const char *id,
695                               Error **errp,
696                               va_list vargs);
697 
698 bool object_apply_global_props(Object *obj, const GPtrArray *props,
699                                Error **errp);
700 void object_set_machine_compat_props(GPtrArray *compat_props);
701 void object_set_accelerator_compat_props(GPtrArray *compat_props);
702 void object_register_sugar_prop(const char *driver, const char *prop,
703                                 const char *value, bool optional);
704 void object_apply_compat_props(Object *obj);
705 
706 /**
707  * object_set_props:
708  * @obj: the object instance to set properties on
709  * @errp: pointer to error object
710  * @...: list of property names and values
711  *
712  * This function will set a list of properties on an existing object
713  * instance.
714  *
715  * The variadic parameters are a list of pairs of (propname, propvalue)
716  * strings. The propname of %NULL indicates the end of the property
717  * list.
718  *
719  * .. code-block:: c
720  *    :caption: Update an object's properties
721  *
722  *      Error *err = NULL;
723  *      Object *obj = ...get / create object...;
724  *
725  *      if (!object_set_props(obj,
726  *                            &err,
727  *                            "share", "yes",
728  *                            "mem-path", "/dev/shm/somefile",
729  *                            "prealloc", "yes",
730  *                            "size", "1048576",
731  *                            NULL)) {
732  *        error_reportf_err(err, "Cannot set properties: ");
733  *      }
734  *
735  * The returned object will have one stable reference maintained
736  * for as long as it is present in the object hierarchy.
737  *
738  * Returns: %true on success, %false on error.
739  */
740 bool object_set_props(Object *obj, Error **errp, ...) G_GNUC_NULL_TERMINATED;
741 
742 /**
743  * object_set_propv:
744  * @obj: the object instance to set properties on
745  * @errp: pointer to error object
746  * @vargs: list of property names and values
747  *
748  * See object_set_props() for documentation.
749  *
750  * Returns: %true on success, %false on error.
751  */
752 bool object_set_propv(Object *obj, Error **errp, va_list vargs);
753 
754 /**
755  * object_initialize:
756  * @obj: A pointer to the memory to be used for the object.
757  * @size: The maximum size available at @obj for the object.
758  * @typename: The name of the type of the object to instantiate.
759  *
760  * This function will initialize an object.  The memory for the object should
761  * have already been allocated.  The returned object has a reference count of 1,
762  * and will be finalized when the last reference is dropped.
763  */
764 void object_initialize(void *obj, size_t size, const char *typename);
765 
766 /**
767  * object_initialize_child_with_props:
768  * @parentobj: The parent object to add a property to
769  * @propname: The name of the property
770  * @childobj: A pointer to the memory to be used for the object.
771  * @size: The maximum size available at @childobj for the object.
772  * @type: The name of the type of the object to instantiate.
773  * @errp: If an error occurs, a pointer to an area to store the error
774  * @...: list of property names and values
775  *
776  * This function will initialize an object. The memory for the object should
777  * have already been allocated. The object will then be added as child property
778  * to a parent with object_property_add_child() function. The returned object
779  * has a reference count of 1 (for the "child<...>" property from the parent),
780  * so the object will be finalized automatically when the parent gets removed.
781  *
782  * The variadic parameters are a list of pairs of (propname, propvalue)
783  * strings. The propname of %NULL indicates the end of the property list.
784  * If the object implements the user creatable interface, the object will
785  * be marked complete once all the properties have been processed.
786  *
787  * Returns: %true on success, %false on failure.
788  */
789 bool object_initialize_child_with_props(Object *parentobj,
790                              const char *propname,
791                              void *childobj, size_t size, const char *type,
792                              Error **errp, ...) G_GNUC_NULL_TERMINATED;
793 
794 /**
795  * object_initialize_child_with_propsv:
796  * @parentobj: The parent object to add a property to
797  * @propname: The name of the property
798  * @childobj: A pointer to the memory to be used for the object.
799  * @size: The maximum size available at @childobj for the object.
800  * @type: The name of the type of the object to instantiate.
801  * @errp: If an error occurs, a pointer to an area to store the error
802  * @vargs: list of property names and values
803  *
804  * See object_initialize_child() for documentation.
805  *
806  * Returns: %true on success, %false on failure.
807  */
808 bool object_initialize_child_with_propsv(Object *parentobj,
809                               const char *propname,
810                               void *childobj, size_t size, const char *type,
811                               Error **errp, va_list vargs);
812 
813 /**
814  * object_initialize_child:
815  * @parent: The parent object to add a property to
816  * @propname: The name of the property
817  * @child: A precisely typed pointer to the memory to be used for the
818  * object.
819  * @type: The name of the type of the object to instantiate.
820  *
821  * This is like::
822  *
823  *   object_initialize_child_with_props(parent, propname,
824  *                                      child, sizeof(*child), type,
825  *                                      &error_abort, NULL)
826  */
827 #define object_initialize_child(parent, propname, child, type)          \
828     object_initialize_child_internal((parent), (propname),              \
829                                      (child), sizeof(*(child)), (type))
830 void object_initialize_child_internal(Object *parent, const char *propname,
831                                       void *child, size_t size,
832                                       const char *type);
833 
834 /**
835  * object_dynamic_cast:
836  * @obj: The object to cast.
837  * @typename: The @typename to cast to.
838  *
839  * This function will determine if @obj is-a @typename.  @obj can refer to an
840  * object or an interface associated with an object.
841  *
842  * Returns: This function returns @obj on success or #NULL on failure.
843  */
844 Object *object_dynamic_cast(Object *obj, const char *typename);
845 
846 /**
847  * object_dynamic_cast_assert:
848  * @obj: The object to cast.
849  * @typename: The @typename to cast to.
850  * @file: Source code file where function was called
851  * @line: Source code line where function was called
852  * @func: Name of function where this function was called
853  *
854  * See object_dynamic_cast() for a description of the parameters of this
855  * function.  The only difference in behavior is that this function asserts
856  * instead of returning #NULL on failure if QOM cast debugging is enabled.
857  * This function is not meant to be called directly, but only through
858  * the wrapper macro OBJECT_CHECK.
859  */
860 Object *object_dynamic_cast_assert(Object *obj, const char *typename,
861                                    const char *file, int line, const char *func);
862 
863 /**
864  * object_get_class:
865  * @obj: A derivative of #Object
866  *
867  * Returns: The #ObjectClass of the type associated with @obj.
868  */
869 ObjectClass *object_get_class(Object *obj);
870 
871 /**
872  * object_get_typename:
873  * @obj: A derivative of #Object.
874  *
875  * Returns: The QOM typename of @obj.
876  */
877 const char *object_get_typename(const Object *obj);
878 
879 /**
880  * type_register_static:
881  * @info: The #TypeInfo of the new type.
882  *
883  * @info and all of the strings it points to should exist for the life time
884  * that the type is registered.
885  *
886  * Returns: the new #Type.
887  */
888 Type type_register_static(const TypeInfo *info);
889 
890 /**
891  * type_register:
892  * @info: The #TypeInfo of the new type
893  *
894  * Unlike type_register_static(), this call does not require @info or its
895  * string members to continue to exist after the call returns.
896  *
897  * Returns: the new #Type.
898  */
899 Type type_register(const TypeInfo *info);
900 
901 /**
902  * type_register_static_array:
903  * @infos: The array of the new type #TypeInfo structures.
904  * @nr_infos: number of entries in @infos
905  *
906  * @infos and all of the strings it points to should exist for the life time
907  * that the type is registered.
908  */
909 void type_register_static_array(const TypeInfo *infos, int nr_infos);
910 
911 /**
912  * DEFINE_TYPES:
913  * @type_array: The array containing #TypeInfo structures to register
914  *
915  * @type_array should be static constant that exists for the life time
916  * that the type is registered.
917  */
918 #define DEFINE_TYPES(type_array)                                            \
919 static void do_qemu_init_ ## type_array(void)                               \
920 {                                                                           \
921     type_register_static_array(type_array, ARRAY_SIZE(type_array));         \
922 }                                                                           \
923 type_init(do_qemu_init_ ## type_array)
924 
925 /**
926  * type_print_class_properties:
927  * @type: a QOM class name
928  *
929  * Print the object's class properties to stdout or the monitor.
930  * Return whether an object was found.
931  */
932 bool type_print_class_properties(const char *type);
933 
934 /**
935  * object_set_properties_from_keyval:
936  * @obj: a QOM object
937  * @qdict: a dictionary with the properties to be set
938  * @from_json: true if leaf values of @qdict are typed, false if they
939  * are strings
940  * @errp: pointer to error object
941  *
942  * For each key in the dictionary, parse the value string if needed,
943  * then set the corresponding property in @obj.
944  */
945 void object_set_properties_from_keyval(Object *obj, const QDict *qdict,
946                                        bool from_json, Error **errp);
947 
948 /**
949  * object_class_dynamic_cast_assert:
950  * @klass: The #ObjectClass to attempt to cast.
951  * @typename: The QOM typename of the class to cast to.
952  * @file: Source code file where function was called
953  * @line: Source code line where function was called
954  * @func: Name of function where this function was called
955  *
956  * See object_class_dynamic_cast() for a description of the parameters
957  * of this function.  The only difference in behavior is that this function
958  * asserts instead of returning #NULL on failure if QOM cast debugging is
959  * enabled.  This function is not meant to be called directly, but only through
960  * the wrapper macro OBJECT_CLASS_CHECK.
961  */
962 ObjectClass *object_class_dynamic_cast_assert(ObjectClass *klass,
963                                               const char *typename,
964                                               const char *file, int line,
965                                               const char *func);
966 
967 /**
968  * object_class_dynamic_cast:
969  * @klass: The #ObjectClass to attempt to cast.
970  * @typename: The QOM typename of the class to cast to.
971  *
972  * Returns: If @typename is a class, this function returns @klass if
973  * @typename is a subtype of @klass, else returns #NULL.
974  *
975  * If @typename is an interface, this function returns the interface
976  * definition for @klass if @klass implements it unambiguously; #NULL
977  * is returned if @klass does not implement the interface or if multiple
978  * classes or interfaces on the hierarchy leading to @klass implement
979  * it.  (FIXME: perhaps this can be detected at type definition time?)
980  */
981 ObjectClass *object_class_dynamic_cast(ObjectClass *klass,
982                                        const char *typename);
983 
984 /**
985  * object_class_get_parent:
986  * @klass: The class to obtain the parent for.
987  *
988  * Returns: The parent for @klass or %NULL if none.
989  */
990 ObjectClass *object_class_get_parent(ObjectClass *klass);
991 
992 /**
993  * object_class_get_name:
994  * @klass: The class to obtain the QOM typename for.
995  *
996  * Returns: The QOM typename for @klass.
997  */
998 const char *object_class_get_name(ObjectClass *klass);
999 
1000 /**
1001  * object_class_is_abstract:
1002  * @klass: The class to obtain the abstractness for.
1003  *
1004  * Returns: %true if @klass is abstract, %false otherwise.
1005  */
1006 bool object_class_is_abstract(ObjectClass *klass);
1007 
1008 /**
1009  * object_class_by_name:
1010  * @typename: The QOM typename to obtain the class for.
1011  *
1012  * Returns: The class for @typename or %NULL if not found.
1013  */
1014 ObjectClass *object_class_by_name(const char *typename);
1015 
1016 /**
1017  * module_object_class_by_name:
1018  * @typename: The QOM typename to obtain the class for.
1019  *
1020  * For objects which might be provided by a module.  Behaves like
1021  * object_class_by_name, but additionally tries to load the module
1022  * needed in case the class is not available.
1023  *
1024  * Returns: The class for @typename or %NULL if not found.
1025  */
1026 ObjectClass *module_object_class_by_name(const char *typename);
1027 
1028 void object_class_foreach(void (*fn)(ObjectClass *klass, void *opaque),
1029                           const char *implements_type, bool include_abstract,
1030                           void *opaque);
1031 
1032 /**
1033  * object_class_get_list:
1034  * @implements_type: The type to filter for, including its derivatives.
1035  * @include_abstract: Whether to include abstract classes.
1036  *
1037  * Returns: A singly-linked list of the classes in reverse hashtable order.
1038  */
1039 GSList *object_class_get_list(const char *implements_type,
1040                               bool include_abstract);
1041 
1042 /**
1043  * object_class_get_list_sorted:
1044  * @implements_type: The type to filter for, including its derivatives.
1045  * @include_abstract: Whether to include abstract classes.
1046  *
1047  * Returns: A singly-linked list of the classes in alphabetical
1048  * case-insensitive order.
1049  */
1050 GSList *object_class_get_list_sorted(const char *implements_type,
1051                               bool include_abstract);
1052 
1053 /**
1054  * object_ref:
1055  * @obj: the object
1056  *
1057  * Increase the reference count of a object.  A object cannot be freed as long
1058  * as its reference count is greater than zero.
1059  * Returns: @obj
1060  */
1061 Object *object_ref(void *obj);
1062 
1063 /**
1064  * object_unref:
1065  * @obj: the object
1066  *
1067  * Decrease the reference count of a object.  A object cannot be freed as long
1068  * as its reference count is greater than zero.
1069  */
1070 void object_unref(void *obj);
1071 
1072 /**
1073  * object_property_try_add:
1074  * @obj: the object to add a property to
1075  * @name: the name of the property.  This can contain any character except for
1076  *  a forward slash.  In general, you should use hyphens '-' instead of
1077  *  underscores '_' when naming properties.
1078  * @type: the type name of the property.  This namespace is pretty loosely
1079  *   defined.  Sub namespaces are constructed by using a prefix and then
1080  *   to angle brackets.  For instance, the type 'virtio-net-pci' in the
1081  *   'link' namespace would be 'link<virtio-net-pci>'.
1082  * @get: The getter to be called to read a property.  If this is NULL, then
1083  *   the property cannot be read.
1084  * @set: the setter to be called to write a property.  If this is NULL,
1085  *   then the property cannot be written.
1086  * @release: called when the property is removed from the object.  This is
1087  *   meant to allow a property to free its opaque upon object
1088  *   destruction.  This may be NULL.
1089  * @opaque: an opaque pointer to pass to the callbacks for the property
1090  * @errp: pointer to error object
1091  *
1092  * Returns: The #ObjectProperty; this can be used to set the @resolve
1093  * callback for child and link properties.
1094  */
1095 ObjectProperty *object_property_try_add(Object *obj, const char *name,
1096                                         const char *type,
1097                                         ObjectPropertyAccessor *get,
1098                                         ObjectPropertyAccessor *set,
1099                                         ObjectPropertyRelease *release,
1100                                         void *opaque, Error **errp);
1101 
1102 /**
1103  * object_property_add:
1104  * Same as object_property_try_add() with @errp hardcoded to
1105  * &error_abort.
1106  *
1107  * @obj: the object to add a property to
1108  * @name: the name of the property.  This can contain any character except for
1109  *  a forward slash.  In general, you should use hyphens '-' instead of
1110  *  underscores '_' when naming properties.
1111  * @type: the type name of the property.  This namespace is pretty loosely
1112  *   defined.  Sub namespaces are constructed by using a prefix and then
1113  *   to angle brackets.  For instance, the type 'virtio-net-pci' in the
1114  *   'link' namespace would be 'link<virtio-net-pci>'.
1115  * @get: The getter to be called to read a property.  If this is NULL, then
1116  *   the property cannot be read.
1117  * @set: the setter to be called to write a property.  If this is NULL,
1118  *   then the property cannot be written.
1119  * @release: called when the property is removed from the object.  This is
1120  *   meant to allow a property to free its opaque upon object
1121  *   destruction.  This may be NULL.
1122  * @opaque: an opaque pointer to pass to the callbacks for the property
1123  */
1124 ObjectProperty *object_property_add(Object *obj, const char *name,
1125                                     const char *type,
1126                                     ObjectPropertyAccessor *get,
1127                                     ObjectPropertyAccessor *set,
1128                                     ObjectPropertyRelease *release,
1129                                     void *opaque);
1130 
1131 void object_property_del(Object *obj, const char *name);
1132 
1133 ObjectProperty *object_class_property_add(ObjectClass *klass, const char *name,
1134                                           const char *type,
1135                                           ObjectPropertyAccessor *get,
1136                                           ObjectPropertyAccessor *set,
1137                                           ObjectPropertyRelease *release,
1138                                           void *opaque);
1139 
1140 /**
1141  * object_property_set_default_bool:
1142  * @prop: the property to set
1143  * @value: the value to be written to the property
1144  *
1145  * Set the property default value.
1146  */
1147 void object_property_set_default_bool(ObjectProperty *prop, bool value);
1148 
1149 /**
1150  * object_property_set_default_str:
1151  * @prop: the property to set
1152  * @value: the value to be written to the property
1153  *
1154  * Set the property default value.
1155  */
1156 void object_property_set_default_str(ObjectProperty *prop, const char *value);
1157 
1158 /**
1159  * object_property_set_default_list:
1160  * @prop: the property to set
1161  *
1162  * Set the property default value to be an empty list.
1163  */
1164 void object_property_set_default_list(ObjectProperty *prop);
1165 
1166 /**
1167  * object_property_set_default_int:
1168  * @prop: the property to set
1169  * @value: the value to be written to the property
1170  *
1171  * Set the property default value.
1172  */
1173 void object_property_set_default_int(ObjectProperty *prop, int64_t value);
1174 
1175 /**
1176  * object_property_set_default_uint:
1177  * @prop: the property to set
1178  * @value: the value to be written to the property
1179  *
1180  * Set the property default value.
1181  */
1182 void object_property_set_default_uint(ObjectProperty *prop, uint64_t value);
1183 
1184 /**
1185  * object_property_find:
1186  * @obj: the object
1187  * @name: the name of the property
1188  *
1189  * Look up a property for an object.
1190  *
1191  * Return its #ObjectProperty if found, or NULL.
1192  */
1193 ObjectProperty *object_property_find(Object *obj, const char *name);
1194 
1195 /**
1196  * object_property_find_err:
1197  * @obj: the object
1198  * @name: the name of the property
1199  * @errp: returns an error if this function fails
1200  *
1201  * Look up a property for an object.
1202  *
1203  * Return its #ObjectProperty if found, or NULL.
1204  */
1205 ObjectProperty *object_property_find_err(Object *obj,
1206                                          const char *name,
1207                                          Error **errp);
1208 
1209 /**
1210  * object_class_property_find:
1211  * @klass: the object class
1212  * @name: the name of the property
1213  *
1214  * Look up a property for an object class.
1215  *
1216  * Return its #ObjectProperty if found, or NULL.
1217  */
1218 ObjectProperty *object_class_property_find(ObjectClass *klass,
1219                                            const char *name);
1220 
1221 /**
1222  * object_class_property_find_err:
1223  * @klass: the object class
1224  * @name: the name of the property
1225  * @errp: returns an error if this function fails
1226  *
1227  * Look up a property for an object class.
1228  *
1229  * Return its #ObjectProperty if found, or NULL.
1230  */
1231 ObjectProperty *object_class_property_find_err(ObjectClass *klass,
1232                                                const char *name,
1233                                                Error **errp);
1234 
1235 typedef struct ObjectPropertyIterator {
1236     ObjectClass *nextclass;
1237     GHashTableIter iter;
1238 } ObjectPropertyIterator;
1239 
1240 /**
1241  * object_property_iter_init:
1242  * @iter: the iterator instance
1243  * @obj: the object
1244  *
1245  * Initializes an iterator for traversing all properties
1246  * registered against an object instance, its class and all parent classes.
1247  *
1248  * It is forbidden to modify the property list while iterating,
1249  * whether removing or adding properties.
1250  *
1251  * Typical usage pattern would be
1252  *
1253  * .. code-block:: c
1254  *    :caption: Using object property iterators
1255  *
1256  *      ObjectProperty *prop;
1257  *      ObjectPropertyIterator iter;
1258  *
1259  *      object_property_iter_init(&iter, obj);
1260  *      while ((prop = object_property_iter_next(&iter))) {
1261  *        ... do something with prop ...
1262  *      }
1263  */
1264 void object_property_iter_init(ObjectPropertyIterator *iter,
1265                                Object *obj);
1266 
1267 /**
1268  * object_class_property_iter_init:
1269  * @iter: the iterator instance
1270  * @klass: the class
1271  *
1272  * Initializes an iterator for traversing all properties
1273  * registered against an object class and all parent classes.
1274  *
1275  * It is forbidden to modify the property list while iterating,
1276  * whether removing or adding properties.
1277  *
1278  * This can be used on abstract classes as it does not create a temporary
1279  * instance.
1280  */
1281 void object_class_property_iter_init(ObjectPropertyIterator *iter,
1282                                      ObjectClass *klass);
1283 
1284 /**
1285  * object_property_iter_next:
1286  * @iter: the iterator instance
1287  *
1288  * Return the next available property. If no further properties
1289  * are available, a %NULL value will be returned and the @iter
1290  * pointer should not be used again after this point without
1291  * re-initializing it.
1292  *
1293  * Returns: the next property, or %NULL when all properties
1294  * have been traversed.
1295  */
1296 ObjectProperty *object_property_iter_next(ObjectPropertyIterator *iter);
1297 
1298 void object_unparent(Object *obj);
1299 
1300 /**
1301  * object_property_get:
1302  * @obj: the object
1303  * @name: the name of the property
1304  * @v: the visitor that will receive the property value.  This should be an
1305  *   Output visitor and the data will be written with @name as the name.
1306  * @errp: returns an error if this function fails
1307  *
1308  * Reads a property from a object.
1309  *
1310  * Returns: %true on success, %false on failure.
1311  */
1312 bool object_property_get(Object *obj, const char *name, Visitor *v,
1313                          Error **errp);
1314 
1315 /**
1316  * object_property_set_str:
1317  * @obj: the object
1318  * @name: the name of the property
1319  * @value: the value to be written to the property
1320  * @errp: returns an error if this function fails
1321  *
1322  * Writes a string value to a property.
1323  *
1324  * Returns: %true on success, %false on failure.
1325  */
1326 bool object_property_set_str(Object *obj, const char *name,
1327                              const char *value, Error **errp);
1328 
1329 /**
1330  * object_property_get_str:
1331  * @obj: the object
1332  * @name: the name of the property
1333  * @errp: returns an error if this function fails
1334  *
1335  * Returns: the value of the property, converted to a C string, or NULL if
1336  * an error occurs (including when the property value is not a string).
1337  * The caller should free the string.
1338  */
1339 char *object_property_get_str(Object *obj, const char *name,
1340                               Error **errp);
1341 
1342 /**
1343  * object_property_set_link:
1344  * @obj: the object
1345  * @name: the name of the property
1346  * @value: the value to be written to the property
1347  * @errp: returns an error if this function fails
1348  *
1349  * Writes an object's canonical path to a property.
1350  *
1351  * If the link property was created with
1352  * %OBJ_PROP_LINK_STRONG bit, the old target object is
1353  * unreferenced, and a reference is added to the new target object.
1354  *
1355  * Returns: %true on success, %false on failure.
1356  */
1357 bool object_property_set_link(Object *obj, const char *name,
1358                               Object *value, Error **errp);
1359 
1360 /**
1361  * object_property_get_link:
1362  * @obj: the object
1363  * @name: the name of the property
1364  * @errp: returns an error if this function fails
1365  *
1366  * Returns: the value of the property, resolved from a path to an Object,
1367  * or NULL if an error occurs (including when the property value is not a
1368  * string or not a valid object path).
1369  */
1370 Object *object_property_get_link(Object *obj, const char *name,
1371                                  Error **errp);
1372 
1373 /**
1374  * object_property_set_bool:
1375  * @obj: the object
1376  * @name: the name of the property
1377  * @value: the value to be written to the property
1378  * @errp: returns an error if this function fails
1379  *
1380  * Writes a bool value to a property.
1381  *
1382  * Returns: %true on success, %false on failure.
1383  */
1384 bool object_property_set_bool(Object *obj, const char *name,
1385                               bool value, Error **errp);
1386 
1387 /**
1388  * object_property_get_bool:
1389  * @obj: the object
1390  * @name: the name of the property
1391  * @errp: returns an error if this function fails
1392  *
1393  * Returns: the value of the property, converted to a boolean, or false if
1394  * an error occurs (including when the property value is not a bool).
1395  */
1396 bool object_property_get_bool(Object *obj, const char *name,
1397                               Error **errp);
1398 
1399 /**
1400  * object_property_set_int:
1401  * @obj: the object
1402  * @name: the name of the property
1403  * @value: the value to be written to the property
1404  * @errp: returns an error if this function fails
1405  *
1406  * Writes an integer value to a property.
1407  *
1408  * Returns: %true on success, %false on failure.
1409  */
1410 bool object_property_set_int(Object *obj, const char *name,
1411                              int64_t value, Error **errp);
1412 
1413 /**
1414  * object_property_get_int:
1415  * @obj: the object
1416  * @name: the name of the property
1417  * @errp: returns an error if this function fails
1418  *
1419  * Returns: the value of the property, converted to an integer, or -1 if
1420  * an error occurs (including when the property value is not an integer).
1421  */
1422 int64_t object_property_get_int(Object *obj, const char *name,
1423                                 Error **errp);
1424 
1425 /**
1426  * object_property_set_uint:
1427  * @obj: the object
1428  * @name: the name of the property
1429  * @value: the value to be written to the property
1430  * @errp: returns an error if this function fails
1431  *
1432  * Writes an unsigned integer value to a property.
1433  *
1434  * Returns: %true on success, %false on failure.
1435  */
1436 bool object_property_set_uint(Object *obj, const char *name,
1437                               uint64_t value, Error **errp);
1438 
1439 /**
1440  * object_property_get_uint:
1441  * @obj: the object
1442  * @name: the name of the property
1443  * @errp: returns an error if this function fails
1444  *
1445  * Returns: the value of the property, converted to an unsigned integer, or 0
1446  * an error occurs (including when the property value is not an integer).
1447  */
1448 uint64_t object_property_get_uint(Object *obj, const char *name,
1449                                   Error **errp);
1450 
1451 /**
1452  * object_property_get_enum:
1453  * @obj: the object
1454  * @name: the name of the property
1455  * @typename: the name of the enum data type
1456  * @errp: returns an error if this function fails
1457  *
1458  * Returns: the value of the property, converted to an integer (which
1459  * can't be negative), or -1 on error (including when the property
1460  * value is not an enum).
1461  */
1462 int object_property_get_enum(Object *obj, const char *name,
1463                              const char *typename, Error **errp);
1464 
1465 /**
1466  * object_property_set:
1467  * @obj: the object
1468  * @name: the name of the property
1469  * @v: the visitor that will be used to write the property value.  This should
1470  *   be an Input visitor and the data will be first read with @name as the
1471  *   name and then written as the property value.
1472  * @errp: returns an error if this function fails
1473  *
1474  * Writes a property to a object.
1475  *
1476  * Returns: %true on success, %false on failure.
1477  */
1478 bool object_property_set(Object *obj, const char *name, Visitor *v,
1479                          Error **errp);
1480 
1481 /**
1482  * object_property_parse:
1483  * @obj: the object
1484  * @name: the name of the property
1485  * @string: the string that will be used to parse the property value.
1486  * @errp: returns an error if this function fails
1487  *
1488  * Parses a string and writes the result into a property of an object.
1489  *
1490  * Returns: %true on success, %false on failure.
1491  */
1492 bool object_property_parse(Object *obj, const char *name,
1493                            const char *string, Error **errp);
1494 
1495 /**
1496  * object_property_print:
1497  * @obj: the object
1498  * @name: the name of the property
1499  * @human: if true, print for human consumption
1500  * @errp: returns an error if this function fails
1501  *
1502  * Returns a string representation of the value of the property.  The
1503  * caller shall free the string.
1504  */
1505 char *object_property_print(Object *obj, const char *name, bool human,
1506                             Error **errp);
1507 
1508 /**
1509  * object_property_get_type:
1510  * @obj: the object
1511  * @name: the name of the property
1512  * @errp: returns an error if this function fails
1513  *
1514  * Returns:  The type name of the property.
1515  */
1516 const char *object_property_get_type(Object *obj, const char *name,
1517                                      Error **errp);
1518 
1519 /**
1520  * object_get_root:
1521  *
1522  * Returns: the root object of the composition tree
1523  */
1524 Object *object_get_root(void);
1525 
1526 
1527 /**
1528  * object_get_objects_root:
1529  *
1530  * Get the container object that holds user created
1531  * object instances. This is the object at path
1532  * "/objects"
1533  *
1534  * Returns: the user object container
1535  */
1536 Object *object_get_objects_root(void);
1537 
1538 /**
1539  * object_get_internal_root:
1540  *
1541  * Get the container object that holds internally used object
1542  * instances.  Any object which is put into this container must not be
1543  * user visible, and it will not be exposed in the QOM tree.
1544  *
1545  * Returns: the internal object container
1546  */
1547 Object *object_get_internal_root(void);
1548 
1549 /**
1550  * object_get_canonical_path_component:
1551  * @obj: the object
1552  *
1553  * Returns: The final component in the object's canonical path.  The canonical
1554  * path is the path within the composition tree starting from the root.
1555  * %NULL if the object doesn't have a parent (and thus a canonical path).
1556  */
1557 const char *object_get_canonical_path_component(const Object *obj);
1558 
1559 /**
1560  * object_get_canonical_path:
1561  * @obj: the object
1562  *
1563  * Returns: The canonical path for a object, newly allocated.  This is
1564  * the path within the composition tree starting from the root.  Use
1565  * g_free() to free it.
1566  */
1567 char *object_get_canonical_path(const Object *obj);
1568 
1569 /**
1570  * object_resolve_path:
1571  * @path: the path to resolve
1572  * @ambiguous: returns true if the path resolution failed because of an
1573  *   ambiguous match
1574  *
1575  * There are two types of supported paths--absolute paths and partial paths.
1576  *
1577  * Absolute paths are derived from the root object and can follow child<> or
1578  * link<> properties.  Since they can follow link<> properties, they can be
1579  * arbitrarily long.  Absolute paths look like absolute filenames and are
1580  * prefixed with a leading slash.
1581  *
1582  * Partial paths look like relative filenames.  They do not begin with a
1583  * prefix.  The matching rules for partial paths are subtle but designed to make
1584  * specifying objects easy.  At each level of the composition tree, the partial
1585  * path is matched as an absolute path.  The first match is not returned.  At
1586  * least two matches are searched for.  A successful result is only returned if
1587  * only one match is found.  If more than one match is found, a flag is
1588  * returned to indicate that the match was ambiguous.
1589  *
1590  * Returns: The matched object or NULL on path lookup failure.
1591  */
1592 Object *object_resolve_path(const char *path, bool *ambiguous);
1593 
1594 /**
1595  * object_resolve_path_type:
1596  * @path: the path to resolve
1597  * @typename: the type to look for.
1598  * @ambiguous: returns true if the path resolution failed because of an
1599  *   ambiguous match
1600  *
1601  * This is similar to object_resolve_path.  However, when looking for a
1602  * partial path only matches that implement the given type are considered.
1603  * This restricts the search and avoids spuriously flagging matches as
1604  * ambiguous.
1605  *
1606  * For both partial and absolute paths, the return value goes through
1607  * a dynamic cast to @typename.  This is important if either the link,
1608  * or the typename itself are of interface types.
1609  *
1610  * Returns: The matched object or NULL on path lookup failure.
1611  */
1612 Object *object_resolve_path_type(const char *path, const char *typename,
1613                                  bool *ambiguous);
1614 
1615 /**
1616  * object_resolve_type_unambiguous:
1617  * @typename: the type to look for
1618  * @errp: pointer to error object
1619  *
1620  * Return the only object in the QOM tree of type @typename.
1621  * If no match or more than one match is found, an error is
1622  * returned.
1623  *
1624  * Returns: The matched object or NULL on path lookup failure.
1625  */
1626 Object *object_resolve_type_unambiguous(const char *typename, Error **errp);
1627 
1628 /**
1629  * object_resolve_path_at:
1630  * @parent: the object in which to resolve the path
1631  * @path: the path to resolve
1632  *
1633  * This is like object_resolve_path(), except paths not starting with
1634  * a slash are relative to @parent.
1635  *
1636  * Returns: The resolved object or NULL on path lookup failure.
1637  */
1638 Object *object_resolve_path_at(Object *parent, const char *path);
1639 
1640 /**
1641  * object_resolve_path_component:
1642  * @parent: the object in which to resolve the path
1643  * @part: the component to resolve.
1644  *
1645  * This is similar to object_resolve_path with an absolute path, but it
1646  * only resolves one element (@part) and takes the others from @parent.
1647  *
1648  * Returns: The resolved object or NULL on path lookup failure.
1649  */
1650 Object *object_resolve_path_component(Object *parent, const char *part);
1651 
1652 /**
1653  * object_property_try_add_child:
1654  * @obj: the object to add a property to
1655  * @name: the name of the property
1656  * @child: the child object
1657  * @errp: pointer to error object
1658  *
1659  * Child properties form the composition tree.  All objects need to be a child
1660  * of another object.  Objects can only be a child of one object.
1661  *
1662  * There is no way for a child to determine what its parent is.  It is not
1663  * a bidirectional relationship.  This is by design.
1664  *
1665  * The value of a child property as a C string will be the child object's
1666  * canonical path. It can be retrieved using object_property_get_str().
1667  * The child object itself can be retrieved using object_property_get_link().
1668  *
1669  * Returns: The newly added property on success, or %NULL on failure.
1670  */
1671 ObjectProperty *object_property_try_add_child(Object *obj, const char *name,
1672                                               Object *child, Error **errp);
1673 
1674 /**
1675  * object_property_add_child:
1676  * @obj: the object to add a property to
1677  * @name: the name of the property
1678  * @child: the child object
1679  *
1680  * Same as object_property_try_add_child() with @errp hardcoded to
1681  * &error_abort
1682  */
1683 ObjectProperty *object_property_add_child(Object *obj, const char *name,
1684                                           Object *child);
1685 
1686 typedef enum {
1687     /* Unref the link pointer when the property is deleted */
1688     OBJ_PROP_LINK_STRONG = 0x1,
1689 
1690     /* private */
1691     OBJ_PROP_LINK_DIRECT = 0x2,
1692     OBJ_PROP_LINK_CLASS = 0x4,
1693 } ObjectPropertyLinkFlags;
1694 
1695 /**
1696  * object_property_allow_set_link:
1697  * @obj: the object to add a property to
1698  * @name: the name of the property
1699  * @child: the child object
1700  * @errp: pointer to error object
1701  *
1702  * The default implementation of the object_property_add_link() check()
1703  * callback function.  It allows the link property to be set and never returns
1704  * an error.
1705  */
1706 void object_property_allow_set_link(const Object *obj, const char *name,
1707                                     Object *child, Error **errp);
1708 
1709 /**
1710  * object_property_add_link:
1711  * @obj: the object to add a property to
1712  * @name: the name of the property
1713  * @type: the qobj type of the link
1714  * @targetp: a pointer to where the link object reference is stored
1715  * @check: callback to veto setting or NULL if the property is read-only
1716  * @flags: additional options for the link
1717  *
1718  * Links establish relationships between objects.  Links are unidirectional
1719  * although two links can be combined to form a bidirectional relationship
1720  * between objects.
1721  *
1722  * Links form the graph in the object model.
1723  *
1724  * The @check() callback is invoked when
1725  * object_property_set_link() is called and can raise an error to prevent the
1726  * link being set.  If @check is NULL, the property is read-only
1727  * and cannot be set.
1728  *
1729  * Ownership of the pointer that @child points to is transferred to the
1730  * link property.  The reference count for *@child is
1731  * managed by the property from after the function returns till the
1732  * property is deleted with object_property_del().  If the
1733  * @flags %OBJ_PROP_LINK_STRONG bit is set,
1734  * the reference count is decremented when the property is deleted or
1735  * modified.
1736  *
1737  * Returns: The newly added property on success, or %NULL on failure.
1738  */
1739 ObjectProperty *object_property_add_link(Object *obj, const char *name,
1740                               const char *type, Object **targetp,
1741                               void (*check)(const Object *obj, const char *name,
1742                                             Object *val, Error **errp),
1743                               ObjectPropertyLinkFlags flags);
1744 
1745 ObjectProperty *object_class_property_add_link(ObjectClass *oc,
1746                               const char *name,
1747                               const char *type, ptrdiff_t offset,
1748                               void (*check)(const Object *obj, const char *name,
1749                                             Object *val, Error **errp),
1750                               ObjectPropertyLinkFlags flags);
1751 
1752 /**
1753  * object_property_add_str:
1754  * @obj: the object to add a property to
1755  * @name: the name of the property
1756  * @get: the getter or NULL if the property is write-only.  This function must
1757  *   return a string to be freed by g_free().
1758  * @set: the setter or NULL if the property is read-only
1759  *
1760  * Add a string property using getters/setters.  This function will add a
1761  * property of type 'string'.
1762  *
1763  * Returns: The newly added property on success, or %NULL on failure.
1764  */
1765 ObjectProperty *object_property_add_str(Object *obj, const char *name,
1766                              char *(*get)(Object *, Error **),
1767                              void (*set)(Object *, const char *, Error **));
1768 
1769 ObjectProperty *object_class_property_add_str(ObjectClass *klass,
1770                                    const char *name,
1771                                    char *(*get)(Object *, Error **),
1772                                    void (*set)(Object *, const char *,
1773                                                Error **));
1774 
1775 /**
1776  * object_property_add_bool:
1777  * @obj: the object to add a property to
1778  * @name: the name of the property
1779  * @get: the getter or NULL if the property is write-only.
1780  * @set: the setter or NULL if the property is read-only
1781  *
1782  * Add a bool property using getters/setters.  This function will add a
1783  * property of type 'bool'.
1784  *
1785  * Returns: The newly added property on success, or %NULL on failure.
1786  */
1787 ObjectProperty *object_property_add_bool(Object *obj, const char *name,
1788                               bool (*get)(Object *, Error **),
1789                               void (*set)(Object *, bool, Error **));
1790 
1791 ObjectProperty *object_class_property_add_bool(ObjectClass *klass,
1792                                     const char *name,
1793                                     bool (*get)(Object *, Error **),
1794                                     void (*set)(Object *, bool, Error **));
1795 
1796 /**
1797  * object_property_add_enum:
1798  * @obj: the object to add a property to
1799  * @name: the name of the property
1800  * @typename: the name of the enum data type
1801  * @lookup: enum value namelookup table
1802  * @get: the getter or %NULL if the property is write-only.
1803  * @set: the setter or %NULL if the property is read-only
1804  *
1805  * Add an enum property using getters/setters.  This function will add a
1806  * property of type '@typename'.
1807  *
1808  * Returns: The newly added property on success, or %NULL on failure.
1809  */
1810 ObjectProperty *object_property_add_enum(Object *obj, const char *name,
1811                               const char *typename,
1812                               const QEnumLookup *lookup,
1813                               int (*get)(Object *, Error **),
1814                               void (*set)(Object *, int, Error **));
1815 
1816 ObjectProperty *object_class_property_add_enum(ObjectClass *klass,
1817                                     const char *name,
1818                                     const char *typename,
1819                                     const QEnumLookup *lookup,
1820                                     int (*get)(Object *, Error **),
1821                                     void (*set)(Object *, int, Error **));
1822 
1823 /**
1824  * object_property_add_tm:
1825  * @obj: the object to add a property to
1826  * @name: the name of the property
1827  * @get: the getter or NULL if the property is write-only.
1828  *
1829  * Add a read-only struct tm valued property using a getter function.
1830  * This function will add a property of type 'struct tm'.
1831  *
1832  * Returns: The newly added property on success, or %NULL on failure.
1833  */
1834 ObjectProperty *object_property_add_tm(Object *obj, const char *name,
1835                             void (*get)(Object *, struct tm *, Error **));
1836 
1837 ObjectProperty *object_class_property_add_tm(ObjectClass *klass,
1838                             const char *name,
1839                             void (*get)(Object *, struct tm *, Error **));
1840 
1841 typedef enum {
1842     /* Automatically add a getter to the property */
1843     OBJ_PROP_FLAG_READ = 1 << 0,
1844     /* Automatically add a setter to the property */
1845     OBJ_PROP_FLAG_WRITE = 1 << 1,
1846     /* Automatically add a getter and a setter to the property */
1847     OBJ_PROP_FLAG_READWRITE = (OBJ_PROP_FLAG_READ | OBJ_PROP_FLAG_WRITE),
1848 } ObjectPropertyFlags;
1849 
1850 /**
1851  * object_property_add_uint8_ptr:
1852  * @obj: the object to add a property to
1853  * @name: the name of the property
1854  * @v: pointer to value
1855  * @flags: bitwise-or'd ObjectPropertyFlags
1856  *
1857  * Add an integer property in memory.  This function will add a
1858  * property of type 'uint8'.
1859  *
1860  * Returns: The newly added property on success, or %NULL on failure.
1861  */
1862 ObjectProperty *object_property_add_uint8_ptr(Object *obj, const char *name,
1863                                               const uint8_t *v,
1864                                               ObjectPropertyFlags flags);
1865 
1866 ObjectProperty *object_class_property_add_uint8_ptr(ObjectClass *klass,
1867                                          const char *name,
1868                                          const uint8_t *v,
1869                                          ObjectPropertyFlags flags);
1870 
1871 /**
1872  * object_property_add_uint16_ptr:
1873  * @obj: the object to add a property to
1874  * @name: the name of the property
1875  * @v: pointer to value
1876  * @flags: bitwise-or'd ObjectPropertyFlags
1877  *
1878  * Add an integer property in memory.  This function will add a
1879  * property of type 'uint16'.
1880  *
1881  * Returns: The newly added property on success, or %NULL on failure.
1882  */
1883 ObjectProperty *object_property_add_uint16_ptr(Object *obj, const char *name,
1884                                     const uint16_t *v,
1885                                     ObjectPropertyFlags flags);
1886 
1887 ObjectProperty *object_class_property_add_uint16_ptr(ObjectClass *klass,
1888                                           const char *name,
1889                                           const uint16_t *v,
1890                                           ObjectPropertyFlags flags);
1891 
1892 /**
1893  * object_property_add_uint32_ptr:
1894  * @obj: the object to add a property to
1895  * @name: the name of the property
1896  * @v: pointer to value
1897  * @flags: bitwise-or'd ObjectPropertyFlags
1898  *
1899  * Add an integer property in memory.  This function will add a
1900  * property of type 'uint32'.
1901  *
1902  * Returns: The newly added property on success, or %NULL on failure.
1903  */
1904 ObjectProperty *object_property_add_uint32_ptr(Object *obj, const char *name,
1905                                     const uint32_t *v,
1906                                     ObjectPropertyFlags flags);
1907 
1908 ObjectProperty *object_class_property_add_uint32_ptr(ObjectClass *klass,
1909                                           const char *name,
1910                                           const uint32_t *v,
1911                                           ObjectPropertyFlags flags);
1912 
1913 /**
1914  * object_property_add_uint64_ptr:
1915  * @obj: the object to add a property to
1916  * @name: the name of the property
1917  * @v: pointer to value
1918  * @flags: bitwise-or'd ObjectPropertyFlags
1919  *
1920  * Add an integer property in memory.  This function will add a
1921  * property of type 'uint64'.
1922  *
1923  * Returns: The newly added property on success, or %NULL on failure.
1924  */
1925 ObjectProperty *object_property_add_uint64_ptr(Object *obj, const char *name,
1926                                     const uint64_t *v,
1927                                     ObjectPropertyFlags flags);
1928 
1929 ObjectProperty *object_class_property_add_uint64_ptr(ObjectClass *klass,
1930                                           const char *name,
1931                                           const uint64_t *v,
1932                                           ObjectPropertyFlags flags);
1933 
1934 /**
1935  * object_property_add_alias:
1936  * @obj: the object to add a property to
1937  * @name: the name of the property
1938  * @target_obj: the object to forward property access to
1939  * @target_name: the name of the property on the forwarded object
1940  *
1941  * Add an alias for a property on an object.  This function will add a property
1942  * of the same type as the forwarded property.
1943  *
1944  * The caller must ensure that @target_obj stays alive as long as
1945  * this property exists.  In the case of a child object or an alias on the same
1946  * object this will be the case.  For aliases to other objects the caller is
1947  * responsible for taking a reference.
1948  *
1949  * Returns: The newly added property on success, or %NULL on failure.
1950  */
1951 ObjectProperty *object_property_add_alias(Object *obj, const char *name,
1952                                Object *target_obj, const char *target_name);
1953 
1954 /**
1955  * object_property_add_const_link:
1956  * @obj: the object to add a property to
1957  * @name: the name of the property
1958  * @target: the object to be referred by the link
1959  *
1960  * Add an unmodifiable link for a property on an object.  This function will
1961  * add a property of type link<TYPE> where TYPE is the type of @target.
1962  *
1963  * The caller must ensure that @target stays alive as long as
1964  * this property exists.  In the case @target is a child of @obj,
1965  * this will be the case.  Otherwise, the caller is responsible for
1966  * taking a reference.
1967  *
1968  * Returns: The newly added property on success, or %NULL on failure.
1969  */
1970 ObjectProperty *object_property_add_const_link(Object *obj, const char *name,
1971                                                Object *target);
1972 
1973 /**
1974  * object_property_set_description:
1975  * @obj: the object owning the property
1976  * @name: the name of the property
1977  * @description: the description of the property on the object
1978  *
1979  * Set an object property's description.
1980  *
1981  * Returns: %true on success, %false on failure.
1982  */
1983 void object_property_set_description(Object *obj, const char *name,
1984                                      const char *description);
1985 void object_class_property_set_description(ObjectClass *klass, const char *name,
1986                                            const char *description);
1987 
1988 /**
1989  * object_child_foreach:
1990  * @obj: the object whose children will be navigated
1991  * @fn: the iterator function to be called
1992  * @opaque: an opaque value that will be passed to the iterator
1993  *
1994  * Call @fn passing each child of @obj and @opaque to it, until @fn returns
1995  * non-zero.
1996  *
1997  * It is forbidden to add or remove children from @obj from the @fn
1998  * callback.
1999  *
2000  * Returns: The last value returned by @fn, or 0 if there is no child.
2001  */
2002 int object_child_foreach(Object *obj, int (*fn)(Object *child, void *opaque),
2003                          void *opaque);
2004 
2005 /**
2006  * object_child_foreach_recursive:
2007  * @obj: the object whose children will be navigated
2008  * @fn: the iterator function to be called
2009  * @opaque: an opaque value that will be passed to the iterator
2010  *
2011  * Call @fn passing each child of @obj and @opaque to it, until @fn returns
2012  * non-zero. Calls recursively, all child nodes of @obj will also be passed
2013  * all the way down to the leaf nodes of the tree. Depth first ordering.
2014  *
2015  * It is forbidden to add or remove children from @obj (or its
2016  * child nodes) from the @fn callback.
2017  *
2018  * Returns: The last value returned by @fn, or 0 if there is no child.
2019  */
2020 int object_child_foreach_recursive(Object *obj,
2021                                    int (*fn)(Object *child, void *opaque),
2022                                    void *opaque);
2023 /**
2024  * container_get:
2025  * @root: root of the #path, e.g., object_get_root()
2026  * @path: path to the container
2027  *
2028  * Return a container object whose path is @path.  Create more containers
2029  * along the path if necessary.
2030  *
2031  * Returns: the container object.
2032  */
2033 Object *container_get(Object *root, const char *path);
2034 
2035 /**
2036  * object_type_get_instance_size:
2037  * @typename: Name of the Type whose instance_size is required
2038  *
2039  * Returns the instance_size of the given @typename.
2040  */
2041 size_t object_type_get_instance_size(const char *typename);
2042 
2043 /**
2044  * object_property_help:
2045  * @name: the name of the property
2046  * @type: the type of the property
2047  * @defval: the default value
2048  * @description: description of the property
2049  *
2050  * Returns: a user-friendly formatted string describing the property
2051  * for help purposes.
2052  */
2053 char *object_property_help(const char *name, const char *type,
2054                            QObject *defval, const char *description);
2055 
2056 G_DEFINE_AUTOPTR_CLEANUP_FUNC(Object, object_unref)
2057 
2058 #endif
2059