include/qom/object.h

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