diff options
author | Markus Armbruster <armbru@redhat.com> | 2017-03-15 13:56:54 +0100 |
---|---|---|
committer | Markus Armbruster <armbru@redhat.com> | 2017-03-16 07:13:02 +0100 |
commit | 1554a8fae984cad4704fb94a8cef3c9b42ef6185 (patch) | |
tree | 78d963a98ad801e050bfbd0c6943bd4e9fc30c0c /docs | |
parent | 700dc9f503c61cdd1180e9bf84a225105b22b227 (diff) |
qapi: Have each QAPI schema declare its returns white-list
qapi.py has a hardcoded white-list of command names that may violate
the rules on permitted return types. Add a new pragma directive
'returns-whitelist', and use it to replace the hard-coded white-list.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <1489582656-31133-6-git-send-email-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Diffstat (limited to 'docs')
-rw-r--r-- | docs/qapi-code-gen.txt | 13 |
1 files changed, 7 insertions, 6 deletions
diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt index 5532b60d91..3d17005cf6 100644 --- a/docs/qapi-code-gen.txt +++ b/docs/qapi-code-gen.txt @@ -318,6 +318,9 @@ pragma to different values in parts of the schema doesn't work. Pragma 'doc-required' takes a boolean value. If true, documentation is required. Default is false. +Pragma 'returns-whitelist' takes a list of command names that may +violate the rules on permitted return types. Default is none. + === Struct types === @@ -566,12 +569,10 @@ The member is optional from the command declaration; if absent, the "return" member will be an empty dictionary. If 'returns' is present, it must be the string name of a complex or built-in type, a one-element array containing the name of a complex or built-in type. -Although it is permitted to have the 'returns' member name a built-in -type or an array of built-in types, any command that does this cannot -be extended to return additional information in the future; thus, new -commands should strongly consider returning a dictionary-based type or -an array of dictionaries, even if the dictionary only contains one -member at the present. +To return anything else, you have to list the command in pragma +'returns-whitelist'. If you do this, the command cannot be extended +to return additional information in the future. Use of +'returns-whitelist' for new commands is strongly discouraged. All commands in Client JSON Protocol use a dictionary to report failure, with no way to specify that in QAPI. Where the error return |