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 
21 typedef 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  */
48 typedef 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, Error **errp);
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  */
66 void 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  * @errp: if an error occurs, a pointer to an area to store the error
72  *
73  * Wrapper to call can_be_deleted() method if one of types it's inherited
74  * from implements USER_CREATABLE interface.
75  */
76 bool user_creatable_can_be_deleted(UserCreatable *uc, Error **errp);
77 
78 /**
79  * user_creatable_add:
80  * @qdict: the object definition
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 whose type
85  * is defined in @qdict by the 'qom-type' field, placing it
86  * in the object composition tree with name provided by the
87  * 'id' field. The remaining fields in @qdict are used to
88  * initialize the object properties.
89  *
90  * Returns: the newly created object or NULL on error
91  */
92 Object *user_creatable_add(const QDict *qdict,
93                            Visitor *v, Error **errp);
94 
95 /**
96  * user_creatable_add_type:
97  * @type: the object type name
98  * @id: the unique ID for the object
99  * @qdict: the object properties
100  * @v: the visitor
101  * @errp: if an error occurs, a pointer to an area to store the error
102  *
103  * Create an instance of the user creatable object @type, placing
104  * it in the object composition tree with name @id, initializing
105  * it with properties from @qdict
106  *
107  * Returns: the newly created object or NULL on error
108  */
109 Object *user_creatable_add_type(const char *type, const char *id,
110                                 const QDict *qdict,
111                                 Visitor *v, Error **errp);
112 
113 /**
114  * user_creatable_add_opts:
115  * @opts: the object definition
116  * @errp: if an error occurs, a pointer to an area to store the error
117  *
118  * Create an instance of the user creatable object whose type
119  * is defined in @opts by the 'qom-type' option, placing it
120  * in the object composition tree with name provided by the
121  * 'id' field. The remaining options in @opts are used to
122  * initialize the object properties.
123  *
124  * Returns: the newly created object or NULL on error
125  */
126 Object *user_creatable_add_opts(QemuOpts *opts, Error **errp);
127 
128 
129 /**
130  * user_creatable_add_opts_predicate:
131  * @type: the QOM type to be added
132  *
133  * A callback function to determine whether an object
134  * of type @type should be created. Instances of this
135  * callback should be passed to user_creatable_add_opts_foreach
136  */
137 typedef bool (*user_creatable_add_opts_predicate)(const char *type);
138 
139 /**
140  * user_creatable_add_opts_foreach:
141  * @opaque: a user_creatable_add_opts_predicate callback or NULL
142  * @opts: options to create
143  * @errp: if an error occurs, a pointer to an area to store the error
144  *
145  * An iterator callback to be used in conjunction with
146  * the qemu_opts_foreach() method for creating a list of
147  * objects from a set of QemuOpts
148  *
149  * The @opaque parameter can be passed a user_creatable_add_opts_predicate
150  * callback to filter which types of object are created during iteration.
151  *
152  * Returns: 0 on success, -1 on error
153  */
154 int user_creatable_add_opts_foreach(void *opaque,
155                                     QemuOpts *opts, Error **errp);
156 
157 /**
158  * user_creatable_del:
159  * @id: the unique ID for the object
160  * @errp: if an error occurs, a pointer to an area to store the error
161  *
162  * Delete an instance of the user creatable object identified
163  * by @id.
164  */
165 void user_creatable_del(const char *id, Error **errp);
166 
167 #endif
168