LXR qemu/include/qom/object

   1#ifndef OBJECT_INTERFACES_H
   2#define OBJECT_INTERFACES_H
   3
   4#include "qom/object.h"
   5#include "qapi/qmp/qdict.h"
   6#include "qapi/visitor.h"
   7
   8#define TYPE_USER_CREATABLE "user-creatable"
   9
  10#define USER_CREATABLE_CLASS(klass) \
  11     OBJECT_CLASS_CHECK(UserCreatableClass, (klass), \
  12                        TYPE_USER_CREATABLE)
  13#define USER_CREATABLE_GET_CLASS(obj) \
  14     OBJECT_GET_CLASS(UserCreatableClass, (obj), \
  15                      TYPE_USER_CREATABLE)
  16#define USER_CREATABLE(obj) \
  17     INTERFACE_CHECK(UserCreatable, (obj), \
  18                     TYPE_USER_CREATABLE)
  19
  20
  21typedef struct UserCreatable {
  22    /* <private> */
  23    Object Parent;
  24} UserCreatable;
  25
  26/**
  27 * UserCreatableClass:
  28 * @parent_class: the base class
  29 * @complete: callback to be called after @obj's properties are set.
  30 * @can_be_deleted: callback to be called before an object is removed
  31 * to check if @obj can be removed safely.
  32 *
  33 * Interface is designed to work with -object/object-add/object_add
  34 * commands.
  35 * Interface is mandatory for objects that are designed to be user
  36 * creatable (i.e. -object/object-add/object_add, will accept only
  37 * objects that inherit this interface).
  38 *
  39 * Interface also provides an optional ability to do the second
  40 * stage * initialization of the object after its properties were
  41 * set.
  42 *
  43 * For objects created without using -object/object-add/object_add,
  44 * @user_creatable_complete() wrapper should be called manually if
  45 * object's type implements USER_CREATABLE interface and needs
  46 * complete() callback to be called.
  47 */
  48typedef struct UserCreatableClass {
  49    /* <private> */
  50    InterfaceClass parent_class;
  51
  52    /* <public> */
  53    void (*complete)(UserCreatable *uc, Error **errp);
  54    bool (*can_be_deleted)(UserCreatable *uc);
  55} UserCreatableClass;
  56
  57/**
  58 * user_creatable_complete:
  59 * @obj: the object whose complete() method is called if defined
  60 * @errp: if an error occurs, a pointer to an area to store the error
  61 *
  62 * Wrapper to call complete() method if one of types it's inherited
  63 * from implements USER_CREATABLE interface, otherwise the call does
  64 * nothing.
  65 */
  66void user_creatable_complete(Object *obj, Error **errp);
  67
  68/**
  69 * user_creatable_can_be_deleted:
  70 * @uc: the object whose can_be_deleted() method is called if implemented
  71 *
  72 * Wrapper to call can_be_deleted() method if one of types it's inherited
  73 * from implements USER_CREATABLE interface.
  74 */
  75bool user_creatable_can_be_deleted(UserCreatable *uc);
  76
  77/**
  78 * user_creatable_add_type:
  79 * @type: the object type name
  80 * @id: the unique ID for the object
  81 * @qdict: the object properties
  82 * @v: the visitor
  83 * @errp: if an error occurs, a pointer to an area to store the error
  84 *
  85 * Create an instance of the user creatable object @type, placing
  86 * it in the object composition tree with name @id, initializing
  87 * it with properties from @qdict
  88 *
  89 * Returns: the newly created object or NULL on error
  90 */
  91Object *user_creatable_add_type(const char *type, const char *id,
  92                                const QDict *qdict,
  93                                Visitor *v, Error **errp);
  94
  95/**
  96 * user_creatable_add_opts:
  97 * @opts: the object definition
  98 * @errp: if an error occurs, a pointer to an area to store the error
  99 *
 100 * Create an instance of the user creatable object whose type
 101 * is defined in @opts by the 'qom-type' option, placing it
 102 * in the object composition tree with name provided by the
 103 * 'id' field. The remaining options in @opts are used to
 104 * initialize the object properties.
 105 *
 106 * Returns: the newly created object or NULL on error
 107 */
 108Object *user_creatable_add_opts(QemuOpts *opts, Error **errp);
 109
 110
 111/**
 112 * user_creatable_add_opts_predicate:
 113 * @type: the QOM type to be added
 114 *
 115 * A callback function to determine whether an object
 116 * of type @type should be created. Instances of this
 117 * callback should be passed to user_creatable_add_opts_foreach
 118 */
 119typedef bool (*user_creatable_add_opts_predicate)(const char *type);
 120
 121/**
 122 * user_creatable_add_opts_foreach:
 123 * @opaque: a user_creatable_add_opts_predicate callback or NULL
 124 * @opts: options to create
 125 * @errp: unused
 126 *
 127 * An iterator callback to be used in conjunction with
 128 * the qemu_opts_foreach() method for creating a list of
 129 * objects from a set of QemuOpts
 130 *
 131 * The @opaque parameter can be passed a user_creatable_add_opts_predicate
 132 * callback to filter which types of object are created during iteration.
 133 * When it fails, report the error.
 134 *
 135 * Returns: 0 on success, -1 when an error was reported.
 136 */
 137int user_creatable_add_opts_foreach(void *opaque,
 138                                    QemuOpts *opts, Error **errp);
 139
 140/**
 141 * user_creatable_del:
 142 * @id: the unique ID for the object
 143 * @errp: if an error occurs, a pointer to an area to store the error
 144 *
 145 * Delete an instance of the user creatable object identified
 146 * by @id.
 147 */
 148void user_creatable_del(const char *id, Error **errp);
 149
 150/**
 151 * user_creatable_cleanup:
 152 *
 153 * Delete all user-creatable objects and the user-creatable
 154 * objects container.
 155 */
 156void user_creatable_cleanup(void);
 157
 158#endif
 159