1 #ifndef OBJECT_INTERFACES_H
2 #define OBJECT_INTERFACES_H
3 
4 #include "qom/object.h"
5 #include "qapi/qapi-types-qom.h"
6 #include "qapi/visitor.h"
7 
8 #define TYPE_USER_CREATABLE "user-creatable"
9 
10 typedef struct UserCreatableClass UserCreatableClass;
11 DECLARE_CLASS_CHECKERS(UserCreatableClass, USER_CREATABLE,
12                        TYPE_USER_CREATABLE)
13 #define USER_CREATABLE(obj) \
14      INTERFACE_CHECK(UserCreatable, (obj), \
15                      TYPE_USER_CREATABLE)
16 
17 typedef struct UserCreatable UserCreatable;
18 
19 /**
20  * UserCreatableClass:
21  * @parent_class: the base class
22  * @complete: callback to be called after @obj's properties are set.
23  * @can_be_deleted: callback to be called before an object is removed
24  * to check if @obj can be removed safely.
25  *
26  * Interface is designed to work with -object/object-add/object_add
27  * commands.
28  * Interface is mandatory for objects that are designed to be user
29  * creatable (i.e. -object/object-add/object_add, will accept only
30  * objects that inherit this interface).
31  *
32  * Interface also provides an optional ability to do the second
33  * stage * initialization of the object after its properties were
34  * set.
35  *
36  * For objects created without using -object/object-add/object_add,
37  * @user_creatable_complete() wrapper should be called manually if
38  * object's type implements USER_CREATABLE interface and needs
39  * complete() callback to be called.
40  */
41 struct UserCreatableClass {
42     /* <private> */
43     InterfaceClass parent_class;
44 
45     /* <public> */
46     void (*complete)(UserCreatable *uc, Error **errp);
47     bool (*can_be_deleted)(UserCreatable *uc);
48 };
49 
50 /**
51  * user_creatable_complete:
52  * @uc: the user-creatable object whose complete() method is called if defined
53  * @errp: if an error occurs, a pointer to an area to store the error
54  *
55  * Wrapper to call complete() method if one of types it's inherited
56  * from implements USER_CREATABLE interface, otherwise the call does
57  * nothing.
58  *
59  * Returns: %true on success, %false on failure.
60  */
61 bool 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_qapi:
92  * @options: the object definition
93  * @errp: if an error occurs, a pointer to an area to store the error
94  *
95  * Create an instance of the user creatable object according to the
96  * options passed in @opts as described in the QAPI schema documentation.
97  *
98  * Returns: the newly created object or NULL on error
99  */
100 void user_creatable_add_qapi(ObjectOptions *options, Error **errp);
101 
102 /**
103  * user_creatable_add_opts:
104  * @opts: the object definition
105  * @errp: if an error occurs, a pointer to an area to store the error
106  *
107  * Create an instance of the user creatable object whose type
108  * is defined in @opts by the 'qom-type' option, placing it
109  * in the object composition tree with name provided by the
110  * 'id' field. The remaining options in @opts are used to
111  * initialize the object properties.
112  *
113  * Returns: the newly created object or NULL on error
114  */
115 Object *user_creatable_add_opts(QemuOpts *opts, Error **errp);
116 
117 
118 /**
119  * user_creatable_add_opts_predicate:
120  * @type: the QOM type to be added
121  *
122  * A callback function to determine whether an object
123  * of type @type should be created. Instances of this
124  * callback should be passed to user_creatable_add_opts_foreach
125  */
126 typedef bool (*user_creatable_add_opts_predicate)(const char *type);
127 
128 /**
129  * user_creatable_add_opts_foreach:
130  * @opaque: a user_creatable_add_opts_predicate callback or NULL
131  * @opts: options to create
132  * @errp: unused
133  *
134  * An iterator callback to be used in conjunction with
135  * the qemu_opts_foreach() method for creating a list of
136  * objects from a set of QemuOpts
137  *
138  * The @opaque parameter can be passed a user_creatable_add_opts_predicate
139  * callback to filter which types of object are created during iteration.
140  * When it fails, report the error.
141  *
142  * Returns: 0 on success, -1 when an error was reported.
143  */
144 int user_creatable_add_opts_foreach(void *opaque,
145                                     QemuOpts *opts, Error **errp);
146 
147 /**
148  * user_creatable_process_cmdline:
149  * @optarg: the object definition string as passed on the command line
150  *
151  * Create an instance of the user creatable object by parsing optarg
152  * with a keyval parser and implicit key 'qom-type', converting the
153  * result to ObjectOptions and calling into qmp_object_add().
154  *
155  * If a help option is given, print help instead and exit.
156  *
157  * This function is only meant to be called during command line parsing.
158  * It exits the process on failure or after printing help.
159  */
160 void user_creatable_process_cmdline(const char *optarg);
161 
162 /**
163  * user_creatable_print_help:
164  * @type: the QOM type to be added
165  * @opts: options to create
166  *
167  * Prints help if requested in @type or @opts. Note that if @type is neither
168  * "help"/"?" nor a valid user creatable type, no help will be printed
169  * regardless of @opts.
170  *
171  * Returns: true if a help option was found and help was printed, false
172  * otherwise.
173  */
174 bool user_creatable_print_help(const char *type, QemuOpts *opts);
175 
176 /**
177  * user_creatable_del:
178  * @id: the unique ID for the object
179  * @errp: if an error occurs, a pointer to an area to store the error
180  *
181  * Delete an instance of the user creatable object identified
182  * by @id.
183  *
184  * Returns: %true on success, %false on failure.
185  */
186 bool user_creatable_del(const char *id, Error **errp);
187 
188 /**
189  * user_creatable_cleanup:
190  *
191  * Delete all user-creatable objects and the user-creatable
192  * objects container.
193  */
194 void user_creatable_cleanup(void);
195 
196 #endif
197