Patchwork [35/35] docs: writing-qmp-commands.txt: update error section

login
register
mail settings
Submitter Luiz Capitulino
Date Aug. 7, 2012, 3:53 p.m.
Message ID <1344354826-10375-36-git-send-email-lcapitulino@redhat.com>
Download mbox | patch
Permalink /patch/175727/
State New
Headers show

Comments

Luiz Capitulino - Aug. 7, 2012, 3:53 p.m.
Add information about the new error format and improve the text a bit.

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
 docs/writing-qmp-commands.txt | 47 +++++++++++++++++++++++++------------------
 1 file changed, 27 insertions(+), 20 deletions(-)
Pavel Hrdina - Aug. 8, 2012, 12:35 p.m.
On 08/07/2012 05:53 PM, Luiz Capitulino wrote:
> Add information about the new error format and improve the text a bit.
>
> Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
> ---
>   docs/writing-qmp-commands.txt | 47 +++++++++++++++++++++++++------------------
>   1 file changed, 27 insertions(+), 20 deletions(-)
>
> diff --git a/docs/writing-qmp-commands.txt b/docs/writing-qmp-commands.txt
> index 0ad51aa..10ecd97 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",

you have here trailing white-space  ^

> +        "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
Luiz Capitulino - Aug. 8, 2012, 1:26 p.m.
On Wed, 08 Aug 2012 14:35:23 +0200
Pavel Hrdina <phrdina@redhat.com> wrote:

> On 08/07/2012 05:53 PM, Luiz Capitulino wrote:
> > Add information about the new error format and improve the text a bit.
> >
> > Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
> > ---
> >   docs/writing-qmp-commands.txt | 47 +++++++++++++++++++++++++------------------
> >   1 file changed, 27 insertions(+), 20 deletions(-)
> >
> > diff --git a/docs/writing-qmp-commands.txt b/docs/writing-qmp-commands.txt
> > index 0ad51aa..10ecd97 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",
> 
> you have here trailing white-space  ^

I've fixed it for v3, thanks.

> 
> > +        "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
>

Patch

diff --git a/docs/writing-qmp-commands.txt b/docs/writing-qmp-commands.txt
index 0ad51aa..10ecd97 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