Revision 5307d7d3 QMP/qmp-spec.txt

b/QMP/qmp-spec.txt
44 44

  
45 45
Right when connected the Server will issue a greeting message, which signals
46 46
that the connection has been successfully established and that the Server is
47
waiting for commands.
47
ready for capabilities negotiation (for more information refer to section
48
'4. Capabilities Negotiation').
48 49

  
49 50
The format is:
50 51

  
......
181 182
S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event":
182 183
"POWERDOWN"}
183 184

  
184
4. Compatibility Considerations
185
--------------------------------
185
4. Capabilities Negotiation
186
----------------------------
186 187

  
187
In order to achieve maximum compatibility between versions, Clients must not 
188
assume any particular:
188
When a Client successfully establishes a connection, the Server is in
189
Capabilities Negotiation mode.
189 190

  
190
- Size of json-objects or length of json-arrays
191
- Order of json-object members or json-array elements
192
- Amount of errors generated by a command, that is, new errors can be added
193
  to any existing command in newer versions of the Server
191
In this mode only the 'qmp_capabilities' command is allowed to run, all
192
other commands will return the CommandNotFound error. Asynchronous messages
193
are not delivered either.
194

  
195
Clients should use the 'qmp_capabilities' command to enable capabilities
196
advertised in the Server's greeting (section '2.2 Server Greeting') they
197
support.
194 198

  
195
Additionally, Clients should always:
199
When the 'qmp_capabilities' command is issued, and if it does not return an
200
error, the Server enters in Command mode where capabilities changes take
201
effect, all commands (except 'qmp_capabilities') are allowed and asynchronous
202
messages are delivered.
196 203

  
197
- Check the capabilities json-array at connection time
198
- Check the availability of commands with 'query-commands' before issuing them
204
5 Compatibility Considerations
205
------------------------------
199 206

  
200
5. Recommendations to Client implementors
201
-----------------------------------------
207
All protocol changes or new features which modify the protocol format in an
208
incompatible way are disabled by default and will be advertised by the
209
capabilities array (section '2.2 Server Greeting'). Thus, Clients can check
210
that array and enable the capabilities they support.
202 211

  
203
5.1 The Server should be always started in pause mode, thus the Client is
204
    able to perform any setup procedure without the risk of race conditions
205
    and related problems
212
Additionally, Clients must not assume any particular:
213

  
214
- Size of json-objects or length of json-arrays
215
- Order of json-object members or json-array elements
216
- Amount of errors generated by a command, that is, new errors can be added
217
  to any existing command in newer versions of the Server

Also available in: Unified diff