Statistics
| Branch: | Revision:

root / include / qemu / object.h @ 93148aa5

History | View | Annotate | Download (28.1 kB)

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 NULL
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 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 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 functions requires a class to define its own
151
 * struct and to add a .class_size member to the TypeInfo.  Each function
152
 * will also have a wrapper 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 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

    
191

    
192
/**
193
 * ObjectPropertyAccessor:
194
 * @obj: the object that owns the property
195
 * @v: the visitor that contains the property data
196
 * @opaque: the object property opaque
197
 * @name: the name of the property
198
 * @errp: a pointer to an Error that is filled if getting/setting fails.
199
 *
200
 * Called when trying to get/set a property.
201
 */
202
typedef void (ObjectPropertyAccessor)(Object *obj,
203
                                      struct Visitor *v,
204
                                      void *opaque,
205
                                      const char *name,
206
                                      struct Error **errp);
207

    
208
/**
209
 * ObjectPropertyRelease:
210
 * @obj: the object that owns the property
211
 * @name: the name of the property
212
 * @opaque: the opaque registered with the property
213
 *
214
 * Called when a property is removed from a object.
215
 */
216
typedef void (ObjectPropertyRelease)(Object *obj,
217
                                     const char *name,
218
                                     void *opaque);
219

    
220
typedef struct ObjectProperty
221
{
222
    gchar *name;
223
    gchar *type;
224
    ObjectPropertyAccessor *get;
225
    ObjectPropertyAccessor *set;
226
    ObjectPropertyRelease *release;
227
    void *opaque;
228

    
229
    QTAILQ_ENTRY(ObjectProperty) node;
230
} ObjectProperty;
231

    
232
/**
233
 * ObjectClass:
234
 *
235
 * The base for all classes.  The only thing that #ObjectClass contains is an
236
 * integer type handle.
237
 */
238
struct ObjectClass
239
{
240
    /*< private >*/
241
    Type type;
242
};
243

    
244
/**
245
 * Object:
246
 *
247
 * The base for all objects.  The first member of this object is a pointer to
248
 * a #ObjectClass.  Since C guarantees that the first member of a structure
249
 * always begins at byte 0 of that structure, as long as any sub-object places
250
 * its parent as the first member, we can cast directly to a #Object.
251
 *
252
 * As a result, #Object contains a reference to the objects type as its
253
 * first member.  This allows identification of the real type of the object at
254
 * run time.
255
 *
256
 * #Object also contains a list of #Interfaces that this object
257
 * implements.
258
 */
259
struct Object
260
{
261
    /*< private >*/
262
    ObjectClass *class;
263
    GSList *interfaces;
264
    QTAILQ_HEAD(, ObjectProperty) properties;
265
    uint32_t ref;
266
    Object *parent;
267
};
268

    
269
/**
270
 * TypeInfo:
271
 * @name: The name of the type.
272
 * @parent: The name of the parent type.
273
 * @instance_size: The size of the object (derivative of #Object).  If
274
 *   @instance_size is 0, then the size of the object will be the size of the
275
 *   parent object.
276
 * @instance_init: This function is called to initialize an object.  The parent
277
 *   class will have already been initialized so the type is only responsible
278
 *   for initializing its own members.
279
 * @instance_finalize: This function is called during object destruction.  This
280
 *   is called before the parent @instance_finalize function has been called.
281
 *   An object should only free the members that are unique to its type in this
282
 *   function.
283
 * @abstract: If this field is true, then the class is considered abstract and
284
 *   cannot be directly instantiated.
285
 * @class_size: The size of the class object (derivative of #ObjectClass)
286
 *   for this object.  If @class_size is 0, then the size of the class will be
287
 *   assumed to be the size of the parent class.  This allows a type to avoid
288
 *   implementing an explicit class type if they are not adding additional
289
 *   virtual functions.
290
 * @class_init: This function is called after all parent class initialization
291
 *   has occurred to allow a class to set its default virtual method pointers.
292
 *   This is also the function to use to override virtual methods from a parent
293
 *   class.
294
 * @class_finalize: This function is called during class destruction and is
295
 *   meant to release and dynamic parameters allocated by @class_init.
296
 * @class_data: Data to pass to the @class_init and @class_finalize functions.
297
 *   This can be useful when building dynamic classes.
298
 * @interfaces: The list of interfaces associated with this type.  This
299
 *   should point to a static array that's terminated with a zero filled
300
 *   element.
301
 */
302
struct TypeInfo
303
{
304
    const char *name;
305
    const char *parent;
306

    
307
    size_t instance_size;
308
    void (*instance_init)(Object *obj);
309
    void (*instance_finalize)(Object *obj);
310

    
311
    bool abstract;
312
    size_t class_size;
313

    
314
    void (*class_init)(ObjectClass *klass, void *data);
315
    void (*class_finalize)(ObjectClass *klass, void *data);
316
    void *class_data;
317

    
318
    InterfaceInfo *interfaces;
319
};
320

    
321
/**
322
 * OBJECT:
323
 * @obj: A derivative of #Object
324
 *
325
 * Converts an object to a #Object.  Since all objects are #Objects,
326
 * this function will always succeed.
327
 */
328
#define OBJECT(obj) \
329
    ((Object *)(obj))
330

    
331
/**
332
 * OBJECT_CLASS:
333
 * @class: A derivative of #ObjectClass.
334
 *
335
 * Converts a class to an #ObjectClass.  Since all objects are #Objects,
336
 * this function will always succeed.
337
 */
338
#define OBJECT_CLASS(class) \
339
    ((ObjectClass *)(class))
340

    
341
/**
342
 * OBJECT_CHECK:
343
 * @type: The C type to use for the return value.
344
 * @obj: A derivative of @type to cast.
345
 * @name: The QOM typename of @type
346
 *
347
 * A type safe version of @object_dynamic_cast_assert.  Typically each class
348
 * will define a macro based on this type to perform type safe dynamic_casts to
349
 * this object type.
350
 *
351
 * If an invalid object is passed to this function, a run time assert will be
352
 * generated.
353
 */
354
#define OBJECT_CHECK(type, obj, name) \
355
    ((type *)object_dynamic_cast_assert(OBJECT(obj), (name)))
356

    
357
/**
358
 * OBJECT_CLASS_CHECK:
359
 * @class: The C type to use for the return value.
360
 * @obj: A derivative of @type to cast.
361
 * @name: the QOM typename of @class.
362
 *
363
 * A type safe version of @object_class_dynamic_cast_assert.  This macro is
364
 * typically wrapped by each type to perform type safe casts of a class to a
365
 * specific class type.
366
 */
367
#define OBJECT_CLASS_CHECK(class, obj, name) \
368
    ((class *)object_class_dynamic_cast_assert(OBJECT_CLASS(obj), (name)))
369

    
370
/**
371
 * OBJECT_GET_CLASS:
372
 * @class: The C type to use for the return value.
373
 * @obj: The object to obtain the class for.
374
 * @name: The QOM typename of @obj.
375
 *
376
 * This function will return a specific class for a given object.  Its generally
377
 * used by each type to provide a type safe macro to get a specific class type
378
 * from an object.
379
 */
380
#define OBJECT_GET_CLASS(class, obj, name) \
381
    OBJECT_CLASS_CHECK(class, object_get_class(OBJECT(obj)), name)
382

    
383
/**
384
 * InterfaceClass:
385
 * @parent_class: the base class
386
 *
387
 * The class for all interfaces.  Subclasses of this class should only add
388
 * virtual methods.
389
 */
390
struct InterfaceClass
391
{
392
    ObjectClass parent_class;
393
};
394

    
395
/**
396
 * InterfaceInfo:
397
 * @type: The name of the interface.
398
 * @interface_initfn: This method is called during class initialization and is
399
 *   used to initialize an interface associated with a class.  This function
400
 *   should initialize any default virtual functions for a class and/or override
401
 *   virtual functions in a parent class.
402
 *
403
 * The information associated with an interface.
404
 */
405
struct InterfaceInfo
406
{
407
    const char *type;
408

    
409
    void (*interface_initfn)(ObjectClass *class, void *data);
410
};
411

    
412
#define TYPE_INTERFACE "interface"
413

    
414
/**
415
 * object_new:
416
 * @typename: The name of the type of the object to instantiate.
417
 *
418
 * This function will initialize a new object using heap allocated memory.  This
419
 * function should be paired with object_delete() to free the resources
420
 * associated with the object.
421
 *
422
 * Returns: The newly allocated and instantiated object.
423
 */
424
Object *object_new(const char *typename);
425

    
426
/**
427
 * object_new_with_type:
428
 * @type: The type of the object to instantiate.
429
 *
430
 * This function will initialize a new object using heap allocated memory.  This
431
 * function should be paired with object_delete() to free the resources
432
 * associated with the object.
433
 *
434
 * Returns: The newly allocated and instantiated object.
435
 */
436
Object *object_new_with_type(Type type);
437

    
438
/**
439
 * object_delete:
440
 * @obj: The object to free.
441
 *
442
 * Finalize an object and then free the memory associated with it.  This should
443
 * be paired with object_new() to free the resources associated with an object.
444
 */
445
void object_delete(Object *obj);
446

    
447
/**
448
 * object_initialize_with_type:
449
 * @obj: A pointer to the memory to be used for the object.
450
 * @type: The type of the object to instantiate.
451
 *
452
 * This function will initialize an object.  The memory for the object should
453
 * have already been allocated.
454
 */
455
void object_initialize_with_type(void *data, Type type);
456

    
457
/**
458
 * object_initialize:
459
 * @obj: A pointer to the memory to be used for the object.
460
 * @typename: The name of the type of the object to instantiate.
461
 *
462
 * This function will initialize an object.  The memory for the object should
463
 * have already been allocated.
464
 */
465
void object_initialize(void *obj, const char *typename);
466

    
467
/**
468
 * object_finalize:
469
 * @obj: The object to finalize.
470
 *
471
 * This function destroys and object without freeing the memory associated with
472
 * it.
473
 */
474
void object_finalize(void *obj);
475

    
476
/**
477
 * object_dynamic_cast:
478
 * @obj: The object to cast.
479
 * @typename: The @typename to cast to.
480
 *
481
 * This function will determine if @obj is-a @typename.  @obj can refer to an
482
 * object or an interface associated with an object.
483
 *
484
 * Returns: This function returns @obj on success or #NULL on failure.
485
 */
486
Object *object_dynamic_cast(Object *obj, const char *typename);
487

    
488
/**
489
 * object_dynamic_cast_assert:
490
 *
491
 * See object_dynamic_cast() for a description of the parameters of this
492
 * function.  The only difference in behavior is that this function asserts
493
 * instead of returning #NULL on failure.
494
 */
495
Object *object_dynamic_cast_assert(Object *obj, const char *typename);
496

    
497
/**
498
 * object_get_class:
499
 * @obj: A derivative of #Object
500
 *
501
 * Returns: The #ObjectClass of the type associated with @obj.
502
 */
503
ObjectClass *object_get_class(Object *obj);
504

    
505
/**
506
 * object_get_typename:
507
 * @obj: A derivative of #Object.
508
 *
509
 * Returns: The QOM typename of @obj.
510
 */
511
const char *object_get_typename(Object *obj);
512

    
513
/**
514
 * type_register_static:
515
 * @info: The #TypeInfo of the new type.
516
 *
517
 * @info and all of the strings it points to should exist for the life time
518
 * that the type is registered.
519
 *
520
 * Returns: 0 on failure, the new #Type on success.
521
 */
522
Type type_register_static(const TypeInfo *info);
523

    
524
#define type_register_static_alias(info, name) do { } while (0)
525

    
526
/**
527
 * type_register:
528
 * @info: The #TypeInfo of the new type
529
 *
530
 * Unlike type_register_static(), this call does not require @info or its
531
 * string members to continue to exist after the call returns.
532
 *
533
 * Returns: 0 on failure, the new #Type on success.
534
 */
535
Type type_register(const TypeInfo *info);
536

    
537
/**
538
 * object_class_dynamic_cast_assert:
539
 * @klass: The #ObjectClass to attempt to cast.
540
 * @typename: The QOM typename of the class to cast to.
541
 *
542
 * Returns: This function always returns @klass and asserts on failure.
543
 */
544
ObjectClass *object_class_dynamic_cast_assert(ObjectClass *klass,
545
                                              const char *typename);
546

    
547
ObjectClass *object_class_dynamic_cast(ObjectClass *klass,
548
                                       const char *typename);
549

    
550
/**
551
 * object_class_get_name:
552
 * @klass: The class to obtain the QOM typename for.
553
 *
554
 * Returns: The QOM typename for @klass.
555
 */
556
const char *object_class_get_name(ObjectClass *klass);
557

    
558
ObjectClass *object_class_by_name(const char *typename);
559

    
560
void object_class_foreach(void (*fn)(ObjectClass *klass, void *opaque),
561
                          const char *implements_type, bool include_abstract,
562
                          void *opaque);
563
/**
564
 * object_ref:
565
 * @obj: the object
566
 *
567
 * Increase the reference count of a object.  A object cannot be freed as long
568
 * as its reference count is greater than zero.
569
 */
570
void object_ref(Object *obj);
571

    
572
/**
573
 * qdef_unref:
574
 * @obj: the object
575
 *
576
 * Decrease the reference count of a object.  A object cannot be freed as long
577
 * as its reference count is greater than zero.
578
 */
579
void object_unref(Object *obj);
580

    
581
/**
582
 * object_property_add:
583
 * @obj: the object to add a property to
584
 * @name: the name of the property.  This can contain any character except for
585
 *  a forward slash.  In general, you should use hyphens '-' instead of
586
 *  underscores '_' when naming properties.
587
 * @type: the type name of the property.  This namespace is pretty loosely
588
 *   defined.  Sub namespaces are constructed by using a prefix and then
589
 *   to angle brackets.  For instance, the type 'virtio-net-pci' in the
590
 *   'link' namespace would be 'link<virtio-net-pci>'.
591
 * @get: The getter to be called to read a property.  If this is NULL, then
592
 *   the property cannot be read.
593
 * @set: the setter to be called to write a property.  If this is NULL,
594
 *   then the property cannot be written.
595
 * @release: called when the property is removed from the object.  This is
596
 *   meant to allow a property to free its opaque upon object
597
 *   destruction.  This may be NULL.
598
 * @opaque: an opaque pointer to pass to the callbacks for the property
599
 * @errp: returns an error if this function fails
600
 */
601
void object_property_add(Object *obj, const char *name, const char *type,
602
                         ObjectPropertyAccessor *get,
603
                         ObjectPropertyAccessor *set,
604
                         ObjectPropertyRelease *release,
605
                         void *opaque, struct Error **errp);
606

    
607
void object_property_del(Object *obj, const char *name, struct Error **errp);
608

    
609
void object_unparent(Object *obj);
610

    
611
/**
612
 * object_property_get:
613
 * @obj: the object
614
 * @v: the visitor that will receive the property value.  This should be an
615
 *   Output visitor and the data will be written with @name as the name.
616
 * @name: the name of the property
617
 * @errp: returns an error if this function fails
618
 *
619
 * Reads a property from a object.
620
 */
621
void object_property_get(Object *obj, struct Visitor *v, const char *name,
622
                         struct Error **errp);
623

    
624
/**
625
 * object_property_set_str:
626
 * @value: the value to be written to the property
627
 * @name: the name of the property
628
 * @errp: returns an error if this function fails
629
 *
630
 * Writes a string value to a property.
631
 */
632
void object_property_set_str(Object *obj, const char *value,
633
                             const char *name, struct Error **errp);
634

    
635
/**
636
 * object_property_get_str:
637
 * @obj: the object
638
 * @name: the name of the property
639
 * @errp: returns an error if this function fails
640
 *
641
 * Returns: the value of the property, converted to a C string, or NULL if
642
 * an error occurs (including when the property value is not a string).
643
 * The caller should free the string.
644
 */
645
char *object_property_get_str(Object *obj, const char *name,
646
                              struct Error **errp);
647

    
648
/**
649
 * object_property_set_link:
650
 * @value: the value to be written to the property
651
 * @name: the name of the property
652
 * @errp: returns an error if this function fails
653
 *
654
 * Writes an object's canonical path to a property.
655
 */
656
void object_property_set_link(Object *obj, Object *value,
657
                              const char *name, struct Error **errp);
658

    
659
/**
660
 * object_property_get_link:
661
 * @obj: the object
662
 * @name: the name of the property
663
 * @errp: returns an error if this function fails
664
 *
665
 * Returns: the value of the property, resolved from a path to an Object,
666
 * or NULL if an error occurs (including when the property value is not a
667
 * string or not a valid object path).
668
 */
669
Object *object_property_get_link(Object *obj, const char *name,
670
                                 struct Error **errp);
671

    
672
/**
673
 * object_property_set_bool:
674
 * @value: the value to be written to the property
675
 * @name: the name of the property
676
 * @errp: returns an error if this function fails
677
 *
678
 * Writes a bool value to a property.
679
 */
680
void object_property_set_bool(Object *obj, bool value,
681
                              const char *name, struct Error **errp);
682

    
683
/**
684
 * object_property_get_bool:
685
 * @obj: the object
686
 * @name: the name of the property
687
 * @errp: returns an error if this function fails
688
 *
689
 * Returns: the value of the property, converted to a boolean, or NULL if
690
 * an error occurs (including when the property value is not a bool).
691
 */
692
bool object_property_get_bool(Object *obj, const char *name,
693
                              struct Error **errp);
694

    
695
/**
696
 * object_property_set_int:
697
 * @value: the value to be written to the property
698
 * @name: the name of the property
699
 * @errp: returns an error if this function fails
700
 *
701
 * Writes an integer value to a property.
702
 */
703
void object_property_set_int(Object *obj, int64_t value,
704
                             const char *name, struct Error **errp);
705

    
706
/**
707
 * object_property_get_int:
708
 * @obj: the object
709
 * @name: the name of the property
710
 * @errp: returns an error if this function fails
711
 *
712
 * Returns: the value of the property, converted to an integer, or NULL if
713
 * an error occurs (including when the property value is not an integer).
714
 */
715
int64_t object_property_get_int(Object *obj, const char *name,
716
                                struct Error **errp);
717

    
718
/**
719
 * object_property_set:
720
 * @obj: the object
721
 * @v: the visitor that will be used to write the property value.  This should
722
 *   be an Input visitor and the data will be first read with @name as the
723
 *   name and then written as the property value.
724
 * @name: the name of the property
725
 * @errp: returns an error if this function fails
726
 *
727
 * Writes a property to a object.
728
 */
729
void object_property_set(Object *obj, struct Visitor *v, const char *name,
730
                         struct Error **errp);
731

    
732
/**
733
 * object_property_parse:
734
 * @obj: the object
735
 * @string: the string that will be used to parse the property value.
736
 * @name: the name of the property
737
 * @errp: returns an error if this function fails
738
 *
739
 * Parses a string and writes the result into a property of an object.
740
 */
741
void object_property_parse(Object *obj, const char *string,
742
                           const char *name, struct Error **errp);
743

    
744
/**
745
 * object_property_print:
746
 * @obj: the object
747
 * @name: the name of the property
748
 * @errp: returns an error if this function fails
749
 *
750
 * Returns a string representation of the value of the property.  The
751
 * caller shall free the string.
752
 */
753
char *object_property_print(Object *obj, const char *name,
754
                            struct Error **errp);
755

    
756
/**
757
 * object_property_get_type:
758
 * @obj: the object
759
 * @name: the name of the property
760
 * @errp: returns an error if this function fails
761
 *
762
 * Returns:  The type name of the property.
763
 */
764
const char *object_property_get_type(Object *obj, const char *name,
765
                                     struct Error **errp);
766

    
767
/**
768
 * object_get_root:
769
 *
770
 * Returns: the root object of the composition tree
771
 */
772
Object *object_get_root(void);
773

    
774
/**
775
 * object_get_canonical_path:
776
 *
777
 * Returns: The canonical path for a object.  This is the path within the
778
 * composition tree starting from the root.
779
 */
780
gchar *object_get_canonical_path(Object *obj);
781

    
782
/**
783
 * object_resolve_path:
784
 * @path: the path to resolve
785
 * @ambiguous: returns true if the path resolution failed because of an
786
 *   ambiguous match
787
 *
788
 * There are two types of supported paths--absolute paths and partial paths.
789
 * 
790
 * Absolute paths are derived from the root object and can follow child<> or
791
 * link<> properties.  Since they can follow link<> properties, they can be
792
 * arbitrarily long.  Absolute paths look like absolute filenames and are
793
 * prefixed with a leading slash.
794
 * 
795
 * Partial paths look like relative filenames.  They do not begin with a
796
 * prefix.  The matching rules for partial paths are subtle but designed to make
797
 * specifying objects easy.  At each level of the composition tree, the partial
798
 * path is matched as an absolute path.  The first match is not returned.  At
799
 * least two matches are searched for.  A successful result is only returned if
800
 * only one match is found.  If more than one match is found, a flag is
801
 * returned to indicate that the match was ambiguous.
802
 *
803
 * Returns: The matched object or NULL on path lookup failure.
804
 */
805
Object *object_resolve_path(const char *path, bool *ambiguous);
806

    
807
/**
808
 * object_resolve_path_type:
809
 * @path: the path to resolve
810
 * @typename: the type to look for.
811
 * @ambiguous: returns true if the path resolution failed because of an
812
 *   ambiguous match
813
 *
814
 * This is similar to object_resolve_path.  However, when looking for a
815
 * partial path only matches that implement the given type are considered.
816
 * This restricts the search and avoids spuriously flagging matches as
817
 * ambiguous.
818
 *
819
 * For both partial and absolute paths, the return value goes through
820
 * a dynamic cast to @typename.  This is important if either the link,
821
 * or the typename itself are of interface types.
822
 *
823
 * Returns: The matched object or NULL on path lookup failure.
824
 */
825
Object *object_resolve_path_type(const char *path, const char *typename,
826
                                 bool *ambiguous);
827

    
828
/**
829
 * object_property_add_child:
830
 * @obj: the object to add a property to
831
 * @name: the name of the property
832
 * @child: the child object
833
 * @errp: if an error occurs, a pointer to an area to store the area
834
 *
835
 * Child properties form the composition tree.  All objects need to be a child
836
 * of another object.  Objects can only be a child of one object.
837
 *
838
 * There is no way for a child to determine what its parent is.  It is not
839
 * a bidirectional relationship.  This is by design.
840
 *
841
 * The value of a child property as a C string will be the child object's
842
 * canonical path. It can be retrieved using object_property_get_str().
843
 * The child object itself can be retrieved using object_property_get_link().
844
 */
845
void object_property_add_child(Object *obj, const char *name,
846
                               Object *child, struct Error **errp);
847

    
848
/**
849
 * object_property_add_link:
850
 * @obj: the object to add a property to
851
 * @name: the name of the property
852
 * @type: the qobj type of the link
853
 * @child: a pointer to where the link object reference is stored
854
 * @errp: if an error occurs, a pointer to an area to store the area
855
 *
856
 * Links establish relationships between objects.  Links are unidirectional
857
 * although two links can be combined to form a bidirectional relationship
858
 * between objects.
859
 *
860
 * Links form the graph in the object model.
861
 */
862
void object_property_add_link(Object *obj, const char *name,
863
                              const char *type, Object **child,
864
                              struct Error **errp);
865

    
866
/**
867
 * object_property_add_str:
868
 * @obj: the object to add a property to
869
 * @name: the name of the property
870
 * @get: the getter or NULL if the property is write-only.  This function must
871
 *   return a string to be freed by g_free().
872
 * @set: the setter or NULL if the property is read-only
873
 * @errp: if an error occurs, a pointer to an area to store the error
874
 *
875
 * Add a string property using getters/setters.  This function will add a
876
 * property of type 'string'.
877
 */
878
void object_property_add_str(Object *obj, const char *name,
879
                             char *(*get)(Object *, struct Error **),
880
                             void (*set)(Object *, const char *, struct Error **),
881
                             struct Error **errp);
882

    
883
#endif