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