aboutsummaryrefslogtreecommitdiffstats
path: root/QMP
diff options
context:
space:
mode:
authorLuiz Capitulino <lcapitulino@redhat.com>2010-02-04 18:10:07 -0200
committerAnthony Liguori <aliguori@us.ibm.com>2010-02-10 12:46:05 -0600
commit5307d7d35e70a9bf1b290f2eff00236c7ad22220 (patch)
tree508e4783c08403be2836b5b6013e7a879fb9c636 /QMP
parent09069b19f49311c772e220b44edb19fdd446ba5f (diff)
QMP: spec: Capability negotiation updates
Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com> Signed-off-by: Anthony Liguori <aliguori@us.ibm.com>
Diffstat (limited to 'QMP')
-rw-r--r--QMP/qmp-spec.txt46
1 files changed, 29 insertions, 17 deletions
diff --git a/QMP/qmp-spec.txt b/QMP/qmp-spec.txt
index b2617bb2f..f3c032770 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