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 typedef struct UserCreatableClass UserCreatableClass;
10 DECLARE_CLASS_CHECKERS(UserCreatableClass, USER_CREATABLE,
11                        TYPE_USER_CREATABLE)
12 #define USER_CREATABLE(obj) \
13      INTERFACE_CHECK(UserCreatable, (obj), \
14                      TYPE_USER_CREATABLE)
15 
16 typedef struct UserCreatable UserCreatable;
17 
18 /**
19  * UserCreatableClass:
20  * @parent_class: the base class
21  * @complete: callback to be called after @obj's properties are set.
22  * @can_be_deleted: callback to be called before an object is removed
23  * to check if @obj can be removed safely.
24  *
25  * Interface is designed to work with -object/object-add/object_add
26  * commands.
27  * Interface is mandatory for objects that are designed to be user
28  * creatable (i.e. -object/object-add/object_add, will accept only
29  * objects that inherit this interface).
30  *
31  * Interface also provides an optional ability to do the second
32  * stage * initialization of the object after its properties were
33  * set.
34  *
35  * For objects created without using -object/object-add/object_add,
36  * @user_creatable_complete() wrapper should be called manually if
37  * object's type implements USER_CREATABLE interface and needs
38  * complete() callback to be called.
39  */
40 struct UserCreatableClass {
41     /* <private> */
42     InterfaceClass parent_class;
43 
44     /* <public> */
45     void (*complete)(UserCreatable *uc, Error **errp);
46     bool (*can_be_deleted)(UserCreatable *uc);
47 };
48 
49 /**
50  * user_creatable_complete:
51  * @uc: the user-creatable object whose complete() method is called if defined
52  * @errp: if an error occurs, a pointer to an area to store the error
53  *
54  * Wrapper to call complete() method if one of types it's inherited
55  * from implements USER_CREATABLE interface, otherwise the call does
56  * nothing.
57  *
58  * Returns: %true on success, %false on failure.
59  */
60 bool user_creatable_complete(UserCreatable *uc, Error **errp);
61 
62 /**
63  * user_creatable_can_be_deleted:
64  * @uc: the object whose can_be_deleted() method is called if implemented
65  *
66  * Wrapper to call can_be_deleted() method if one of types it's inherited
67  * from implements USER_CREATABLE interface.
68  */
69 bool user_creatable_can_be_deleted(UserCreatable *uc);
70 
71 /**
72  * user_creatable_add_type:
73  * @type: the object type name
74  * @id: the unique ID for the object
75  * @qdict: the object properties
76  * @v: the visitor
77  * @errp: if an error occurs, a pointer to an area to store the error
78  *
79  * Create an instance of the user creatable object @type, placing
80  * it in the object composition tree with name @id, initializing
81  * it with properties from @qdict
82  *
83  * Returns: the newly created object or NULL on error
84  */
85 Object *user_creatable_add_type(const char *type, const char *id,
86                                 const QDict *qdict,
87                                 Visitor *v, Error **errp);
88 
89 /**
90  * user_creatable_add_dict:
91  * @qdict: the object definition
92  * @keyval: if true, use a keyval visitor for processing @qdict (i.e.
93  *          assume that all @qdict values are strings); otherwise, use
94  *          the normal QObject visitor (i.e. assume all @qdict values
95  *          have the QType expected by the QOM object type)
96  * @errp: if an error occurs, a pointer to an area to store the error
97  *
98  * Create an instance of the user creatable object that is defined by
99  * @qdict.  The object type is taken from the QDict key 'qom-type', its
100  * ID from the key 'id'. The remaining entries in @qdict are used to
101  * initialize the object properties.
102  *
103  * Returns: %true on success, %false on failure.
104  */
105 bool user_creatable_add_dict(QDict *qdict, bool keyval, Error **errp);
106 
107 /**
108  * user_creatable_add_opts:
109  * @opts: the object definition
110  * @errp: if an error occurs, a pointer to an area to store the error
111  *
112  * Create an instance of the user creatable object whose type
113  * is defined in @opts by the 'qom-type' option, placing it
114  * in the object composition tree with name provided by the
115  * 'id' field. The remaining options in @opts are used to
116  * initialize the object properties.
117  *
118  * Returns: the newly created object or NULL on error
119  */
120 Object *user_creatable_add_opts(QemuOpts *opts, Error **errp);
121 
122 
123 /**
124  * user_creatable_add_opts_predicate:
125  * @type: the QOM type to be added
126  *
127  * A callback function to determine whether an object
128  * of type @type should be created. Instances of this
129  * callback should be passed to user_creatable_add_opts_foreach
130  */
131 typedef bool (*user_creatable_add_opts_predicate)(const char *type);
132 
133 /**
134  * user_creatable_add_opts_foreach:
135  * @opaque: a user_creatable_add_opts_predicate callback or NULL
136  * @opts: options to create
137  * @errp: unused
138  *
139  * An iterator callback to be used in conjunction with
140  * the qemu_opts_foreach() method for creating a list of
141  * objects from a set of QemuOpts
142  *
143  * The @opaque parameter can be passed a user_creatable_add_opts_predicate
144  * callback to filter which types of object are created during iteration.
145  * When it fails, report the error.
146  *
147  * Returns: 0 on success, -1 when an error was reported.
148  */
149 int user_creatable_add_opts_foreach(void *opaque,
150                                     QemuOpts *opts, Error **errp);
151 
152 /**
153  * user_creatable_print_help:
154  * @type: the QOM type to be added
155  * @opts: options to create
156  *
157  * Prints help if requested in @type or @opts. Note that if @type is neither
158  * "help"/"?" nor a valid user creatable type, no help will be printed
159  * regardless of @opts.
160  *
161  * Returns: true if a help option was found and help was printed, false
162  * otherwise.
163  */
164 bool user_creatable_print_help(const char *type, QemuOpts *opts);
165 
166 /**
167  * user_creatable_print_help_from_qdict:
168  * @args: options to create
169  *
170  * Prints help considering the other options given in @args (if "qom-type" is
171  * given and valid, print properties for the type, otherwise print valid types)
172  *
173  * In contrast to user_creatable_print_help(), this function can't return that
174  * no help was requested. It should only be called if we know that help is
175  * requested and it will always print some help.
176  */
177 void user_creatable_print_help_from_qdict(QDict *args);
178 
179 /**
180  * user_creatable_del:
181  * @id: the unique ID for the object
182  * @errp: if an error occurs, a pointer to an area to store the error
183  *
184  * Delete an instance of the user creatable object identified
185  * by @id.
186  *
187  * Returns: %true on success, %false on failure.
188  */
189 bool user_creatable_del(const char *id, Error **errp);
190 
191 /**
192  * user_creatable_cleanup:
193  *
194  * Delete all user-creatable objects and the user-creatable
195  * objects container.
196  */
197 void user_creatable_cleanup(void);
198 
199 /**
200  * qmp_object_add:
201  *
202  * QMP command handler for object-add. See the QAPI schema for documentation.
203  */
204 void qmp_object_add(QDict *qdict, QObject **ret_data, Error **errp);
205 
206 #endif
207