blob: 682ba1d9b06eea29edbef8f6991750c33178d1c5 [file] [log] [blame]
Igor Mammedov269e09f2014-01-16 17:34:38 +01001#ifndef OBJECT_INTERFACES_H
2#define OBJECT_INTERFACES_H
3
4#include "qom/object.h"
Daniel P. Berrange90998d52016-02-10 18:40:59 +00005#include "qapi/visitor.h"
Igor Mammedov269e09f2014-01-16 17:34:38 +01006
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
Marc-André Lureauaa1b35b2018-12-04 18:20:06 +040019typedef struct UserCreatable UserCreatable;
Igor Mammedov269e09f2014-01-16 17:34:38 +010020
21/**
22 * UserCreatableClass:
23 * @parent_class: the base class
24 * @complete: callback to be called after @obj's properties are set.
Lin Mad6edb152015-03-30 16:36:28 +080025 * @can_be_deleted: callback to be called before an object is removed
26 * to check if @obj can be removed safely.
Igor Mammedov269e09f2014-01-16 17:34:38 +010027 *
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 */
43typedef struct UserCreatableClass {
44 /* <private> */
45 InterfaceClass parent_class;
46
47 /* <public> */
48 void (*complete)(UserCreatable *uc, Error **errp);
Eduardo Habkost3beacfb2017-08-29 19:03:37 -030049 bool (*can_be_deleted)(UserCreatable *uc);
Igor Mammedov269e09f2014-01-16 17:34:38 +010050} UserCreatableClass;
51
52/**
53 * user_creatable_complete:
Marc-André Lureau3650b2d2018-12-04 18:20:07 +040054 * @uc: the user-creatable object whose complete() method is called if defined
Igor Mammedov269e09f2014-01-16 17:34:38 +010055 * @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 */
Marc-André Lureau3650b2d2018-12-04 18:20:07 +040061void user_creatable_complete(UserCreatable *uc, Error **errp);
Lin Mad6edb152015-03-30 16:36:28 +080062
63/**
64 * user_creatable_can_be_deleted:
65 * @uc: the object whose can_be_deleted() method is called if implemented
Lin Mad6edb152015-03-30 16:36:28 +080066 *
67 * Wrapper to call can_be_deleted() method if one of types it's inherited
68 * from implements USER_CREATABLE interface.
69 */
Eduardo Habkost3beacfb2017-08-29 19:03:37 -030070bool user_creatable_can_be_deleted(UserCreatable *uc);
Daniel P. Berrange90998d52016-02-10 18:40:59 +000071
72/**
Daniel P. Berrange90998d52016-02-10 18:40:59 +000073 * 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 */
86Object *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_opts:
92 * @opts: 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 whose type
96 * is defined in @opts by the 'qom-type' option, placing it
97 * in the object composition tree with name provided by the
98 * 'id' field. The remaining options in @opts are used to
99 * initialize the object properties.
100 *
101 * Returns: the newly created object or NULL on error
102 */
103Object *user_creatable_add_opts(QemuOpts *opts, Error **errp);
104
105
106/**
107 * user_creatable_add_opts_predicate:
108 * @type: the QOM type to be added
109 *
110 * A callback function to determine whether an object
111 * of type @type should be created. Instances of this
112 * callback should be passed to user_creatable_add_opts_foreach
113 */
114typedef bool (*user_creatable_add_opts_predicate)(const char *type);
115
116/**
117 * user_creatable_add_opts_foreach:
118 * @opaque: a user_creatable_add_opts_predicate callback or NULL
119 * @opts: options to create
Markus Armbruster51b9b472016-04-27 16:29:09 +0200120 * @errp: unused
Daniel P. Berrange90998d52016-02-10 18:40:59 +0000121 *
122 * An iterator callback to be used in conjunction with
123 * the qemu_opts_foreach() method for creating a list of
124 * objects from a set of QemuOpts
125 *
126 * The @opaque parameter can be passed a user_creatable_add_opts_predicate
127 * callback to filter which types of object are created during iteration.
Markus Armbruster51b9b472016-04-27 16:29:09 +0200128 * When it fails, report the error.
Daniel P. Berrange90998d52016-02-10 18:40:59 +0000129 *
Markus Armbruster51b9b472016-04-27 16:29:09 +0200130 * Returns: 0 on success, -1 when an error was reported.
Daniel P. Berrange90998d52016-02-10 18:40:59 +0000131 */
132int user_creatable_add_opts_foreach(void *opaque,
133 QemuOpts *opts, Error **errp);
134
135/**
136 * user_creatable_del:
137 * @id: the unique ID for the object
138 * @errp: if an error occurs, a pointer to an area to store the error
139 *
140 * Delete an instance of the user creatable object identified
141 * by @id.
142 */
143void user_creatable_del(const char *id, Error **errp);
144
Eduardo Habkost9d5139e2017-08-24 16:23:13 -0300145/**
146 * user_creatable_cleanup:
147 *
148 * Delete all user-creatable objects and the user-creatable
149 * objects container.
150 */
151void user_creatable_cleanup(void);
152
Igor Mammedov269e09f2014-01-16 17:34:38 +0100153#endif