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