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 <glib.h> 18 #include <stdint.h> 19 #include <stdbool.h> 20 #include "qemu/queue.h" 21 22 struct Visitor; 23 struct Error; 24 25 struct TypeImpl; 26 typedef struct TypeImpl *Type; 27 28 typedef struct ObjectClass ObjectClass; 29 typedef struct Object Object; 30 31 typedef struct TypeInfo TypeInfo; 32 33 typedef struct InterfaceClass InterfaceClass; 34 typedef struct InterfaceInfo InterfaceInfo; 35 36 #define TYPE_OBJECT "object" 37 38 /** 39 * SECTION:object.h 40 * @title:Base Object Type System 41 * @short_description: interfaces for creating new types and objects 42 * 43 * The QEMU Object Model provides a framework for registering user creatable 44 * types and instantiating objects from those types. QOM provides the following 45 * features: 46 * 47 * - System for dynamically registering types 48 * - Support for single-inheritance of types 49 * - Multiple inheritance of stateless interfaces 50 * 51 * <example> 52 * <title>Creating a minimal type</title> 53 * <programlisting> 54 * #include "qdev.h" 55 * 56 * #define TYPE_MY_DEVICE "my-device" 57 * 58 * // No new virtual functions: we can reuse the typedef for the 59 * // superclass. 60 * typedef DeviceClass MyDeviceClass; 61 * typedef struct MyDevice 62 * { 63 * DeviceState parent; 64 * 65 * int reg0, reg1, reg2; 66 * } MyDevice; 67 * 68 * static const TypeInfo my_device_info = { 69 * .name = TYPE_MY_DEVICE, 70 * .parent = TYPE_DEVICE, 71 * .instance_size = sizeof(MyDevice), 72 * }; 73 * 74 * static void my_device_register_types(void) 75 * { 76 * type_register_static(&my_device_info); 77 * } 78 * 79 * type_init(my_device_register_types) 80 * </programlisting> 81 * </example> 82 * 83 * In the above example, we create a simple type that is described by #TypeInfo. 84 * #TypeInfo describes information about the type including what it inherits 85 * from, the instance and class size, and constructor/destructor hooks. 86 * 87 * Every type has an #ObjectClass associated with it. #ObjectClass derivatives 88 * are instantiated dynamically but there is only ever one instance for any 89 * given type. The #ObjectClass typically holds a table of function pointers 90 * for the virtual methods implemented by this type. 91 * 92 * Using object_new(), a new #Object derivative will be instantiated. You can 93 * cast an #Object to a subclass (or base-class) type using 94 * object_dynamic_cast(). You typically want to define macro wrappers around 95 * OBJECT_CHECK() and OBJECT_CLASS_CHECK() to make it easier to convert to a 96 * specific type: 97 * 98 * <example> 99 * <title>Typecasting macros</title> 100 * <programlisting> 101 * #define MY_DEVICE_GET_CLASS(obj) \ 102 * OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE) 103 * #define MY_DEVICE_CLASS(klass) \ 104 * OBJECT_CLASS_CHECK(MyDeviceClass, klass, TYPE_MY_DEVICE) 105 * #define MY_DEVICE(obj) \ 106 * OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE) 107 * </programlisting> 108 * </example> 109 * 110 * # Class Initialization # 111 * 112 * Before an object is initialized, the class for the object must be 113 * initialized. There is only one class object for all instance objects 114 * that is created lazily. 115 * 116 * Classes are initialized by first initializing any parent classes (if 117 * necessary). After the parent class object has initialized, it will be 118 * copied into the current class object and any additional storage in the 119 * class object is zero filled. 120 * 121 * The effect of this is that classes automatically inherit any virtual 122 * function pointers that the parent class has already initialized. All 123 * other fields will be zero filled. 124 * 125 * Once all of the parent classes have been initialized, #TypeInfo::class_init 126 * is called to let the class being instantiated provide default initialize for 127 * its virtual functions. Here is how the above example might be modified 128 * to introduce an overridden virtual function: 129 * 130 * <example> 131 * <title>Overriding a virtual function</title> 132 * <programlisting> 133 * #include "qdev.h" 134 * 135 * void my_device_class_init(ObjectClass *klass, void *class_data) 136 * { 137 * DeviceClass *dc = DEVICE_CLASS(klass); 138 * dc->reset = my_device_reset; 139 * } 140 * 141 * static const TypeInfo my_device_info = { 142 * .name = TYPE_MY_DEVICE, 143 * .parent = TYPE_DEVICE, 144 * .instance_size = sizeof(MyDevice), 145 * .class_init = my_device_class_init, 146 * }; 147 * </programlisting> 148 * </example> 149 * 150 * Introducing new virtual methods requires a class to define its own 151 * struct and to add a .class_size member to the #TypeInfo. Each method 152 * will also have a wrapper function to call it easily: 153 * 154 * <example> 155 * <title>Defining an abstract class</title> 156 * <programlisting> 157 * #include "qdev.h" 158 * 159 * typedef struct MyDeviceClass 160 * { 161 * DeviceClass parent; 162 * 163 * void (*frobnicate) (MyDevice *obj); 164 * } MyDeviceClass; 165 * 166 * static const TypeInfo my_device_info = { 167 * .name = TYPE_MY_DEVICE, 168 * .parent = TYPE_DEVICE, 169 * .instance_size = sizeof(MyDevice), 170 * .abstract = true, // or set a default in my_device_class_init 171 * .class_size = sizeof(MyDeviceClass), 172 * }; 173 * 174 * void my_device_frobnicate(MyDevice *obj) 175 * { 176 * MyDeviceClass *klass = MY_DEVICE_GET_CLASS(obj); 177 * 178 * klass->frobnicate(obj); 179 * } 180 * </programlisting> 181 * </example> 182 * 183 * # Interfaces # 184 * 185 * Interfaces allow a limited form of multiple inheritance. Instances are 186 * similar to normal types except for the fact that are only defined by 187 * their classes and never carry any state. You can dynamically cast an object 188 * to one of its #Interface types and vice versa. 189 * 190 * # Methods # 191 * 192 * A <emphasis>method</emphasis> is a function within the namespace scope of 193 * a class. It usually operates on the object instance by passing it as a 194 * strongly-typed first argument. 195 * If it does not operate on an object instance, it is dubbed 196 * <emphasis>class method</emphasis>. 197 * 198 * Methods cannot be overloaded. That is, the #ObjectClass and method name 199 * uniquely identity the function to be called; the signature does not vary 200 * except for trailing varargs. 201 * 202 * Methods are always <emphasis>virtual</emphasis>. Overriding a method in 203 * #TypeInfo.class_init of a subclass leads to any user of the class obtained 204 * via OBJECT_GET_CLASS() accessing the overridden function. 205 * The original function is not automatically invoked. It is the responsability 206 * of the overriding class to determine whether and when to invoke the method 207 * being overridden. 208 * 209 * To invoke the method being overridden, the preferred solution is to store 210 * the original value in the overriding class before overriding the method. 211 * This corresponds to |[ {super,base}.method(...) ]| in Java and C# 212 * respectively; this frees the overriding class from hardcoding its parent 213 * class, which someone might choose to change at some point. 214 * 215 * <example> 216 * <title>Overriding a virtual method</title> 217 * <programlisting> 218 * typedef struct MyState MyState; 219 * 220 * typedef void (*MyDoSomething)(MyState *obj); 221 * 222 * typedef struct MyClass { 223 * ObjectClass parent_class; 224 * 225 * MyDoSomething do_something; 226 * } MyClass; 227 * 228 * static void my_do_something(MyState *obj) 229 * { 230 * // do something 231 * } 232 * 233 * static void my_class_init(ObjectClass *oc, void *data) 234 * { 235 * MyClass *mc = MY_CLASS(oc); 236 * 237 * mc->do_something = my_do_something; 238 * } 239 * 240 * static const TypeInfo my_type_info = { 241 * .name = TYPE_MY, 242 * .parent = TYPE_OBJECT, 243 * .instance_size = sizeof(MyState), 244 * .class_size = sizeof(MyClass), 245 * .class_init = my_class_init, 246 * }; 247 * 248 * typedef struct DerivedClass { 249 * MyClass parent_class; 250 * 251 * MyDoSomething parent_do_something; 252 * } MyClass; 253 * 254 * static void derived_do_something(MyState *obj) 255 * { 256 * DerivedClass *dc = DERIVED_GET_CLASS(obj); 257 * 258 * // do something here 259 * dc->parent_do_something(obj); 260 * // do something else here 261 * } 262 * 263 * static void derived_class_init(ObjectClass *oc, void *data) 264 * { 265 * MyClass *mc = MY_CLASS(oc); 266 * DerivedClass *dc = DERIVED_CLASS(oc); 267 * 268 * dc->parent_do_something = mc->do_something; 269 * mc->do_something = derived_do_something; 270 * } 271 * 272 * static const TypeInfo derived_type_info = { 273 * .name = TYPE_DERIVED, 274 * .parent = TYPE_MY, 275 * .class_size = sizeof(DerivedClass), 276 * .class_init = my_class_init, 277 * }; 278 * </programlisting> 279 * </example> 280 * 281 * Alternatively, object_class_by_name() can be used to obtain the class and 282 * its non-overridden methods for a specific type. This would correspond to 283 * |[ MyClass::method(...) ]| in C++. 284 * 285 * The first example of such a QOM method was #CPUClass.reset, 286 * another example is #DeviceClass.realize. 287 */ 288 289 290 /** 291 * ObjectPropertyAccessor: 292 * @obj: the object that owns the property 293 * @v: the visitor that contains the property data 294 * @opaque: the object property opaque 295 * @name: the name of the property 296 * @errp: a pointer to an Error that is filled if getting/setting fails. 297 * 298 * Called when trying to get/set a property. 299 */ 300 typedef void (ObjectPropertyAccessor)(Object *obj, 301 struct Visitor *v, 302 void *opaque, 303 const char *name, 304 struct Error **errp); 305 306 /** 307 * ObjectPropertyRelease: 308 * @obj: the object that owns the property 309 * @name: the name of the property 310 * @opaque: the opaque registered with the property 311 * 312 * Called when a property is removed from a object. 313 */ 314 typedef void (ObjectPropertyRelease)(Object *obj, 315 const char *name, 316 void *opaque); 317 318 typedef struct ObjectProperty 319 { 320 gchar *name; 321 gchar *type; 322 ObjectPropertyAccessor *get; 323 ObjectPropertyAccessor *set; 324 ObjectPropertyRelease *release; 325 void *opaque; 326 327 QTAILQ_ENTRY(ObjectProperty) node; 328 } ObjectProperty; 329 330 /** 331 * ObjectUnparent: 332 * @obj: the object that is being removed from the composition tree 333 * 334 * Called when an object is being removed from the QOM composition tree. 335 * The function should remove any backlinks from children objects to @obj. 336 */ 337 typedef void (ObjectUnparent)(Object *obj); 338 339 /** 340 * ObjectFree: 341 * @obj: the object being freed 342 * 343 * Called when an object's last reference is removed. 344 */ 345 typedef void (ObjectFree)(void *obj); 346 347 /** 348 * ObjectClass: 349 * 350 * The base for all classes. The only thing that #ObjectClass contains is an 351 * integer type handle. 352 */ 353 struct ObjectClass 354 { 355 /*< private >*/ 356 Type type; 357 GSList *interfaces; 358 359 ObjectUnparent *unparent; 360 }; 361 362 /** 363 * Object: 364 * 365 * The base for all objects. The first member of this object is a pointer to 366 * a #ObjectClass. Since C guarantees that the first member of a structure 367 * always begins at byte 0 of that structure, as long as any sub-object places 368 * its parent as the first member, we can cast directly to a #Object. 369 * 370 * As a result, #Object contains a reference to the objects type as its 371 * first member. This allows identification of the real type of the object at 372 * run time. 373 * 374 * #Object also contains a list of #Interfaces that this object 375 * implements. 376 */ 377 struct Object 378 { 379 /*< private >*/ 380 ObjectClass *class; 381 ObjectFree *free; 382 QTAILQ_HEAD(, ObjectProperty) properties; 383 uint32_t ref; 384 Object *parent; 385 }; 386 387 /** 388 * TypeInfo: 389 * @name: The name of the type. 390 * @parent: The name of the parent type. 391 * @instance_size: The size of the object (derivative of #Object). If 392 * @instance_size is 0, then the size of the object will be the size of the 393 * parent object. 394 * @instance_init: This function is called to initialize an object. The parent 395 * class will have already been initialized so the type is only responsible 396 * for initializing its own members. 397 * @instance_finalize: This function is called during object destruction. This 398 * is called before the parent @instance_finalize function has been called. 399 * An object should only free the members that are unique to its type in this 400 * function. 401 * @abstract: If this field is true, then the class is considered abstract and 402 * cannot be directly instantiated. 403 * @class_size: The size of the class object (derivative of #ObjectClass) 404 * for this object. If @class_size is 0, then the size of the class will be 405 * assumed to be the size of the parent class. This allows a type to avoid 406 * implementing an explicit class type if they are not adding additional 407 * virtual functions. 408 * @class_init: This function is called after all parent class initialization 409 * has occurred to allow a class to set its default virtual method pointers. 410 * This is also the function to use to override virtual methods from a parent 411 * class. 412 * @class_base_init: This function is called for all base classes after all 413 * parent class initialization has occurred, but before the class itself 414 * is initialized. This is the function to use to undo the effects of 415 * memcpy from the parent class to the descendents. 416 * @class_finalize: This function is called during class destruction and is 417 * meant to release and dynamic parameters allocated by @class_init. 418 * @class_data: Data to pass to the @class_init, @class_base_init and 419 * @class_finalize functions. This can be useful when building dynamic 420 * classes. 421 * @interfaces: The list of interfaces associated with this type. This 422 * should point to a static array that's terminated with a zero filled 423 * element. 424 */ 425 struct TypeInfo 426 { 427 const char *name; 428 const char *parent; 429 430 size_t instance_size; 431 void (*instance_init)(Object *obj); 432 void (*instance_finalize)(Object *obj); 433 434 bool abstract; 435 size_t class_size; 436 437 void (*class_init)(ObjectClass *klass, void *data); 438 void (*class_base_init)(ObjectClass *klass, void *data); 439 void (*class_finalize)(ObjectClass *klass, void *data); 440 void *class_data; 441 442 InterfaceInfo *interfaces; 443 }; 444 445 /** 446 * OBJECT: 447 * @obj: A derivative of #Object 448 * 449 * Converts an object to a #Object. Since all objects are #Objects, 450 * this function will always succeed. 451 */ 452 #define OBJECT(obj) \ 453 ((Object *)(obj)) 454 455 /** 456 * OBJECT_CLASS: 457 * @class: A derivative of #ObjectClass. 458 * 459 * Converts a class to an #ObjectClass. Since all objects are #Objects, 460 * this function will always succeed. 461 */ 462 #define OBJECT_CLASS(class) \ 463 ((ObjectClass *)(class)) 464 465 /** 466 * OBJECT_CHECK: 467 * @type: The C type to use for the return value. 468 * @obj: A derivative of @type to cast. 469 * @name: The QOM typename of @type 470 * 471 * A type safe version of @object_dynamic_cast_assert. Typically each class 472 * will define a macro based on this type to perform type safe dynamic_casts to 473 * this object type. 474 * 475 * If an invalid object is passed to this function, a run time assert will be 476 * generated. 477 */ 478 #define OBJECT_CHECK(type, obj, name) \ 479 ((type *)object_dynamic_cast_assert(OBJECT(obj), (name))) 480 481 /** 482 * OBJECT_CLASS_CHECK: 483 * @class: The C type to use for the return value. 484 * @obj: A derivative of @type to cast. 485 * @name: the QOM typename of @class. 486 * 487 * A type safe version of @object_class_dynamic_cast_assert. This macro is 488 * typically wrapped by each type to perform type safe casts of a class to a 489 * specific class type. 490 */ 491 #define OBJECT_CLASS_CHECK(class, obj, name) \ 492 ((class *)object_class_dynamic_cast_assert(OBJECT_CLASS(obj), (name))) 493 494 /** 495 * OBJECT_GET_CLASS: 496 * @class: The C type to use for the return value. 497 * @obj: The object to obtain the class for. 498 * @name: The QOM typename of @obj. 499 * 500 * This function will return a specific class for a given object. Its generally 501 * used by each type to provide a type safe macro to get a specific class type 502 * from an object. 503 */ 504 #define OBJECT_GET_CLASS(class, obj, name) \ 505 OBJECT_CLASS_CHECK(class, object_get_class(OBJECT(obj)), name) 506 507 /** 508 * InterfaceInfo: 509 * @type: The name of the interface. 510 * 511 * The information associated with an interface. 512 */ 513 struct InterfaceInfo { 514 const char *type; 515 }; 516 517 /** 518 * InterfaceClass: 519 * @parent_class: the base class 520 * 521 * The class for all interfaces. Subclasses of this class should only add 522 * virtual methods. 523 */ 524 struct InterfaceClass 525 { 526 ObjectClass parent_class; 527 /*< private >*/ 528 ObjectClass *concrete_class; 529 }; 530 531 #define TYPE_INTERFACE "interface" 532 533 /** 534 * INTERFACE_CLASS: 535 * @klass: class to cast from 536 * Returns: An #InterfaceClass or raise an error if cast is invalid 537 */ 538 #define INTERFACE_CLASS(klass) \ 539 OBJECT_CLASS_CHECK(InterfaceClass, klass, TYPE_INTERFACE) 540 541 /** 542 * INTERFACE_CHECK: 543 * @interface: the type to return 544 * @obj: the object to convert to an interface 545 * @name: the interface type name 546 * 547 * Returns: @obj casted to @interface if cast is valid, otherwise raise error. 548 */ 549 #define INTERFACE_CHECK(interface, obj, name) \ 550 ((interface *)object_dynamic_cast_assert(OBJECT((obj)), (name))) 551 552 /** 553 * object_new: 554 * @typename: The name of the type of the object to instantiate. 555 * 556 * This function will initialize a new object using heap allocated memory. This 557 * function should be paired with object_delete() to free the resources 558 * associated with the object. 559 * 560 * Returns: The newly allocated and instantiated object. 561 */ 562 Object *object_new(const char *typename); 563 564 /** 565 * object_new_with_type: 566 * @type: The type of the object to instantiate. 567 * 568 * This function will initialize a new object using heap allocated memory. This 569 * function should be paired with object_delete() to free the resources 570 * associated with the object. 571 * 572 * Returns: The newly allocated and instantiated object. 573 */ 574 Object *object_new_with_type(Type type); 575 576 /** 577 * object_delete: 578 * @obj: The object to free. 579 * 580 * Finalize an object and then free the memory associated with it. This should 581 * be paired with object_new() to free the resources associated with an object. 582 */ 583 void object_delete(Object *obj); 584 585 /** 586 * object_initialize_with_type: 587 * @obj: A pointer to the memory to be used for the object. 588 * @type: The type of the object to instantiate. 589 * 590 * This function will initialize an object. The memory for the object should 591 * have already been allocated. 592 */ 593 void object_initialize_with_type(void *data, Type type); 594 595 /** 596 * object_initialize: 597 * @obj: A pointer to the memory to be used for the object. 598 * @typename: The name of the type of the object to instantiate. 599 * 600 * This function will initialize an object. The memory for the object should 601 * have already been allocated. 602 */ 603 void object_initialize(void *obj, const char *typename); 604 605 /** 606 * object_dynamic_cast: 607 * @obj: The object to cast. 608 * @typename: The @typename to cast to. 609 * 610 * This function will determine if @obj is-a @typename. @obj can refer to an 611 * object or an interface associated with an object. 612 * 613 * Returns: This function returns @obj on success or #NULL on failure. 614 */ 615 Object *object_dynamic_cast(Object *obj, const char *typename); 616 617 /** 618 * object_dynamic_cast_assert: 619 * 620 * See object_dynamic_cast() for a description of the parameters of this 621 * function. The only difference in behavior is that this function asserts 622 * instead of returning #NULL on failure. 623 */ 624 Object *object_dynamic_cast_assert(Object *obj, const char *typename); 625 626 /** 627 * object_get_class: 628 * @obj: A derivative of #Object 629 * 630 * Returns: The #ObjectClass of the type associated with @obj. 631 */ 632 ObjectClass *object_get_class(Object *obj); 633 634 /** 635 * object_get_typename: 636 * @obj: A derivative of #Object. 637 * 638 * Returns: The QOM typename of @obj. 639 */ 640 const char *object_get_typename(Object *obj); 641 642 /** 643 * type_register_static: 644 * @info: The #TypeInfo of the new type. 645 * 646 * @info and all of the strings it points to should exist for the life time 647 * that the type is registered. 648 * 649 * Returns: 0 on failure, the new #Type on success. 650 */ 651 Type type_register_static(const TypeInfo *info); 652 653 /** 654 * type_register: 655 * @info: The #TypeInfo of the new type 656 * 657 * Unlike type_register_static(), this call does not require @info or its 658 * string members to continue to exist after the call returns. 659 * 660 * Returns: 0 on failure, the new #Type on success. 661 */ 662 Type type_register(const TypeInfo *info); 663 664 /** 665 * object_class_dynamic_cast_assert: 666 * @klass: The #ObjectClass to attempt to cast. 667 * @typename: The QOM typename of the class to cast to. 668 * 669 * Returns: This function always returns @klass and asserts on failure. 670 */ 671 ObjectClass *object_class_dynamic_cast_assert(ObjectClass *klass, 672 const char *typename); 673 674 ObjectClass *object_class_dynamic_cast(ObjectClass *klass, 675 const char *typename); 676 677 /** 678 * object_class_get_parent: 679 * @klass: The class to obtain the parent for. 680 * 681 * Returns: The parent for @klass or %NULL if none. 682 */ 683 ObjectClass *object_class_get_parent(ObjectClass *klass); 684 685 /** 686 * object_class_get_name: 687 * @klass: The class to obtain the QOM typename for. 688 * 689 * Returns: The QOM typename for @klass. 690 */ 691 const char *object_class_get_name(ObjectClass *klass); 692 693 /** 694 * object_class_is_abstract: 695 * @klass: The class to obtain the abstractness for. 696 * 697 * Returns: %true if @klass is abstract, %false otherwise. 698 */ 699 bool object_class_is_abstract(ObjectClass *klass); 700 701 /** 702 * object_class_by_name: 703 * @typename: The QOM typename to obtain the class for. 704 * 705 * Returns: The class for @typename or %NULL if not found. 706 */ 707 ObjectClass *object_class_by_name(const char *typename); 708 709 void object_class_foreach(void (*fn)(ObjectClass *klass, void *opaque), 710 const char *implements_type, bool include_abstract, 711 void *opaque); 712 713 /** 714 * object_class_get_list: 715 * @implements_type: The type to filter for, including its derivatives. 716 * @include_abstract: Whether to include abstract classes. 717 * 718 * Returns: A singly-linked list of the classes in reverse hashtable order. 719 */ 720 GSList *object_class_get_list(const char *implements_type, 721 bool include_abstract); 722 723 /** 724 * object_ref: 725 * @obj: the object 726 * 727 * Increase the reference count of a object. A object cannot be freed as long 728 * as its reference count is greater than zero. 729 */ 730 void object_ref(Object *obj); 731 732 /** 733 * qdef_unref: 734 * @obj: the object 735 * 736 * Decrease the reference count of a object. A object cannot be freed as long 737 * as its reference count is greater than zero. 738 */ 739 void object_unref(Object *obj); 740 741 /** 742 * object_property_add: 743 * @obj: the object to add a property to 744 * @name: the name of the property. This can contain any character except for 745 * a forward slash. In general, you should use hyphens '-' instead of 746 * underscores '_' when naming properties. 747 * @type: the type name of the property. This namespace is pretty loosely 748 * defined. Sub namespaces are constructed by using a prefix and then 749 * to angle brackets. For instance, the type 'virtio-net-pci' in the 750 * 'link' namespace would be 'link<virtio-net-pci>'. 751 * @get: The getter to be called to read a property. If this is NULL, then 752 * the property cannot be read. 753 * @set: the setter to be called to write a property. If this is NULL, 754 * then the property cannot be written. 755 * @release: called when the property is removed from the object. This is 756 * meant to allow a property to free its opaque upon object 757 * destruction. This may be NULL. 758 * @opaque: an opaque pointer to pass to the callbacks for the property 759 * @errp: returns an error if this function fails 760 */ 761 void object_property_add(Object *obj, const char *name, const char *type, 762 ObjectPropertyAccessor *get, 763 ObjectPropertyAccessor *set, 764 ObjectPropertyRelease *release, 765 void *opaque, struct Error **errp); 766 767 void object_property_del(Object *obj, const char *name, struct Error **errp); 768 769 /** 770 * object_property_find: 771 * @obj: the object 772 * @name: the name of the property 773 * @errp: returns an error if this function fails 774 * 775 * Look up a property for an object and return its #ObjectProperty if found. 776 */ 777 ObjectProperty *object_property_find(Object *obj, const char *name, 778 struct Error **errp); 779 780 void object_unparent(Object *obj); 781 782 /** 783 * object_property_get: 784 * @obj: the object 785 * @v: the visitor that will receive the property value. This should be an 786 * Output visitor and the data will be written with @name as the name. 787 * @name: the name of the property 788 * @errp: returns an error if this function fails 789 * 790 * Reads a property from a object. 791 */ 792 void object_property_get(Object *obj, struct Visitor *v, const char *name, 793 struct Error **errp); 794 795 /** 796 * object_property_set_str: 797 * @value: the value to be written to the property 798 * @name: the name of the property 799 * @errp: returns an error if this function fails 800 * 801 * Writes a string value to a property. 802 */ 803 void object_property_set_str(Object *obj, const char *value, 804 const char *name, struct Error **errp); 805 806 /** 807 * object_property_get_str: 808 * @obj: the object 809 * @name: the name of the property 810 * @errp: returns an error if this function fails 811 * 812 * Returns: the value of the property, converted to a C string, or NULL if 813 * an error occurs (including when the property value is not a string). 814 * The caller should free the string. 815 */ 816 char *object_property_get_str(Object *obj, const char *name, 817 struct Error **errp); 818 819 /** 820 * object_property_set_link: 821 * @value: the value to be written to the property 822 * @name: the name of the property 823 * @errp: returns an error if this function fails 824 * 825 * Writes an object's canonical path to a property. 826 */ 827 void object_property_set_link(Object *obj, Object *value, 828 const char *name, struct Error **errp); 829 830 /** 831 * object_property_get_link: 832 * @obj: the object 833 * @name: the name of the property 834 * @errp: returns an error if this function fails 835 * 836 * Returns: the value of the property, resolved from a path to an Object, 837 * or NULL if an error occurs (including when the property value is not a 838 * string or not a valid object path). 839 */ 840 Object *object_property_get_link(Object *obj, const char *name, 841 struct Error **errp); 842 843 /** 844 * object_property_set_bool: 845 * @value: the value to be written to the property 846 * @name: the name of the property 847 * @errp: returns an error if this function fails 848 * 849 * Writes a bool value to a property. 850 */ 851 void object_property_set_bool(Object *obj, bool value, 852 const char *name, struct Error **errp); 853 854 /** 855 * object_property_get_bool: 856 * @obj: the object 857 * @name: the name of the property 858 * @errp: returns an error if this function fails 859 * 860 * Returns: the value of the property, converted to a boolean, or NULL if 861 * an error occurs (including when the property value is not a bool). 862 */ 863 bool object_property_get_bool(Object *obj, const char *name, 864 struct Error **errp); 865 866 /** 867 * object_property_set_int: 868 * @value: the value to be written to the property 869 * @name: the name of the property 870 * @errp: returns an error if this function fails 871 * 872 * Writes an integer value to a property. 873 */ 874 void object_property_set_int(Object *obj, int64_t value, 875 const char *name, struct Error **errp); 876 877 /** 878 * object_property_get_int: 879 * @obj: the object 880 * @name: the name of the property 881 * @errp: returns an error if this function fails 882 * 883 * Returns: the value of the property, converted to an integer, or NULL if 884 * an error occurs (including when the property value is not an integer). 885 */ 886 int64_t object_property_get_int(Object *obj, const char *name, 887 struct Error **errp); 888 889 /** 890 * object_property_set: 891 * @obj: the object 892 * @v: the visitor that will be used to write the property value. This should 893 * be an Input visitor and the data will be first read with @name as the 894 * name and then written as the property value. 895 * @name: the name of the property 896 * @errp: returns an error if this function fails 897 * 898 * Writes a property to a object. 899 */ 900 void object_property_set(Object *obj, struct Visitor *v, const char *name, 901 struct Error **errp); 902 903 /** 904 * object_property_parse: 905 * @obj: the object 906 * @string: the string that will be used to parse the property value. 907 * @name: the name of the property 908 * @errp: returns an error if this function fails 909 * 910 * Parses a string and writes the result into a property of an object. 911 */ 912 void object_property_parse(Object *obj, const char *string, 913 const char *name, struct Error **errp); 914 915 /** 916 * object_property_print: 917 * @obj: the object 918 * @name: the name of the property 919 * @errp: returns an error if this function fails 920 * 921 * Returns a string representation of the value of the property. The 922 * caller shall free the string. 923 */ 924 char *object_property_print(Object *obj, const char *name, 925 struct Error **errp); 926 927 /** 928 * object_property_get_type: 929 * @obj: the object 930 * @name: the name of the property 931 * @errp: returns an error if this function fails 932 * 933 * Returns: The type name of the property. 934 */ 935 const char *object_property_get_type(Object *obj, const char *name, 936 struct Error **errp); 937 938 /** 939 * object_get_root: 940 * 941 * Returns: the root object of the composition tree 942 */ 943 Object *object_get_root(void); 944 945 /** 946 * object_get_canonical_path: 947 * 948 * Returns: The canonical path for a object. This is the path within the 949 * composition tree starting from the root. 950 */ 951 gchar *object_get_canonical_path(Object *obj); 952 953 /** 954 * object_resolve_path: 955 * @path: the path to resolve 956 * @ambiguous: returns true if the path resolution failed because of an 957 * ambiguous match 958 * 959 * There are two types of supported paths--absolute paths and partial paths. 960 * 961 * Absolute paths are derived from the root object and can follow child<> or 962 * link<> properties. Since they can follow link<> properties, they can be 963 * arbitrarily long. Absolute paths look like absolute filenames and are 964 * prefixed with a leading slash. 965 * 966 * Partial paths look like relative filenames. They do not begin with a 967 * prefix. The matching rules for partial paths are subtle but designed to make 968 * specifying objects easy. At each level of the composition tree, the partial 969 * path is matched as an absolute path. The first match is not returned. At 970 * least two matches are searched for. A successful result is only returned if 971 * only one match is found. If more than one match is found, a flag is 972 * returned to indicate that the match was ambiguous. 973 * 974 * Returns: The matched object or NULL on path lookup failure. 975 */ 976 Object *object_resolve_path(const char *path, bool *ambiguous); 977 978 /** 979 * object_resolve_path_type: 980 * @path: the path to resolve 981 * @typename: the type to look for. 982 * @ambiguous: returns true if the path resolution failed because of an 983 * ambiguous match 984 * 985 * This is similar to object_resolve_path. However, when looking for a 986 * partial path only matches that implement the given type are considered. 987 * This restricts the search and avoids spuriously flagging matches as 988 * ambiguous. 989 * 990 * For both partial and absolute paths, the return value goes through 991 * a dynamic cast to @typename. This is important if either the link, 992 * or the typename itself are of interface types. 993 * 994 * Returns: The matched object or NULL on path lookup failure. 995 */ 996 Object *object_resolve_path_type(const char *path, const char *typename, 997 bool *ambiguous); 998 999 /** 1000 * object_resolve_path_component: 1001 * @parent: the object in which to resolve the path 1002 * @part: the component to resolve. 1003 * 1004 * This is similar to object_resolve_path with an absolute path, but it 1005 * only resolves one element (@part) and takes the others from @parent. 1006 * 1007 * Returns: The resolved object or NULL on path lookup failure. 1008 */ 1009 Object *object_resolve_path_component(Object *parent, const gchar *part); 1010 1011 /** 1012 * object_property_add_child: 1013 * @obj: the object to add a property to 1014 * @name: the name of the property 1015 * @child: the child object 1016 * @errp: if an error occurs, a pointer to an area to store the area 1017 * 1018 * Child properties form the composition tree. All objects need to be a child 1019 * of another object. Objects can only be a child of one object. 1020 * 1021 * There is no way for a child to determine what its parent is. It is not 1022 * a bidirectional relationship. This is by design. 1023 * 1024 * The value of a child property as a C string will be the child object's 1025 * canonical path. It can be retrieved using object_property_get_str(). 1026 * The child object itself can be retrieved using object_property_get_link(). 1027 */ 1028 void object_property_add_child(Object *obj, const char *name, 1029 Object *child, struct Error **errp); 1030 1031 /** 1032 * object_property_add_link: 1033 * @obj: the object to add a property to 1034 * @name: the name of the property 1035 * @type: the qobj type of the link 1036 * @child: a pointer to where the link object reference is stored 1037 * @errp: if an error occurs, a pointer to an area to store the area 1038 * 1039 * Links establish relationships between objects. Links are unidirectional 1040 * although two links can be combined to form a bidirectional relationship 1041 * between objects. 1042 * 1043 * Links form the graph in the object model. 1044 */ 1045 void object_property_add_link(Object *obj, const char *name, 1046 const char *type, Object **child, 1047 struct Error **errp); 1048 1049 /** 1050 * object_property_add_str: 1051 * @obj: the object to add a property to 1052 * @name: the name of the property 1053 * @get: the getter or NULL if the property is write-only. This function must 1054 * return a string to be freed by g_free(). 1055 * @set: the setter or NULL if the property is read-only 1056 * @errp: if an error occurs, a pointer to an area to store the error 1057 * 1058 * Add a string property using getters/setters. This function will add a 1059 * property of type 'string'. 1060 */ 1061 void object_property_add_str(Object *obj, const char *name, 1062 char *(*get)(Object *, struct Error **), 1063 void (*set)(Object *, const char *, struct Error **), 1064 struct Error **errp); 1065 1066 /** 1067 * object_property_add_bool: 1068 * @obj: the object to add a property to 1069 * @name: the name of the property 1070 * @get: the getter or NULL if the property is write-only. 1071 * @set: the setter or NULL if the property is read-only 1072 * @errp: if an error occurs, a pointer to an area to store the error 1073 * 1074 * Add a bool property using getters/setters. This function will add a 1075 * property of type 'bool'. 1076 */ 1077 void object_property_add_bool(Object *obj, const char *name, 1078 bool (*get)(Object *, struct Error **), 1079 void (*set)(Object *, bool, struct Error **), 1080 struct Error **errp); 1081 1082 /** 1083 * object_child_foreach: 1084 * @obj: the object whose children will be navigated 1085 * @fn: the iterator function to be called 1086 * @opaque: an opaque value that will be passed to the iterator 1087 * 1088 * Call @fn passing each child of @obj and @opaque to it, until @fn returns 1089 * non-zero. 1090 * 1091 * Returns: The last value returned by @fn, or 0 if there is no child. 1092 */ 1093 int object_child_foreach(Object *obj, int (*fn)(Object *child, void *opaque), 1094 void *opaque); 1095 1096 /** 1097 * container_get: 1098 * @root: root of the #path, e.g., object_get_root() 1099 * @path: path to the container 1100 * 1101 * Return a container object whose path is @path. Create more containers 1102 * along the path if necessary. 1103 * 1104 * Returns: the container object. 1105 */ 1106 Object *container_get(Object *root, const char *path); 1107 1108 1109 #endif 1110