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
487     bool abstract;
641  * @...: list of property names and values
651  * strings. The propname of %NULL indicates the end of the property
656  * .. code-block:: c
667  *                                  "mem-path", "/dev/shm/somefile",
693  * @vargs: list of property names and values
703 bool object_apply_global_props(Object *obj, const GPtrArray *props,
708                                 const char *value, bool optional);
715  * @...: list of property names and values
721  * strings. The propname of %NULL indicates the end of the property
724  * .. code-block:: c
733  *                            "mem-path", "/dev/shm/somefile",
745 bool object_set_props(Object *obj, Error **errp, ...) G_GNUC_NULL_TERMINATED;
751  * @vargs: list of property names and values
757 bool object_set_propv(Object *obj, Error **errp, va_list vargs);
773  * @parentobj: The parent object to add a property to
774  * @propname: The name of the property
779  * @...: list of property names and values
782  * have already been allocated. The object will then be added as child property
784  * has a reference count of 1 (for the "child<...>" property from the parent),
788  * strings. The propname of %NULL indicates the end of the property list.
794 bool object_initialize_child_with_props(Object *parentobj,
801  * @parentobj: The parent object to add a property to
802  * @propname: The name of the property
807  * @vargs: list of property names and values
813 bool object_initialize_child_with_propsv(Object *parentobj,
820  * @parent: The parent object to add a property to
821  * @propname: The name of the property
844  * This function will determine if @obj is-a @typename.  @obj can refer to an
923 bool type_print_class_properties(const char *type);
934  * then set the corresponding property in @obj.
937                                        bool from_json, Error **errp);
997 bool object_class_is_abstract(ObjectClass *klass);
1020                           const char *implements_type, bool include_abstract,
1028  * Returns: A singly-linked list of the classes in reverse hashtable order.
1031                               bool include_abstract);
1038  * Returns: A singly-linked list of the classes in alphabetical
1039  * case-insensitive order.
1042                               bool include_abstract);
1065  * @obj: the object to add a property to
1066  * @name: the name of the property.  This can contain any character except for
1067  *  a forward slash.  In general, you should use hyphens '-' instead of
1069  * @type: the type name of the property.  This namespace is pretty loosely
1071  *   to angle brackets.  For instance, the type 'virtio-net-pci' in the
1072  *   'link' namespace would be 'link<virtio-net-pci>'.
1073  * @get: The getter to be called to read a property.  If this is NULL, then
1074  *   the property cannot be read.
1075  * @set: the setter to be called to write a property.  If this is NULL,
1076  *   then the property cannot be written.
1077  * @release: called when the property is removed from the object.  This is
1078  *   meant to allow a property to free its opaque upon object
1080  * @opaque: an opaque pointer to pass to the callbacks for the property
1098  * @obj: the object to add a property to
1099  * @name: the name of the property.  This can contain any character except for
1100  *  a forward slash.  In general, you should use hyphens '-' instead of
1102  * @type: the type name of the property.  This namespace is pretty loosely
1104  *   to angle brackets.  For instance, the type 'virtio-net-pci' in the
1105  *   'link' namespace would be 'link<virtio-net-pci>'.
1106  * @get: The getter to be called to read a property.  If this is NULL, then
1107  *   the property cannot be read.
1108  * @set: the setter to be called to write a property.  If this is NULL,
1109  *   then the property cannot be written.
1110  * @release: called when the property is removed from the object.  This is
1111  *   meant to allow a property to free its opaque upon object
1113  * @opaque: an opaque pointer to pass to the callbacks for the property
1133  * @prop: the property to set
1134  * @value: the value to be written to the property
1136  * Set the property default value.
1138 void object_property_set_default_bool(ObjectProperty *prop, bool value);
1142  * @prop: the property to set
1143  * @value: the value to be written to the property
1145  * Set the property default value.
1151  * @prop: the property to set
1153  * Set the property default value to be an empty list.
1159  * @prop: the property to set
1160  * @value: the value to be written to the property
1162  * Set the property default value.
1168  * @prop: the property to set
1169  * @value: the value to be written to the property
1171  * Set the property default value.
1178  * @name: the name of the property
1180  * Look up a property for an object.
1189  * @name: the name of the property
1192  * Look up a property for an object.
1203  * @name: the name of the property
1205  * Look up a property for an object class.
1215  * @name: the name of the property
1218  * Look up a property for an object class.
1239  * It is forbidden to modify the property list while iterating,
1244  * .. code-block:: c
1245  *    :caption: Using object property iterators
1266  * It is forbidden to modify the property list while iterating,
1279  * Return the next available property. If no further properties
1282  * re-initializing it.
1284  * Returns: the next property, or %NULL when all properties
1294  * @name: the name of the property
1295  * @v: the visitor that will receive the property value.  This should be an
1299  * Reads a property from a object.
1303 bool object_property_get(Object *obj, const char *name, Visitor *v,
1309  * @name: the name of the property
1310  * @value: the value to be written to the property
1313  * Writes a string value to a property.
1317 bool object_property_set_str(Object *obj, const char *name,
1323  * @name: the name of the property
1326  * Returns: the value of the property, converted to a C string, or NULL if
1327  * an error occurs (including when the property value is not a string).
1336  * @name: the name of the property
1337  * @value: the value to be written to the property
1340  * Writes an object's canonical path to a property.
1342  * If the link property was created with
1348 bool object_property_set_link(Object *obj, const char *name,
1354  * @name: the name of the property
1357  * Returns: the value of the property, resolved from a path to an Object,
1358  * or NULL if an error occurs (including when the property value is not a
1367  * @name: the name of the property
1368  * @value: the value to be written to the property
1371  * Writes a bool value to a property.
1375 bool object_property_set_bool(Object *obj, const char *name,
1376                               bool value, Error **errp);
1381  * @name: the name of the property
1384  * Returns: the value of the property, converted to a boolean, or false if
1385  * an error occurs (including when the property value is not a bool).
1387 bool object_property_get_bool(Object *obj, const char *name,
1393  * @name: the name of the property
1394  * @value: the value to be written to the property
1397  * Writes an integer value to a property.
1401 bool object_property_set_int(Object *obj, const char *name,
1407  * @name: the name of the property
1410  * Returns: the value of the property, converted to an integer, or -1 if
1411  * an error occurs (including when the property value is not an integer).
1419  * @name: the name of the property
1420  * @value: the value to be written to the property
1423  * Writes an unsigned integer value to a property.
1427 bool object_property_set_uint(Object *obj, const char *name,
1433  * @name: the name of the property
1436  * Returns: the value of the property, converted to an unsigned integer, or 0
1437  * an error occurs (including when the property value is not an integer).
1445  * @name: the name of the property
1449  * Returns: the value of the property, converted to an integer (which
1450  * can't be negative), or -1 on error (including when the property
1459  * @name: the name of the property
1460  * @v: the visitor that will be used to write the property value.  This should
1462  *   name and then written as the property value.
1465  * Writes a property to a object.
1469 bool object_property_set(Object *obj, const char *name, Visitor *v,
1475  * @name: the name of the property
1476  * @string: the string that will be used to parse the property value.
1479  * Parses a string and writes the result into a property of an object.
1483 bool object_property_parse(Object *obj, const char *name,
1489  * @name: the name of the property
1493  * Returns a string representation of the value of the property.  The
1496 char *object_property_print(Object *obj, const char *name, bool human,
1502  * @name: the name of the property
1505  * Returns:  The type name of the property.
1576  * There are two types of supported paths--absolute paths and partial paths.
1593 Object *object_resolve_path(const char *path, bool *ambiguous);
1614                                  bool *ambiguous);
1655  * @obj: the object to add a property to
1656  * @name: the name of the property
1666  * The value of a child property as a C string will be the child object's
1670  * Returns: The newly added property on success, or %NULL on failure.
1677  * @obj: the object to add a property to
1678  * @name: the name of the property
1688     /* Unref the link pointer when the property is deleted */
1698  * @obj: the object to add a property to
1699  * @name: the name of the property
1704  * callback function.  It allows the link property to be set and never returns
1712  * @obj: the object to add a property to
1713  * @name: the name of the property
1716  * @check: callback to veto setting or NULL if the property is read-only
1727  * link being set.  If @check is NULL, the property is read-only
1731  * link property.  The reference count for *@child is
1732  * managed by the property from after the function returns till the
1733  * property is deleted with object_property_del().  If the
1735  * the reference count is decremented when the property is deleted or
1738  * Returns: The newly added property on success, or %NULL on failure.
1755  * @obj: the object to add a property to
1756  * @name: the name of the property
1757  * @get: the getter or NULL if the property is write-only.  This function must
1759  * @set: the setter or NULL if the property is read-only
1761  * Add a string property using getters/setters.  This function will add a
1762  * property of type 'string'.
1764  * Returns: The newly added property on success, or %NULL on failure.
1778  * @obj: the object to add a property to
1779  * @name: the name of the property
1780  * @get: the getter or NULL if the property is write-only.
1781  * @set: the setter or NULL if the property is read-only
1783  * Add a bool property using getters/setters.  This function will add a
1784  * property of type 'bool'.
1786  * Returns: The newly added property on success, or %NULL on failure.
1789                               bool (*get)(Object *, Error **),
1790                               void (*set)(Object *, bool, Error **));
1794                                     bool (*get)(Object *, Error **),
1795                                     void (*set)(Object *, bool, Error **));
1799  * @obj: the object to add a property to
1800  * @name: the name of the property
1803  * @get: the getter or %NULL if the property is write-only.
1804  * @set: the setter or %NULL if the property is read-only
1806  * Add an enum property using getters/setters.  This function will add a
1807  * property of type '@typename'.
1809  * Returns: The newly added property on success, or %NULL on failure.
1826  * @obj: the object to add a property to
1827  * @name: the name of the property
1828  * @get: the getter or NULL if the property is write-only.
1830  * Add a read-only struct tm valued property using a getter function.
1831  * This function will add a property of type 'struct tm'.
1833  * Returns: The newly added property on success, or %NULL on failure.
1843     /* Automatically add a getter to the property */
1845     /* Automatically add a setter to the property */
1847     /* Automatically add a getter and a setter to the property */
1853  * @obj: the object to add a property to
1854  * @name: the name of the property
1856  * @flags: bitwise-or'd ObjectPropertyFlags
1858  * Add an integer property in memory.  This function will add a
1859  * property of type 'uint8'.
1861  * Returns: The newly added property on success, or %NULL on failure.
1874  * @obj: the object to add a property to
1875  * @name: the name of the property
1877  * @flags: bitwise-or'd ObjectPropertyFlags
1879  * Add an integer property in memory.  This function will add a
1880  * property of type 'uint16'.
1882  * Returns: The newly added property on success, or %NULL on failure.
1895  * @obj: the object to add a property to
1896  * @name: the name of the property
1898  * @flags: bitwise-or'd ObjectPropertyFlags
1900  * Add an integer property in memory.  This function will add a
1901  * property of type 'uint32'.
1903  * Returns: The newly added property on success, or %NULL on failure.
1916  * @obj: the object to add a property to
1917  * @name: the name of the property
1919  * @flags: bitwise-or'd ObjectPropertyFlags
1921  * Add an integer property in memory.  This function will add a
1922  * property of type 'uint64'.
1924  * Returns: The newly added property on success, or %NULL on failure.
1937  * @obj: the object to add a property to
1938  * @name: the name of the property
1939  * @target_obj: the object to forward property access to
1940  * @target_name: the name of the property on the forwarded object
1942  * Add an alias for a property on an object.  This function will add a property
1943  * of the same type as the forwarded property.
1946  * this property exists.  In the case of a child object or an alias on the same
1950  * Returns: The newly added property on success, or %NULL on failure.
1957  * @obj: the object to add a property to
1958  * @name: the name of the property
1961  * Add an unmodifiable link for a property on an object.  This function will
1962  * add a property of type link<TYPE> where TYPE is the type of @target.
1965  * this property exists.  In the case @target is a child of @obj,
1969  * Returns: The newly added property on success, or %NULL on failure.
1976  * @obj: the object owning the property
1977  * @name: the name of the property
1978  * @description: the description of the property on the object
1980  * Set an object property's description.
1996  * non-zero.
2013  * non-zero. Calls recursively, all child nodes of @obj will also be passed
2028  * @name: the name of the parent object's property to add
2039  * @name: the name of the property
2040  * @type: the type of the property
2042  * @description: description of the property
2044  * Returns: a user-friendly formatted string describing the property