From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([208.118.235.92]:49664) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Sz5U6-00041B-Lv for qemu-devel@nongnu.org; Wed, 08 Aug 2012 08:35:39 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Sz5Ty-0004x2-Gm for qemu-devel@nongnu.org; Wed, 08 Aug 2012 08:35:34 -0400 Received: from mx1.redhat.com ([209.132.183.28]:55436) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Sz5Ty-0004wu-8M for qemu-devel@nongnu.org; Wed, 08 Aug 2012 08:35:26 -0400 Received: from int-mx11.intmail.prod.int.phx2.redhat.com (int-mx11.intmail.prod.int.phx2.redhat.com [10.5.11.24]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id q78CZP9F003313 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Wed, 8 Aug 2012 08:35:25 -0400 Message-ID: <50225D0B.6060206@redhat.com> Date: Wed, 08 Aug 2012 14:35:23 +0200 From: Pavel Hrdina MIME-Version: 1.0 References: <1344354826-10375-1-git-send-email-lcapitulino@redhat.com> <1344354826-10375-36-git-send-email-lcapitulino@redhat.com> In-Reply-To: <1344354826-10375-36-git-send-email-lcapitulino@redhat.com> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Subject: Re: [Qemu-devel] [PATCH 35/35] docs: writing-qmp-commands.txt: update error section List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Luiz Capitulino Cc: qemu-devel@nongnu.org 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 > --- > 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