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": "POWERDOWN"} +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