qemu/include/qom/object_interfaces.h
Paolo Bonzini bc2f4fcb1d qom: move user_creatable_add_opts logic to vl.c and QAPIfy it
Emulators are currently using OptsVisitor (via user_creatable_add_opts)
to parse the -object command line option.  This has one extra feature,
compared to keyval, which is automatic conversion of integers to lists
as well as support for lists as repeated options:

  -object memory-backend-ram,id=pc.ram,size=1048576000,host-nodes=0,policy=bind

So we cannot replace OptsVisitor with keyval right now.  Still, this
patch moves the user_creatable_add_opts logic to vl.c since it is
not needed anywhere else, and makes it go through user_creatable_add_qapi.

In order to minimize code changes, the predicate still takes a string.
This can be changed later to use the ObjectType QAPI enum directly.

Reviewed-by: Eric Blake <eblake@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Message-Id: <20210312173547.1283477-3-pbonzini@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Kevin Wolf <kwolf@redhat.com>
2021-03-19 10:18:17 +01:00

181 lines
5.9 KiB
C

#ifndef OBJECT_INTERFACES_H
#define OBJECT_INTERFACES_H
#include "qom/object.h"
#include "qapi/qapi-types-qom.h"
#include "qapi/visitor.h"
#define TYPE_USER_CREATABLE "user-creatable"
typedef struct UserCreatableClass UserCreatableClass;
DECLARE_CLASS_CHECKERS(UserCreatableClass, USER_CREATABLE,
TYPE_USER_CREATABLE)
#define USER_CREATABLE(obj) \
INTERFACE_CHECK(UserCreatable, (obj), \
TYPE_USER_CREATABLE)
typedef struct UserCreatable UserCreatable;
/**
* UserCreatableClass:
* @parent_class: the base class
* @complete: callback to be called after @obj's properties are set.
* @can_be_deleted: callback to be called before an object is removed
* to check if @obj can be removed safely.
*
* Interface is designed to work with -object/object-add/object_add
* commands.
* Interface is mandatory for objects that are designed to be user
* creatable (i.e. -object/object-add/object_add, will accept only
* objects that inherit this interface).
*
* Interface also provides an optional ability to do the second
* stage * initialization of the object after its properties were
* set.
*
* For objects created without using -object/object-add/object_add,
* @user_creatable_complete() wrapper should be called manually if
* object's type implements USER_CREATABLE interface and needs
* complete() callback to be called.
*/
struct UserCreatableClass {
/* <private> */
InterfaceClass parent_class;
/* <public> */
void (*complete)(UserCreatable *uc, Error **errp);
bool (*can_be_deleted)(UserCreatable *uc);
};
/**
* user_creatable_complete:
* @uc: the user-creatable object whose complete() method is called if defined
* @errp: if an error occurs, a pointer to an area to store the error
*
* Wrapper to call complete() method if one of types it's inherited
* from implements USER_CREATABLE interface, otherwise the call does
* nothing.
*
* Returns: %true on success, %false on failure.
*/
bool user_creatable_complete(UserCreatable *uc, Error **errp);
/**
* user_creatable_can_be_deleted:
* @uc: the object whose can_be_deleted() method is called if implemented
*
* Wrapper to call can_be_deleted() method if one of types it's inherited
* from implements USER_CREATABLE interface.
*/
bool user_creatable_can_be_deleted(UserCreatable *uc);
/**
* user_creatable_add_type:
* @type: the object type name
* @id: the unique ID for the object
* @qdict: the object properties
* @v: the visitor
* @errp: if an error occurs, a pointer to an area to store the error
*
* Create an instance of the user creatable object @type, placing
* it in the object composition tree with name @id, initializing
* it with properties from @qdict
*
* Returns: the newly created object or NULL on error
*/
Object *user_creatable_add_type(const char *type, const char *id,
const QDict *qdict,
Visitor *v, Error **errp);
/**
* user_creatable_add_qapi:
* @options: the object definition
* @errp: if an error occurs, a pointer to an area to store the error
*
* Create an instance of the user creatable object according to the
* options passed in @opts as described in the QAPI schema documentation.
*/
void user_creatable_add_qapi(ObjectOptions *options, Error **errp);
/**
* user_creatable_parse_str:
* @optarg: the object definition string as passed on the command line
* @errp: if an error occurs, a pointer to an area to store the error
*
* Parses the option for the user creatable object with a keyval parser and
* implicit key 'qom-type', converting the result to ObjectOptions.
*
* If a help option is given, print help instead.
*
* Returns: ObjectOptions on success, NULL when an error occurred (*errp is set
* then) or help was printed (*errp is not set).
*/
ObjectOptions *user_creatable_parse_str(const char *optarg, Error **errp);
/**
* user_creatable_add_from_str:
* @optarg: the object definition string as passed on the command line
* @errp: if an error occurs, a pointer to an area to store the error
*
* Create an instance of the user creatable object by parsing optarg
* with a keyval parser and implicit key 'qom-type', converting the
* result to ObjectOptions and calling into qmp_object_add().
*
* If a help option is given, print help instead.
*
* Returns: true when an object was successfully created, false when an error
* occurred (*errp is set then) or help was printed (*errp is not set).
*/
bool user_creatable_add_from_str(const char *optarg, Error **errp);
/**
* user_creatable_process_cmdline:
* @optarg: the object definition string as passed on the command line
*
* Create an instance of the user creatable object by parsing optarg
* with a keyval parser and implicit key 'qom-type', converting the
* result to ObjectOptions and calling into qmp_object_add().
*
* If a help option is given, print help instead and exit.
*
* This function is only meant to be called during command line parsing.
* It exits the process on failure or after printing help.
*/
void user_creatable_process_cmdline(const char *optarg);
/**
* user_creatable_print_help:
* @type: the QOM type to be added
* @opts: options to create
*
* Prints help if requested in @type or @opts. Note that if @type is neither
* "help"/"?" nor a valid user creatable type, no help will be printed
* regardless of @opts.
*
* Returns: true if a help option was found and help was printed, false
* otherwise.
*/
bool user_creatable_print_help(const char *type, QemuOpts *opts);
/**
* user_creatable_del:
* @id: the unique ID for the object
* @errp: if an error occurs, a pointer to an area to store the error
*
* Delete an instance of the user creatable object identified
* by @id.
*
* Returns: %true on success, %false on failure.
*/
bool user_creatable_del(const char *id, Error **errp);
/**
* user_creatable_cleanup:
*
* Delete all user-creatable objects and the user-creatable
* objects container.
*/
void user_creatable_cleanup(void);
#endif