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