include/qom/object_interfaces.h

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