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