LXR qemu/include/qom/object

   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
  19typedef 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 */
  43typedef 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 */
  61void 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 */
  70bool 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 */
  86Object *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_opts:
  92 * @opts: 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 whose type
  96 * is defined in @opts by the 'qom-type' option, placing it
  97 * in the object composition tree with name provided by the
  98 * 'id' field. The remaining options in @opts are used to
  99 * initialize the object properties.
 100 *
 101 * Returns: the newly created object or NULL on error
 102 */
 103Object *user_creatable_add_opts(QemuOpts *opts, Error **errp);
 104
 105
 106/**
 107 * user_creatable_add_opts_predicate:
 108 * @type: the QOM type to be added
 109 *
 110 * A callback function to determine whether an object
 111 * of type @type should be created. Instances of this
 112 * callback should be passed to user_creatable_add_opts_foreach
 113 */
 114typedef bool (*user_creatable_add_opts_predicate)(const char *type);
 115
 116/**
 117 * user_creatable_add_opts_foreach:
 118 * @opaque: a user_creatable_add_opts_predicate callback or NULL
 119 * @opts: options to create
 120 * @errp: unused
 121 *
 122 * An iterator callback to be used in conjunction with
 123 * the qemu_opts_foreach() method for creating a list of
 124 * objects from a set of QemuOpts
 125 *
 126 * The @opaque parameter can be passed a user_creatable_add_opts_predicate
 127 * callback to filter which types of object are created during iteration.
 128 * When it fails, report the error.
 129 *
 130 * Returns: 0 on success, -1 when an error was reported.
 131 */
 132int user_creatable_add_opts_foreach(void *opaque,
 133                                    QemuOpts *opts, Error **errp);
 134
 135/**
 136 * user_creatable_print_help:
 137 * @type: the QOM type to be added
 138 * @opts: options to create
 139 *
 140 * Prints help if requested in @opts.
 141 *
 142 * Returns: true if @opts contained a help option and help was printed, false
 143 * if no help option was found.
 144 */
 145bool user_creatable_print_help(const char *type, QemuOpts *opts);
 146
 147/**
 148 * user_creatable_del:
 149 * @id: the unique ID for the object
 150 * @errp: if an error occurs, a pointer to an area to store the error
 151 *
 152 * Delete an instance of the user creatable object identified
 153 * by @id.
 154 */
 155void user_creatable_del(const char *id, Error **errp);
 156
 157/**
 158 * user_creatable_cleanup:
 159 *
 160 * Delete all user-creatable objects and the user-creatable
 161 * objects container.
 162 */
 163void user_creatable_cleanup(void);
 164
 165#endif
 166