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 typedef 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  */
43 typedef 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  */
61 void 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_dict:
92  * @qdict: the object definition
93  * @keyval: if true, use a keyval visitor for processing @qdict (i.e.
94  *          assume that all @qdict values are strings); otherwise, use
95  *          the normal QObject visitor (i.e. assume all @qdict values
96  *          have the QType expected by the QOM object type)
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 that is defined by
100  * @qdict.  The object type is taken from the QDict key 'qom-type', its
101  * ID from the key 'id'. The remaining entries in @qdict are used to
102  * initialize the object properties.
103  */
104 void user_creatable_add_dict(QDict *qdict, bool keyval, Error **errp);
105 
106 /**
107  * user_creatable_add_opts:
108  * @opts: the object definition
109  * @errp: if an error occurs, a pointer to an area to store the error
110  *
111  * Create an instance of the user creatable object whose type
112  * is defined in @opts by the 'qom-type' option, placing it
113  * in the object composition tree with name provided by the
114  * 'id' field. The remaining options in @opts are used to
115  * initialize the object properties.
116  *
117  * Returns: the newly created object or NULL on error
118  */
119 Object *user_creatable_add_opts(QemuOpts *opts, Error **errp);
120 
121 
122 /**
123  * user_creatable_add_opts_predicate:
124  * @type: the QOM type to be added
125  *
126  * A callback function to determine whether an object
127  * of type @type should be created. Instances of this
128  * callback should be passed to user_creatable_add_opts_foreach
129  */
130 typedef bool (*user_creatable_add_opts_predicate)(const char *type);
131 
132 /**
133  * user_creatable_add_opts_foreach:
134  * @opaque: a user_creatable_add_opts_predicate callback or NULL
135  * @opts: options to create
136  * @errp: unused
137  *
138  * An iterator callback to be used in conjunction with
139  * the qemu_opts_foreach() method for creating a list of
140  * objects from a set of QemuOpts
141  *
142  * The @opaque parameter can be passed a user_creatable_add_opts_predicate
143  * callback to filter which types of object are created during iteration.
144  * When it fails, report the error.
145  *
146  * Returns: 0 on success, -1 when an error was reported.
147  */
148 int user_creatable_add_opts_foreach(void *opaque,
149                                     QemuOpts *opts, Error **errp);
150 
151 /**
152  * user_creatable_print_help:
153  * @type: the QOM type to be added
154  * @opts: options to create
155  *
156  * Prints help if requested in @opts.
157  *
158  * Returns: true if @opts contained a help option and help was printed, false
159  * if no help option was found.
160  */
161 bool user_creatable_print_help(const char *type, QemuOpts *opts);
162 
163 /**
164  * user_creatable_del:
165  * @id: the unique ID for the object
166  * @errp: if an error occurs, a pointer to an area to store the error
167  *
168  * Delete an instance of the user creatable object identified
169  * by @id.
170  */
171 void user_creatable_del(const char *id, Error **errp);
172 
173 /**
174  * user_creatable_cleanup:
175  *
176  * Delete all user-creatable objects and the user-creatable
177  * objects container.
178  */
179 void user_creatable_cleanup(void);
180 
181 /**
182  * qmp_object_add:
183  *
184  * QMP command handler for object-add. See the QAPI schema for documentation.
185  */
186 void qmp_object_add(QDict *qdict, QObject **ret_data, Error **errp);
187 
188 #endif
189