[8/8] QMP: spec: Feature negotiation related changes

Message ID 1264686180-29845-9-git-send-email-lcapitulino@redhat.com
State New
Headers show

Commit Message

Luiz Capitulino Jan. 28, 2010, 1:43 p.m.
Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
 QMP/qmp-spec.txt |   60 ++++++++++++++++++++++++++++++++++-------------------
 1 files changed, 38 insertions(+), 22 deletions(-)


diff --git a/QMP/qmp-spec.txt b/QMP/qmp-spec.txt
index 56f388c..5aea09d 100644
--- a/QMP/qmp-spec.txt
+++ b/QMP/qmp-spec.txt
@@ -39,14 +39,20 @@  they can be in ANY order, thus no particular order should be assumed.
 2.1.2 All json-objects members are mandatory when not specified otherwise
-2.2 Server Greeting
+2.2 Server Modes
-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.
+The Server supports two modes of operation: handshake and operational.
-The format is:
+2.2.1 Handshake mode
+When a Client establishes a connection to the Server, the greeting message
+is issued and the Server is in handshake mode. In this mode only a subset of
+the Server's commands are available, most of them deals exclusively with
+capabilities negotiation.
+The format of the greeting message is:
 { "QMP": { "capabilities": json-array } }
@@ -55,6 +61,17 @@  The format is:
 - The "capabilities" member specify the availability of features beyond the
   baseline specification
+Clients should use the handshake mode to enable protocol features they support.
+2.2.2 Operational mode
+In operational mode the full set of Server's commands are available, the only
+exceptions are commands which deal exclusively with capabilities negotiation.
+Clients can switch from handshake mode to operational mode at any time,
+section 3.6 contains an example.
 2.3 Issuing Commands
@@ -123,8 +140,9 @@  if provided by the client.
 2.5 Asynchronous events
-As a result of state changes, the Server may send messages unilaterally
-to the Client at any time. They are called 'asynchronous events'.
+When in operational mode, as a result of state changes, the Server may send
+messages unilaterally to the Client at any time. Theses messages are called
+'asynchronous events'.
 The format is:
@@ -179,25 +197,23 @@  S: {"error": {"class": "JSONParsing", "desc": "Invalid JSON syntax", "data":
 S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event":
+3.6 Mode switch
+C: { "execute": "qmp_switch_mode", "arguments": { "mode": "operational" } }
+S: {"return": {}}
 4. Compatibility Considerations
-In order to achieve maximum compatibility between versions, Clients must not 
-assume any particular:
+All protocol changes or new features which modify the protocol format in an
+incompatible way are disabled by default and will be listed in the capabilities
+array (section 2.2.1). Thus, Clients can enable new features they support at
+handshake mode.
+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
-Additionally, Clients should always:
-- Check the capabilities json-array at connection time
-- Check the availability of commands with 'query-commands' before issuing them
-5. Recommendations to Client implementors
-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