include/qom/object_interfaces.h

   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
  20 typedef 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  */
  47 typedef 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  */
  65 void 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  */
  74 bool 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  */
  90 Object *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  */
 107 Object *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  */
 118 typedef 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  */
 136 int 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  */
 147 void 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  */
 155 void user_creatable_cleanup(void);
 156
 157 #endif