From patchwork Fri Aug 10 17:44:13 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luiz Capitulino X-Patchwork-Id: 176569 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (Client did not present a certificate) by ozlabs.org (Postfix) with ESMTPS id C8FA92C0095 for ; Sat, 11 Aug 2012 03:46:21 +1000 (EST) Received: from localhost ([::1]:53109 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SztHv-000423-TA for incoming@patchwork.ozlabs.org; Fri, 10 Aug 2012 13:46:19 -0400 Received: from eggs.gnu.org ([208.118.235.92]:41242) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SztH3-0002ui-Ew for qemu-devel@nongnu.org; Fri, 10 Aug 2012 13:45:26 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1SztH2-0001vS-CY for qemu-devel@nongnu.org; Fri, 10 Aug 2012 13:45:25 -0400 Received: from mx1.redhat.com ([209.132.183.28]:24756) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SztH2-0001vH-2Q for qemu-devel@nongnu.org; Fri, 10 Aug 2012 13:45:24 -0400 Received: from int-mx12.intmail.prod.int.phx2.redhat.com (int-mx12.intmail.prod.int.phx2.redhat.com [10.5.11.25]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id q7AHjLXY031148 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Fri, 10 Aug 2012 13:45:21 -0400 Received: from localhost (ovpn-113-102.phx2.redhat.com [10.3.113.102]) by int-mx12.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id q7AHjJWR019098; Fri, 10 Aug 2012 13:45:20 -0400 From: Luiz Capitulino To: qemu-devel@nongnu.org Date: Fri, 10 Aug 2012 14:44:13 -0300 Message-Id: <1344620653-29067-36-git-send-email-lcapitulino@redhat.com> In-Reply-To: <1344620653-29067-1-git-send-email-lcapitulino@redhat.com> References: <1344620653-29067-1-git-send-email-lcapitulino@redhat.com> X-Scanned-By: MIMEDefang 2.68 on 10.5.11.25 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 209.132.183.28 Cc: kwolf@redhat.com, aliguori@us.ibm.com, armbru@redhat.com, mdroth@linux.vnet.ibm.com, pbonzini@redhat.com, eblake@redhat.com Subject: [Qemu-devel] [PATCH 35/35] docs: writing-qmp-commands.txt: update error section X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org 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..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