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 typedef struct UserCreatable UserCreatable;
  20
  21 /**
  22  * UserCreatableClass:
  23  * @parent_class: the base class
  24  * @complete: callback to be called after @obj's properties are set.
  25  * @can_be_deleted: callback to be called before an object is removed
  26  * to check if @obj can be removed safely.
  27  *
  28  * Interface is designed to work with -object/object-add/object_add
  29  * commands.
  30  * Interface is mandatory for objects that are designed to be user
  31  * creatable (i.e. -object/object-add/object_add, will accept only
  32  * objects that inherit this interface).
  33  *
  34  * Interface also provides an optional ability to do the second
  35  * stage * initialization of the object after its properties were
  36  * set.
  37  *
  38  * For objects created without using -object/object-add/object_add,
  39  * @user_creatable_complete() wrapper should be called manually if
  40  * object's type implements USER_CREATABLE interface and needs
  41  * complete() callback to be called.
  42  */
  43 typedef struct UserCreatableClass {
  44     /* <private> */
  45     InterfaceClass parent_class;
  46
  47     /* <public> */
  48     void (*complete)(UserCreatable *uc, Error **errp);
  49     bool (*can_be_deleted)(UserCreatable *uc);
  50 } UserCreatableClass;
  51
  52 /**
  53  * user_creatable_complete:
  54  * @uc: the user-creatable object whose complete() method is called if defined
  55  * @errp: if an error occurs, a pointer to an area to store the error
  56  *
  57  * Wrapper to call complete() method if one of types it's inherited
  58  * from implements USER_CREATABLE interface, otherwise the call does
  59  * nothing.
  60  *
  61  * Returns: %true on success, %false on failure.
  62  */
  63 bool user_creatable_complete(UserCreatable *uc, Error **errp);
  64
  65 /**
  66  * user_creatable_can_be_deleted:
  67  * @uc: the object whose can_be_deleted() method is called if implemented
  68  *
  69  * Wrapper to call can_be_deleted() method if one of types it's inherited
  70  * from implements USER_CREATABLE interface.
  71  */
  72 bool user_creatable_can_be_deleted(UserCreatable *uc);
  73
  74 /**
  75  * user_creatable_add_type:
  76  * @type: the object type name
  77  * @id: the unique ID for the object
  78  * @qdict: the object properties
  79  * @v: the visitor
  80  * @errp: if an error occurs, a pointer to an area to store the error
  81  *
  82  * Create an instance of the user creatable object @type, placing
  83  * it in the object composition tree with name @id, initializing
  84  * it with properties from @qdict
  85  *
  86  * Returns: the newly created object or NULL on error
  87  */
  88 Object *user_creatable_add_type(const char *type, const char *id,
  89                                 const QDict *qdict,
  90                                 Visitor *v, Error **errp);
  91
  92 /**
  93  * user_creatable_add_dict:
  94  * @qdict: the object definition
  95  * @keyval: if true, use a keyval visitor for processing @qdict (i.e.
  96  *          assume that all @qdict values are strings); otherwise, use
  97  *          the normal QObject visitor (i.e. assume all @qdict values
  98  *          have the QType expected by the QOM object type)
  99  * @errp: if an error occurs, a pointer to an area to store the error
 100  *
 101  * Create an instance of the user creatable object that is defined by
 102  * @qdict.  The object type is taken from the QDict key 'qom-type', its
 103  * ID from the key 'id'. The remaining entries in @qdict are used to
 104  * initialize the object properties.
 105  *
 106  * Returns: %true on success, %false on failure.
 107  */
 108 bool user_creatable_add_dict(QDict *qdict, bool keyval, Error **errp);
 109
 110 /**
 111  * user_creatable_add_opts:
 112  * @opts: the object definition
 113  * @errp: if an error occurs, a pointer to an area to store the error
 114  *
 115  * Create an instance of the user creatable object whose type
 116  * is defined in @opts by the 'qom-type' option, placing it
 117  * in the object composition tree with name provided by the
 118  * 'id' field. The remaining options in @opts are used to
 119  * initialize the object properties.
 120  *
 121  * Returns: the newly created object or NULL on error
 122  */
 123 Object *user_creatable_add_opts(QemuOpts *opts, Error **errp);
 124
 125
 126 /**
 127  * user_creatable_add_opts_predicate:
 128  * @type: the QOM type to be added
 129  *
 130  * A callback function to determine whether an object
 131  * of type @type should be created. Instances of this
 132  * callback should be passed to user_creatable_add_opts_foreach
 133  */
 134 typedef bool (*user_creatable_add_opts_predicate)(const char *type);
 135
 136 /**
 137  * user_creatable_add_opts_foreach:
 138  * @opaque: a user_creatable_add_opts_predicate callback or NULL
 139  * @opts: options to create
 140  * @errp: unused
 141  *
 142  * An iterator callback to be used in conjunction with
 143  * the qemu_opts_foreach() method for creating a list of
 144  * objects from a set of QemuOpts
 145  *
 146  * The @opaque parameter can be passed a user_creatable_add_opts_predicate
 147  * callback to filter which types of object are created during iteration.
 148  * When it fails, report the error.
 149  *
 150  * Returns: 0 on success, -1 when an error was reported.
 151  */
 152 int user_creatable_add_opts_foreach(void *opaque,
 153                                     QemuOpts *opts, Error **errp);
 154
 155 /**
 156  * user_creatable_print_help:
 157  * @type: the QOM type to be added
 158  * @opts: options to create
 159  *
 160  * Prints help if requested in @opts.
 161  *
 162  * Returns: true if @opts contained a help option and help was printed, false
 163  * if no help option was found.
 164  */
 165 bool user_creatable_print_help(const char *type, QemuOpts *opts);
 166
 167 /**
 168  * user_creatable_del:
 169  * @id: the unique ID for the object
 170  * @errp: if an error occurs, a pointer to an area to store the error
 171  *
 172  * Delete an instance of the user creatable object identified
 173  * by @id.
 174  *
 175  * Returns: %true on success, %false on failure.
 176  */
 177 bool user_creatable_del(const char *id, Error **errp);
 178
 179 /**
 180  * user_creatable_cleanup:
 181  *
 182  * Delete all user-creatable objects and the user-creatable
 183  * objects container.
 184  */
 185 void user_creatable_cleanup(void);
 186
 187 /**
 188  * qmp_object_add:
 189  *
 190  * QMP command handler for object-add. See the QAPI schema for documentation.
 191  */
 192 void qmp_object_add(QDict *qdict, QObject **ret_data, Error **errp);
 193
 194 #endif