include/qom/object.h

9  * This work is licensed under the terms of the GNU GPL, version 2 or later.
37  * @name: the name of the property
53  * @part: the name of the property
71  * @name: the name of the property
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
151  * first member.  This allows identification of the real type of the object at
170  * Direct usage of this macro should be avoided, and the complete
187  * Direct usage of this macro should be avoided, and the complete
209  * Direct usage of this macro should be avoided, and the complete
270  * @CLASS_SIZE: size of the type's class
271  * @...: list of initializers for "InterfaceInfo" to declare implemented interfaces
315  * @...: list of initializers for "InterfaceInfo" to declare implemented interfaces
323  * After using this macro, implementations of the _finalize, _class_init,
324  * and _init methods need to be written. Any of these can be zero-line
327  * This macro should rarely be used, instead one of the more specialized
346  * This is a specialization of OBJECT_DEFINE_TYPE_EXTENDED, which is suitable
347  * for the common case of a non-abstract type, without any interfaces.
362  * @...: list of initializers for "InterfaceInfo" to declare implemented interfaces
364  * This is a specialization of OBJECT_DEFINE_TYPE_EXTENDED, which is suitable
365  * for the common case of a non-abstract type, with one or more implemented
368  * Note when passing the list of interfaces, be sure to include the final
386  * This is a specialization of OBJECT_DEFINE_TYPE_EXTENDED, which is suitable
403  * This is a variant of OBJECT_DEFINE_TYPE_EXTENDED, which is suitable for
404  * the case of a non-abstract type, with interfaces, and with no requirement
423  * This is a variant of OBJECT_DEFINE_TYPE_EXTENDED, which is suitable for
424  * the common case of a non-abstract type, without any interfaces, and with
436  * @name: The name of the type.
437  * @parent: The name of the parent type.
438  * @instance_size: The size of the object (derivative of #Object).  If
439  *   @instance_size is 0, then the size of the object will be the size of the
441  * @instance_align: The required alignment of the object.  If @instance_align
447  * @instance_post_init: This function is called to finish initialization of
456  * @class_size: The size of the class object (derivative of #ObjectClass)
457  *   for this object.  If @class_size is 0, then the size of the class will be
458  *   assumed to be the size of the parent class.  This allows a type to avoid
467  *   is initialized.  This is the function to use to undo the effects of
472  * @interfaces: The list of interfaces associated with this type.  This
499  * @obj: A derivative of #Object
509  * @class: A derivative of #ObjectClass.
520  * @obj: A derivative of @type to cast.
521  * @name: The QOM typename of @type
523  * A type safe version of @object_dynamic_cast_assert.  Typically each class
537  * @class: A derivative class of @class_type to cast.
538  * @name: the QOM typename of @class_type.
540  * A type safe version of @object_class_dynamic_cast_assert.  This macro is
541  * typically wrapped by each type to perform type safe casts of a class to a
552  * @name: The QOM typename of @obj.
563  * @type: The name of the interface.
575  * The class for all interfaces.  Subclasses of this class should only add
578  * Note that most of the fields of ObjectClass are unused (all except
616  * The returned object has a reference count of 1, and will be freed when
625  * @typename: The name of the type of the object to instantiate.
628  * The returned object has a reference count of 1, and will be freed when
637  * @typename:  The name of the type of the object to instantiate.
639  * @id: The unique ID of the object
641  * @...: list of property names and values
644  * The returned object has a reference count of 1, and will be freed when
648  * child of @parent in the composition tree.
650  * The variadic parameters are a list of pairs of (propname, propvalue)
651  * strings. The propname of %NULL indicates the end of the property
689  * @typename:  The name of the type of the object to instantiate.
691  * @id: The unique ID of the object
693  * @vargs: list of property names and values
715  * @...: list of property names and values
717  * This function will set a list of properties on an existing object
720  * The variadic parameters are a list of pairs of (propname, propvalue)
721  * strings. The propname of %NULL indicates the end of the property
751  * @vargs: list of property names and values
763  * @typename: The name of the type of the object to instantiate.
766  * have already been allocated.  The returned object has a reference count of 1,
774  * @propname: The name of the property
777  * @type: The name of the type of the object to instantiate.
779  * @...: list of property names and values
784  * has a reference count of 1 (for the "child<...>" property from the parent),
787  * The variadic parameters are a list of pairs of (propname, propvalue)
788  * strings. The propname of %NULL indicates the end of the property list.
802  * @propname: The name of the property
805  * @type: The name of the type of the object to instantiate.
807  * @vargs: list of property names and values
821  * @propname: The name of the property
824  * @type: The name of the type of the object to instantiate.
857  * @func: Name of function where this function was called
859  * See object_dynamic_cast() for a description of the parameters of this
861  * instead of returning #NULL on failure if QOM cast debugging is enabled.
870  * @obj: A derivative of #Object
872  * Returns: The #ObjectClass of the type associated with @obj.
878  * @obj: A derivative of #Object.
880  * Returns: The QOM typename of @obj.
886  * @info: The #TypeInfo of the new type.
894  * @infos: The array of the new type #TypeInfo structures.
895  * @nr_infos: number of entries in @infos
897  * @infos and all of the strings it points to should exist for the life time
929  * @from_json: true if leaf values of @qdict are typed, false if they
942  * @typename: The QOM typename of the class to cast to.
945  * @func: Name of function where this function was called
947  * See object_class_dynamic_cast() for a description of the parameters
948  * of this function.  The only difference in behavior is that this function
949  * asserts instead of returning #NULL on failure if QOM cast debugging is
961  * @typename: The QOM typename of the class to cast to.
964  * @typename is a subtype of @klass, else returns #NULL.
1028  * Returns: A singly-linked list of the classes in reverse hashtable order.
1038  * Returns: A singly-linked list of the classes in alphabetical
1048  * Increase the reference count of a object.  A object cannot be freed as long
1058  * Decrease the reference count of a object.  A object cannot be freed as long
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
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
1178  * @name: the name of the property
1189  * @name: the name of the property
1203  * @name: the name of the property
1215  * @name: the name of the property
1294  * @name: the name of the property
1309  * @name: the name of the property
1323  * @name: the name of the property
1326  * Returns: the value of the property, converted to a C string, or NULL if
1336  * @name: the name of the property
1354  * @name: the name of the property
1357  * Returns: the value of the property, resolved from a path to an Object,
1367  * @name: the name of the property
1381  * @name: the name of the property
1384  * Returns: the value of the property, converted to a boolean, or false if
1393  * @name: the name of the property
1407  * @name: the name of the property
1410  * Returns: the value of the property, converted to an integer, or -1 if
1419  * @name: the name of the property
1433  * @name: the name of the property
1436  * Returns: the value of the property, converted to an unsigned integer, or 0
1445  * @name: the name of the property
1446  * @typename: the name of the enum data type
1449  * Returns: the value of the property, converted to an integer (which
1459  * @name: the name of the property
1475  * @name: the name of the property
1479  * Parses a string and writes the result into a property of an object.
1489  * @name: the name of the property
1493  * Returns a string representation of the value of the property.  The
1502  * @name: the name of the property
1505  * Returns:  The type name of the property.
1513  * Returns: the root object of the composition tree
1519  * @name: the name of container to lookup
1576  * There are two types of supported paths--absolute paths and partial paths.
1585  * specifying objects easy.  At each level of the composition tree, the partial
1609  * or the typename itself are of interface types.
1621  * Return the only object in the QOM tree of type @typename.
1656  * @name: the name of the property
1661  * of another object.  Objects can only be a child of one object.
1666  * The value of a child property as a C string will be the child object's
1678  * @name: the name of the property
1699  * @name: the name of the property
1703  * The default implementation of the object_property_add_link() check()
1713  * @name: the name of the property
1714  * @type: the qobj type of the link
1730  * Ownership of the pointer that @child points to is transferred to the
1756  * @name: the name of the property
1762  * property of type 'string'.
1779  * @name: the name of the property
1784  * property of type 'bool'.
1800  * @name: the name of the property
1801  * @typename: the name of the enum data type
1807  * property of type '@typename'.
1827  * @name: the name of the property
1831  * This function will add a property of type 'struct tm'.
1854  * @name: the name of the property
1859  * property of type 'uint8'.
1875  * @name: the name of the property
1880  * property of type 'uint16'.
1896  * @name: the name of the property
1901  * property of type 'uint32'.
1917  * @name: the name of the property
1922  * property of type 'uint64'.
1938  * @name: the name of the property
1940  * @target_name: the name of the property on the forwarded object
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
1958  * @name: the name of the property
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,
1977  * @name: the name of the property
1978  * @description: the description of the property on the object
1995  * Call @fn passing each child of @obj and @opaque to it, until @fn returns
2012  * Call @fn passing each child of @obj and @opaque to it, until @fn returns
2013  * non-zero. Calls recursively, all child nodes of @obj will also be passed
2014  * all the way down to the leaf nodes of the tree. Depth first ordering.
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