@samitouri / QOSamiQemu
Code Commits Issues Pulls Sessions CI/CD
master
master
h 170 lines 5.71 KB
Raw
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 * @prepare_delete: to be called before an attempt to delete @obj
24 * to validate whether the object can be deleted and trigger any
25 * cleanup of any resources which have to be dealt with before the
26 * object is unparented and enters finalization.
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. Similarly @user_creatable_prepare_delete()
42 * should be called manually prior to an attempt to the delete the
43 * object.
44 */
45 struct UserCreatableClass {
46 /* <private> */
47 InterfaceClass parent_class;
48
49 /* <public> */
50 void (*complete)(UserCreatable *uc, Error **errp);
51 bool (*prepare_delete)(UserCreatable *uc, Error **errp);
52 };
53
54 /**
55 * user_creatable_complete:
56 * @uc: the user-creatable object whose complete() method is called if defined
57 * @errp: if an error occurs, a pointer to an area to store the error
58 *
59 * Wrapper to call complete() method if one of types it's inherited
60 * from implements USER_CREATABLE interface, otherwise the call does
61 * nothing.
62 *
63 * Returns: %true on success, %false on failure.
64 */
65 bool user_creatable_complete(UserCreatable *uc, Error **errp);
66
67 /**
68 * user_creatable_prepare_delete:
69 * @uc: the user-creatable object whose prepare_delete() method is called
70 * @errp: if an error occurs, a pointer to an area to store the error
71 *
72 * Wrapper to call prepare_delete() class method if defined, otherwise
73 * does nothing.
74 *
75 * Returns: %true on success or if prepare_delete() is not defined,
76 * %false on failure.
77 */
78 bool user_creatable_prepare_delete(UserCreatable *uc, Error **errp);
79
80 /**
81 * user_creatable_add_qapi:
82 * @options: the object definition
83 * @errp: if an error occurs, a pointer to an area to store the error
84 *
85 * Create an instance of the user creatable object according to the
86 * options passed in @opts as described in the QAPI schema documentation.
87 */
88 void user_creatable_add_qapi(ObjectOptions *options, Error **errp);
89
90 /**
91 * user_creatable_parse_str:
92 * @str: the object definition string as passed on the command line
93 * @errp: if an error occurs, a pointer to an area to store the error
94 *
95 * Parses the option for the user creatable object with a keyval parser and
96 * implicit key 'qom-type', converting the result to ObjectOptions.
97 *
98 * If a help option is given, print help instead.
99 *
100 * Returns: ObjectOptions on success, NULL when an error occurred (*errp is set
101 * then) or help was printed (*errp is not set).
102 */
103 ObjectOptions *user_creatable_parse_str(const char *str, Error **errp);
104
105 /**
106 * user_creatable_add_from_str:
107 * @str: the object definition string as passed on the command line
108 * @errp: if an error occurs, a pointer to an area to store the error
109 *
110 * Create an instance of the user creatable object by parsing @str
111 * with a keyval parser and implicit key 'qom-type', converting the
112 * result to ObjectOptions and calling into qmp_object_add().
113 *
114 * If a help option is given, print help instead.
115 *
116 * Returns: true when an object was successfully created, false when an error
117 * occurred (*errp is set then) or help was printed (*errp is not set).
118 */
119 bool user_creatable_add_from_str(const char *str, Error **errp);
120
121 /**
122 * user_creatable_process_cmdline:
123 * @cmdline: the object definition string as passed on the command line
124 *
125 * Create an instance of the user creatable object by parsing @cmdline
126 * with a keyval parser and implicit key 'qom-type', converting the
127 * result to ObjectOptions and calling into qmp_object_add().
128 *
129 * If a help option is given, print help instead and exit.
130 *
131 * This function is only meant to be called during command line parsing.
132 * It exits the process on failure or after printing help.
133 */
134 void user_creatable_process_cmdline(const char *cmdline);
135
136 /**
137 * user_creatable_print_help:
138 * @type: the QOM type to be added
139 * @opts: options to create
140 *
141 * Prints help if requested in @type or @opts. Note that if @type is neither
142 * "help"/"?" nor a valid user creatable type, no help will be printed
143 * regardless of @opts.
144 *
145 * Returns: true if a help option was found and help was printed, false
146 * otherwise.
147 */
148 bool user_creatable_print_help(const char *type, QemuOpts *opts);
149
150 /**
151 * user_creatable_del:
152 * @id: the unique ID for the object
153 * @errp: if an error occurs, a pointer to an area to store the error
154 *
155 * Delete an instance of the user creatable object identified
156 * by @id.
157 *
158 * Returns: %true on success, %false on failure.
159 */
160 bool user_creatable_del(const char *id, Error **errp);
161
162 /**
163 * user_creatable_cleanup:
164 *
165 * Delete all user-creatable objects and the user-creatable
166 * objects container.
167 */
168 void user_creatable_cleanup(void);
169
170 #endif