include/qom/object.h

10  * See the COPYING file in the top-level directory.
17 #include "qapi/qapi-builtin-types.h"
35  * @obj: the object that owns the property
36  * @v: the visitor that contains the property data
37  * @name: the name of the property
38  * @opaque: the object property opaque
41  * Called when trying to get/set a property.
51  * @obj: the object that owns the property
52  * @opaque: the opaque registered with the property
53  * @part: the name of the property
55  * Resolves the #Object corresponding to property @part.
70  * @obj: the object that owns the property
71  * @name: the name of the property
72  * @opaque: the opaque registered with the property
74  * Called when a property is removed from a object.
82  * @obj: the object that owns the property
83  * @prop: the property to set
85  * Called when a property is initialized.
147  * always begins at byte 0 of that structure, as long as any sub-object places
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
319  *   - declare prototypes for _finalize, _class_init and _init methods
320  *   - declare the TypeInfo struct instance
321  *   - provide the constructor to register the type
324  * and _init methods need to be written. Any of these can be zero-line
325  * no-op impls if no special logic is required for a given type.
347  * for the common case of a non-abstract type, without any interfaces.
365  * for the common case of a non-abstract type, with one or more implemented
404  * the case of a non-abstract type, with interfaces, and with no requirement
424  * the common case of a non-abstract type, without any interfaces, and with
442  *   is 0, then normal malloc alignment is sufficient; if non-zero, then we
486     bool abstract;
640  * @...: list of property names and values
650  * strings. The propname of %NULL indicates the end of the property
655  * .. code-block:: c
666  *                                  "mem-path", "/dev/shm/somefile",
692  * @vargs: list of property names and values
702 bool object_apply_global_props(Object *obj, const GPtrArray *props,
707                                 const char *value, bool optional);
714  * @...: list of property names and values
720  * strings. The propname of %NULL indicates the end of the property
723  * .. code-block:: c
732  *                            "mem-path", "/dev/shm/somefile",
744 bool object_set_props(Object *obj, Error **errp, ...) G_GNUC_NULL_TERMINATED;
750  * @vargs: list of property names and values
756 bool object_set_propv(Object *obj, Error **errp, va_list vargs);
772  * @parentobj: The parent object to add a property to
773  * @propname: The name of the property
778  * @...: list of property names and values
781  * have already been allocated. The object will then be added as child property
783  * has a reference count of 1 (for the "child<...>" property from the parent),
787  * strings. The propname of %NULL indicates the end of the property list.
793 bool object_initialize_child_with_props(Object *parentobj,
800  * @parentobj: The parent object to add a property to
801  * @propname: The name of the property
806  * @vargs: list of property names and values
812 bool object_initialize_child_with_propsv(Object *parentobj,
819  * @parent: The parent object to add a property to
820  * @propname: The name of the property
843  * This function will determine if @obj is-a @typename.  @obj can refer to an
922 bool type_print_class_properties(const char *type);
933  * then set the corresponding property in @obj.
936                                        bool from_json, Error **errp);
996 bool object_class_is_abstract(ObjectClass *klass);
1019                           const char *implements_type, bool include_abstract,
1027  * Returns: A singly-linked list of the classes in reverse hashtable order.
1030                               bool include_abstract);
1037  * Returns: A singly-linked list of the classes in alphabetical
1038  * case-insensitive order.
1041                               bool include_abstract);
1064  * @obj: the object to add a property to
1065  * @name: the name of the property.  This can contain any character except for
1066  *  a forward slash.  In general, you should use hyphens '-' instead of
1068  * @type: the type name of the property.  This namespace is pretty loosely
1070  *   to angle brackets.  For instance, the type 'virtio-net-pci' in the
1071  *   'link' namespace would be 'link<virtio-net-pci>'.
1072  * @get: The getter to be called to read a property.  If this is NULL, then
1073  *   the property cannot be read.
1074  * @set: the setter to be called to write a property.  If this is NULL,
1075  *   then the property cannot be written.
1076  * @release: called when the property is removed from the object.  This is
1077  *   meant to allow a property to free its opaque upon object
1079  * @opaque: an opaque pointer to pass to the callbacks for the property
1097  * @obj: the object to add a property to
1098  * @name: the name of the property.  This can contain any character except for
1099  *  a forward slash.  In general, you should use hyphens '-' instead of
1101  * @type: the type name of the property.  This namespace is pretty loosely
1103  *   to angle brackets.  For instance, the type 'virtio-net-pci' in the
1104  *   'link' namespace would be 'link<virtio-net-pci>'.
1105  * @get: The getter to be called to read a property.  If this is NULL, then
1106  *   the property cannot be read.
1107  * @set: the setter to be called to write a property.  If this is NULL,
1108  *   then the property cannot be written.
1109  * @release: called when the property is removed from the object.  This is
1110  *   meant to allow a property to free its opaque upon object
1112  * @opaque: an opaque pointer to pass to the callbacks for the property
1132  * @prop: the property to set
1133  * @value: the value to be written to the property
1135  * Set the property default value.
1137 void object_property_set_default_bool(ObjectProperty *prop, bool value);
1141  * @prop: the property to set
1142  * @value: the value to be written to the property
1144  * Set the property default value.
1150  * @prop: the property to set
1152  * Set the property default value to be an empty list.
1158  * @prop: the property to set
1159  * @value: the value to be written to the property
1161  * Set the property default value.
1167  * @prop: the property to set
1168  * @value: the value to be written to the property
1170  * Set the property default value.
1177  * @name: the name of the property
1179  * Look up a property for an object.
1188  * @name: the name of the property
1191  * Look up a property for an object.
1202  * @name: the name of the property
1204  * Look up a property for an object class.
1214  * @name: the name of the property
1217  * Look up a property for an object class.
1238  * It is forbidden to modify the property list while iterating,
1243  * .. code-block:: c
1244  *    :caption: Using object property iterators
1265  * It is forbidden to modify the property list while iterating,
1278  * Return the next available property. If no further properties
1281  * re-initializing it.
1283  * Returns: the next property, or %NULL when all properties
1293  * @name: the name of the property
1294  * @v: the visitor that will receive the property value.  This should be an
1298  * Reads a property from a object.
1302 bool object_property_get(Object *obj, const char *name, Visitor *v,
1308  * @name: the name of the property
1309  * @value: the value to be written to the property
1312  * Writes a string value to a property.
1316 bool object_property_set_str(Object *obj, const char *name,
1322  * @name: the name of the property
1325  * Returns: the value of the property, converted to a C string, or NULL if
1326  * an error occurs (including when the property value is not a string).
1335  * @name: the name of the property
1336  * @value: the value to be written to the property
1339  * Writes an object's canonical path to a property.
1341  * If the link property was created with
1347 bool object_property_set_link(Object *obj, const char *name,
1353  * @name: the name of the property
1356  * Returns: the value of the property, resolved from a path to an Object,
1357  * or NULL if an error occurs (including when the property value is not a
1366  * @name: the name of the property
1367  * @value: the value to be written to the property
1370  * Writes a bool value to a property.
1374 bool object_property_set_bool(Object *obj, const char *name,
1375                               bool value, Error **errp);
1380  * @name: the name of the property
1383  * Returns: the value of the property, converted to a boolean, or false if
1384  * an error occurs (including when the property value is not a bool).
1386 bool object_property_get_bool(Object *obj, const char *name,
1392  * @name: the name of the property
1393  * @value: the value to be written to the property
1396  * Writes an integer value to a property.
1400 bool object_property_set_int(Object *obj, const char *name,
1406  * @name: the name of the property
1409  * Returns: the value of the property, converted to an integer, or -1 if
1410  * an error occurs (including when the property value is not an integer).
1418  * @name: the name of the property
1419  * @value: the value to be written to the property
1422  * Writes an unsigned integer value to a property.
1426 bool object_property_set_uint(Object *obj, const char *name,
1432  * @name: the name of the property
1435  * Returns: the value of the property, converted to an unsigned integer, or 0
1436  * an error occurs (including when the property value is not an integer).
1444  * @name: the name of the property
1448  * Returns: the value of the property, converted to an integer (which
1449  * can't be negative), or -1 on error (including when the property
1458  * @name: the name of the property
1459  * @v: the visitor that will be used to write the property value.  This should
1461  *   name and then written as the property value.
1464  * Writes a property to a object.
1468 bool object_property_set(Object *obj, const char *name, Visitor *v,
1474  * @name: the name of the property
1475  * @string: the string that will be used to parse the property value.
1478  * Parses a string and writes the result into a property of an object.
1482 bool object_property_parse(Object *obj, const char *name,
1488  * @name: the name of the property
1492  * Returns a string representation of the value of the property.  The
1495 char *object_property_print(Object *obj, const char *name, bool human,
1501  * @name: the name of the property
1504  * Returns:  The type name of the property.
1575  * There are two types of supported paths--absolute paths and partial paths.
1592 Object *object_resolve_path(const char *path, bool *ambiguous);
1613                                  bool *ambiguous);
1654  * @obj: the object to add a property to
1655  * @name: the name of the property
1665  * The value of a child property as a C string will be the child object's
1669  * Returns: The newly added property on success, or %NULL on failure.
1676  * @obj: the object to add a property to
1677  * @name: the name of the property
1687     /* Unref the link pointer when the property is deleted */
1697  * @obj: the object to add a property to
1698  * @name: the name of the property
1703  * callback function.  It allows the link property to be set and never returns
1711  * @obj: the object to add a property to
1712  * @name: the name of the property
1715  * @check: callback to veto setting or NULL if the property is read-only
1726  * link being set.  If @check is NULL, the property is read-only
1730  * link property.  The reference count for *@child is
1731  * managed by the property from after the function returns till the
1732  * property is deleted with object_property_del().  If the
1734  * the reference count is decremented when the property is deleted or
1737  * Returns: The newly added property on success, or %NULL on failure.
1754  * @obj: the object to add a property to
1755  * @name: the name of the property
1756  * @get: the getter or NULL if the property is write-only.  This function must
1758  * @set: the setter or NULL if the property is read-only
1760  * Add a string property using getters/setters.  This function will add a
1761  * property of type 'string'.
1763  * Returns: The newly added property on success, or %NULL on failure.
1777  * @obj: the object to add a property to
1778  * @name: the name of the property
1779  * @get: the getter or NULL if the property is write-only.
1780  * @set: the setter or NULL if the property is read-only
1782  * Add a bool property using getters/setters.  This function will add a
1783  * property of type 'bool'.
1785  * Returns: The newly added property on success, or %NULL on failure.
1788                               bool (*get)(Object *, Error **),
1789                               void (*set)(Object *, bool, Error **));
1793                                     bool (*get)(Object *, Error **),
1794                                     void (*set)(Object *, bool, Error **));
1798  * @obj: the object to add a property to
1799  * @name: the name of the property
1802  * @get: the getter or %NULL if the property is write-only.
1803  * @set: the setter or %NULL if the property is read-only
1805  * Add an enum property using getters/setters.  This function will add a
1806  * property of type '@typename'.
1808  * Returns: The newly added property on success, or %NULL on failure.
1825  * @obj: the object to add a property to
1826  * @name: the name of the property
1827  * @get: the getter or NULL if the property is write-only.
1829  * Add a read-only struct tm valued property using a getter function.
1830  * This function will add a property of type 'struct tm'.
1832  * Returns: The newly added property on success, or %NULL on failure.
1842     /* Automatically add a getter to the property */
1844     /* Automatically add a setter to the property */
1846     /* Automatically add a getter and a setter to the property */
1852  * @obj: the object to add a property to
1853  * @name: the name of the property
1855  * @flags: bitwise-or'd ObjectPropertyFlags
1857  * Add an integer property in memory.  This function will add a
1858  * property of type 'uint8'.
1860  * Returns: The newly added property on success, or %NULL on failure.
1873  * @obj: the object to add a property to
1874  * @name: the name of the property
1876  * @flags: bitwise-or'd ObjectPropertyFlags
1878  * Add an integer property in memory.  This function will add a
1879  * property of type 'uint16'.
1881  * Returns: The newly added property on success, or %NULL on failure.
1894  * @obj: the object to add a property to
1895  * @name: the name of the property
1897  * @flags: bitwise-or'd ObjectPropertyFlags
1899  * Add an integer property in memory.  This function will add a
1900  * property of type 'uint32'.
1902  * Returns: The newly added property on success, or %NULL on failure.
1915  * @obj: the object to add a property to
1916  * @name: the name of the property
1918  * @flags: bitwise-or'd ObjectPropertyFlags
1920  * Add an integer property in memory.  This function will add a
1921  * property of type 'uint64'.
1923  * Returns: The newly added property on success, or %NULL on failure.
1936  * @obj: the object to add a property to
1937  * @name: the name of the property
1938  * @target_obj: the object to forward property access to
1939  * @target_name: the name of the property on the forwarded object
1941  * Add an alias for a property on an object.  This function will add a property
1942  * of the same type as the forwarded property.
1945  * this property exists.  In the case of a child object or an alias on the same
1949  * Returns: The newly added property on success, or %NULL on failure.
1956  * @obj: the object to add a property to
1957  * @name: the name of the property
1960  * Add an unmodifiable link for a property on an object.  This function will
1961  * add a property of type link<TYPE> where TYPE is the type of @target.
1964  * this property exists.  In the case @target is a child of @obj,
1968  * Returns: The newly added property on success, or %NULL on failure.
1975  * @obj: the object owning the property
1976  * @name: the name of the property
1977  * @description: the description of the property on the object
1979  * Set an object property's description.
1995  * non-zero.
2012  * non-zero. Calls recursively, all child nodes of @obj will also be passed
2027  * @name: the name of the parent object's property to add
2038  * @name: the name of the property
2039  * @type: the type of the property
2041  * @description: description of the property
2043  * Returns: a user-friendly formatted string describing the property