aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorLuiz Capitulino <lcapitulino@redhat.com>2012-08-06 11:35:22 -0300
committerLuiz Capitulino <lcapitulino@redhat.com>2012-08-13 14:17:53 -0300
commitadb2072ed0fd595b05f6571e985b271a3cfa872d (patch)
tree30dd5e41dc2e813dd19fff2c4b5898f3e3749086 /docs
parent6d3f0dbb304d59759b2faf1e50db94d996f51f8a (diff)
downloadqemu-adb2072ed0fd595b05f6571e985b271a3cfa872d.zip
qemu-adb2072ed0fd595b05f6571e985b271a3cfa872d.tar.gz
qemu-adb2072ed0fd595b05f6571e985b271a3cfa872d.tar.bz2
docs: writing-qmp-commands.txt: update error section
Add information about the new error format and improve the text a bit. Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com>
Diffstat (limited to 'docs')
-rw-r--r--docs/writing-qmp-commands.txt47
1 files changed, 27 insertions, 20 deletions
diff --git a/docs/writing-qmp-commands.txt b/docs/writing-qmp-commands.txt
index 0ad51aa..8349dec 100644
--- a/docs/writing-qmp-commands.txt
+++ b/docs/writing-qmp-commands.txt
@@ -210,19 +210,17 @@ if you don't see these strings, then something went wrong.
=== Errors ===
QMP commands should use the error interface exported by the error.h header
-file. The basic function used to set an error is the error_set() one.
+file. Basically, errors are set by calling the error_set() function.
Let's say we don't accept the string "message" to contain the word "love". If
-it does contain it, we want the "hello-world" command to the return the
-InvalidParameter error.
-
-Only one change is required, and it's in the C implementation:
+it does contain it, we want the "hello-world" command to return an error:
void qmp_hello_world(bool has_message, const char *message, Error **errp)
{
if (has_message) {
if (strstr(message, "love")) {
- error_set(errp, QERR_INVALID_PARAMETER, "message");
+ error_set(errp, ERROR_CLASS_GENERIC_ERROR,
+ "the word 'love' is not allowed");
return;
}
printf("%s\n", message);
@@ -231,30 +229,40 @@ void qmp_hello_world(bool has_message, const char *message, Error **errp)
}
}
-Let's test it. Build qemu, run it as defined in the "Testing" section, and
-then issue the following command:
+The first argument to the error_set() function is the Error pointer to pointer,
+which is passed to all QMP functions. The second argument is a ErrorClass
+value, which should be ERROR_CLASS_GENERIC_ERROR most of the time (more
+details about error classes are given below). The third argument is a human
+description of the error, this is a free-form printf-like string.
+
+Let's test the example above. Build qemu, run it as defined in the "Testing"
+section, and then issue the following command:
-{ "execute": "hello-world", "arguments": { "message": "we love qemu" } }
+{ "execute": "hello-world", "arguments": { "message": "all you need is love" } }
The QMP server's response should be:
{
"error": {
- "class": "InvalidParameter",
- "desc": "Invalid parameter 'message'",
- "data": {
- "name": "message"
- }
+ "class": "GenericError",
+ "desc": "the word 'love' is not allowed"
}
}
-Which is the InvalidParameter error.
+As a general rule, all QMP errors should use ERROR_CLASS_GENERIC_ERROR. There
+are two exceptions to this rule:
+
+ 1. A non-generic ErrorClass value exists* for the failure you want to report
+ (eg. DeviceNotFound)
+
+ 2. Management applications have to take special action on the failure you
+ want to report, hence you have to add a new ErrorClass value so that they
+ can check for it
-When you have to return an error but you're unsure what error to return or
-which arguments an error takes, you should look at the qerror.h file. Note
-that you might be required to add new errors if needed.
+If the failure you want to report doesn't fall in one of the two cases above,
+just report ERROR_CLASS_GENERIC_ERROR.
-FIXME: describe better the error API and how to add new errors.
+ * All existing ErrorClass values are defined in the qapi-schema.json file
=== Command Documentation ===
@@ -275,7 +283,6 @@ here goes "hello-world"'s new entry for the qapi-schema.json file:
# @message: #optional string to be printed
#
# Returns: Nothing on success.
-# If @message contains "love", InvalidParameter
#
# Notes: if @message is not provided, the "Hello, world" string will
# be printed instead