From 5307d7d35e70a9bf1b290f2eff00236c7ad22220 Mon Sep 17 00:00:00 2001 From: Luiz Capitulino Date: Thu, 4 Feb 2010 18:10:07 -0200 Subject: QMP: spec: Capability negotiation updates Signed-off-by: Luiz Capitulino Signed-off-by: Anthony Liguori --- QMP/qmp-spec.txt | 46 +++++++++++++++++++++++++++++----------------- 1 file changed, 29 insertions(+), 17 deletions(-) (limited to 'QMP/qmp-spec.txt') diff --git a/QMP/qmp-spec.txt b/QMP/qmp-spec.txt index b2617bb2f0..f3c0327703 100644 --- a/QMP/qmp-spec.txt +++ b/QMP/qmp-spec.txt @@ -44,7 +44,8 @@ they can be in ANY order, thus no particular order should be assumed. Right when connected the Server will issue a greeting message, which signals that the connection has been successfully established and that the Server is -waiting for commands. +ready for capabilities negotiation (for more information refer to section +'4. Capabilities Negotiation'). The format is: @@ -181,25 +182,36 @@ S: {"error": {"class": "JSONParsing", "desc": "Invalid JSON syntax", "data": S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event": "POWERDOWN"} -4. Compatibility Considerations --------------------------------- +4. Capabilities Negotiation +---------------------------- -In order to achieve maximum compatibility between versions, Clients must not -assume any particular: +When a Client successfully establishes a connection, the Server is in +Capabilities Negotiation mode. -- Size of json-objects or length of json-arrays -- Order of json-object members or json-array elements -- Amount of errors generated by a command, that is, new errors can be added - to any existing command in newer versions of the Server +In this mode only the 'qmp_capabilities' command is allowed to run, all +other commands will return the CommandNotFound error. Asynchronous messages +are not delivered either. + +Clients should use the 'qmp_capabilities' command to enable capabilities +advertised in the Server's greeting (section '2.2 Server Greeting') they +support. -Additionally, Clients should always: +When the 'qmp_capabilities' command is issued, and if it does not return an +error, the Server enters in Command mode where capabilities changes take +effect, all commands (except 'qmp_capabilities') are allowed and asynchronous +messages are delivered. -- Check the capabilities json-array at connection time -- Check the availability of commands with 'query-commands' before issuing them +5 Compatibility Considerations +------------------------------ -5. Recommendations to Client implementors ------------------------------------------ +All protocol changes or new features which modify the protocol format in an +incompatible way are disabled by default and will be advertised by the +capabilities array (section '2.2 Server Greeting'). Thus, Clients can check +that array and enable the capabilities they support. -5.1 The Server should be always started in pause mode, thus the Client is - able to perform any setup procedure without the risk of race conditions - and related problems +Additionally, Clients must not assume any particular: + +- Size of json-objects or length of json-arrays +- Order of json-object members or json-array elements +- Amount of errors generated by a command, that is, new errors can be added + to any existing command in newer versions of the Server -- cgit v1.2.3