#include <stdint.h>
#include <stdbool.h>
#include "qemu/queue.h"
+#include "qapi/error.h"
struct Visitor;
-struct Error;
struct TypeImpl;
typedef struct TypeImpl *Type;
* Methods are always <emphasis>virtual</emphasis>. Overriding a method in
* #TypeInfo.class_init of a subclass leads to any user of the class obtained
* via OBJECT_GET_CLASS() accessing the overridden function.
- * The original function is not automatically invoked. It is the responsability
+ * The original function is not automatically invoked. It is the responsibility
* of the overriding class to determine whether and when to invoke the method
* being overridden.
*
* MyClass parent_class;
*
* MyDoSomething parent_do_something;
- * } MyClass;
+ * } DerivedClass;
*
* static void derived_do_something(MyState *obj)
* {
struct Visitor *v,
void *opaque,
const char *name,
- struct Error **errp);
+ Error **errp);
+
+/**
+ * ObjectPropertyResolve:
+ * @obj: the object that owns the property
+ * @opaque: the opaque registered with the property
+ * @part: the name of the property
+ *
+ * Resolves the #Object corresponding to property @part.
+ *
+ * The returned object can also be used as a starting point
+ * to resolve a relative path starting with "@part".
+ *
+ * Returns: If @path is the path that led to @obj, the function
+ * returns the #Object corresponding to "@path/@part".
+ * If "@path/@part" is not a valid object path, it returns #NULL.
+ */
+typedef Object *(ObjectPropertyResolve)(Object *obj,
+ void *opaque,
+ const char *part);
/**
* ObjectPropertyRelease:
gchar *type;
ObjectPropertyAccessor *get;
ObjectPropertyAccessor *set;
+ ObjectPropertyResolve *resolve;
ObjectPropertyRelease *release;
void *opaque;
*/
typedef void (ObjectFree)(void *obj);
+#define OBJECT_CLASS_CAST_CACHE 4
+
/**
* ObjectClass:
*
Type type;
GSList *interfaces;
+ const char *object_cast_cache[OBJECT_CLASS_CAST_CACHE];
+ const char *class_cast_cache[OBJECT_CLASS_CAST_CACHE];
+
ObjectUnparent *unparent;
};
* @instance_init: This function is called to initialize an object. The parent
* class will have already been initialized so the type is only responsible
* for initializing its own members.
+ * @instance_post_init: This function is called to finish initialization of
+ * an object, after all @instance_init functions were called.
* @instance_finalize: This function is called during object destruction. This
* is called before the parent @instance_finalize function has been called.
* An object should only free the members that are unique to its type in this
size_t instance_size;
void (*instance_init)(Object *obj);
+ void (*instance_post_init)(Object *obj);
void (*instance_finalize)(Object *obj);
bool abstract;
* generated.
*/
#define OBJECT_CHECK(type, obj, name) \
- ((type *)object_dynamic_cast_assert(OBJECT(obj), (name)))
+ ((type *)object_dynamic_cast_assert(OBJECT(obj), (name), \
+ __FILE__, __LINE__, __func__))
/**
* OBJECT_CLASS_CHECK:
* specific class type.
*/
#define OBJECT_CLASS_CHECK(class, obj, name) \
- ((class *)object_class_dynamic_cast_assert(OBJECT_CLASS(obj), (name)))
+ ((class *)object_class_dynamic_cast_assert(OBJECT_CLASS(obj), (name), \
+ __FILE__, __LINE__, __func__))
/**
* OBJECT_GET_CLASS:
ObjectClass parent_class;
/*< private >*/
ObjectClass *concrete_class;
+ Type interface_type;
};
#define TYPE_INTERFACE "interface"
* Returns: @obj casted to @interface if cast is valid, otherwise raise error.
*/
#define INTERFACE_CHECK(interface, obj, name) \
- ((interface *)object_dynamic_cast_assert(OBJECT((obj)), (name)))
+ ((interface *)object_dynamic_cast_assert(OBJECT((obj)), (name), \
+ __FILE__, __LINE__, __func__))
/**
* object_new:
* @typename: The name of the type of the object to instantiate.
*
- * This function will initialize a new object using heap allocated memory. This
- * function should be paired with object_delete() to free the resources
- * associated with the object.
+ * This function will initialize a new object using heap allocated memory.
+ * The returned object has a reference count of 1, and will be freed when
+ * the last reference is dropped.
*
* Returns: The newly allocated and instantiated object.
*/
* object_new_with_type:
* @type: The type of the object to instantiate.
*
- * This function will initialize a new object using heap allocated memory. This
- * function should be paired with object_delete() to free the resources
- * associated with the object.
+ * This function will initialize a new object using heap allocated memory.
+ * The returned object has a reference count of 1, and will be freed when
+ * the last reference is dropped.
*
* Returns: The newly allocated and instantiated object.
*/
Object *object_new_with_type(Type type);
-/**
- * object_delete:
- * @obj: The object to free.
- *
- * Finalize an object and then free the memory associated with it. This should
- * be paired with object_new() to free the resources associated with an object.
- */
-void object_delete(Object *obj);
-
/**
* object_initialize_with_type:
- * @obj: A pointer to the memory to be used for the object.
+ * @data: A pointer to the memory to be used for the object.
+ * @size: The maximum size available at @data for the object.
* @type: The type of the object to instantiate.
*
* This function will initialize an object. The memory for the object should
- * have already been allocated.
+ * have already been allocated. The returned object has a reference count of 1,
+ * and will be finalized when the last reference is dropped.
*/
-void object_initialize_with_type(void *data, Type type);
+void object_initialize_with_type(void *data, size_t size, Type type);
/**
* object_initialize:
* @obj: A pointer to the memory to be used for the object.
+ * @size: The maximum size available at @obj for the object.
* @typename: The name of the type of the object to instantiate.
*
* This function will initialize an object. The memory for the object should
- * have already been allocated.
+ * have already been allocated. The returned object has a reference count of 1,
+ * and will be finalized when the last reference is dropped.
*/
-void object_initialize(void *obj, const char *typename);
+void object_initialize(void *obj, size_t size, const char *typename);
/**
* object_dynamic_cast:
*
* See object_dynamic_cast() for a description of the parameters of this
* function. The only difference in behavior is that this function asserts
- * instead of returning #NULL on failure.
+ * instead of returning #NULL on failure if QOM cast debugging is enabled.
+ * This function is not meant to be called directly, but only through
+ * the wrapper macro OBJECT_CHECK.
*/
-Object *object_dynamic_cast_assert(Object *obj, const char *typename);
+Object *object_dynamic_cast_assert(Object *obj, const char *typename,
+ const char *file, int line, const char *func);
/**
* object_get_class:
* @klass: The #ObjectClass to attempt to cast.
* @typename: The QOM typename of the class to cast to.
*
- * Returns: This function always returns @klass and asserts on failure.
+ * See object_class_dynamic_cast() for a description of the parameters
+ * of this function. The only difference in behavior is that this function
+ * asserts instead of returning #NULL on failure if QOM cast debugging is
+ * enabled. This function is not meant to be called directly, but only through
+ * the wrapper macros OBJECT_CLASS_CHECK and INTERFACE_CHECK.
*/
ObjectClass *object_class_dynamic_cast_assert(ObjectClass *klass,
- const char *typename);
+ const char *typename,
+ const char *file, int line,
+ const char *func);
+/**
+ * object_class_dynamic_cast:
+ * @klass: The #ObjectClass to attempt to cast.
+ * @typename: The QOM typename of the class to cast to.
+ *
+ * Returns: If @typename is a class, this function returns @klass if
+ * @typename is a subtype of @klass, else returns #NULL.
+ *
+ * If @typename is an interface, this function returns the interface
+ * definition for @klass if @klass implements it unambiguously; #NULL
+ * is returned if @klass does not implement the interface or if multiple
+ * classes or interfaces on the hierarchy leading to @klass implement
+ * it. (FIXME: perhaps this can be detected at type definition time?)
+ */
ObjectClass *object_class_dynamic_cast(ObjectClass *klass,
const char *typename);
* destruction. This may be NULL.
* @opaque: an opaque pointer to pass to the callbacks for the property
* @errp: returns an error if this function fails
+ *
+ * Returns: The #ObjectProperty; this can be used to set the @resolve
+ * callback for child and link properties.
*/
-void object_property_add(Object *obj, const char *name, const char *type,
- ObjectPropertyAccessor *get,
- ObjectPropertyAccessor *set,
- ObjectPropertyRelease *release,
- void *opaque, struct Error **errp);
+ObjectProperty *object_property_add(Object *obj, const char *name,
+ const char *type,
+ ObjectPropertyAccessor *get,
+ ObjectPropertyAccessor *set,
+ ObjectPropertyRelease *release,
+ void *opaque, Error **errp);
-void object_property_del(Object *obj, const char *name, struct Error **errp);
+void object_property_del(Object *obj, const char *name, Error **errp);
/**
* object_property_find:
* Look up a property for an object and return its #ObjectProperty if found.
*/
ObjectProperty *object_property_find(Object *obj, const char *name,
- struct Error **errp);
+ Error **errp);
void object_unparent(Object *obj);
* Reads a property from a object.
*/
void object_property_get(Object *obj, struct Visitor *v, const char *name,
- struct Error **errp);
+ Error **errp);
/**
* object_property_set_str:
* Writes a string value to a property.
*/
void object_property_set_str(Object *obj, const char *value,
- const char *name, struct Error **errp);
+ const char *name, Error **errp);
/**
* object_property_get_str:
* The caller should free the string.
*/
char *object_property_get_str(Object *obj, const char *name,
- struct Error **errp);
+ Error **errp);
/**
* object_property_set_link:
* Writes an object's canonical path to a property.
*/
void object_property_set_link(Object *obj, Object *value,
- const char *name, struct Error **errp);
+ const char *name, Error **errp);
/**
* object_property_get_link:
* string or not a valid object path).
*/
Object *object_property_get_link(Object *obj, const char *name,
- struct Error **errp);
+ Error **errp);
/**
* object_property_set_bool:
* Writes a bool value to a property.
*/
void object_property_set_bool(Object *obj, bool value,
- const char *name, struct Error **errp);
+ const char *name, Error **errp);
/**
* object_property_get_bool:
* an error occurs (including when the property value is not a bool).
*/
bool object_property_get_bool(Object *obj, const char *name,
- struct Error **errp);
+ Error **errp);
/**
* object_property_set_int:
* Writes an integer value to a property.
*/
void object_property_set_int(Object *obj, int64_t value,
- const char *name, struct Error **errp);
+ const char *name, Error **errp);
/**
* object_property_get_int:
* an error occurs (including when the property value is not an integer).
*/
int64_t object_property_get_int(Object *obj, const char *name,
- struct Error **errp);
+ Error **errp);
+
+/**
+ * object_property_get_enum:
+ * @obj: the object
+ * @name: the name of the property
+ * @strings: strings corresponding to enums
+ * @errp: returns an error if this function fails
+ *
+ * Returns: the value of the property, converted to an integer, or
+ * undefined if an error occurs (including when the property value is not
+ * an enum).
+ */
+int object_property_get_enum(Object *obj, const char *name,
+ const char *strings[], Error **errp);
+
+/**
+ * object_property_get_uint16List:
+ * @obj: the object
+ * @name: the name of the property
+ * @list: the returned int list
+ * @errp: returns an error if this function fails
+ *
+ * Returns: the value of the property, converted to integers, or
+ * undefined if an error occurs (including when the property value is not
+ * an list of integers).
+ */
+void object_property_get_uint16List(Object *obj, const char *name,
+ uint16List **list, Error **errp);
/**
* object_property_set:
* Writes a property to a object.
*/
void object_property_set(Object *obj, struct Visitor *v, const char *name,
- struct Error **errp);
+ Error **errp);
/**
* object_property_parse:
* Parses a string and writes the result into a property of an object.
*/
void object_property_parse(Object *obj, const char *string,
- const char *name, struct Error **errp);
+ const char *name, Error **errp);
/**
* object_property_print:
* @obj: the object
* @name: the name of the property
+ * @human: if true, print for human consumption
* @errp: returns an error if this function fails
*
* Returns a string representation of the value of the property. The
* caller shall free the string.
*/
-char *object_property_print(Object *obj, const char *name,
- struct Error **errp);
+char *object_property_print(Object *obj, const char *name, bool human,
+ Error **errp);
/**
* object_property_get_type:
* Returns: The type name of the property.
*/
const char *object_property_get_type(Object *obj, const char *name,
- struct Error **errp);
+ Error **errp);
/**
* object_get_root:
*/
Object *object_get_root(void);
+/**
+ * object_get_canonical_path_component:
+ *
+ * Returns: The final component in the object's canonical path. The canonical
+ * path is the path within the composition tree starting from the root.
+ */
+gchar *object_get_canonical_path_component(Object *obj);
+
/**
* object_get_canonical_path:
*
* The child object itself can be retrieved using object_property_get_link().
*/
void object_property_add_child(Object *obj, const char *name,
- Object *child, struct Error **errp);
+ Object *child, Error **errp);
+
+typedef enum {
+ /* Unref the link pointer when the property is deleted */
+ OBJ_PROP_LINK_UNREF_ON_RELEASE = 0x1,
+} ObjectPropertyLinkFlags;
+
+/**
+ * object_property_allow_set_link:
+ *
+ * The default implementation of the object_property_add_link() check()
+ * callback function. It allows the link property to be set and never returns
+ * an error.
+ */
+void object_property_allow_set_link(Object *, const char *,
+ Object *, Error **);
/**
* object_property_add_link:
* @name: the name of the property
* @type: the qobj type of the link
* @child: a pointer to where the link object reference is stored
+ * @check: callback to veto setting or NULL if the property is read-only
+ * @flags: additional options for the link
* @errp: if an error occurs, a pointer to an area to store the area
*
* Links establish relationships between objects. Links are unidirectional
*
* Links form the graph in the object model.
*
+ * The <code>@check()</code> callback is invoked when
+ * object_property_set_link() is called and can raise an error to prevent the
+ * link being set. If <code>@check</code> is NULL, the property is read-only
+ * and cannot be set.
+ *
* Ownership of the pointer that @child points to is transferred to the
* link property. The reference count for <code>*@child</code> is
* managed by the property from after the function returns till the
- * property is deleted with object_property_del().
+ * property is deleted with object_property_del(). If the
+ * <code>@flags</code> <code>OBJ_PROP_LINK_UNREF_ON_RELEASE</code> bit is set,
+ * the reference count is decremented when the property is deleted.
*/
void object_property_add_link(Object *obj, const char *name,
const char *type, Object **child,
- struct Error **errp);
+ void (*check)(Object *obj, const char *name,
+ Object *val, Error **errp),
+ ObjectPropertyLinkFlags flags,
+ Error **errp);
/**
* object_property_add_str:
* property of type 'string'.
*/
void object_property_add_str(Object *obj, const char *name,
- char *(*get)(Object *, struct Error **),
- void (*set)(Object *, const char *, struct Error **),
- struct Error **errp);
+ char *(*get)(Object *, Error **),
+ void (*set)(Object *, const char *, Error **),
+ Error **errp);
/**
* object_property_add_bool:
* property of type 'bool'.
*/
void object_property_add_bool(Object *obj, const char *name,
- bool (*get)(Object *, struct Error **),
- void (*set)(Object *, bool, struct Error **),
- struct Error **errp);
+ bool (*get)(Object *, Error **),
+ void (*set)(Object *, bool, Error **),
+ Error **errp);
+
+/**
+ * object_property_add_uint8_ptr:
+ * @obj: the object to add a property to
+ * @name: the name of the property
+ * @v: pointer to value
+ * @errp: if an error occurs, a pointer to an area to store the error
+ *
+ * Add an integer property in memory. This function will add a
+ * property of type 'uint8'.
+ */
+void object_property_add_uint8_ptr(Object *obj, const char *name,
+ const uint8_t *v, Error **errp);
+
+/**
+ * object_property_add_uint16_ptr:
+ * @obj: the object to add a property to
+ * @name: the name of the property
+ * @v: pointer to value
+ * @errp: if an error occurs, a pointer to an area to store the error
+ *
+ * Add an integer property in memory. This function will add a
+ * property of type 'uint16'.
+ */
+void object_property_add_uint16_ptr(Object *obj, const char *name,
+ const uint16_t *v, Error **errp);
+
+/**
+ * object_property_add_uint32_ptr:
+ * @obj: the object to add a property to
+ * @name: the name of the property
+ * @v: pointer to value
+ * @errp: if an error occurs, a pointer to an area to store the error
+ *
+ * Add an integer property in memory. This function will add a
+ * property of type 'uint32'.
+ */
+void object_property_add_uint32_ptr(Object *obj, const char *name,
+ const uint32_t *v, Error **errp);
+
+/**
+ * object_property_add_uint64_ptr:
+ * @obj: the object to add a property to
+ * @name: the name of the property
+ * @v: pointer to value
+ * @errp: if an error occurs, a pointer to an area to store the error
+ *
+ * Add an integer property in memory. This function will add a
+ * property of type 'uint64'.
+ */
+void object_property_add_uint64_ptr(Object *obj, const char *name,
+ const uint64_t *v, Error **Errp);
+
+/**
+ * object_property_add_alias:
+ * @obj: the object to add a property to
+ * @name: the name of the property
+ * @target_obj: the object to forward property access to
+ * @target_name: the name of the property on the forwarded object
+ * @errp: if an error occurs, a pointer to an area to store the error
+ *
+ * Add an alias for a property on an object. This function will add a property
+ * of the same type as the forwarded property.
+ *
+ * The caller must ensure that <code>@target_obj</code> stays alive as long as
+ * this property exists. In the case of a child object or an alias on the same
+ * object this will be the case. For aliases to other objects the caller is
+ * responsible for taking a reference.
+ */
+void object_property_add_alias(Object *obj, const char *name,
+ Object *target_obj, const char *target_name,
+ Error **errp);
/**
* object_child_foreach:
projects / qemu.git / blobdiff