1 | /* |
2 | * QEMU Object Model |
3 | * |
4 | * Copyright IBM, Corp. 2011 |
5 | * |
6 | * Authors: |
7 | * Anthony Liguori <aliguori@us.ibm.com> |
8 | * |
9 | * This work is licensed under the terms of the GNU GPL, version 2 or later. |
10 | * See the COPYING file in the top-level directory. |
11 | * |
12 | */ |
13 | |
14 | #ifndef QEMU_OBJECT_H |
15 | #define QEMU_OBJECT_H |
16 | |
17 | #include "qapi/qapi-builtin-types.h" |
18 | #include "qemu/module.h" |
19 | |
20 | struct TypeImpl; |
21 | typedef struct TypeImpl *Type; |
22 | |
23 | typedef struct 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_data: Data to pass to the @class_init, |
458 | * @class_base_init. This can be useful when building dynamic |
459 | * classes. |
460 | * @interfaces: The list of interfaces associated with this type. This |
461 | * should point to a static array that's terminated with a zero filled |
462 | * element. |
463 | */ |
464 | struct TypeInfo |
465 | { |
466 | const char *name; |
467 | const char *parent; |
468 | |
469 | size_t instance_size; |
470 | void (*instance_init)(Object *obj); |
471 | void (*instance_post_init)(Object *obj); |
472 | void (*instance_finalize)(Object *obj); |
473 | |
474 | bool abstract; |
475 | size_t class_size; |
476 | |
477 | void (*class_init)(ObjectClass *klass, void *data); |
478 | void (*class_base_init)(ObjectClass *klass, void *data); |
479 | void *class_data; |
480 | |
481 | InterfaceInfo *interfaces; |
482 | }; |
483 | |
484 | /** |
485 | * OBJECT: |
486 | * @obj: A derivative of #Object |
487 | * |
488 | * Converts an object to a #Object. Since all objects are #Objects, |
489 | * this function will always succeed. |
490 | */ |
491 | #define OBJECT(obj) \ |
492 | ((Object *)(obj)) |
493 | |
494 | /** |
495 | * OBJECT_CLASS: |
496 | * @class: A derivative of #ObjectClass. |
497 | * |
498 | * Converts a class to an #ObjectClass. Since all objects are #Objects, |
499 | * this function will always succeed. |
500 | */ |
501 | #define OBJECT_CLASS(class) \ |
502 | ((ObjectClass *)(class)) |
503 | |
504 | /** |
505 | * OBJECT_CHECK: |
506 | * @type: The C type to use for the return value. |
507 | * @obj: A derivative of @type to cast. |
508 | * @name: The QOM typename of @type |
509 | * |
510 | * A type safe version of @object_dynamic_cast_assert. Typically each class |
511 | * will define a macro based on this type to perform type safe dynamic_casts to |
512 | * this object type. |
513 | * |
514 | * If an invalid object is passed to this function, a run time assert will be |
515 | * generated. |
516 | */ |
517 | #define OBJECT_CHECK(type, obj, name) \ |
518 | ((type *)object_dynamic_cast_assert(OBJECT(obj), (name), \ |
519 | __FILE__, __LINE__, __func__)) |
520 | |
521 | /** |
522 | * OBJECT_CLASS_CHECK: |
523 | * @class_type: The C type to use for the return value. |
524 | * @class: A derivative class of @class_type to cast. |
525 | * @name: the QOM typename of @class_type. |
526 | * |
527 | * A type safe version of @object_class_dynamic_cast_assert. This macro is |
528 | * typically wrapped by each type to perform type safe casts of a class to a |
529 | * specific class type. |
530 | */ |
531 | #define OBJECT_CLASS_CHECK(class_type, class, name) \ |
532 | ((class_type *)object_class_dynamic_cast_assert(OBJECT_CLASS(class), (name), \ |
533 | __FILE__, __LINE__, __func__)) |
534 | |
535 | /** |
536 | * OBJECT_GET_CLASS: |
537 | * @class: The C type to use for the return value. |
538 | * @obj: The object to obtain the class for. |
539 | * @name: The QOM typename of @obj. |
540 | * |
541 | * This function will return a specific class for a given object. Its generally |
542 | * used by each type to provide a type safe macro to get a specific class type |
543 | * from an object. |
544 | */ |
545 | #define OBJECT_GET_CLASS(class, obj, name) \ |
546 | OBJECT_CLASS_CHECK(class, object_get_class(OBJECT(obj)), name) |
547 | |
548 | /** |
549 | * InterfaceInfo: |
550 | * @type: The name of the interface. |
551 | * |
552 | * The information associated with an interface. |
553 | */ |
554 | struct InterfaceInfo { |
555 | const char *type; |
556 | }; |
557 | |
558 | /** |
559 | * InterfaceClass: |
560 | * @parent_class: the base class |
561 | * |
562 | * The class for all interfaces. Subclasses of this class should only add |
563 | * virtual methods. |
564 | */ |
565 | struct InterfaceClass |
566 | { |
567 | ObjectClass parent_class; |
568 | /*< private >*/ |
569 | ObjectClass *concrete_class; |
570 | Type interface_type; |
571 | }; |
572 | |
573 | #define TYPE_INTERFACE "interface" |
574 | |
575 | /** |
576 | * INTERFACE_CLASS: |
577 | * @klass: class to cast from |
578 | * Returns: An #InterfaceClass or raise an error if cast is invalid |
579 | */ |
580 | #define INTERFACE_CLASS(klass) \ |
581 | OBJECT_CLASS_CHECK(InterfaceClass, klass, TYPE_INTERFACE) |
582 | |
583 | /** |
584 | * INTERFACE_CHECK: |
585 | * @interface: the type to return |
586 | * @obj: the object to convert to an interface |
587 | * @name: the interface type name |
588 | * |
589 | * Returns: @obj casted to @interface if cast is valid, otherwise raise error. |
590 | */ |
591 | #define INTERFACE_CHECK(interface, obj, name) \ |
592 | ((interface *)object_dynamic_cast_assert(OBJECT((obj)), (name), \ |
593 | __FILE__, __LINE__, __func__)) |
594 | |
595 | /** |
596 | * object_new: |
597 | * @typename: The name of the type of the object to instantiate. |
598 | * |
599 | * This function will initialize a new object using heap allocated memory. |
600 | * The returned object has a reference count of 1, and will be freed when |
601 | * the last reference is dropped. |
602 | * |
603 | * Returns: The newly allocated and instantiated object. |
604 | */ |
605 | Object *object_new(const char *typename); |
606 | |
607 | /** |
608 | * object_new_with_props: |
609 | * @typename: The name of the type of the object to instantiate. |
610 | * @parent: the parent object |
611 | * @id: The unique ID of the object |
612 | * @errp: pointer to error object |
613 | * @...: list of property names and values |
614 | * |
615 | * This function will initialize a new object using heap allocated memory. |
616 | * The returned object has a reference count of 1, and will be freed when |
617 | * the last reference is dropped. |
618 | * |
619 | * The @id parameter will be used when registering the object as a |
620 | * child of @parent in the composition tree. |
621 | * |
622 | * The variadic parameters are a list of pairs of (propname, propvalue) |
623 | * strings. The propname of %NULL indicates the end of the property |
624 | * list. If the object implements the user creatable interface, the |
625 | * object will be marked complete once all the properties have been |
626 | * processed. |
627 | * |
628 | * <example> |
629 | * <title>Creating an object with properties</title> |
630 | * <programlisting> |
631 | * Error *err = NULL; |
632 | * Object *obj; |
633 | * |
634 | * obj = object_new_with_props(TYPE_MEMORY_BACKEND_FILE, |
635 | * object_get_objects_root(), |
636 | * "hostmem0", |
637 | * &err, |
638 | * "share", "yes", |
639 | * "mem-path", "/dev/shm/somefile", |
640 | * "prealloc", "yes", |
641 | * "size", "1048576", |
642 | * NULL); |
643 | * |
644 | * if (!obj) { |
645 | * g_printerr("Cannot create memory backend: %s\n", |
646 | * error_get_pretty(err)); |
647 | * } |
648 | * </programlisting> |
649 | * </example> |
650 | * |
651 | * The returned object will have one stable reference maintained |
652 | * for as long as it is present in the object hierarchy. |
653 | * |
654 | * Returns: The newly allocated, instantiated & initialized object. |
655 | */ |
656 | Object *object_new_with_props(const char *typename, |
657 | Object *parent, |
658 | const char *id, |
659 | Error **errp, |
660 | ...) QEMU_SENTINEL; |
661 | |
662 | /** |
663 | * object_new_with_propv: |
664 | * @typename: The name of the type of the object to instantiate. |
665 | * @parent: the parent object |
666 | * @id: The unique ID of the object |
667 | * @errp: pointer to error object |
668 | * @vargs: list of property names and values |
669 | * |
670 | * See object_new_with_props() for documentation. |
671 | */ |
672 | Object *object_new_with_propv(const char *typename, |
673 | Object *parent, |
674 | const char *id, |
675 | Error **errp, |
676 | va_list vargs); |
677 | |
678 | void object_apply_global_props(Object *obj, const GPtrArray *props, |
679 | Error **errp); |
680 | void object_set_machine_compat_props(GPtrArray *compat_props); |
681 | void object_set_accelerator_compat_props(GPtrArray *compat_props); |
682 | void object_apply_compat_props(Object *obj); |
683 | |
684 | /** |
685 | * object_set_props: |
686 | * @obj: the object instance to set properties on |
687 | * @errp: pointer to error object |
688 | * @...: list of property names and values |
689 | * |
690 | * This function will set a list of properties on an existing object |
691 | * instance. |
692 | * |
693 | * The variadic parameters are a list of pairs of (propname, propvalue) |
694 | * strings. The propname of %NULL indicates the end of the property |
695 | * list. |
696 | * |
697 | * <example> |
698 | * <title>Update an object's properties</title> |
699 | * <programlisting> |
700 | * Error *err = NULL; |
701 | * Object *obj = ...get / create object...; |
702 | * |
703 | * obj = object_set_props(obj, |
704 | * &err, |
705 | * "share", "yes", |
706 | * "mem-path", "/dev/shm/somefile", |
707 | * "prealloc", "yes", |
708 | * "size", "1048576", |
709 | * NULL); |
710 | * |
711 | * if (!obj) { |
712 | * g_printerr("Cannot set properties: %s\n", |
713 | * error_get_pretty(err)); |
714 | * } |
715 | * </programlisting> |
716 | * </example> |
717 | * |
718 | * The returned object will have one stable reference maintained |
719 | * for as long as it is present in the object hierarchy. |
720 | * |
721 | * Returns: -1 on error, 0 on success |
722 | */ |
723 | int object_set_props(Object *obj, |
724 | Error **errp, |
725 | ...) QEMU_SENTINEL; |
726 | |
727 | /** |
728 | * object_set_propv: |
729 | * @obj: the object instance to set properties on |
730 | * @errp: pointer to error object |
731 | * @vargs: list of property names and values |
732 | * |
733 | * See object_set_props() for documentation. |
734 | * |
735 | * Returns: -1 on error, 0 on success |
736 | */ |
737 | int object_set_propv(Object *obj, |
738 | Error **errp, |
739 | va_list vargs); |
740 | |
741 | /** |
742 | * object_initialize: |
743 | * @obj: A pointer to the memory to be used for the object. |
744 | * @size: The maximum size available at @obj for the object. |
745 | * @typename: The name of the type of the object to instantiate. |
746 | * |
747 | * This function will initialize an object. The memory for the object should |
748 | * have already been allocated. The returned object has a reference count of 1, |
749 | * and will be finalized when the last reference is dropped. |
750 | */ |
751 | void object_initialize(void *obj, size_t size, const char *typename); |
752 | |
753 | /** |
754 | * object_initialize_child: |
755 | * @parentobj: The parent object to add a property to |
756 | * @propname: The name of the property |
757 | * @childobj: A pointer to the memory to be used for the object. |
758 | * @size: The maximum size available at @childobj for the object. |
759 | * @type: The name of the type of the object to instantiate. |
760 | * @errp: If an error occurs, a pointer to an area to store the error |
761 | * @...: list of property names and values |
762 | * |
763 | * This function will initialize an object. The memory for the object should |
764 | * have already been allocated. The object will then be added as child property |
765 | * to a parent with object_property_add_child() function. The returned object |
766 | * has a reference count of 1 (for the "child<...>" property from the parent), |
767 | * so the object will be finalized automatically when the parent gets removed. |
768 | * |
769 | * The variadic parameters are a list of pairs of (propname, propvalue) |
770 | * strings. The propname of %NULL indicates the end of the property list. |
771 | * If the object implements the user creatable interface, the object will |
772 | * be marked complete once all the properties have been processed. |
773 | */ |
774 | void object_initialize_child(Object *parentobj, const char *propname, |
775 | void *childobj, size_t size, const char *type, |
776 | Error **errp, ...) QEMU_SENTINEL; |
777 | |
778 | /** |
779 | * object_initialize_childv: |
780 | * @parentobj: The parent object to add a property to |
781 | * @propname: The name of the property |
782 | * @childobj: A pointer to the memory to be used for the object. |
783 | * @size: The maximum size available at @childobj for the object. |
784 | * @type: The name of the type of the object to instantiate. |
785 | * @errp: If an error occurs, a pointer to an area to store the error |
786 | * @vargs: list of property names and values |
787 | * |
788 | * See object_initialize_child() for documentation. |
789 | */ |
790 | void object_initialize_childv(Object *parentobj, const char *propname, |
791 | void *childobj, size_t size, const char *type, |
792 | Error **errp, va_list vargs); |
793 | |
794 | /** |
795 | * object_dynamic_cast: |
796 | * @obj: The object to cast. |
797 | * @typename: The @typename to cast to. |
798 | * |
799 | * This function will determine if @obj is-a @typename. @obj can refer to an |
800 | * object or an interface associated with an object. |
801 | * |
802 | * Returns: This function returns @obj on success or #NULL on failure. |
803 | */ |
804 | Object *object_dynamic_cast(Object *obj, const char *typename); |
805 | |
806 | /** |
807 | * object_dynamic_cast_assert: |
808 | * |
809 | * See object_dynamic_cast() for a description of the parameters of this |
810 | * function. The only difference in behavior is that this function asserts |
811 | * instead of returning #NULL on failure if QOM cast debugging is enabled. |
812 | * This function is not meant to be called directly, but only through |
813 | * the wrapper macro OBJECT_CHECK. |
814 | */ |
815 | Object *object_dynamic_cast_assert(Object *obj, const char *typename, |
816 | const char *file, int line, const char *func); |
817 | |
818 | /** |
819 | * object_get_class: |
820 | * @obj: A derivative of #Object |
821 | * |
822 | * Returns: The #ObjectClass of the type associated with @obj. |
823 | */ |
824 | ObjectClass *object_get_class(Object *obj); |
825 | |
826 | /** |
827 | * object_get_typename: |
828 | * @obj: A derivative of #Object. |
829 | * |
830 | * Returns: The QOM typename of @obj. |
831 | */ |
832 | const char *object_get_typename(const Object *obj); |
833 | |
834 | /** |
835 | * type_register_static: |
836 | * @info: The #TypeInfo of the new type. |
837 | * |
838 | * @info and all of the strings it points to should exist for the life time |
839 | * that the type is registered. |
840 | * |
841 | * Returns: the new #Type. |
842 | */ |
843 | Type type_register_static(const TypeInfo *info); |
844 | |
845 | /** |
846 | * type_register: |
847 | * @info: The #TypeInfo of the new type |
848 | * |
849 | * Unlike type_register_static(), this call does not require @info or its |
850 | * string members to continue to exist after the call returns. |
851 | * |
852 | * Returns: the new #Type. |
853 | */ |
854 | Type type_register(const TypeInfo *info); |
855 | |
856 | /** |
857 | * type_register_static_array: |
858 | * @infos: The array of the new type #TypeInfo structures. |
859 | * @nr_infos: number of entries in @infos |
860 | * |
861 | * @infos and all of the strings it points to should exist for the life time |
862 | * that the type is registered. |
863 | */ |
864 | void type_register_static_array(const TypeInfo *infos, int nr_infos); |
865 | |
866 | /** |
867 | * DEFINE_TYPES: |
868 | * @type_array: The array containing #TypeInfo structures to register |
869 | * |
870 | * @type_array should be static constant that exists for the life time |
871 | * that the type is registered. |
872 | */ |
873 | #define DEFINE_TYPES(type_array) \ |
874 | static void do_qemu_init_ ## type_array(void) \ |
875 | { \ |
876 | type_register_static_array(type_array, ARRAY_SIZE(type_array)); \ |
877 | } \ |
878 | type_init(do_qemu_init_ ## type_array) |
879 | |
880 | /** |
881 | * object_class_dynamic_cast_assert: |
882 | * @klass: The #ObjectClass to attempt to cast. |
883 | * @typename: The QOM typename of the class to cast to. |
884 | * |
885 | * See object_class_dynamic_cast() for a description of the parameters |
886 | * of this function. The only difference in behavior is that this function |
887 | * asserts instead of returning #NULL on failure if QOM cast debugging is |
888 | * enabled. This function is not meant to be called directly, but only through |
889 | * the wrapper macros OBJECT_CLASS_CHECK and INTERFACE_CHECK. |
890 | */ |
891 | ObjectClass *object_class_dynamic_cast_assert(ObjectClass *klass, |
892 | const char *typename, |
893 | const char *file, int line, |
894 | const char *func); |
895 | |
896 | /** |
897 | * object_class_dynamic_cast: |
898 | * @klass: The #ObjectClass to attempt to cast. |
899 | * @typename: The QOM typename of the class to cast to. |
900 | * |
901 | * Returns: If @typename is a class, this function returns @klass if |
902 | * @typename is a subtype of @klass, else returns #NULL. |
903 | * |
904 | * If @typename is an interface, this function returns the interface |
905 | * definition for @klass if @klass implements it unambiguously; #NULL |
906 | * is returned if @klass does not implement the interface or if multiple |
907 | * classes or interfaces on the hierarchy leading to @klass implement |
908 | * it. (FIXME: perhaps this can be detected at type definition time?) |
909 | */ |
910 | ObjectClass *object_class_dynamic_cast(ObjectClass *klass, |
911 | const char *typename); |
912 | |
913 | /** |
914 | * object_class_get_parent: |
915 | * @klass: The class to obtain the parent for. |
916 | * |
917 | * Returns: The parent for @klass or %NULL if none. |
918 | */ |
919 | ObjectClass *object_class_get_parent(ObjectClass *klass); |
920 | |
921 | /** |
922 | * object_class_get_name: |
923 | * @klass: The class to obtain the QOM typename for. |
924 | * |
925 | * Returns: The QOM typename for @klass. |
926 | */ |
927 | const char *object_class_get_name(ObjectClass *klass); |
928 | |
929 | /** |
930 | * object_class_is_abstract: |
931 | * @klass: The class to obtain the abstractness for. |
932 | * |
933 | * Returns: %true if @klass is abstract, %false otherwise. |
934 | */ |
935 | bool object_class_is_abstract(ObjectClass *klass); |
936 | |
937 | /** |
938 | * object_class_by_name: |
939 | * @typename: The QOM typename to obtain the class for. |
940 | * |
941 | * Returns: The class for @typename or %NULL if not found. |
942 | */ |
943 | ObjectClass *object_class_by_name(const char *typename); |
944 | |
945 | void object_class_foreach(void (*fn)(ObjectClass *klass, void *opaque), |
946 | const char *implements_type, bool include_abstract, |
947 | void *opaque); |
948 | |
949 | /** |
950 | * object_class_get_list: |
951 | * @implements_type: The type to filter for, including its derivatives. |
952 | * @include_abstract: Whether to include abstract classes. |
953 | * |
954 | * Returns: A singly-linked list of the classes in reverse hashtable order. |
955 | */ |
956 | GSList *object_class_get_list(const char *implements_type, |
957 | bool include_abstract); |
958 | |
959 | /** |
960 | * object_class_get_list_sorted: |
961 | * @implements_type: The type to filter for, including its derivatives. |
962 | * @include_abstract: Whether to include abstract classes. |
963 | * |
964 | * Returns: A singly-linked list of the classes in alphabetical |
965 | * case-insensitive order. |
966 | */ |
967 | GSList *object_class_get_list_sorted(const char *implements_type, |
968 | bool include_abstract); |
969 | |
970 | /** |
971 | * object_ref: |
972 | * @obj: the object |
973 | * |
974 | * Increase the reference count of a object. A object cannot be freed as long |
975 | * as its reference count is greater than zero. |
976 | */ |
977 | void object_ref(Object *obj); |
978 | |
979 | /** |
980 | * object_unref: |
981 | * @obj: the object |
982 | * |
983 | * Decrease the reference count of a object. A object cannot be freed as long |
984 | * as its reference count is greater than zero. |
985 | */ |
986 | void object_unref(Object *obj); |
987 | |
988 | /** |
989 | * object_property_add: |
990 | * @obj: the object to add a property to |
991 | * @name: the name of the property. This can contain any character except for |
992 | * a forward slash. In general, you should use hyphens '-' instead of |
993 | * underscores '_' when naming properties. |
994 | * @type: the type name of the property. This namespace is pretty loosely |
995 | * defined. Sub namespaces are constructed by using a prefix and then |
996 | * to angle brackets. For instance, the type 'virtio-net-pci' in the |
997 | * 'link' namespace would be 'link<virtio-net-pci>'. |
998 | * @get: The getter to be called to read a property. If this is NULL, then |
999 | * the property cannot be read. |
1000 | * @set: the setter to be called to write a property. If this is NULL, |
1001 | * then the property cannot be written. |
1002 | * @release: called when the property is removed from the object. This is |
1003 | * meant to allow a property to free its opaque upon object |
1004 | * destruction. This may be NULL. |
1005 | * @opaque: an opaque pointer to pass to the callbacks for the property |
1006 | * @errp: returns an error if this function fails |
1007 | * |
1008 | * Returns: The #ObjectProperty; this can be used to set the @resolve |
1009 | * callback for child and link properties. |
1010 | */ |
1011 | ObjectProperty *object_property_add(Object *obj, const char *name, |
1012 | const char *type, |
1013 | ObjectPropertyAccessor *get, |
1014 | ObjectPropertyAccessor *set, |
1015 | ObjectPropertyRelease *release, |
1016 | void *opaque, Error **errp); |
1017 | |
1018 | void object_property_del(Object *obj, const char *name, Error **errp); |
1019 | |
1020 | ObjectProperty *object_class_property_add(ObjectClass *klass, const char *name, |
1021 | const char *type, |
1022 | ObjectPropertyAccessor *get, |
1023 | ObjectPropertyAccessor *set, |
1024 | ObjectPropertyRelease *release, |
1025 | void *opaque, Error **errp); |
1026 | |
1027 | /** |
1028 | * object_property_find: |
1029 | * @obj: the object |
1030 | * @name: the name of the property |
1031 | * @errp: returns an error if this function fails |
1032 | * |
1033 | * Look up a property for an object and return its #ObjectProperty if found. |
1034 | */ |
1035 | ObjectProperty *object_property_find(Object *obj, const char *name, |
1036 | Error **errp); |
1037 | ObjectProperty *object_class_property_find(ObjectClass *klass, const char *name, |
1038 | Error **errp); |
1039 | |
1040 | typedef struct ObjectPropertyIterator { |
1041 | ObjectClass *nextclass; |
1042 | GHashTableIter iter; |
1043 | } ObjectPropertyIterator; |
1044 | |
1045 | /** |
1046 | * object_property_iter_init: |
1047 | * @obj: the object |
1048 | * |
1049 | * Initializes an iterator for traversing all properties |
1050 | * registered against an object instance, its class and all parent classes. |
1051 | * |
1052 | * It is forbidden to modify the property list while iterating, |
1053 | * whether removing or adding properties. |
1054 | * |
1055 | * Typical usage pattern would be |
1056 | * |
1057 | * <example> |
1058 | * <title>Using object property iterators</title> |
1059 | * <programlisting> |
1060 | * ObjectProperty *prop; |
1061 | * ObjectPropertyIterator iter; |
1062 | * |
1063 | * object_property_iter_init(&iter, obj); |
1064 | * while ((prop = object_property_iter_next(&iter))) { |
1065 | * ... do something with prop ... |
1066 | * } |
1067 | * </programlisting> |
1068 | * </example> |
1069 | */ |
1070 | void object_property_iter_init(ObjectPropertyIterator *iter, |
1071 | Object *obj); |
1072 | |
1073 | /** |
1074 | * object_class_property_iter_init: |
1075 | * @klass: the class |
1076 | * |
1077 | * Initializes an iterator for traversing all properties |
1078 | * registered against an object class and all parent classes. |
1079 | * |
1080 | * It is forbidden to modify the property list while iterating, |
1081 | * whether removing or adding properties. |
1082 | * |
1083 | * This can be used on abstract classes as it does not create a temporary |
1084 | * instance. |
1085 | */ |
1086 | void object_class_property_iter_init(ObjectPropertyIterator *iter, |
1087 | ObjectClass *klass); |
1088 | |
1089 | /** |
1090 | * object_property_iter_next: |
1091 | * @iter: the iterator instance |
1092 | * |
1093 | * Return the next available property. If no further properties |
1094 | * are available, a %NULL value will be returned and the @iter |
1095 | * pointer should not be used again after this point without |
1096 | * re-initializing it. |
1097 | * |
1098 | * Returns: the next property, or %NULL when all properties |
1099 | * have been traversed. |
1100 | */ |
1101 | ObjectProperty *object_property_iter_next(ObjectPropertyIterator *iter); |
1102 | |
1103 | void object_unparent(Object *obj); |
1104 | |
1105 | /** |
1106 | * object_property_get: |
1107 | * @obj: the object |
1108 | * @v: the visitor that will receive the property value. This should be an |
1109 | * Output visitor and the data will be written with @name as the name. |
1110 | * @name: the name of the property |
1111 | * @errp: returns an error if this function fails |
1112 | * |
1113 | * Reads a property from a object. |
1114 | */ |
1115 | void object_property_get(Object *obj, Visitor *v, const char *name, |
1116 | Error **errp); |
1117 | |
1118 | /** |
1119 | * object_property_set_str: |
1120 | * @value: the value to be written to the property |
1121 | * @name: the name of the property |
1122 | * @errp: returns an error if this function fails |
1123 | * |
1124 | * Writes a string value to a property. |
1125 | */ |
1126 | void object_property_set_str(Object *obj, const char *value, |
1127 | const char *name, Error **errp); |
1128 | |
1129 | /** |
1130 | * object_property_get_str: |
1131 | * @obj: the object |
1132 | * @name: the name of the property |
1133 | * @errp: returns an error if this function fails |
1134 | * |
1135 | * Returns: the value of the property, converted to a C string, or NULL if |
1136 | * an error occurs (including when the property value is not a string). |
1137 | * The caller should free the string. |
1138 | */ |
1139 | char *object_property_get_str(Object *obj, const char *name, |
1140 | Error **errp); |
1141 | |
1142 | /** |
1143 | * object_property_set_link: |
1144 | * @value: the value to be written to the property |
1145 | * @name: the name of the property |
1146 | * @errp: returns an error if this function fails |
1147 | * |
1148 | * Writes an object's canonical path to a property. |
1149 | * |
1150 | * If the link property was created with |
1151 | * <code>OBJ_PROP_LINK_STRONG</code> bit, the old target object is |
1152 | * unreferenced, and a reference is added to the new target object. |
1153 | * |
1154 | */ |
1155 | void object_property_set_link(Object *obj, Object *value, |
1156 | const char *name, Error **errp); |
1157 | |
1158 | /** |
1159 | * object_property_get_link: |
1160 | * @obj: the object |
1161 | * @name: the name of the property |
1162 | * @errp: returns an error if this function fails |
1163 | * |
1164 | * Returns: the value of the property, resolved from a path to an Object, |
1165 | * or NULL if an error occurs (including when the property value is not a |
1166 | * string or not a valid object path). |
1167 | */ |
1168 | Object *object_property_get_link(Object *obj, const char *name, |
1169 | Error **errp); |
1170 | |
1171 | /** |
1172 | * object_property_set_bool: |
1173 | * @value: the value to be written to the property |
1174 | * @name: the name of the property |
1175 | * @errp: returns an error if this function fails |
1176 | * |
1177 | * Writes a bool value to a property. |
1178 | */ |
1179 | void object_property_set_bool(Object *obj, bool value, |
1180 | const char *name, Error **errp); |
1181 | |
1182 | /** |
1183 | * object_property_get_bool: |
1184 | * @obj: the object |
1185 | * @name: the name of the property |
1186 | * @errp: returns an error if this function fails |
1187 | * |
1188 | * Returns: the value of the property, converted to a boolean, or NULL if |
1189 | * an error occurs (including when the property value is not a bool). |
1190 | */ |
1191 | bool object_property_get_bool(Object *obj, const char *name, |
1192 | Error **errp); |
1193 | |
1194 | /** |
1195 | * object_property_set_int: |
1196 | * @value: the value to be written to the property |
1197 | * @name: the name of the property |
1198 | * @errp: returns an error if this function fails |
1199 | * |
1200 | * Writes an integer value to a property. |
1201 | */ |
1202 | void object_property_set_int(Object *obj, int64_t value, |
1203 | const char *name, Error **errp); |
1204 | |
1205 | /** |
1206 | * object_property_get_int: |
1207 | * @obj: the object |
1208 | * @name: the name of the property |
1209 | * @errp: returns an error if this function fails |
1210 | * |
1211 | * Returns: the value of the property, converted to an integer, or negative if |
1212 | * an error occurs (including when the property value is not an integer). |
1213 | */ |
1214 | int64_t object_property_get_int(Object *obj, const char *name, |
1215 | Error **errp); |
1216 | |
1217 | /** |
1218 | * object_property_set_uint: |
1219 | * @value: the value to be written to the property |
1220 | * @name: the name of the property |
1221 | * @errp: returns an error if this function fails |
1222 | * |
1223 | * Writes an unsigned integer value to a property. |
1224 | */ |
1225 | void object_property_set_uint(Object *obj, uint64_t value, |
1226 | const char *name, Error **errp); |
1227 | |
1228 | /** |
1229 | * object_property_get_uint: |
1230 | * @obj: the object |
1231 | * @name: the name of the property |
1232 | * @errp: returns an error if this function fails |
1233 | * |
1234 | * Returns: the value of the property, converted to an unsigned integer, or 0 |
1235 | * an error occurs (including when the property value is not an integer). |
1236 | */ |
1237 | uint64_t object_property_get_uint(Object *obj, const char *name, |
1238 | Error **errp); |
1239 | |
1240 | /** |
1241 | * object_property_get_enum: |
1242 | * @obj: the object |
1243 | * @name: the name of the property |
1244 | * @typename: the name of the enum data type |
1245 | * @errp: returns an error if this function fails |
1246 | * |
1247 | * Returns: the value of the property, converted to an integer, or |
1248 | * undefined if an error occurs (including when the property value is not |
1249 | * an enum). |
1250 | */ |
1251 | int object_property_get_enum(Object *obj, const char *name, |
1252 | const char *typename, Error **errp); |
1253 | |
1254 | /** |
1255 | * object_property_get_uint16List: |
1256 | * @obj: the object |
1257 | * @name: the name of the property |
1258 | * @list: the returned int list |
1259 | * @errp: returns an error if this function fails |
1260 | * |
1261 | * Returns: the value of the property, converted to integers, or |
1262 | * undefined if an error occurs (including when the property value is not |
1263 | * an list of integers). |
1264 | */ |
1265 | void object_property_get_uint16List(Object *obj, const char *name, |
1266 | uint16List **list, Error **errp); |
1267 | |
1268 | /** |
1269 | * object_property_set: |
1270 | * @obj: the object |
1271 | * @v: the visitor that will be used to write the property value. This should |
1272 | * be an Input visitor and the data will be first read with @name as the |
1273 | * name and then written as the property value. |
1274 | * @name: the name of the property |
1275 | * @errp: returns an error if this function fails |
1276 | * |
1277 | * Writes a property to a object. |
1278 | */ |
1279 | void object_property_set(Object *obj, Visitor *v, const char *name, |
1280 | Error **errp); |
1281 | |
1282 | /** |
1283 | * object_property_parse: |
1284 | * @obj: the object |
1285 | * @string: the string that will be used to parse the property value. |
1286 | * @name: the name of the property |
1287 | * @errp: returns an error if this function fails |
1288 | * |
1289 | * Parses a string and writes the result into a property of an object. |
1290 | */ |
1291 | void object_property_parse(Object *obj, const char *string, |
1292 | const char *name, Error **errp); |
1293 | |
1294 | /** |
1295 | * object_property_print: |
1296 | * @obj: the object |
1297 | * @name: the name of the property |
1298 | * @human: if true, print for human consumption |
1299 | * @errp: returns an error if this function fails |
1300 | * |
1301 | * Returns a string representation of the value of the property. The |
1302 | * caller shall free the string. |
1303 | */ |
1304 | char *object_property_print(Object *obj, const char *name, bool human, |
1305 | Error **errp); |
1306 | |
1307 | /** |
1308 | * object_property_get_type: |
1309 | * @obj: the object |
1310 | * @name: the name of the property |
1311 | * @errp: returns an error if this function fails |
1312 | * |
1313 | * Returns: The type name of the property. |
1314 | */ |
1315 | const char *object_property_get_type(Object *obj, const char *name, |
1316 | Error **errp); |
1317 | |
1318 | /** |
1319 | * object_get_root: |
1320 | * |
1321 | * Returns: the root object of the composition tree |
1322 | */ |
1323 | Object *object_get_root(void); |
1324 | |
1325 | |
1326 | /** |
1327 | * object_get_objects_root: |
1328 | * |
1329 | * Get the container object that holds user created |
1330 | * object instances. This is the object at path |
1331 | * "/objects" |
1332 | * |
1333 | * Returns: the user object container |
1334 | */ |
1335 | Object *object_get_objects_root(void); |
1336 | |
1337 | /** |
1338 | * object_get_internal_root: |
1339 | * |
1340 | * Get the container object that holds internally used object |
1341 | * instances. Any object which is put into this container must not be |
1342 | * user visible, and it will not be exposed in the QOM tree. |
1343 | * |
1344 | * Returns: the internal object container |
1345 | */ |
1346 | Object *object_get_internal_root(void); |
1347 | |
1348 | /** |
1349 | * object_get_canonical_path_component: |
1350 | * |
1351 | * Returns: The final component in the object's canonical path. The canonical |
1352 | * path is the path within the composition tree starting from the root. |
1353 | * %NULL if the object doesn't have a parent (and thus a canonical path). |
1354 | */ |
1355 | gchar *object_get_canonical_path_component(Object *obj); |
1356 | |
1357 | /** |
1358 | * object_get_canonical_path: |
1359 | * |
1360 | * Returns: The canonical path for a object. This is the path within the |
1361 | * composition tree starting from the root. |
1362 | */ |
1363 | gchar *object_get_canonical_path(Object *obj); |
1364 | |
1365 | /** |
1366 | * object_resolve_path: |
1367 | * @path: the path to resolve |
1368 | * @ambiguous: returns true if the path resolution failed because of an |
1369 | * ambiguous match |
1370 | * |
1371 | * There are two types of supported paths--absolute paths and partial paths. |
1372 | * |
1373 | * Absolute paths are derived from the root object and can follow child<> or |
1374 | * link<> properties. Since they can follow link<> properties, they can be |
1375 | * arbitrarily long. Absolute paths look like absolute filenames and are |
1376 | * prefixed with a leading slash. |
1377 | * |
1378 | * Partial paths look like relative filenames. They do not begin with a |
1379 | * prefix. The matching rules for partial paths are subtle but designed to make |
1380 | * specifying objects easy. At each level of the composition tree, the partial |
1381 | * path is matched as an absolute path. The first match is not returned. At |
1382 | * least two matches are searched for. A successful result is only returned if |
1383 | * only one match is found. If more than one match is found, a flag is |
1384 | * returned to indicate that the match was ambiguous. |
1385 | * |
1386 | * Returns: The matched object or NULL on path lookup failure. |
1387 | */ |
1388 | Object *object_resolve_path(const char *path, bool *ambiguous); |
1389 | |
1390 | /** |
1391 | * object_resolve_path_type: |
1392 | * @path: the path to resolve |
1393 | * @typename: the type to look for. |
1394 | * @ambiguous: returns true if the path resolution failed because of an |
1395 | * ambiguous match |
1396 | * |
1397 | * This is similar to object_resolve_path. However, when looking for a |
1398 | * partial path only matches that implement the given type are considered. |
1399 | * This restricts the search and avoids spuriously flagging matches as |
1400 | * ambiguous. |
1401 | * |
1402 | * For both partial and absolute paths, the return value goes through |
1403 | * a dynamic cast to @typename. This is important if either the link, |
1404 | * or the typename itself are of interface types. |
1405 | * |
1406 | * Returns: The matched object or NULL on path lookup failure. |
1407 | */ |
1408 | Object *object_resolve_path_type(const char *path, const char *typename, |
1409 | bool *ambiguous); |
1410 | |
1411 | /** |
1412 | * object_resolve_path_component: |
1413 | * @parent: the object in which to resolve the path |
1414 | * @part: the component to resolve. |
1415 | * |
1416 | * This is similar to object_resolve_path with an absolute path, but it |
1417 | * only resolves one element (@part) and takes the others from @parent. |
1418 | * |
1419 | * Returns: The resolved object or NULL on path lookup failure. |
1420 | */ |
1421 | Object *object_resolve_path_component(Object *parent, const gchar *part); |
1422 | |
1423 | /** |
1424 | * object_property_add_child: |
1425 | * @obj: the object to add a property to |
1426 | * @name: the name of the property |
1427 | * @child: the child object |
1428 | * @errp: if an error occurs, a pointer to an area to store the error |
1429 | * |
1430 | * Child properties form the composition tree. All objects need to be a child |
1431 | * of another object. Objects can only be a child of one object. |
1432 | * |
1433 | * There is no way for a child to determine what its parent is. It is not |
1434 | * a bidirectional relationship. This is by design. |
1435 | * |
1436 | * The value of a child property as a C string will be the child object's |
1437 | * canonical path. It can be retrieved using object_property_get_str(). |
1438 | * The child object itself can be retrieved using object_property_get_link(). |
1439 | */ |
1440 | void object_property_add_child(Object *obj, const char *name, |
1441 | Object *child, Error **errp); |
1442 | |
1443 | typedef enum { |
1444 | /* Unref the link pointer when the property is deleted */ |
1445 | OBJ_PROP_LINK_STRONG = 0x1, |
1446 | } ObjectPropertyLinkFlags; |
1447 | |
1448 | /** |
1449 | * object_property_allow_set_link: |
1450 | * |
1451 | * The default implementation of the object_property_add_link() check() |
1452 | * callback function. It allows the link property to be set and never returns |
1453 | * an error. |
1454 | */ |
1455 | void object_property_allow_set_link(const Object *, const char *, |
1456 | Object *, Error **); |
1457 | |
1458 | /** |
1459 | * object_property_add_link: |
1460 | * @obj: the object to add a property to |
1461 | * @name: the name of the property |
1462 | * @type: the qobj type of the link |
1463 | * @child: a pointer to where the link object reference is stored |
1464 | * @check: callback to veto setting or NULL if the property is read-only |
1465 | * @flags: additional options for the link |
1466 | * @errp: if an error occurs, a pointer to an area to store the error |
1467 | * |
1468 | * Links establish relationships between objects. Links are unidirectional |
1469 | * although two links can be combined to form a bidirectional relationship |
1470 | * between objects. |
1471 | * |
1472 | * Links form the graph in the object model. |
1473 | * |
1474 | * The <code>@check()</code> callback is invoked when |
1475 | * object_property_set_link() is called and can raise an error to prevent the |
1476 | * link being set. If <code>@check</code> is NULL, the property is read-only |
1477 | * and cannot be set. |
1478 | * |
1479 | * Ownership of the pointer that @child points to is transferred to the |
1480 | * link property. The reference count for <code>*@child</code> is |
1481 | * managed by the property from after the function returns till the |
1482 | * property is deleted with object_property_del(). If the |
1483 | * <code>@flags</code> <code>OBJ_PROP_LINK_STRONG</code> bit is set, |
1484 | * the reference count is decremented when the property is deleted or |
1485 | * modified. |
1486 | */ |
1487 | void object_property_add_link(Object *obj, const char *name, |
1488 | const char *type, Object **child, |
1489 | void (*check)(const Object *obj, const char *name, |
1490 | Object *val, Error **errp), |
1491 | ObjectPropertyLinkFlags flags, |
1492 | Error **errp); |
1493 | |
1494 | /** |
1495 | * object_property_add_str: |
1496 | * @obj: the object to add a property to |
1497 | * @name: the name of the property |
1498 | * @get: the getter or NULL if the property is write-only. This function must |
1499 | * return a string to be freed by g_free(). |
1500 | * @set: the setter or NULL if the property is read-only |
1501 | * @errp: if an error occurs, a pointer to an area to store the error |
1502 | * |
1503 | * Add a string property using getters/setters. This function will add a |
1504 | * property of type 'string'. |
1505 | */ |
1506 | void object_property_add_str(Object *obj, const char *name, |
1507 | char *(*get)(Object *, Error **), |
1508 | void (*set)(Object *, const char *, Error **), |
1509 | Error **errp); |
1510 | |
1511 | void object_class_property_add_str(ObjectClass *klass, const char *name, |
1512 | char *(*get)(Object *, Error **), |
1513 | void (*set)(Object *, const char *, |
1514 | Error **), |
1515 | Error **errp); |
1516 | |
1517 | /** |
1518 | * object_property_add_bool: |
1519 | * @obj: the object to add a property to |
1520 | * @name: the name of the property |
1521 | * @get: the getter or NULL if the property is write-only. |
1522 | * @set: the setter or NULL if the property is read-only |
1523 | * @errp: if an error occurs, a pointer to an area to store the error |
1524 | * |
1525 | * Add a bool property using getters/setters. This function will add a |
1526 | * property of type 'bool'. |
1527 | */ |
1528 | void object_property_add_bool(Object *obj, const char *name, |
1529 | bool (*get)(Object *, Error **), |
1530 | void (*set)(Object *, bool, Error **), |
1531 | Error **errp); |
1532 | |
1533 | void object_class_property_add_bool(ObjectClass *klass, const char *name, |
1534 | bool (*get)(Object *, Error **), |
1535 | void (*set)(Object *, bool, Error **), |
1536 | Error **errp); |
1537 | |
1538 | /** |
1539 | * object_property_add_enum: |
1540 | * @obj: the object to add a property to |
1541 | * @name: the name of the property |
1542 | * @typename: the name of the enum data type |
1543 | * @get: the getter or %NULL if the property is write-only. |
1544 | * @set: the setter or %NULL if the property is read-only |
1545 | * @errp: if an error occurs, a pointer to an area to store the error |
1546 | * |
1547 | * Add an enum property using getters/setters. This function will add a |
1548 | * property of type '@typename'. |
1549 | */ |
1550 | void object_property_add_enum(Object *obj, const char *name, |
1551 | const char *typename, |
1552 | const QEnumLookup *lookup, |
1553 | int (*get)(Object *, Error **), |
1554 | void (*set)(Object *, int, Error **), |
1555 | Error **errp); |
1556 | |
1557 | void object_class_property_add_enum(ObjectClass *klass, const char *name, |
1558 | const char *typename, |
1559 | const QEnumLookup *lookup, |
1560 | int (*get)(Object *, Error **), |
1561 | void (*set)(Object *, int, Error **), |
1562 | Error **errp); |
1563 | |
1564 | /** |
1565 | * object_property_add_tm: |
1566 | * @obj: the object to add a property to |
1567 | * @name: the name of the property |
1568 | * @get: the getter or NULL if the property is write-only. |
1569 | * @errp: if an error occurs, a pointer to an area to store the error |
1570 | * |
1571 | * Add a read-only struct tm valued property using a getter function. |
1572 | * This function will add a property of type 'struct tm'. |
1573 | */ |
1574 | void object_property_add_tm(Object *obj, const char *name, |
1575 | void (*get)(Object *, struct tm *, Error **), |
1576 | Error **errp); |
1577 | |
1578 | void object_class_property_add_tm(ObjectClass *klass, const char *name, |
1579 | void (*get)(Object *, struct tm *, Error **), |
1580 | Error **errp); |
1581 | |
1582 | /** |
1583 | * object_property_add_uint8_ptr: |
1584 | * @obj: the object to add a property to |
1585 | * @name: the name of the property |
1586 | * @v: pointer to value |
1587 | * @errp: if an error occurs, a pointer to an area to store the error |
1588 | * |
1589 | * Add an integer property in memory. This function will add a |
1590 | * property of type 'uint8'. |
1591 | */ |
1592 | void object_property_add_uint8_ptr(Object *obj, const char *name, |
1593 | const uint8_t *v, Error **errp); |
1594 | void object_class_property_add_uint8_ptr(ObjectClass *klass, const char *name, |
1595 | const uint8_t *v, Error **errp); |
1596 | |
1597 | /** |
1598 | * object_property_add_uint16_ptr: |
1599 | * @obj: the object to add a property to |
1600 | * @name: the name of the property |
1601 | * @v: pointer to value |
1602 | * @errp: if an error occurs, a pointer to an area to store the error |
1603 | * |
1604 | * Add an integer property in memory. This function will add a |
1605 | * property of type 'uint16'. |
1606 | */ |
1607 | void object_property_add_uint16_ptr(Object *obj, const char *name, |
1608 | const uint16_t *v, Error **errp); |
1609 | void object_class_property_add_uint16_ptr(ObjectClass *klass, const char *name, |
1610 | const uint16_t *v, Error **errp); |
1611 | |
1612 | /** |
1613 | * object_property_add_uint32_ptr: |
1614 | * @obj: the object to add a property to |
1615 | * @name: the name of the property |
1616 | * @v: pointer to value |
1617 | * @errp: if an error occurs, a pointer to an area to store the error |
1618 | * |
1619 | * Add an integer property in memory. This function will add a |
1620 | * property of type 'uint32'. |
1621 | */ |
1622 | void object_property_add_uint32_ptr(Object *obj, const char *name, |
1623 | const uint32_t *v, Error **errp); |
1624 | void object_class_property_add_uint32_ptr(ObjectClass *klass, const char *name, |
1625 | const uint32_t *v, Error **errp); |
1626 | |
1627 | /** |
1628 | * object_property_add_uint64_ptr: |
1629 | * @obj: the object to add a property to |
1630 | * @name: the name of the property |
1631 | * @v: pointer to value |
1632 | * @errp: if an error occurs, a pointer to an area to store the error |
1633 | * |
1634 | * Add an integer property in memory. This function will add a |
1635 | * property of type 'uint64'. |
1636 | */ |
1637 | void object_property_add_uint64_ptr(Object *obj, const char *name, |
1638 | const uint64_t *v, Error **Errp); |
1639 | void object_class_property_add_uint64_ptr(ObjectClass *klass, const char *name, |
1640 | const uint64_t *v, Error **Errp); |
1641 | |
1642 | /** |
1643 | * object_property_add_alias: |
1644 | * @obj: the object to add a property to |
1645 | * @name: the name of the property |
1646 | * @target_obj: the object to forward property access to |
1647 | * @target_name: the name of the property on the forwarded object |
1648 | * @errp: if an error occurs, a pointer to an area to store the error |
1649 | * |
1650 | * Add an alias for a property on an object. This function will add a property |
1651 | * of the same type as the forwarded property. |
1652 | * |
1653 | * The caller must ensure that <code>@target_obj</code> stays alive as long as |
1654 | * this property exists. In the case of a child object or an alias on the same |
1655 | * object this will be the case. For aliases to other objects the caller is |
1656 | * responsible for taking a reference. |
1657 | */ |
1658 | void object_property_add_alias(Object *obj, const char *name, |
1659 | Object *target_obj, const char *target_name, |
1660 | Error **errp); |
1661 | |
1662 | /** |
1663 | * object_property_add_const_link: |
1664 | * @obj: the object to add a property to |
1665 | * @name: the name of the property |
1666 | * @target: the object to be referred by the link |
1667 | * @errp: if an error occurs, a pointer to an area to store the error |
1668 | * |
1669 | * Add an unmodifiable link for a property on an object. This function will |
1670 | * add a property of type link<TYPE> where TYPE is the type of @target. |
1671 | * |
1672 | * The caller must ensure that @target stays alive as long as |
1673 | * this property exists. In the case @target is a child of @obj, |
1674 | * this will be the case. Otherwise, the caller is responsible for |
1675 | * taking a reference. |
1676 | */ |
1677 | void object_property_add_const_link(Object *obj, const char *name, |
1678 | Object *target, Error **errp); |
1679 | |
1680 | /** |
1681 | * object_property_set_description: |
1682 | * @obj: the object owning the property |
1683 | * @name: the name of the property |
1684 | * @description: the description of the property on the object |
1685 | * @errp: if an error occurs, a pointer to an area to store the error |
1686 | * |
1687 | * Set an object property's description. |
1688 | * |
1689 | */ |
1690 | void object_property_set_description(Object *obj, const char *name, |
1691 | const char *description, Error **errp); |
1692 | void object_class_property_set_description(ObjectClass *klass, const char *name, |
1693 | const char *description, |
1694 | Error **errp); |
1695 | |
1696 | /** |
1697 | * object_child_foreach: |
1698 | * @obj: the object whose children will be navigated |
1699 | * @fn: the iterator function to be called |
1700 | * @opaque: an opaque value that will be passed to the iterator |
1701 | * |
1702 | * Call @fn passing each child of @obj and @opaque to it, until @fn returns |
1703 | * non-zero. |
1704 | * |
1705 | * It is forbidden to add or remove children from @obj from the @fn |
1706 | * callback. |
1707 | * |
1708 | * Returns: The last value returned by @fn, or 0 if there is no child. |
1709 | */ |
1710 | int object_child_foreach(Object *obj, int (*fn)(Object *child, void *opaque), |
1711 | void *opaque); |
1712 | |
1713 | /** |
1714 | * object_child_foreach_recursive: |
1715 | * @obj: the object whose children will be navigated |
1716 | * @fn: the iterator function to be called |
1717 | * @opaque: an opaque value that will be passed to the iterator |
1718 | * |
1719 | * Call @fn passing each child of @obj and @opaque to it, until @fn returns |
1720 | * non-zero. Calls recursively, all child nodes of @obj will also be passed |
1721 | * all the way down to the leaf nodes of the tree. Depth first ordering. |
1722 | * |
1723 | * It is forbidden to add or remove children from @obj (or its |
1724 | * child nodes) from the @fn callback. |
1725 | * |
1726 | * Returns: The last value returned by @fn, or 0 if there is no child. |
1727 | */ |
1728 | int object_child_foreach_recursive(Object *obj, |
1729 | int (*fn)(Object *child, void *opaque), |
1730 | void *opaque); |
1731 | /** |
1732 | * container_get: |
1733 | * @root: root of the #path, e.g., object_get_root() |
1734 | * @path: path to the container |
1735 | * |
1736 | * Return a container object whose path is @path. Create more containers |
1737 | * along the path if necessary. |
1738 | * |
1739 | * Returns: the container object. |
1740 | */ |
1741 | Object *container_get(Object *root, const char *path); |
1742 | |
1743 | /** |
1744 | * object_type_get_instance_size: |
1745 | * @typename: Name of the Type whose instance_size is required |
1746 | * |
1747 | * Returns the instance_size of the given @typename. |
1748 | */ |
1749 | size_t object_type_get_instance_size(const char *typename); |
1750 | #endif |
1751 | |