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