LXR qemu/include/qom/object

   1#ifndef OBJECT_INTERFACES_H
   2#define OBJECT_INTERFACES_H
   3
   4#include "qom/object.h"
   5#include "qapi/visitor.h"
   6
   7#define TYPE_USER_CREATABLE "user-creatable"
   8
   9#define USER_CREATABLE_CLASS(klass) \
  10     OBJECT_CLASS_CHECK(UserCreatableClass, (klass), \
  11                        TYPE_USER_CREATABLE)
  12#define USER_CREATABLE_GET_CLASS(obj) \
  13     OBJECT_GET_CLASS(UserCreatableClass, (obj), \
  14                      TYPE_USER_CREATABLE)
  15#define USER_CREATABLE(obj) \
  16     INTERFACE_CHECK(UserCreatable, (obj), \
  17                     TYPE_USER_CREATABLE)
  18
  19
  20typedef struct UserCreatable {
  21    /* <private> */
  22    Object Parent;
  23} UserCreatable;
  24
  25/**
  26 * UserCreatableClass:
  27 * @parent_class: the base class
  28 * @complete: callback to be called after @obj's properties are set.
  29 * @can_be_deleted: callback to be called before an object is removed
  30 * to check if @obj can be removed safely.
  31 *
  32 * Interface is designed to work with -object/object-add/object_add
  33 * commands.
  34 * Interface is mandatory for objects that are designed to be user
  35 * creatable (i.e. -object/object-add/object_add, will accept only
  36 * objects that inherit this interface).
  37 *
  38 * Interface also provides an optional ability to do the second
  39 * stage * initialization of the object after its properties were
  40 * set.
  41 *
  42 * For objects created without using -object/object-add/object_add,
  43 * @user_creatable_complete() wrapper should be called manually if
  44 * object's type implements USER_CREATABLE interface and needs
  45 * complete() callback to be called.
  46 */
  47typedef struct UserCreatableClass {
  48    /* <private> */
  49    InterfaceClass parent_class;
  50
  51    /* <public> */
  52    void (*complete)(UserCreatable *uc, Error **errp);
  53    bool (*can_be_deleted)(UserCreatable *uc);
  54} UserCreatableClass;
  55
  56/**
  57 * user_creatable_complete:
  58 * @obj: the object whose complete() method is called if defined
  59 * @errp: if an error occurs, a pointer to an area to store the error
  60 *
  61 * Wrapper to call complete() method if one of types it's inherited
  62 * from implements USER_CREATABLE interface, otherwise the call does
  63 * nothing.
  64 */
  65void user_creatable_complete(Object *obj, Error **errp);
  66
  67/**
  68 * user_creatable_can_be_deleted:
  69 * @uc: the object whose can_be_deleted() method is called if implemented
  70 *
  71 * Wrapper to call can_be_deleted() method if one of types it's inherited
  72 * from implements USER_CREATABLE interface.
  73 */
  74bool user_creatable_can_be_deleted(UserCreatable *uc);
  75
  76/**
  77 * user_creatable_add_type:
  78 * @type: the object type name
  79 * @id: the unique ID for the object
  80 * @qdict: the object properties
  81 * @v: the visitor
  82 * @errp: if an error occurs, a pointer to an area to store the error
  83 *
  84 * Create an instance of the user creatable object @type, placing
  85 * it in the object composition tree with name @id, initializing
  86 * it with properties from @qdict
  87 *
  88 * Returns: the newly created object or NULL on error
  89 */
  90Object *user_creatable_add_type(const char *type, const char *id,
  91                                const QDict *qdict,
  92                                Visitor *v, Error **errp);
  93
  94/**
  95 * user_creatable_add_opts:
  96 * @opts: the object definition
  97 * @errp: if an error occurs, a pointer to an area to store the error
  98 *
  99 * Create an instance of the user creatable object whose type
 100 * is defined in @opts by the 'qom-type' option, placing it
 101 * in the object composition tree with name provided by the
 102 * 'id' field. The remaining options in @opts are used to
 103 * initialize the object properties.
 104 *
 105 * Returns: the newly created object or NULL on error
 106 */
 107Object *user_creatable_add_opts(QemuOpts *opts, Error **errp);
 108
 109
 110/**
 111 * user_creatable_add_opts_predicate:
 112 * @type: the QOM type to be added
 113 *
 114 * A callback function to determine whether an object
 115 * of type @type should be created. Instances of this
 116 * callback should be passed to user_creatable_add_opts_foreach
 117 */
 118typedef bool (*user_creatable_add_opts_predicate)(const char *type);
 119
 120/**
 121 * user_creatable_add_opts_foreach:
 122 * @opaque: a user_creatable_add_opts_predicate callback or NULL
 123 * @opts: options to create
 124 * @errp: unused
 125 *
 126 * An iterator callback to be used in conjunction with
 127 * the qemu_opts_foreach() method for creating a list of
 128 * objects from a set of QemuOpts
 129 *
 130 * The @opaque parameter can be passed a user_creatable_add_opts_predicate
 131 * callback to filter which types of object are created during iteration.
 132 * When it fails, report the error.
 133 *
 134 * Returns: 0 on success, -1 when an error was reported.
 135 */
 136int user_creatable_add_opts_foreach(void *opaque,
 137                                    QemuOpts *opts, Error **errp);
 138
 139/**
 140 * user_creatable_del:
 141 * @id: the unique ID for the object
 142 * @errp: if an error occurs, a pointer to an area to store the error
 143 *
 144 * Delete an instance of the user creatable object identified
 145 * by @id.
 146 */
 147void user_creatable_del(const char *id, Error **errp);
 148
 149/**
 150 * user_creatable_cleanup:
 151 *
 152 * Delete all user-creatable objects and the user-creatable
 153 * objects container.
 154 */
 155void user_creatable_cleanup(void);
 156
 157#endif
 158