Revision 94048982
| b/QMP/qmp-spec.txt | ||
|---|---|---|
| 1 |
QEMU Monitor Protocol Draft Specification - Version 0.1
|
|
| 1 |
QEMU Monitor Protocol Specification - Version 0.1 |
|
| 2 | 2 |
|
| 3 | 3 |
1. Introduction |
| 4 | 4 |
=============== |
| ... | ... | |
| 27 | 27 |
|
| 28 | 28 |
http://www.ietf.org/rfc/rfc4627.txt |
| 29 | 29 |
|
| 30 |
For convenience, json-objects mentioned in this document will have its members
|
|
| 31 |
in a certain order. However, in real protocol usage json-objects members can
|
|
| 32 |
be in ANY order, thus no particular order should be assumed. |
|
| 30 |
For convenience, json-object members and json-array elements mentioned in
|
|
| 31 |
this document will be in a certain order. However, in real protocol usage
|
|
| 32 |
they can be in ANY order, thus no particular order should be assumed.
|
|
| 33 | 33 |
|
| 34 | 34 |
2.1 General Definitions |
| 35 | 35 |
----------------------- |
| ... | ... | |
| 85 | 85 |
|
| 86 | 86 |
The format is: |
| 87 | 87 |
|
| 88 |
{ "return": json-value, "id": json-value }
|
|
| 88 |
{ "return": json-object, "id": json-value }
|
|
| 89 | 89 |
|
| 90 | 90 |
Where, |
| 91 | 91 |
|
| 92 | 92 |
- The "return" member contains the command returned data, which is defined |
| 93 |
in a per-command basis or "OK" if the command does not return data |
|
| 93 |
in a per-command basis or an empty json-object if the command does not |
|
| 94 |
return data |
|
| 94 | 95 |
- The "id" member contains the transaction identification associated |
| 95 | 96 |
with the command execution (if issued by the Client) |
| 96 | 97 |
|
| ... | ... | |
| 102 | 103 |
|
| 103 | 104 |
The format is: |
| 104 | 105 |
|
| 105 |
{ "error": { "class": json-string, "data": json-value, "desc": json-string },
|
|
| 106 |
{ "error": { "class": json-string, "data": json-object, "desc": json-string },
|
|
| 106 | 107 |
"id": json-value } |
| 107 | 108 |
|
| 108 | 109 |
Where, |
| ... | ... | |
| 110 | 111 |
- The "class" member contains the error class name (eg. "ServiceUnavailable") |
| 111 | 112 |
- The "data" member contains specific error data and is defined in a |
| 112 | 113 |
per-command basis, it will be an empty json-object if the error has no data |
| 113 |
- The "desc" member is a human-readable error message. Clients should
|
|
| 114 |
- The "desc" member is a human-readable error message. Clients should |
|
| 114 | 115 |
not attempt to parse this message. |
| 115 | 116 |
- The "id" member contains the transaction identification associated with |
| 116 | 117 |
the command execution (if issued by the Client) |
| ... | ... | |
| 127 | 128 |
|
| 128 | 129 |
The format is: |
| 129 | 130 |
|
| 130 |
{ "event": json-string, "data": json-value,
|
|
| 131 |
{ "event": json-string, "data": json-object,
|
|
| 131 | 132 |
"timestamp": { "seconds": json-number, "microseconds": json-number } }
|
| 132 | 133 |
|
| 133 | 134 |
Where, |
| ... | ... | |
| 135 | 136 |
- The "event" member contains the event's name |
| 136 | 137 |
- The "data" member contains event specific data, which is defined in a |
| 137 | 138 |
per-event basis, it is optional |
| 138 |
- The "timestamp" member contains the exact time of when the event ocurred |
|
| 139 |
- The "timestamp" member contains the exact time of when the event occurred
|
|
| 139 | 140 |
in the Server. It is a fixed json-object with time in seconds and |
| 140 | 141 |
microseconds |
| 141 | 142 |
|
| ... | ... | |
| 157 | 158 |
--------------------------- |
| 158 | 159 |
|
| 159 | 160 |
C: { "execute": "stop" }
|
| 160 |
S: {"return": "OK"}
|
|
| 161 |
S: {"return": {}}
|
|
| 161 | 162 |
|
| 162 | 163 |
3.3 KVM information |
| 163 | 164 |
------------------- |
| 164 | 165 |
|
| 165 |
C: {"execute": "query-kvm", "id": "example"}
|
|
| 166 |
S: {"return": "enabled", "id": "example"}
|
|
| 166 |
C: { "execute": "query-kvm", "id": "example" }
|
|
| 167 |
S: {"return": {"enabled": true, "present": true}, "id": "example"}
|
|
| 167 | 168 |
|
| 168 | 169 |
3.4 Parsing error |
| 169 | 170 |
------------------ |
| 170 | 171 |
|
| 171 | 172 |
C: { "execute": }
|
| 172 |
S: {"error": {"class": "JSONParsing", "data": {}}}
|
|
| 173 |
S: {"error": {"class": "JSONParsing", "desc": "Invalid JSON syntax", "data":
|
|
| 174 |
{}}}
|
|
| 173 | 175 |
|
| 174 | 176 |
3.5 Powerdown event |
| 175 | 177 |
------------------- |
| ... | ... | |
| 177 | 179 |
S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event":
|
| 178 | 180 |
"POWERDOWN"} |
| 179 | 181 |
|
| 180 |
4. Notes to Client implementors
|
|
| 181 |
------------------------------- |
|
| 182 |
4. Compatibility Considerations
|
|
| 183 |
--------------------------------
|
|
| 182 | 184 |
|
| 183 |
4.1 It is recommended to always start the Server in pause mode, thus the |
|
| 184 |
Client is able to perform any setup procedure without the risk of |
|
| 185 |
race conditions and related problems |
|
| 185 |
In order to achieve maximum compatibility between versions, Clients must not |
|
| 186 |
assume any particular: |
|
| 186 | 187 |
|
| 187 |
4.2 It is recommended to always check the capabilities json-array, issued |
|
| 188 |
with the greeting message, at connection time |
|
| 188 |
- Size of json-objects or length of json-arrays |
|
| 189 |
- Order of json-object members or json-array elements |
|
| 190 |
- Amount of errors generated by a command, that is, new errors can be added |
|
| 191 |
to any existing command in newer versions of the Server |
|
| 189 | 192 |
|
| 190 |
4.3 Json-objects or json-arrays mentioned in this document are not fixed |
|
| 191 |
and no particular size or number of members/elements should be assumed. |
|
| 192 |
New members/elements can be added at any time. |
|
| 193 |
Additionally, Clients should always: |
|
| 193 | 194 |
|
| 194 |
4.4 No particular order of json-objects members should be assumed, they |
|
| 195 |
can change at any time |
|
| 195 |
- Check the capabilities json-array at connection time |
|
| 196 |
- Check the availability of commands with 'query-commands' before issuing them |
|
| 197 |
|
|
| 198 |
5. Recommendations to Client implementors |
|
| 199 |
----------------------------------------- |
|
| 200 |
|
|
| 201 |
5.1 The Server should be always started in pause mode, thus the Client is |
|
| 202 |
able to perform any setup procedure without the risk of race conditions |
|
| 203 |
and related problems |
|
Also available in: Unified diff