qemu/include/qom/object_interfaces.h

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