xref: /qemu/qapi/ui.json (revision 4797adce5f0b7542c5aa4a83bdce7f0e63d6deae)
1608cfed6SMarkus Armbruster# -*- Mode: Python -*-
2f7160f32SAndrea Bolognani# vim: filetype=python
3608cfed6SMarkus Armbruster#
4608cfed6SMarkus Armbruster
5608cfed6SMarkus Armbruster##
6608cfed6SMarkus Armbruster# = Remote desktop
7608cfed6SMarkus Armbruster##
8608cfed6SMarkus Armbruster
930e863e5SKevin Wolf{ 'include': 'common.json' }
10608cfed6SMarkus Armbruster{ 'include': 'sockets.json' }
11608cfed6SMarkus Armbruster
12608cfed6SMarkus Armbruster##
137277db91SStefan Reiter# @DisplayProtocol:
147277db91SStefan Reiter#
157277db91SStefan Reiter# Display protocols which support changing password options.
167277db91SStefan Reiter#
177277db91SStefan Reiter# Since: 7.0
187277db91SStefan Reiter#
197277db91SStefan Reiter##
207277db91SStefan Reiter{ 'enum': 'DisplayProtocol',
217277db91SStefan Reiter  'data': [ 'vnc', 'spice' ] }
227277db91SStefan Reiter
237277db91SStefan Reiter##
247277db91SStefan Reiter# @SetPasswordAction:
257277db91SStefan Reiter#
267277db91SStefan Reiter# An action to take on changing a password on a connection with active clients.
277277db91SStefan Reiter#
287277db91SStefan Reiter# @keep: maintain existing clients
297277db91SStefan Reiter#
307277db91SStefan Reiter# @fail: fail the command if clients are connected
317277db91SStefan Reiter#
327277db91SStefan Reiter# @disconnect: disconnect existing clients
337277db91SStefan Reiter#
347277db91SStefan Reiter# Since: 7.0
357277db91SStefan Reiter#
367277db91SStefan Reiter##
377277db91SStefan Reiter{ 'enum': 'SetPasswordAction',
387277db91SStefan Reiter  'data': [ 'keep', 'fail', 'disconnect' ] }
397277db91SStefan Reiter
407277db91SStefan Reiter##
41675fd3c9SStefan Reiter# @SetPasswordOptions:
42608cfed6SMarkus Armbruster#
43675fd3c9SStefan Reiter# Options for set_password.
44608cfed6SMarkus Armbruster#
45e050e426SPeter Maydell# @protocol: - 'vnc' to modify the VNC server password
46e050e426SPeter Maydell#            - 'spice' to modify the Spice server password
47608cfed6SMarkus Armbruster#
48608cfed6SMarkus Armbruster# @password: the new password
49608cfed6SMarkus Armbruster#
50675fd3c9SStefan Reiter# @connected: How to handle existing clients when changing the
51675fd3c9SStefan Reiter#             password. If nothing is specified, defaults to 'keep'.
52675fd3c9SStefan Reiter#             For VNC, only 'keep' is currently implemented.
53675fd3c9SStefan Reiter#
54675fd3c9SStefan Reiter# Since: 7.0
55675fd3c9SStefan Reiter#
56675fd3c9SStefan Reiter##
57675fd3c9SStefan Reiter{ 'union': 'SetPasswordOptions',
58675fd3c9SStefan Reiter  'base': { 'protocol': 'DisplayProtocol',
59675fd3c9SStefan Reiter            'password': 'str',
60675fd3c9SStefan Reiter            '*connected': 'SetPasswordAction' },
61675fd3c9SStefan Reiter  'discriminator': 'protocol',
62675fd3c9SStefan Reiter  'data': { 'vnc': 'SetPasswordOptionsVnc' } }
63675fd3c9SStefan Reiter
64675fd3c9SStefan Reiter##
65675fd3c9SStefan Reiter# @SetPasswordOptionsVnc:
66675fd3c9SStefan Reiter#
67675fd3c9SStefan Reiter# Options for set_password specific to the VNC procotol.
68675fd3c9SStefan Reiter#
69675fd3c9SStefan Reiter# @display: The id of the display where the password should be changed.
70675fd3c9SStefan Reiter#           Defaults to the first.
71675fd3c9SStefan Reiter#
72675fd3c9SStefan Reiter# Since: 7.0
73675fd3c9SStefan Reiter#
74675fd3c9SStefan Reiter##
75675fd3c9SStefan Reiter{ 'struct': 'SetPasswordOptionsVnc',
76675fd3c9SStefan Reiter  'data': { '*display': 'str' } }
77675fd3c9SStefan Reiter
78675fd3c9SStefan Reiter##
79675fd3c9SStefan Reiter# @set_password:
80675fd3c9SStefan Reiter#
81675fd3c9SStefan Reiter# Set the password of a remote display server.
82608cfed6SMarkus Armbruster#
83e050e426SPeter Maydell# Returns: - Nothing on success
84e050e426SPeter Maydell#          - If Spice is not enabled, DeviceNotFound
85608cfed6SMarkus Armbruster#
869bc6e893SMarkus Armbruster# Since: 0.14
87608cfed6SMarkus Armbruster#
88608cfed6SMarkus Armbruster# Example:
89608cfed6SMarkus Armbruster#
90608cfed6SMarkus Armbruster# -> { "execute": "set_password", "arguments": { "protocol": "vnc",
91608cfed6SMarkus Armbruster#                                                "password": "secret" } }
92608cfed6SMarkus Armbruster# <- { "return": {} }
93608cfed6SMarkus Armbruster#
94608cfed6SMarkus Armbruster##
95675fd3c9SStefan Reiter{ 'command': 'set_password', 'boxed': true, 'data': 'SetPasswordOptions' }
96608cfed6SMarkus Armbruster
97608cfed6SMarkus Armbruster##
98675fd3c9SStefan Reiter# @ExpirePasswordOptions:
99608cfed6SMarkus Armbruster#
100675fd3c9SStefan Reiter# General options for expire_password.
101608cfed6SMarkus Armbruster#
102675fd3c9SStefan Reiter# @protocol: - 'vnc' to modify the VNC server expiration
103675fd3c9SStefan Reiter#            - 'spice' to modify the Spice server expiration
104608cfed6SMarkus Armbruster#
105608cfed6SMarkus Armbruster# @time: when to expire the password.
106608cfed6SMarkus Armbruster#
107e050e426SPeter Maydell#        - 'now' to expire the password immediately
108e050e426SPeter Maydell#        - 'never' to cancel password expiration
109e050e426SPeter Maydell#        - '+INT' where INT is the number of seconds from now (integer)
110e050e426SPeter Maydell#        - 'INT' where INT is the absolute time in seconds
111e050e426SPeter Maydell#
112608cfed6SMarkus Armbruster# Notes: Time is relative to the server and currently there is no way to
113608cfed6SMarkus Armbruster#        coordinate server time with client time.  It is not recommended to
114608cfed6SMarkus Armbruster#        use the absolute time version of the @time parameter unless you're
115608cfed6SMarkus Armbruster#        sure you are on the same machine as the QEMU instance.
116608cfed6SMarkus Armbruster#
117675fd3c9SStefan Reiter# Since: 7.0
118675fd3c9SStefan Reiter#
119675fd3c9SStefan Reiter##
120675fd3c9SStefan Reiter{ 'union': 'ExpirePasswordOptions',
121675fd3c9SStefan Reiter  'base': { 'protocol': 'DisplayProtocol',
122675fd3c9SStefan Reiter            'time': 'str' },
123675fd3c9SStefan Reiter  'discriminator': 'protocol',
124675fd3c9SStefan Reiter  'data': { 'vnc': 'ExpirePasswordOptionsVnc' } }
125675fd3c9SStefan Reiter
126675fd3c9SStefan Reiter##
127675fd3c9SStefan Reiter# @ExpirePasswordOptionsVnc:
128675fd3c9SStefan Reiter#
129675fd3c9SStefan Reiter# Options for expire_password specific to the VNC procotol.
130675fd3c9SStefan Reiter#
131675fd3c9SStefan Reiter# @display: The id of the display where the expiration should be changed.
132675fd3c9SStefan Reiter#           Defaults to the first.
133675fd3c9SStefan Reiter#
134675fd3c9SStefan Reiter# Since: 7.0
135675fd3c9SStefan Reiter#
136675fd3c9SStefan Reiter##
137675fd3c9SStefan Reiter
138675fd3c9SStefan Reiter{ 'struct': 'ExpirePasswordOptionsVnc',
139675fd3c9SStefan Reiter  'data': { '*display': 'str' } }
140675fd3c9SStefan Reiter
141675fd3c9SStefan Reiter##
142675fd3c9SStefan Reiter# @expire_password:
143675fd3c9SStefan Reiter#
144675fd3c9SStefan Reiter# Expire the password of a remote display server.
145675fd3c9SStefan Reiter#
146675fd3c9SStefan Reiter# Returns: - Nothing on success
147675fd3c9SStefan Reiter#          - If @protocol is 'spice' and Spice is not active, DeviceNotFound
148675fd3c9SStefan Reiter#
149675fd3c9SStefan Reiter# Since: 0.14
150675fd3c9SStefan Reiter#
151608cfed6SMarkus Armbruster# Example:
152608cfed6SMarkus Armbruster#
153608cfed6SMarkus Armbruster# -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
154608cfed6SMarkus Armbruster#                                                   "time": "+60" } }
155608cfed6SMarkus Armbruster# <- { "return": {} }
156608cfed6SMarkus Armbruster#
157608cfed6SMarkus Armbruster##
158675fd3c9SStefan Reiter{ 'command': 'expire_password', 'boxed': true, 'data': 'ExpirePasswordOptions' }
159608cfed6SMarkus Armbruster
160608cfed6SMarkus Armbruster##
161608cfed6SMarkus Armbruster# @screendump:
162608cfed6SMarkus Armbruster#
163608cfed6SMarkus Armbruster# Write a PPM of the VGA screen to a file.
164608cfed6SMarkus Armbruster#
165608cfed6SMarkus Armbruster# @filename: the path of a new PPM file to store the image
166608cfed6SMarkus Armbruster#
167f771c544SThomas Huth# @device: ID of the display device that should be dumped. If this parameter
168f771c544SThomas Huth#          is missing, the primary display will be used. (Since 2.12)
169f771c544SThomas Huth#
170f771c544SThomas Huth# @head: head to use in case the device supports multiple heads. If this
171f771c544SThomas Huth#        parameter is missing, head #0 will be used. Also note that the head
172f771c544SThomas Huth#        can only be specified in conjunction with the device ID. (Since 2.12)
173f771c544SThomas Huth#
174608cfed6SMarkus Armbruster# Returns: Nothing on success
175608cfed6SMarkus Armbruster#
1769bc6e893SMarkus Armbruster# Since: 0.14
177608cfed6SMarkus Armbruster#
178608cfed6SMarkus Armbruster# Example:
179608cfed6SMarkus Armbruster#
180608cfed6SMarkus Armbruster# -> { "execute": "screendump",
181608cfed6SMarkus Armbruster#      "arguments": { "filename": "/tmp/image" } }
182608cfed6SMarkus Armbruster# <- { "return": {} }
183608cfed6SMarkus Armbruster#
184608cfed6SMarkus Armbruster##
185f771c544SThomas Huth{ 'command': 'screendump',
1860d9b90ceSMarc-André Lureau  'data': {'filename': 'str', '*device': 'str', '*head': 'int'},
1870d9b90ceSMarc-André Lureau  'coroutine': true }
188608cfed6SMarkus Armbruster
189608cfed6SMarkus Armbruster##
190608cfed6SMarkus Armbruster# == Spice
191608cfed6SMarkus Armbruster##
192608cfed6SMarkus Armbruster
193608cfed6SMarkus Armbruster##
194608cfed6SMarkus Armbruster# @SpiceBasicInfo:
195608cfed6SMarkus Armbruster#
196608cfed6SMarkus Armbruster# The basic information for SPICE network connection
197608cfed6SMarkus Armbruster#
198608cfed6SMarkus Armbruster# @host: IP address
199608cfed6SMarkus Armbruster#
200608cfed6SMarkus Armbruster# @port: port number
201608cfed6SMarkus Armbruster#
202608cfed6SMarkus Armbruster# @family: address family
203608cfed6SMarkus Armbruster#
204608cfed6SMarkus Armbruster# Since: 2.1
205608cfed6SMarkus Armbruster##
206608cfed6SMarkus Armbruster{ 'struct': 'SpiceBasicInfo',
207608cfed6SMarkus Armbruster  'data': { 'host': 'str',
208608cfed6SMarkus Armbruster            'port': 'str',
209514337c1SMarc-André Lureau            'family': 'NetworkAddressFamily' },
2108a9f1e1dSMarc-André Lureau  'if': 'CONFIG_SPICE' }
211608cfed6SMarkus Armbruster
212608cfed6SMarkus Armbruster##
213608cfed6SMarkus Armbruster# @SpiceServerInfo:
214608cfed6SMarkus Armbruster#
215608cfed6SMarkus Armbruster# Information about a SPICE server
216608cfed6SMarkus Armbruster#
217608cfed6SMarkus Armbruster# @auth: authentication method
218608cfed6SMarkus Armbruster#
219608cfed6SMarkus Armbruster# Since: 2.1
220608cfed6SMarkus Armbruster##
221608cfed6SMarkus Armbruster{ 'struct': 'SpiceServerInfo',
222608cfed6SMarkus Armbruster  'base': 'SpiceBasicInfo',
223514337c1SMarc-André Lureau  'data': { '*auth': 'str' },
2248a9f1e1dSMarc-André Lureau  'if': 'CONFIG_SPICE' }
225608cfed6SMarkus Armbruster
226608cfed6SMarkus Armbruster##
227608cfed6SMarkus Armbruster# @SpiceChannel:
228608cfed6SMarkus Armbruster#
229608cfed6SMarkus Armbruster# Information about a SPICE client channel.
230608cfed6SMarkus Armbruster#
231608cfed6SMarkus Armbruster# @connection-id: SPICE connection id number.  All channels with the same id
232608cfed6SMarkus Armbruster#                 belong to the same SPICE session.
233608cfed6SMarkus Armbruster#
234608cfed6SMarkus Armbruster# @channel-type: SPICE channel type number.  "1" is the main control
235608cfed6SMarkus Armbruster#                channel, filter for this one if you want to track spice
236608cfed6SMarkus Armbruster#                sessions only
237608cfed6SMarkus Armbruster#
238608cfed6SMarkus Armbruster# @channel-id: SPICE channel ID number.  Usually "0", might be different when
239608cfed6SMarkus Armbruster#              multiple channels of the same type exist, such as multiple
240608cfed6SMarkus Armbruster#              display channels in a multihead setup
241608cfed6SMarkus Armbruster#
242608cfed6SMarkus Armbruster# @tls: true if the channel is encrypted, false otherwise.
243608cfed6SMarkus Armbruster#
2449bc6e893SMarkus Armbruster# Since: 0.14
245608cfed6SMarkus Armbruster##
246608cfed6SMarkus Armbruster{ 'struct': 'SpiceChannel',
247608cfed6SMarkus Armbruster  'base': 'SpiceBasicInfo',
248608cfed6SMarkus Armbruster  'data': {'connection-id': 'int', 'channel-type': 'int', 'channel-id': 'int',
249514337c1SMarc-André Lureau           'tls': 'bool'},
2508a9f1e1dSMarc-André Lureau  'if': 'CONFIG_SPICE' }
251608cfed6SMarkus Armbruster
252608cfed6SMarkus Armbruster##
253608cfed6SMarkus Armbruster# @SpiceQueryMouseMode:
254608cfed6SMarkus Armbruster#
255608cfed6SMarkus Armbruster# An enumeration of Spice mouse states.
256608cfed6SMarkus Armbruster#
257608cfed6SMarkus Armbruster# @client: Mouse cursor position is determined by the client.
258608cfed6SMarkus Armbruster#
259608cfed6SMarkus Armbruster# @server: Mouse cursor position is determined by the server.
260608cfed6SMarkus Armbruster#
261608cfed6SMarkus Armbruster# @unknown: No information is available about mouse mode used by
262608cfed6SMarkus Armbruster#           the spice server.
263608cfed6SMarkus Armbruster#
264608cfed6SMarkus Armbruster# Note: spice/enums.h has a SpiceMouseMode already, hence the name.
265608cfed6SMarkus Armbruster#
266608cfed6SMarkus Armbruster# Since: 1.1
267608cfed6SMarkus Armbruster##
268608cfed6SMarkus Armbruster{ 'enum': 'SpiceQueryMouseMode',
269514337c1SMarc-André Lureau  'data': [ 'client', 'server', 'unknown' ],
2708a9f1e1dSMarc-André Lureau  'if': 'CONFIG_SPICE' }
271608cfed6SMarkus Armbruster
272608cfed6SMarkus Armbruster##
273608cfed6SMarkus Armbruster# @SpiceInfo:
274608cfed6SMarkus Armbruster#
275608cfed6SMarkus Armbruster# Information about the SPICE session.
276608cfed6SMarkus Armbruster#
277608cfed6SMarkus Armbruster# @enabled: true if the SPICE server is enabled, false otherwise
278608cfed6SMarkus Armbruster#
279608cfed6SMarkus Armbruster# @migrated: true if the last guest migration completed and spice
280608cfed6SMarkus Armbruster#            migration had completed as well. false otherwise. (since 1.4)
281608cfed6SMarkus Armbruster#
282608cfed6SMarkus Armbruster# @host: The hostname the SPICE server is bound to.  This depends on
283608cfed6SMarkus Armbruster#        the name resolution on the host and may be an IP address.
284608cfed6SMarkus Armbruster#
285608cfed6SMarkus Armbruster# @port: The SPICE server's port number.
286608cfed6SMarkus Armbruster#
287608cfed6SMarkus Armbruster# @compiled-version: SPICE server version.
288608cfed6SMarkus Armbruster#
289608cfed6SMarkus Armbruster# @tls-port: The SPICE server's TLS port number.
290608cfed6SMarkus Armbruster#
291608cfed6SMarkus Armbruster# @auth: the current authentication type used by the server
292e050e426SPeter Maydell#
293e050e426SPeter Maydell#        - 'none'  if no authentication is being used
294e050e426SPeter Maydell#        - 'spice' uses SASL or direct TLS authentication, depending on command
295608cfed6SMarkus Armbruster#          line options
296608cfed6SMarkus Armbruster#
297608cfed6SMarkus Armbruster# @mouse-mode: The mode in which the mouse cursor is displayed currently. Can
298608cfed6SMarkus Armbruster#              be determined by the client or the server, or unknown if spice
299608cfed6SMarkus Armbruster#              server doesn't provide this information. (since: 1.1)
300608cfed6SMarkus Armbruster#
301608cfed6SMarkus Armbruster# @channels: a list of @SpiceChannel for each active spice channel
302608cfed6SMarkus Armbruster#
3039bc6e893SMarkus Armbruster# Since: 0.14
304608cfed6SMarkus Armbruster##
305608cfed6SMarkus Armbruster{ 'struct': 'SpiceInfo',
306608cfed6SMarkus Armbruster  'data': {'enabled': 'bool', 'migrated': 'bool', '*host': 'str', '*port': 'int',
307608cfed6SMarkus Armbruster           '*tls-port': 'int', '*auth': 'str', '*compiled-version': 'str',
308514337c1SMarc-André Lureau           'mouse-mode': 'SpiceQueryMouseMode', '*channels': ['SpiceChannel']},
3098a9f1e1dSMarc-André Lureau  'if': 'CONFIG_SPICE' }
310608cfed6SMarkus Armbruster
311608cfed6SMarkus Armbruster##
312608cfed6SMarkus Armbruster# @query-spice:
313608cfed6SMarkus Armbruster#
314608cfed6SMarkus Armbruster# Returns information about the current SPICE server
315608cfed6SMarkus Armbruster#
316608cfed6SMarkus Armbruster# Returns: @SpiceInfo
317608cfed6SMarkus Armbruster#
3189bc6e893SMarkus Armbruster# Since: 0.14
319608cfed6SMarkus Armbruster#
320608cfed6SMarkus Armbruster# Example:
321608cfed6SMarkus Armbruster#
322608cfed6SMarkus Armbruster# -> { "execute": "query-spice" }
323608cfed6SMarkus Armbruster# <- { "return": {
324608cfed6SMarkus Armbruster#          "enabled": true,
325608cfed6SMarkus Armbruster#          "auth": "spice",
326608cfed6SMarkus Armbruster#          "port": 5920,
327608cfed6SMarkus Armbruster#          "tls-port": 5921,
328608cfed6SMarkus Armbruster#          "host": "0.0.0.0",
329608cfed6SMarkus Armbruster#          "channels": [
330608cfed6SMarkus Armbruster#             {
331608cfed6SMarkus Armbruster#                "port": "54924",
332608cfed6SMarkus Armbruster#                "family": "ipv4",
333608cfed6SMarkus Armbruster#                "channel-type": 1,
334608cfed6SMarkus Armbruster#                "connection-id": 1804289383,
335608cfed6SMarkus Armbruster#                "host": "127.0.0.1",
336608cfed6SMarkus Armbruster#                "channel-id": 0,
337608cfed6SMarkus Armbruster#                "tls": true
338608cfed6SMarkus Armbruster#             },
339608cfed6SMarkus Armbruster#             {
340608cfed6SMarkus Armbruster#                "port": "36710",
341608cfed6SMarkus Armbruster#                "family": "ipv4",
342608cfed6SMarkus Armbruster#                "channel-type": 4,
343608cfed6SMarkus Armbruster#                "connection-id": 1804289383,
344608cfed6SMarkus Armbruster#                "host": "127.0.0.1",
345608cfed6SMarkus Armbruster#                "channel-id": 0,
346608cfed6SMarkus Armbruster#                "tls": false
347608cfed6SMarkus Armbruster#             },
348608cfed6SMarkus Armbruster#             [ ... more channels follow ... ]
349608cfed6SMarkus Armbruster#          ]
350608cfed6SMarkus Armbruster#       }
351608cfed6SMarkus Armbruster#    }
352608cfed6SMarkus Armbruster#
353608cfed6SMarkus Armbruster##
354514337c1SMarc-André Lureau{ 'command': 'query-spice', 'returns': 'SpiceInfo',
3558a9f1e1dSMarc-André Lureau  'if': 'CONFIG_SPICE' }
356608cfed6SMarkus Armbruster
357608cfed6SMarkus Armbruster##
358608cfed6SMarkus Armbruster# @SPICE_CONNECTED:
359608cfed6SMarkus Armbruster#
360608cfed6SMarkus Armbruster# Emitted when a SPICE client establishes a connection
361608cfed6SMarkus Armbruster#
362608cfed6SMarkus Armbruster# @server: server information
363608cfed6SMarkus Armbruster#
364608cfed6SMarkus Armbruster# @client: client information
365608cfed6SMarkus Armbruster#
3669bc6e893SMarkus Armbruster# Since: 0.14
367608cfed6SMarkus Armbruster#
368608cfed6SMarkus Armbruster# Example:
369608cfed6SMarkus Armbruster#
370608cfed6SMarkus Armbruster# <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
371608cfed6SMarkus Armbruster#      "event": "SPICE_CONNECTED",
372608cfed6SMarkus Armbruster#      "data": {
373608cfed6SMarkus Armbruster#        "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
374608cfed6SMarkus Armbruster#        "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
375608cfed6SMarkus Armbruster#    }}
376608cfed6SMarkus Armbruster#
377608cfed6SMarkus Armbruster##
378608cfed6SMarkus Armbruster{ 'event': 'SPICE_CONNECTED',
379608cfed6SMarkus Armbruster  'data': { 'server': 'SpiceBasicInfo',
380514337c1SMarc-André Lureau            'client': 'SpiceBasicInfo' },
3818a9f1e1dSMarc-André Lureau  'if': 'CONFIG_SPICE' }
382608cfed6SMarkus Armbruster
383608cfed6SMarkus Armbruster##
384608cfed6SMarkus Armbruster# @SPICE_INITIALIZED:
385608cfed6SMarkus Armbruster#
386608cfed6SMarkus Armbruster# Emitted after initial handshake and authentication takes place (if any)
387608cfed6SMarkus Armbruster# and the SPICE channel is up and running
388608cfed6SMarkus Armbruster#
389608cfed6SMarkus Armbruster# @server: server information
390608cfed6SMarkus Armbruster#
391608cfed6SMarkus Armbruster# @client: client information
392608cfed6SMarkus Armbruster#
3939bc6e893SMarkus Armbruster# Since: 0.14
394608cfed6SMarkus Armbruster#
395608cfed6SMarkus Armbruster# Example:
396608cfed6SMarkus Armbruster#
397608cfed6SMarkus Armbruster# <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
398608cfed6SMarkus Armbruster#      "event": "SPICE_INITIALIZED",
399608cfed6SMarkus Armbruster#      "data": {"server": {"auth": "spice", "port": "5921",
400608cfed6SMarkus Armbruster#                          "family": "ipv4", "host": "127.0.0.1"},
401608cfed6SMarkus Armbruster#               "client": {"port": "49004", "family": "ipv4", "channel-type": 3,
402608cfed6SMarkus Armbruster#                          "connection-id": 1804289383, "host": "127.0.0.1",
403608cfed6SMarkus Armbruster#                          "channel-id": 0, "tls": true}
404608cfed6SMarkus Armbruster#    }}
405608cfed6SMarkus Armbruster#
406608cfed6SMarkus Armbruster##
407608cfed6SMarkus Armbruster{ 'event': 'SPICE_INITIALIZED',
408608cfed6SMarkus Armbruster  'data': { 'server': 'SpiceServerInfo',
409514337c1SMarc-André Lureau            'client': 'SpiceChannel' },
4108a9f1e1dSMarc-André Lureau  'if': 'CONFIG_SPICE' }
411608cfed6SMarkus Armbruster
412608cfed6SMarkus Armbruster##
413608cfed6SMarkus Armbruster# @SPICE_DISCONNECTED:
414608cfed6SMarkus Armbruster#
415608cfed6SMarkus Armbruster# Emitted when the SPICE connection is closed
416608cfed6SMarkus Armbruster#
417608cfed6SMarkus Armbruster# @server: server information
418608cfed6SMarkus Armbruster#
419608cfed6SMarkus Armbruster# @client: client information
420608cfed6SMarkus Armbruster#
4219bc6e893SMarkus Armbruster# Since: 0.14
422608cfed6SMarkus Armbruster#
423608cfed6SMarkus Armbruster# Example:
424608cfed6SMarkus Armbruster#
425608cfed6SMarkus Armbruster# <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
426608cfed6SMarkus Armbruster#      "event": "SPICE_DISCONNECTED",
427608cfed6SMarkus Armbruster#      "data": {
428608cfed6SMarkus Armbruster#        "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
429608cfed6SMarkus Armbruster#        "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
430608cfed6SMarkus Armbruster#    }}
431608cfed6SMarkus Armbruster#
432608cfed6SMarkus Armbruster##
433608cfed6SMarkus Armbruster{ 'event': 'SPICE_DISCONNECTED',
434608cfed6SMarkus Armbruster  'data': { 'server': 'SpiceBasicInfo',
435514337c1SMarc-André Lureau            'client': 'SpiceBasicInfo' },
4368a9f1e1dSMarc-André Lureau  'if': 'CONFIG_SPICE' }
437608cfed6SMarkus Armbruster
438608cfed6SMarkus Armbruster##
439608cfed6SMarkus Armbruster# @SPICE_MIGRATE_COMPLETED:
440608cfed6SMarkus Armbruster#
441608cfed6SMarkus Armbruster# Emitted when SPICE migration has completed
442608cfed6SMarkus Armbruster#
443608cfed6SMarkus Armbruster# Since: 1.3
444608cfed6SMarkus Armbruster#
445608cfed6SMarkus Armbruster# Example:
446608cfed6SMarkus Armbruster#
447608cfed6SMarkus Armbruster# <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
448608cfed6SMarkus Armbruster#      "event": "SPICE_MIGRATE_COMPLETED" }
449608cfed6SMarkus Armbruster#
450608cfed6SMarkus Armbruster##
451514337c1SMarc-André Lureau{ 'event': 'SPICE_MIGRATE_COMPLETED',
4528a9f1e1dSMarc-André Lureau  'if': 'CONFIG_SPICE' }
453608cfed6SMarkus Armbruster
454608cfed6SMarkus Armbruster##
455608cfed6SMarkus Armbruster# == VNC
456608cfed6SMarkus Armbruster##
457608cfed6SMarkus Armbruster
458608cfed6SMarkus Armbruster##
459608cfed6SMarkus Armbruster# @VncBasicInfo:
460608cfed6SMarkus Armbruster#
461608cfed6SMarkus Armbruster# The basic information for vnc network connection
462608cfed6SMarkus Armbruster#
463608cfed6SMarkus Armbruster# @host: IP address
464608cfed6SMarkus Armbruster#
465608cfed6SMarkus Armbruster# @service: The service name of the vnc port. This may depend on the host
466608cfed6SMarkus Armbruster#           system's service database so symbolic names should not be relied
467608cfed6SMarkus Armbruster#           on.
468608cfed6SMarkus Armbruster#
469608cfed6SMarkus Armbruster# @family: address family
470608cfed6SMarkus Armbruster#
471608cfed6SMarkus Armbruster# @websocket: true in case the socket is a websocket (since 2.3).
472608cfed6SMarkus Armbruster#
473608cfed6SMarkus Armbruster# Since: 2.1
474608cfed6SMarkus Armbruster##
475608cfed6SMarkus Armbruster{ 'struct': 'VncBasicInfo',
476608cfed6SMarkus Armbruster  'data': { 'host': 'str',
477608cfed6SMarkus Armbruster            'service': 'str',
478608cfed6SMarkus Armbruster            'family': 'NetworkAddressFamily',
47905eb4a25SMarc-André Lureau            'websocket': 'bool' },
4808a9f1e1dSMarc-André Lureau  'if': 'CONFIG_VNC' }
481608cfed6SMarkus Armbruster
482608cfed6SMarkus Armbruster##
483608cfed6SMarkus Armbruster# @VncServerInfo:
484608cfed6SMarkus Armbruster#
485608cfed6SMarkus Armbruster# The network connection information for server
486608cfed6SMarkus Armbruster#
487608cfed6SMarkus Armbruster# @auth: authentication method used for
488608cfed6SMarkus Armbruster#        the plain (non-websocket) VNC server
489608cfed6SMarkus Armbruster#
490608cfed6SMarkus Armbruster# Since: 2.1
491608cfed6SMarkus Armbruster##
492608cfed6SMarkus Armbruster{ 'struct': 'VncServerInfo',
493608cfed6SMarkus Armbruster  'base': 'VncBasicInfo',
49405eb4a25SMarc-André Lureau  'data': { '*auth': 'str' },
4958a9f1e1dSMarc-André Lureau  'if': 'CONFIG_VNC' }
496608cfed6SMarkus Armbruster
497608cfed6SMarkus Armbruster##
498608cfed6SMarkus Armbruster# @VncClientInfo:
499608cfed6SMarkus Armbruster#
500608cfed6SMarkus Armbruster# Information about a connected VNC client.
501608cfed6SMarkus Armbruster#
502608cfed6SMarkus Armbruster# @x509_dname: If x509 authentication is in use, the Distinguished
503608cfed6SMarkus Armbruster#              Name of the client.
504608cfed6SMarkus Armbruster#
505608cfed6SMarkus Armbruster# @sasl_username: If SASL authentication is in use, the SASL username
506608cfed6SMarkus Armbruster#                 used for authentication.
507608cfed6SMarkus Armbruster#
5089bc6e893SMarkus Armbruster# Since: 0.14
509608cfed6SMarkus Armbruster##
510608cfed6SMarkus Armbruster{ 'struct': 'VncClientInfo',
511608cfed6SMarkus Armbruster  'base': 'VncBasicInfo',
51205eb4a25SMarc-André Lureau  'data': { '*x509_dname': 'str', '*sasl_username': 'str' },
5138a9f1e1dSMarc-André Lureau  'if': 'CONFIG_VNC' }
514608cfed6SMarkus Armbruster
515608cfed6SMarkus Armbruster##
516608cfed6SMarkus Armbruster# @VncInfo:
517608cfed6SMarkus Armbruster#
518608cfed6SMarkus Armbruster# Information about the VNC session.
519608cfed6SMarkus Armbruster#
520608cfed6SMarkus Armbruster# @enabled: true if the VNC server is enabled, false otherwise
521608cfed6SMarkus Armbruster#
522608cfed6SMarkus Armbruster# @host: The hostname the VNC server is bound to.  This depends on
523608cfed6SMarkus Armbruster#        the name resolution on the host and may be an IP address.
524608cfed6SMarkus Armbruster#
525e050e426SPeter Maydell# @family: - 'ipv6' if the host is listening for IPv6 connections
526e050e426SPeter Maydell#          - 'ipv4' if the host is listening for IPv4 connections
527e050e426SPeter Maydell#          - 'unix' if the host is listening on a unix domain socket
528e050e426SPeter Maydell#          - 'unknown' otherwise
529608cfed6SMarkus Armbruster#
530608cfed6SMarkus Armbruster# @service: The service name of the server's port.  This may depends
531608cfed6SMarkus Armbruster#           on the host system's service database so symbolic names should not
532608cfed6SMarkus Armbruster#           be relied on.
533608cfed6SMarkus Armbruster#
534608cfed6SMarkus Armbruster# @auth: the current authentication type used by the server
535e050e426SPeter Maydell#
536e050e426SPeter Maydell#        - 'none' if no authentication is being used
537e050e426SPeter Maydell#        - 'vnc' if VNC authentication is being used
538e050e426SPeter Maydell#        - 'vencrypt+plain' if VEncrypt is used with plain text authentication
539e050e426SPeter Maydell#        - 'vencrypt+tls+none' if VEncrypt is used with TLS and no authentication
540e050e426SPeter Maydell#        - 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC authentication
541e050e426SPeter Maydell#        - 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain text auth
542e050e426SPeter Maydell#        - 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth
543e050e426SPeter Maydell#        - 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth
544e050e426SPeter Maydell#        - 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain text auth
545e050e426SPeter Maydell#        - 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth
546e050e426SPeter Maydell#        - 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL auth
547608cfed6SMarkus Armbruster#
548608cfed6SMarkus Armbruster# @clients: a list of @VncClientInfo of all currently connected clients
549608cfed6SMarkus Armbruster#
5509bc6e893SMarkus Armbruster# Since: 0.14
551608cfed6SMarkus Armbruster##
552608cfed6SMarkus Armbruster{ 'struct': 'VncInfo',
553608cfed6SMarkus Armbruster  'data': {'enabled': 'bool', '*host': 'str',
554608cfed6SMarkus Armbruster           '*family': 'NetworkAddressFamily',
55505eb4a25SMarc-André Lureau           '*service': 'str', '*auth': 'str', '*clients': ['VncClientInfo']},
5568a9f1e1dSMarc-André Lureau  'if': 'CONFIG_VNC' }
557608cfed6SMarkus Armbruster
558608cfed6SMarkus Armbruster##
559608cfed6SMarkus Armbruster# @VncPrimaryAuth:
560608cfed6SMarkus Armbruster#
561608cfed6SMarkus Armbruster# vnc primary authentication method.
562608cfed6SMarkus Armbruster#
563608cfed6SMarkus Armbruster# Since: 2.3
564608cfed6SMarkus Armbruster##
565608cfed6SMarkus Armbruster{ 'enum': 'VncPrimaryAuth',
566608cfed6SMarkus Armbruster  'data': [ 'none', 'vnc', 'ra2', 'ra2ne', 'tight', 'ultra',
56705eb4a25SMarc-André Lureau            'tls', 'vencrypt', 'sasl' ],
5688a9f1e1dSMarc-André Lureau  'if': 'CONFIG_VNC' }
569608cfed6SMarkus Armbruster
570608cfed6SMarkus Armbruster##
571608cfed6SMarkus Armbruster# @VncVencryptSubAuth:
572608cfed6SMarkus Armbruster#
573608cfed6SMarkus Armbruster# vnc sub authentication method with vencrypt.
574608cfed6SMarkus Armbruster#
575608cfed6SMarkus Armbruster# Since: 2.3
576608cfed6SMarkus Armbruster##
577608cfed6SMarkus Armbruster{ 'enum': 'VncVencryptSubAuth',
578608cfed6SMarkus Armbruster  'data': [ 'plain',
579608cfed6SMarkus Armbruster            'tls-none',  'x509-none',
580608cfed6SMarkus Armbruster            'tls-vnc',   'x509-vnc',
581608cfed6SMarkus Armbruster            'tls-plain', 'x509-plain',
58205eb4a25SMarc-André Lureau            'tls-sasl',  'x509-sasl' ],
5838a9f1e1dSMarc-André Lureau  'if': 'CONFIG_VNC' }
584608cfed6SMarkus Armbruster
585608cfed6SMarkus Armbruster##
586608cfed6SMarkus Armbruster# @VncServerInfo2:
587608cfed6SMarkus Armbruster#
588608cfed6SMarkus Armbruster# The network connection information for server
589608cfed6SMarkus Armbruster#
590608cfed6SMarkus Armbruster# @auth: The current authentication type used by the servers
591608cfed6SMarkus Armbruster#
592608cfed6SMarkus Armbruster# @vencrypt: The vencrypt sub authentication type used by the
593608cfed6SMarkus Armbruster#            servers, only specified in case auth == vencrypt.
594608cfed6SMarkus Armbruster#
595608cfed6SMarkus Armbruster# Since: 2.9
596608cfed6SMarkus Armbruster##
597608cfed6SMarkus Armbruster{ 'struct': 'VncServerInfo2',
598608cfed6SMarkus Armbruster  'base': 'VncBasicInfo',
599608cfed6SMarkus Armbruster  'data': { 'auth'      : 'VncPrimaryAuth',
60005eb4a25SMarc-André Lureau            '*vencrypt' : 'VncVencryptSubAuth' },
6018a9f1e1dSMarc-André Lureau  'if': 'CONFIG_VNC' }
602608cfed6SMarkus Armbruster
603608cfed6SMarkus Armbruster##
604608cfed6SMarkus Armbruster# @VncInfo2:
605608cfed6SMarkus Armbruster#
606608cfed6SMarkus Armbruster# Information about a vnc server
607608cfed6SMarkus Armbruster#
608608cfed6SMarkus Armbruster# @id: vnc server name.
609608cfed6SMarkus Armbruster#
610608cfed6SMarkus Armbruster# @server: A list of @VncBasincInfo describing all listening sockets.
611608cfed6SMarkus Armbruster#          The list can be empty (in case the vnc server is disabled).
612608cfed6SMarkus Armbruster#          It also may have multiple entries: normal + websocket,
613608cfed6SMarkus Armbruster#          possibly also ipv4 + ipv6 in the future.
614608cfed6SMarkus Armbruster#
615608cfed6SMarkus Armbruster# @clients: A list of @VncClientInfo of all currently connected clients.
616608cfed6SMarkus Armbruster#           The list can be empty, for obvious reasons.
617608cfed6SMarkus Armbruster#
618608cfed6SMarkus Armbruster# @auth: The current authentication type used by the non-websockets servers
619608cfed6SMarkus Armbruster#
620608cfed6SMarkus Armbruster# @vencrypt: The vencrypt authentication type used by the servers,
621608cfed6SMarkus Armbruster#            only specified in case auth == vencrypt.
622608cfed6SMarkus Armbruster#
623608cfed6SMarkus Armbruster# @display: The display device the vnc server is linked to.
624608cfed6SMarkus Armbruster#
625608cfed6SMarkus Armbruster# Since: 2.3
626608cfed6SMarkus Armbruster##
627608cfed6SMarkus Armbruster{ 'struct': 'VncInfo2',
628608cfed6SMarkus Armbruster  'data': { 'id'        : 'str',
629608cfed6SMarkus Armbruster            'server'    : ['VncServerInfo2'],
630608cfed6SMarkus Armbruster            'clients'   : ['VncClientInfo'],
631608cfed6SMarkus Armbruster            'auth'      : 'VncPrimaryAuth',
632608cfed6SMarkus Armbruster            '*vencrypt' : 'VncVencryptSubAuth',
63305eb4a25SMarc-André Lureau            '*display'  : 'str' },
6348a9f1e1dSMarc-André Lureau  'if': 'CONFIG_VNC' }
635608cfed6SMarkus Armbruster
636608cfed6SMarkus Armbruster##
637608cfed6SMarkus Armbruster# @query-vnc:
638608cfed6SMarkus Armbruster#
639608cfed6SMarkus Armbruster# Returns information about the current VNC server
640608cfed6SMarkus Armbruster#
641608cfed6SMarkus Armbruster# Returns: @VncInfo
642608cfed6SMarkus Armbruster#
6439bc6e893SMarkus Armbruster# Since: 0.14
644608cfed6SMarkus Armbruster#
645608cfed6SMarkus Armbruster# Example:
646608cfed6SMarkus Armbruster#
647608cfed6SMarkus Armbruster# -> { "execute": "query-vnc" }
648608cfed6SMarkus Armbruster# <- { "return": {
649608cfed6SMarkus Armbruster#          "enabled":true,
650608cfed6SMarkus Armbruster#          "host":"0.0.0.0",
651608cfed6SMarkus Armbruster#          "service":"50402",
652608cfed6SMarkus Armbruster#          "auth":"vnc",
653608cfed6SMarkus Armbruster#          "family":"ipv4",
654608cfed6SMarkus Armbruster#          "clients":[
655608cfed6SMarkus Armbruster#             {
656608cfed6SMarkus Armbruster#                "host":"127.0.0.1",
657608cfed6SMarkus Armbruster#                "service":"50401",
658608cfed6SMarkus Armbruster#                "family":"ipv4"
659608cfed6SMarkus Armbruster#             }
660608cfed6SMarkus Armbruster#          ]
661608cfed6SMarkus Armbruster#       }
662608cfed6SMarkus Armbruster#    }
663608cfed6SMarkus Armbruster#
664608cfed6SMarkus Armbruster##
66505eb4a25SMarc-André Lureau{ 'command': 'query-vnc', 'returns': 'VncInfo',
6668a9f1e1dSMarc-André Lureau  'if': 'CONFIG_VNC' }
667608cfed6SMarkus Armbruster##
668608cfed6SMarkus Armbruster# @query-vnc-servers:
669608cfed6SMarkus Armbruster#
670608cfed6SMarkus Armbruster# Returns a list of vnc servers.  The list can be empty.
671608cfed6SMarkus Armbruster#
672608cfed6SMarkus Armbruster# Returns: a list of @VncInfo2
673608cfed6SMarkus Armbruster#
674608cfed6SMarkus Armbruster# Since: 2.3
675608cfed6SMarkus Armbruster##
67605eb4a25SMarc-André Lureau{ 'command': 'query-vnc-servers', 'returns': ['VncInfo2'],
6778a9f1e1dSMarc-André Lureau  'if': 'CONFIG_VNC' }
678608cfed6SMarkus Armbruster
679608cfed6SMarkus Armbruster##
680608cfed6SMarkus Armbruster# @change-vnc-password:
681608cfed6SMarkus Armbruster#
682608cfed6SMarkus Armbruster# Change the VNC server password.
683608cfed6SMarkus Armbruster#
684608cfed6SMarkus Armbruster# @password: the new password to use with VNC authentication
685608cfed6SMarkus Armbruster#
686608cfed6SMarkus Armbruster# Since: 1.1
687608cfed6SMarkus Armbruster#
688608cfed6SMarkus Armbruster# Notes: An empty password in this command will set the password to the empty
689608cfed6SMarkus Armbruster#        string.  Existing clients are unaffected by executing this command.
690608cfed6SMarkus Armbruster##
691b0ddeba2SMarc-André Lureau{ 'command': 'change-vnc-password',
692b0ddeba2SMarc-André Lureau  'data': { 'password': 'str' },
6938a9f1e1dSMarc-André Lureau  'if': 'CONFIG_VNC' }
694608cfed6SMarkus Armbruster
695608cfed6SMarkus Armbruster##
696608cfed6SMarkus Armbruster# @VNC_CONNECTED:
697608cfed6SMarkus Armbruster#
698608cfed6SMarkus Armbruster# Emitted when a VNC client establishes a connection
699608cfed6SMarkus Armbruster#
700608cfed6SMarkus Armbruster# @server: server information
701608cfed6SMarkus Armbruster#
702608cfed6SMarkus Armbruster# @client: client information
703608cfed6SMarkus Armbruster#
704608cfed6SMarkus Armbruster# Note: This event is emitted before any authentication takes place, thus
705608cfed6SMarkus Armbruster#       the authentication ID is not provided
706608cfed6SMarkus Armbruster#
7079bc6e893SMarkus Armbruster# Since: 0.13
708608cfed6SMarkus Armbruster#
709608cfed6SMarkus Armbruster# Example:
710608cfed6SMarkus Armbruster#
711608cfed6SMarkus Armbruster# <- { "event": "VNC_CONNECTED",
712608cfed6SMarkus Armbruster#      "data": {
713608cfed6SMarkus Armbruster#            "server": { "auth": "sasl", "family": "ipv4",
714608cfed6SMarkus Armbruster#                        "service": "5901", "host": "0.0.0.0" },
715608cfed6SMarkus Armbruster#            "client": { "family": "ipv4", "service": "58425",
716608cfed6SMarkus Armbruster#                        "host": "127.0.0.1" } },
717608cfed6SMarkus Armbruster#      "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
718608cfed6SMarkus Armbruster#
719608cfed6SMarkus Armbruster##
720608cfed6SMarkus Armbruster{ 'event': 'VNC_CONNECTED',
721608cfed6SMarkus Armbruster  'data': { 'server': 'VncServerInfo',
72205eb4a25SMarc-André Lureau            'client': 'VncBasicInfo' },
7238a9f1e1dSMarc-André Lureau  'if': 'CONFIG_VNC' }
724608cfed6SMarkus Armbruster
725608cfed6SMarkus Armbruster##
726608cfed6SMarkus Armbruster# @VNC_INITIALIZED:
727608cfed6SMarkus Armbruster#
728608cfed6SMarkus Armbruster# Emitted after authentication takes place (if any) and the VNC session is
729608cfed6SMarkus Armbruster# made active
730608cfed6SMarkus Armbruster#
731608cfed6SMarkus Armbruster# @server: server information
732608cfed6SMarkus Armbruster#
733608cfed6SMarkus Armbruster# @client: client information
734608cfed6SMarkus Armbruster#
7359bc6e893SMarkus Armbruster# Since: 0.13
736608cfed6SMarkus Armbruster#
737608cfed6SMarkus Armbruster# Example:
738608cfed6SMarkus Armbruster#
739608cfed6SMarkus Armbruster# <-  { "event": "VNC_INITIALIZED",
740608cfed6SMarkus Armbruster#       "data": {
741608cfed6SMarkus Armbruster#            "server": { "auth": "sasl", "family": "ipv4",
742608cfed6SMarkus Armbruster#                        "service": "5901", "host": "0.0.0.0"},
743608cfed6SMarkus Armbruster#            "client": { "family": "ipv4", "service": "46089",
744608cfed6SMarkus Armbruster#                        "host": "127.0.0.1", "sasl_username": "luiz" } },
745608cfed6SMarkus Armbruster#       "timestamp": { "seconds": 1263475302, "microseconds": 150772 } }
746608cfed6SMarkus Armbruster#
747608cfed6SMarkus Armbruster##
748608cfed6SMarkus Armbruster{ 'event': 'VNC_INITIALIZED',
749608cfed6SMarkus Armbruster  'data': { 'server': 'VncServerInfo',
75005eb4a25SMarc-André Lureau            'client': 'VncClientInfo' },
7518a9f1e1dSMarc-André Lureau  'if': 'CONFIG_VNC' }
752608cfed6SMarkus Armbruster
753608cfed6SMarkus Armbruster##
754608cfed6SMarkus Armbruster# @VNC_DISCONNECTED:
755608cfed6SMarkus Armbruster#
756608cfed6SMarkus Armbruster# Emitted when the connection is closed
757608cfed6SMarkus Armbruster#
758608cfed6SMarkus Armbruster# @server: server information
759608cfed6SMarkus Armbruster#
760608cfed6SMarkus Armbruster# @client: client information
761608cfed6SMarkus Armbruster#
7629bc6e893SMarkus Armbruster# Since: 0.13
763608cfed6SMarkus Armbruster#
764608cfed6SMarkus Armbruster# Example:
765608cfed6SMarkus Armbruster#
766608cfed6SMarkus Armbruster# <- { "event": "VNC_DISCONNECTED",
767608cfed6SMarkus Armbruster#      "data": {
768608cfed6SMarkus Armbruster#            "server": { "auth": "sasl", "family": "ipv4",
769608cfed6SMarkus Armbruster#                        "service": "5901", "host": "0.0.0.0" },
770608cfed6SMarkus Armbruster#            "client": { "family": "ipv4", "service": "58425",
771608cfed6SMarkus Armbruster#                        "host": "127.0.0.1", "sasl_username": "luiz" } },
772608cfed6SMarkus Armbruster#      "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
773608cfed6SMarkus Armbruster#
774608cfed6SMarkus Armbruster##
775608cfed6SMarkus Armbruster{ 'event': 'VNC_DISCONNECTED',
776608cfed6SMarkus Armbruster  'data': { 'server': 'VncServerInfo',
77705eb4a25SMarc-André Lureau            'client': 'VncClientInfo' },
7788a9f1e1dSMarc-André Lureau  'if': 'CONFIG_VNC' }
779608cfed6SMarkus Armbruster
780608cfed6SMarkus Armbruster##
781608cfed6SMarkus Armbruster# = Input
782608cfed6SMarkus Armbruster##
783608cfed6SMarkus Armbruster
784608cfed6SMarkus Armbruster##
785608cfed6SMarkus Armbruster# @MouseInfo:
786608cfed6SMarkus Armbruster#
787608cfed6SMarkus Armbruster# Information about a mouse device.
788608cfed6SMarkus Armbruster#
789608cfed6SMarkus Armbruster# @name: the name of the mouse device
790608cfed6SMarkus Armbruster#
791608cfed6SMarkus Armbruster# @index: the index of the mouse device
792608cfed6SMarkus Armbruster#
793608cfed6SMarkus Armbruster# @current: true if this device is currently receiving mouse events
794608cfed6SMarkus Armbruster#
795608cfed6SMarkus Armbruster# @absolute: true if this device supports absolute coordinates as input
796608cfed6SMarkus Armbruster#
7979bc6e893SMarkus Armbruster# Since: 0.14
798608cfed6SMarkus Armbruster##
799608cfed6SMarkus Armbruster{ 'struct': 'MouseInfo',
800608cfed6SMarkus Armbruster  'data': {'name': 'str', 'index': 'int', 'current': 'bool',
801608cfed6SMarkus Armbruster           'absolute': 'bool'} }
802608cfed6SMarkus Armbruster
803608cfed6SMarkus Armbruster##
804608cfed6SMarkus Armbruster# @query-mice:
805608cfed6SMarkus Armbruster#
806608cfed6SMarkus Armbruster# Returns information about each active mouse device
807608cfed6SMarkus Armbruster#
808608cfed6SMarkus Armbruster# Returns: a list of @MouseInfo for each device
809608cfed6SMarkus Armbruster#
8109bc6e893SMarkus Armbruster# Since: 0.14
811608cfed6SMarkus Armbruster#
812608cfed6SMarkus Armbruster# Example:
813608cfed6SMarkus Armbruster#
814608cfed6SMarkus Armbruster# -> { "execute": "query-mice" }
815608cfed6SMarkus Armbruster# <- { "return": [
816608cfed6SMarkus Armbruster#          {
817608cfed6SMarkus Armbruster#             "name":"QEMU Microsoft Mouse",
818608cfed6SMarkus Armbruster#             "index":0,
819608cfed6SMarkus Armbruster#             "current":false,
820608cfed6SMarkus Armbruster#             "absolute":false
821608cfed6SMarkus Armbruster#          },
822608cfed6SMarkus Armbruster#          {
823608cfed6SMarkus Armbruster#             "name":"QEMU PS/2 Mouse",
824608cfed6SMarkus Armbruster#             "index":1,
825608cfed6SMarkus Armbruster#             "current":true,
826608cfed6SMarkus Armbruster#             "absolute":true
827608cfed6SMarkus Armbruster#          }
828608cfed6SMarkus Armbruster#       ]
829608cfed6SMarkus Armbruster#    }
830608cfed6SMarkus Armbruster#
831608cfed6SMarkus Armbruster##
832608cfed6SMarkus Armbruster{ 'command': 'query-mice', 'returns': ['MouseInfo'] }
833608cfed6SMarkus Armbruster
834608cfed6SMarkus Armbruster##
835608cfed6SMarkus Armbruster# @QKeyCode:
836608cfed6SMarkus Armbruster#
837608cfed6SMarkus Armbruster# An enumeration of key name.
838608cfed6SMarkus Armbruster#
839608cfed6SMarkus Armbruster# This is used by the @send-key command.
840608cfed6SMarkus Armbruster#
841608cfed6SMarkus Armbruster# @unmapped: since 2.0
842608cfed6SMarkus Armbruster# @pause: since 2.0
843608cfed6SMarkus Armbruster# @ro: since 2.4
844608cfed6SMarkus Armbruster# @kp_comma: since 2.4
845608cfed6SMarkus Armbruster# @kp_equals: since 2.6
846608cfed6SMarkus Armbruster# @power: since 2.6
847608cfed6SMarkus Armbruster# @hiragana: since 2.9
848608cfed6SMarkus Armbruster# @henkan: since 2.9
849608cfed6SMarkus Armbruster# @yen: since 2.9
850608cfed6SMarkus Armbruster#
851608cfed6SMarkus Armbruster# @sleep: since 2.10
852608cfed6SMarkus Armbruster# @wake: since 2.10
853608cfed6SMarkus Armbruster# @audionext: since 2.10
854608cfed6SMarkus Armbruster# @audioprev: since 2.10
855608cfed6SMarkus Armbruster# @audiostop: since 2.10
856608cfed6SMarkus Armbruster# @audioplay: since 2.10
857608cfed6SMarkus Armbruster# @audiomute: since 2.10
858608cfed6SMarkus Armbruster# @volumeup: since 2.10
859608cfed6SMarkus Armbruster# @volumedown: since 2.10
860608cfed6SMarkus Armbruster# @mediaselect: since 2.10
861608cfed6SMarkus Armbruster# @mail: since 2.10
862608cfed6SMarkus Armbruster# @calculator: since 2.10
863608cfed6SMarkus Armbruster# @computer: since 2.10
864608cfed6SMarkus Armbruster# @ac_home: since 2.10
865608cfed6SMarkus Armbruster# @ac_back: since 2.10
866608cfed6SMarkus Armbruster# @ac_forward: since 2.10
867608cfed6SMarkus Armbruster# @ac_refresh: since 2.10
868608cfed6SMarkus Armbruster# @ac_bookmarks: since 2.10
869608cfed6SMarkus Armbruster#
870280b8da3SMiika S# @muhenkan: since 2.12
871280b8da3SMiika S# @katakanahiragana: since 2.12
872280b8da3SMiika S#
873d7696ff8SAkihiko Odaki# @lang1: since 6.1
874d7696ff8SAkihiko Odaki# @lang2: since 6.1
875d7696ff8SAkihiko Odaki#
87680b857f0SDaniel P. Berrange# 'sysrq' was mistakenly added to hack around the fact that
87780b857f0SDaniel P. Berrange# the ps2 driver was not generating correct scancodes sequences
87880b857f0SDaniel P. Berrange# when 'alt+print' was pressed. This flaw is now fixed and the
87980b857f0SDaniel P. Berrange# 'sysrq' key serves no further purpose. Any further use of
88080b857f0SDaniel P. Berrange# 'sysrq' will be transparently changed to 'print', so they
88180b857f0SDaniel P. Berrange# are effectively synonyms.
88280b857f0SDaniel P. Berrange#
8839bc6e893SMarkus Armbruster# Since: 1.3
884608cfed6SMarkus Armbruster#
885608cfed6SMarkus Armbruster##
886608cfed6SMarkus Armbruster{ 'enum': 'QKeyCode',
887608cfed6SMarkus Armbruster  'data': [ 'unmapped',
888608cfed6SMarkus Armbruster            'shift', 'shift_r', 'alt', 'alt_r', 'ctrl',
889608cfed6SMarkus Armbruster            'ctrl_r', 'menu', 'esc', '1', '2', '3', '4', '5', '6', '7', '8',
890608cfed6SMarkus Armbruster            '9', '0', 'minus', 'equal', 'backspace', 'tab', 'q', 'w', 'e',
891608cfed6SMarkus Armbruster            'r', 't', 'y', 'u', 'i', 'o', 'p', 'bracket_left', 'bracket_right',
892608cfed6SMarkus Armbruster            'ret', 'a', 's', 'd', 'f', 'g', 'h', 'j', 'k', 'l', 'semicolon',
893608cfed6SMarkus Armbruster            'apostrophe', 'grave_accent', 'backslash', 'z', 'x', 'c', 'v', 'b',
894608cfed6SMarkus Armbruster            'n', 'm', 'comma', 'dot', 'slash', 'asterisk', 'spc', 'caps_lock',
895608cfed6SMarkus Armbruster            'f1', 'f2', 'f3', 'f4', 'f5', 'f6', 'f7', 'f8', 'f9', 'f10',
896608cfed6SMarkus Armbruster            'num_lock', 'scroll_lock', 'kp_divide', 'kp_multiply',
897608cfed6SMarkus Armbruster            'kp_subtract', 'kp_add', 'kp_enter', 'kp_decimal', 'sysrq', 'kp_0',
898608cfed6SMarkus Armbruster            'kp_1', 'kp_2', 'kp_3', 'kp_4', 'kp_5', 'kp_6', 'kp_7', 'kp_8',
899608cfed6SMarkus Armbruster            'kp_9', 'less', 'f11', 'f12', 'print', 'home', 'pgup', 'pgdn', 'end',
900608cfed6SMarkus Armbruster            'left', 'up', 'down', 'right', 'insert', 'delete', 'stop', 'again',
901608cfed6SMarkus Armbruster            'props', 'undo', 'front', 'copy', 'open', 'paste', 'find', 'cut',
902608cfed6SMarkus Armbruster            'lf', 'help', 'meta_l', 'meta_r', 'compose', 'pause',
903280b8da3SMiika S            'ro', 'hiragana', 'henkan', 'yen', 'muhenkan', 'katakanahiragana',
904608cfed6SMarkus Armbruster            'kp_comma', 'kp_equals', 'power', 'sleep', 'wake',
905608cfed6SMarkus Armbruster            'audionext', 'audioprev', 'audiostop', 'audioplay', 'audiomute',
906608cfed6SMarkus Armbruster            'volumeup', 'volumedown', 'mediaselect',
907608cfed6SMarkus Armbruster            'mail', 'calculator', 'computer',
908d7696ff8SAkihiko Odaki            'ac_home', 'ac_back', 'ac_forward', 'ac_refresh', 'ac_bookmarks',
909d7696ff8SAkihiko Odaki            'lang1', 'lang2' ] }
910608cfed6SMarkus Armbruster
911608cfed6SMarkus Armbruster##
9123cda299dSMarkus Armbruster# @KeyValueKind:
9133cda299dSMarkus Armbruster#
9143cda299dSMarkus Armbruster# Since: 1.3
9153cda299dSMarkus Armbruster##
9163cda299dSMarkus Armbruster{ 'enum': 'KeyValueKind',
9173cda299dSMarkus Armbruster  'data': [ 'number', 'qcode' ] }
9183cda299dSMarkus Armbruster
9193cda299dSMarkus Armbruster##
9203cda299dSMarkus Armbruster# @IntWrapper:
9213cda299dSMarkus Armbruster#
9223cda299dSMarkus Armbruster# Since: 1.3
9233cda299dSMarkus Armbruster##
9243cda299dSMarkus Armbruster{ 'struct': 'IntWrapper',
9253cda299dSMarkus Armbruster  'data': { 'data': 'int' } }
9263cda299dSMarkus Armbruster
9273cda299dSMarkus Armbruster##
9283cda299dSMarkus Armbruster# @QKeyCodeWrapper:
9293cda299dSMarkus Armbruster#
9303cda299dSMarkus Armbruster# Since: 1.3
9313cda299dSMarkus Armbruster##
9323cda299dSMarkus Armbruster{ 'struct': 'QKeyCodeWrapper',
9333cda299dSMarkus Armbruster  'data': { 'data': 'QKeyCode' } }
9343cda299dSMarkus Armbruster
9353cda299dSMarkus Armbruster##
936608cfed6SMarkus Armbruster# @KeyValue:
937608cfed6SMarkus Armbruster#
938608cfed6SMarkus Armbruster# Represents a keyboard key.
939608cfed6SMarkus Armbruster#
9409bc6e893SMarkus Armbruster# Since: 1.3
941608cfed6SMarkus Armbruster##
942608cfed6SMarkus Armbruster{ 'union': 'KeyValue',
9433cda299dSMarkus Armbruster  'base': { 'type': 'KeyValueKind' },
9443cda299dSMarkus Armbruster  'discriminator': 'type',
945608cfed6SMarkus Armbruster  'data': {
9463cda299dSMarkus Armbruster    'number': 'IntWrapper',
9473cda299dSMarkus Armbruster    'qcode': 'QKeyCodeWrapper' } }
948608cfed6SMarkus Armbruster
949608cfed6SMarkus Armbruster##
950608cfed6SMarkus Armbruster# @send-key:
951608cfed6SMarkus Armbruster#
952608cfed6SMarkus Armbruster# Send keys to guest.
953608cfed6SMarkus Armbruster#
954608cfed6SMarkus Armbruster# @keys: An array of @KeyValue elements. All @KeyValues in this array are
955608cfed6SMarkus Armbruster#        simultaneously sent to the guest. A @KeyValue.number value is sent
956608cfed6SMarkus Armbruster#        directly to the guest, while @KeyValue.qcode must be a valid
957608cfed6SMarkus Armbruster#        @QKeyCode value
958608cfed6SMarkus Armbruster#
959608cfed6SMarkus Armbruster# @hold-time: time to delay key up events, milliseconds. Defaults
960608cfed6SMarkus Armbruster#             to 100
961608cfed6SMarkus Armbruster#
962e050e426SPeter Maydell# Returns: - Nothing on success
963e050e426SPeter Maydell#          - If key is unknown or redundant, InvalidParameter
964608cfed6SMarkus Armbruster#
9659bc6e893SMarkus Armbruster# Since: 1.3
966608cfed6SMarkus Armbruster#
967608cfed6SMarkus Armbruster# Example:
968608cfed6SMarkus Armbruster#
969608cfed6SMarkus Armbruster# -> { "execute": "send-key",
970608cfed6SMarkus Armbruster#      "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
971608cfed6SMarkus Armbruster#                               { "type": "qcode", "data": "alt" },
972608cfed6SMarkus Armbruster#                               { "type": "qcode", "data": "delete" } ] } }
973608cfed6SMarkus Armbruster# <- { "return": {} }
974608cfed6SMarkus Armbruster#
975608cfed6SMarkus Armbruster##
976608cfed6SMarkus Armbruster{ 'command': 'send-key',
977608cfed6SMarkus Armbruster  'data': { 'keys': ['KeyValue'], '*hold-time': 'int' } }
978608cfed6SMarkus Armbruster
979608cfed6SMarkus Armbruster##
980608cfed6SMarkus Armbruster# @InputButton:
981608cfed6SMarkus Armbruster#
982608cfed6SMarkus Armbruster# Button of a pointer input device (mouse, tablet).
983608cfed6SMarkus Armbruster#
984608cfed6SMarkus Armbruster# @side: front side button of a 5-button mouse (since 2.9)
985608cfed6SMarkus Armbruster#
986608cfed6SMarkus Armbruster# @extra: rear side button of a 5-button mouse (since 2.9)
987608cfed6SMarkus Armbruster#
988608cfed6SMarkus Armbruster# Since: 2.0
989608cfed6SMarkus Armbruster##
990608cfed6SMarkus Armbruster{ 'enum'  : 'InputButton',
991608cfed6SMarkus Armbruster  'data'  : [ 'left', 'middle', 'right', 'wheel-up', 'wheel-down', 'side',
99264ebbb7dSDmitry Petrov  'extra', 'wheel-left', 'wheel-right' ] }
993608cfed6SMarkus Armbruster
994608cfed6SMarkus Armbruster##
995608cfed6SMarkus Armbruster# @InputAxis:
996608cfed6SMarkus Armbruster#
997608cfed6SMarkus Armbruster# Position axis of a pointer input device (mouse, tablet).
998608cfed6SMarkus Armbruster#
999608cfed6SMarkus Armbruster# Since: 2.0
1000608cfed6SMarkus Armbruster##
1001608cfed6SMarkus Armbruster{ 'enum'  : 'InputAxis',
1002608cfed6SMarkus Armbruster  'data'  : [ 'x', 'y' ] }
1003608cfed6SMarkus Armbruster
1004608cfed6SMarkus Armbruster##
1005608cfed6SMarkus Armbruster# @InputKeyEvent:
1006608cfed6SMarkus Armbruster#
1007608cfed6SMarkus Armbruster# Keyboard input event.
1008608cfed6SMarkus Armbruster#
1009608cfed6SMarkus Armbruster# @key:    Which key this event is for.
1010608cfed6SMarkus Armbruster# @down:   True for key-down and false for key-up events.
1011608cfed6SMarkus Armbruster#
1012608cfed6SMarkus Armbruster# Since: 2.0
1013608cfed6SMarkus Armbruster##
1014608cfed6SMarkus Armbruster{ 'struct'  : 'InputKeyEvent',
1015608cfed6SMarkus Armbruster  'data'  : { 'key'     : 'KeyValue',
1016608cfed6SMarkus Armbruster              'down'    : 'bool' } }
1017608cfed6SMarkus Armbruster
1018608cfed6SMarkus Armbruster##
1019608cfed6SMarkus Armbruster# @InputBtnEvent:
1020608cfed6SMarkus Armbruster#
1021608cfed6SMarkus Armbruster# Pointer button input event.
1022608cfed6SMarkus Armbruster#
1023608cfed6SMarkus Armbruster# @button: Which button this event is for.
1024608cfed6SMarkus Armbruster# @down:   True for key-down and false for key-up events.
1025608cfed6SMarkus Armbruster#
1026608cfed6SMarkus Armbruster# Since: 2.0
1027608cfed6SMarkus Armbruster##
1028608cfed6SMarkus Armbruster{ 'struct'  : 'InputBtnEvent',
1029608cfed6SMarkus Armbruster  'data'  : { 'button'  : 'InputButton',
1030608cfed6SMarkus Armbruster              'down'    : 'bool' } }
1031608cfed6SMarkus Armbruster
1032608cfed6SMarkus Armbruster##
1033608cfed6SMarkus Armbruster# @InputMoveEvent:
1034608cfed6SMarkus Armbruster#
1035608cfed6SMarkus Armbruster# Pointer motion input event.
1036608cfed6SMarkus Armbruster#
1037608cfed6SMarkus Armbruster# @axis: Which axis is referenced by @value.
1038608cfed6SMarkus Armbruster# @value: Pointer position.  For absolute coordinates the
1039608cfed6SMarkus Armbruster#         valid range is 0 -> 0x7ffff
1040608cfed6SMarkus Armbruster#
1041608cfed6SMarkus Armbruster# Since: 2.0
1042608cfed6SMarkus Armbruster##
1043608cfed6SMarkus Armbruster{ 'struct'  : 'InputMoveEvent',
1044608cfed6SMarkus Armbruster  'data'  : { 'axis'    : 'InputAxis',
1045608cfed6SMarkus Armbruster              'value'   : 'int' } }
1046608cfed6SMarkus Armbruster
1047608cfed6SMarkus Armbruster##
1048b6fd5434SMarkus Armbruster# @InputEventKind:
1049b6fd5434SMarkus Armbruster#
1050b6fd5434SMarkus Armbruster# Since: 2.0
1051b6fd5434SMarkus Armbruster##
1052b6fd5434SMarkus Armbruster{ 'enum': 'InputEventKind',
1053b6fd5434SMarkus Armbruster  'data': [ 'key', 'btn', 'rel', 'abs' ] }
1054b6fd5434SMarkus Armbruster
1055b6fd5434SMarkus Armbruster##
1056b6fd5434SMarkus Armbruster# @InputKeyEventWrapper:
1057b6fd5434SMarkus Armbruster#
1058b6fd5434SMarkus Armbruster# Since: 2.0
1059b6fd5434SMarkus Armbruster##
1060b6fd5434SMarkus Armbruster{ 'struct': 'InputKeyEventWrapper',
1061b6fd5434SMarkus Armbruster  'data': { 'data': 'InputKeyEvent' } }
1062b6fd5434SMarkus Armbruster
1063b6fd5434SMarkus Armbruster##
1064b6fd5434SMarkus Armbruster# @InputBtnEventWrapper:
1065b6fd5434SMarkus Armbruster#
1066b6fd5434SMarkus Armbruster# Since: 2.0
1067b6fd5434SMarkus Armbruster##
1068b6fd5434SMarkus Armbruster{ 'struct': 'InputBtnEventWrapper',
1069b6fd5434SMarkus Armbruster  'data': { 'data': 'InputBtnEvent' } }
1070b6fd5434SMarkus Armbruster
1071b6fd5434SMarkus Armbruster##
1072b6fd5434SMarkus Armbruster# @InputMoveEventWrapper:
1073b6fd5434SMarkus Armbruster#
1074b6fd5434SMarkus Armbruster# Since: 2.0
1075b6fd5434SMarkus Armbruster##
1076b6fd5434SMarkus Armbruster{ 'struct': 'InputMoveEventWrapper',
1077b6fd5434SMarkus Armbruster  'data': { 'data': 'InputMoveEvent' } }
1078b6fd5434SMarkus Armbruster
1079b6fd5434SMarkus Armbruster##
1080608cfed6SMarkus Armbruster# @InputEvent:
1081608cfed6SMarkus Armbruster#
1082608cfed6SMarkus Armbruster# Input event union.
1083608cfed6SMarkus Armbruster#
1084608cfed6SMarkus Armbruster# @type: the input type, one of:
1085100cc4feSPeter Maydell#
1086608cfed6SMarkus Armbruster#        - 'key': Input event of Keyboard
1087608cfed6SMarkus Armbruster#        - 'btn': Input event of pointer buttons
1088608cfed6SMarkus Armbruster#        - 'rel': Input event of relative pointer motion
1089608cfed6SMarkus Armbruster#        - 'abs': Input event of absolute pointer motion
1090608cfed6SMarkus Armbruster#
1091608cfed6SMarkus Armbruster# Since: 2.0
1092608cfed6SMarkus Armbruster##
1093608cfed6SMarkus Armbruster{ 'union' : 'InputEvent',
1094b6fd5434SMarkus Armbruster  'base': { 'type': 'InputEventKind' },
1095b6fd5434SMarkus Armbruster  'discriminator': 'type',
1096b6fd5434SMarkus Armbruster  'data'  : { 'key'     : 'InputKeyEventWrapper',
1097b6fd5434SMarkus Armbruster              'btn'     : 'InputBtnEventWrapper',
1098b6fd5434SMarkus Armbruster              'rel'     : 'InputMoveEventWrapper',
1099b6fd5434SMarkus Armbruster              'abs'     : 'InputMoveEventWrapper' } }
1100608cfed6SMarkus Armbruster
1101608cfed6SMarkus Armbruster##
1102608cfed6SMarkus Armbruster# @input-send-event:
1103608cfed6SMarkus Armbruster#
1104608cfed6SMarkus Armbruster# Send input event(s) to guest.
1105608cfed6SMarkus Armbruster#
1106608cfed6SMarkus Armbruster# The @device and @head parameters can be used to send the input event
1107608cfed6SMarkus Armbruster# to specific input devices in case (a) multiple input devices of the
1108608cfed6SMarkus Armbruster# same kind are added to the virtual machine and (b) you have
1109608cfed6SMarkus Armbruster# configured input routing (see docs/multiseat.txt) for those input
1110608cfed6SMarkus Armbruster# devices.  The parameters work exactly like the device and head
1111608cfed6SMarkus Armbruster# properties of input devices.  If @device is missing, only devices
1112608cfed6SMarkus Armbruster# that have no input routing config are admissible.  If @device is
1113608cfed6SMarkus Armbruster# specified, both input devices with and without input routing config
1114608cfed6SMarkus Armbruster# are admissible, but devices with input routing config take
1115608cfed6SMarkus Armbruster# precedence.
1116608cfed6SMarkus Armbruster#
111743d7c2d0SPeter Maydell# @device: display device to send event(s) to.
111843d7c2d0SPeter Maydell# @head: head to send event(s) to, in case the
111943d7c2d0SPeter Maydell#        display device supports multiple scanouts.
112043d7c2d0SPeter Maydell# @events: List of InputEvent union.
112143d7c2d0SPeter Maydell#
112243d7c2d0SPeter Maydell# Returns: Nothing on success.
112343d7c2d0SPeter Maydell#
1124608cfed6SMarkus Armbruster# Since: 2.6
1125608cfed6SMarkus Armbruster#
1126608cfed6SMarkus Armbruster# Note: The consoles are visible in the qom tree, under
1127608cfed6SMarkus Armbruster#       /backend/console[$index]. They have a device link and head property,
1128608cfed6SMarkus Armbruster#       so it is possible to map which console belongs to which device and
1129608cfed6SMarkus Armbruster#       display.
1130608cfed6SMarkus Armbruster#
1131608cfed6SMarkus Armbruster# Example:
1132608cfed6SMarkus Armbruster#
1133608cfed6SMarkus Armbruster# 1. Press left mouse button.
1134608cfed6SMarkus Armbruster#
1135608cfed6SMarkus Armbruster# -> { "execute": "input-send-event",
1136608cfed6SMarkus Armbruster#     "arguments": { "device": "video0",
1137608cfed6SMarkus Armbruster#                    "events": [ { "type": "btn",
1138608cfed6SMarkus Armbruster#                    "data" : { "down": true, "button": "left" } } ] } }
1139608cfed6SMarkus Armbruster# <- { "return": {} }
1140608cfed6SMarkus Armbruster#
1141608cfed6SMarkus Armbruster# -> { "execute": "input-send-event",
1142608cfed6SMarkus Armbruster#     "arguments": { "device": "video0",
1143608cfed6SMarkus Armbruster#                    "events": [ { "type": "btn",
1144608cfed6SMarkus Armbruster#                    "data" : { "down": false, "button": "left" } } ] } }
1145608cfed6SMarkus Armbruster# <- { "return": {} }
1146608cfed6SMarkus Armbruster#
1147608cfed6SMarkus Armbruster# 2. Press ctrl-alt-del.
1148608cfed6SMarkus Armbruster#
1149608cfed6SMarkus Armbruster# -> { "execute": "input-send-event",
1150608cfed6SMarkus Armbruster#      "arguments": { "events": [
1151608cfed6SMarkus Armbruster#         { "type": "key", "data" : { "down": true,
1152608cfed6SMarkus Armbruster#           "key": {"type": "qcode", "data": "ctrl" } } },
1153608cfed6SMarkus Armbruster#         { "type": "key", "data" : { "down": true,
1154608cfed6SMarkus Armbruster#           "key": {"type": "qcode", "data": "alt" } } },
1155608cfed6SMarkus Armbruster#         { "type": "key", "data" : { "down": true,
1156608cfed6SMarkus Armbruster#           "key": {"type": "qcode", "data": "delete" } } } ] } }
1157608cfed6SMarkus Armbruster# <- { "return": {} }
1158608cfed6SMarkus Armbruster#
1159608cfed6SMarkus Armbruster# 3. Move mouse pointer to absolute coordinates (20000, 400).
1160608cfed6SMarkus Armbruster#
1161608cfed6SMarkus Armbruster# -> { "execute": "input-send-event" ,
1162608cfed6SMarkus Armbruster#   "arguments": { "events": [
1163608cfed6SMarkus Armbruster#                { "type": "abs", "data" : { "axis": "x", "value" : 20000 } },
1164608cfed6SMarkus Armbruster#                { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } }
1165608cfed6SMarkus Armbruster# <- { "return": {} }
1166608cfed6SMarkus Armbruster#
1167608cfed6SMarkus Armbruster##
1168608cfed6SMarkus Armbruster{ 'command': 'input-send-event',
1169608cfed6SMarkus Armbruster  'data': { '*device': 'str',
1170608cfed6SMarkus Armbruster            '*head'  : 'int',
1171608cfed6SMarkus Armbruster            'events' : [ 'InputEvent' ] } }
11720c8d7065SGerd Hoffmann
11732657846fSRyan El Kochta##
11740c8d7065SGerd Hoffmann# @DisplayGTK:
11750c8d7065SGerd Hoffmann#
11760c8d7065SGerd Hoffmann# GTK display options.
11770c8d7065SGerd Hoffmann#
11780c8d7065SGerd Hoffmann# @grab-on-hover: Grab keyboard input on mouse hover.
1179e8b1386eSGerd Hoffmann# @zoom-to-fit: Zoom guest display to fit into the host window.  When
1180e8b1386eSGerd Hoffmann#               turned off the host window will be resized instead.
1181e8b1386eSGerd Hoffmann#               In case the display device can notify the guest on
1182e8b1386eSGerd Hoffmann#               window resizes (virtio-gpu) this will default to "on",
1183e8b1386eSGerd Hoffmann#               assuming the guest will resize the display to match
1184e8b1386eSGerd Hoffmann#               the window size then.  Otherwise it defaults to "off".
1185e8b1386eSGerd Hoffmann#               Since 3.1
11860c8d7065SGerd Hoffmann#
11870c8d7065SGerd Hoffmann# Since: 2.12
11880c8d7065SGerd Hoffmann#
11890c8d7065SGerd Hoffmann##
11900c8d7065SGerd Hoffmann{ 'struct'  : 'DisplayGTK',
1191e8b1386eSGerd Hoffmann  'data'    : { '*grab-on-hover' : 'bool',
1192e8b1386eSGerd Hoffmann                '*zoom-to-fit'   : 'bool'  } }
11930c8d7065SGerd Hoffmann
11940c8d7065SGerd Hoffmann##
1195d4dc4ab1SErik Skultety# @DisplayEGLHeadless:
1196d4dc4ab1SErik Skultety#
1197d4dc4ab1SErik Skultety# EGL headless display options.
1198d4dc4ab1SErik Skultety#
1199d4dc4ab1SErik Skultety# @rendernode: Which DRM render node should be used. Default is the first
1200d4dc4ab1SErik Skultety#              available node on the host.
1201d4dc4ab1SErik Skultety#
1202d4dc4ab1SErik Skultety# Since: 3.1
1203d4dc4ab1SErik Skultety#
1204d4dc4ab1SErik Skultety##
1205d4dc4ab1SErik Skultety{ 'struct'  : 'DisplayEGLHeadless',
1206d4dc4ab1SErik Skultety  'data'    : { '*rendernode' : 'str' } }
1207d4dc4ab1SErik Skultety
1208d4dc4ab1SErik Skultety##
1209142ca628SMarc-André Lureau# @DisplayDBus:
1210142ca628SMarc-André Lureau#
1211142ca628SMarc-André Lureau# DBus display options.
1212142ca628SMarc-André Lureau#
1213142ca628SMarc-André Lureau# @addr: The D-Bus bus address (default to the session bus).
1214142ca628SMarc-André Lureau#
1215142ca628SMarc-André Lureau# @rendernode: Which DRM render node should be used. Default is the first
1216142ca628SMarc-André Lureau#              available node on the host.
1217142ca628SMarc-André Lureau#
121899997823SMarc-André Lureau# @p2p: Whether to use peer-to-peer connections (accepted through
121999997823SMarc-André Lureau#       ``add_client``).
122099997823SMarc-André Lureau#
1221739362d4SMarc-André Lureau# @audiodev: Use the specified DBus audiodev to export audio.
1222739362d4SMarc-André Lureau#
1223142ca628SMarc-André Lureau# Since: 7.0
1224142ca628SMarc-André Lureau#
1225142ca628SMarc-André Lureau##
1226142ca628SMarc-André Lureau{ 'struct'  : 'DisplayDBus',
1227142ca628SMarc-André Lureau  'data'    : { '*rendernode' : 'str',
122899997823SMarc-André Lureau                '*addr': 'str',
1229739362d4SMarc-André Lureau                '*p2p': 'bool',
1230739362d4SMarc-André Lureau                '*audiodev': 'str' } }
1231142ca628SMarc-André Lureau
1232142ca628SMarc-André Lureau ##
123362f27922SElie Tournier # @DisplayGLMode:
123462f27922SElie Tournier #
123562f27922SElie Tournier # Display OpenGL mode.
123662f27922SElie Tournier #
123762f27922SElie Tournier # @off: Disable OpenGL (default).
123862f27922SElie Tournier # @on: Use OpenGL, pick context type automatically.
123962f27922SElie Tournier #      Would better be named 'auto' but is called 'on' for backward
124062f27922SElie Tournier #      compatibility with bool type.
124162f27922SElie Tournier # @core: Use OpenGL with Core (desktop) Context.
124262f27922SElie Tournier # @es: Use OpenGL with ES (embedded systems) Context.
124362f27922SElie Tournier #
124451f63ec7SPeter Maydell # Since: 3.0
124562f27922SElie Tournier #
124662f27922SElie Tournier ##
124762f27922SElie Tournier{ 'enum'    : 'DisplayGLMode',
124862f27922SElie Tournier  'data'    : [ 'off', 'on', 'core', 'es' ] }
124962f27922SElie Tournier
125062f27922SElie Tournier##
12512f8b7cd5SSamuel Thibault# @DisplayCurses:
12522f8b7cd5SSamuel Thibault#
12532f8b7cd5SSamuel Thibault# Curses display options.
12542f8b7cd5SSamuel Thibault#
12552f8b7cd5SSamuel Thibault# @charset:       Font charset used by guest (default: CP437).
12562f8b7cd5SSamuel Thibault#
12572f8b7cd5SSamuel Thibault# Since: 4.0
12582f8b7cd5SSamuel Thibault#
12592f8b7cd5SSamuel Thibault##
12602f8b7cd5SSamuel Thibault{ 'struct'  : 'DisplayCurses',
12612f8b7cd5SSamuel Thibault  'data'    : { '*charset'       : 'str' } }
12622f8b7cd5SSamuel Thibault
12632f8b7cd5SSamuel Thibault##
126448941a52SCarwyn Ellis# @DisplayCocoa:
126548941a52SCarwyn Ellis#
126648941a52SCarwyn Ellis# Cocoa display options.
126748941a52SCarwyn Ellis#
126848941a52SCarwyn Ellis# @left-command-key: Enable/disable forwarding of left command key to
126948941a52SCarwyn Ellis#                    guest. Allows command-tab window switching on the
127048941a52SCarwyn Ellis#                    host without sending this key to the guest when
127148941a52SCarwyn Ellis#                    "off". Defaults to "on"
127248941a52SCarwyn Ellis#
1273f844cdb9SGustavo Noronha Silva# @full-grab: Capture all key presses, including system combos. This
1274f844cdb9SGustavo Noronha Silva#             requires accessibility permissions, since it performs
1275f844cdb9SGustavo Noronha Silva#             a global grab on key events. (default: off)
1276f844cdb9SGustavo Noronha Silva#             See https://support.apple.com/en-in/guide/mac-help/mh32356/mac
1277f844cdb9SGustavo Noronha Silva#
1278*4797adceSGustavo Noronha Silva# @swap-opt-cmd: Swap the Option and Command keys so that their key codes match
1279*4797adceSGustavo Noronha Silva#                their position on non-Mac keyboards and you can use Meta/Super
1280*4797adceSGustavo Noronha Silva#                and Alt where you expect them. (default: off)
1281*4797adceSGustavo Noronha Silva#
128248941a52SCarwyn Ellis# Since: 7.0
128348941a52SCarwyn Ellis##
128448941a52SCarwyn Ellis{ 'struct': 'DisplayCocoa',
128548941a52SCarwyn Ellis  'data': {
1286f844cdb9SGustavo Noronha Silva      '*left-command-key': 'bool',
1287*4797adceSGustavo Noronha Silva      '*full-grab': 'bool',
1288*4797adceSGustavo Noronha Silva      '*swap-opt-cmd': 'bool'
128948941a52SCarwyn Ellis  } }
129048941a52SCarwyn Ellis
129148941a52SCarwyn Ellis##
12920c8d7065SGerd Hoffmann# @DisplayType:
12930c8d7065SGerd Hoffmann#
12940c8d7065SGerd Hoffmann# Display (user interface) type.
12950c8d7065SGerd Hoffmann#
129642176d77SMarc-André Lureau# @default: The default user interface, selecting from the first available
129742176d77SMarc-André Lureau#           of gtk, sdl, cocoa, and vnc.
129842176d77SMarc-André Lureau#
129942176d77SMarc-André Lureau# @none: No user interface or video output display. The guest will
130042176d77SMarc-André Lureau#        still see an emulated graphics card, but its output will not
130142176d77SMarc-André Lureau#        be displayed to the QEMU user.
130242176d77SMarc-André Lureau#
130342176d77SMarc-André Lureau# @gtk: The GTK user interface.
130442176d77SMarc-André Lureau#
130542176d77SMarc-André Lureau# @sdl: The SDL user interface.
130642176d77SMarc-André Lureau#
130742176d77SMarc-André Lureau# @egl-headless: No user interface, offload GL operations to a local
130842176d77SMarc-André Lureau#                DRI device. Graphical display need to be paired with
130942176d77SMarc-André Lureau#                VNC or Spice. (Since 3.1)
131042176d77SMarc-André Lureau#
131142176d77SMarc-André Lureau# @curses: Display video output via curses.  For graphics device
131242176d77SMarc-André Lureau#          models which support a text mode, QEMU can display this
131342176d77SMarc-André Lureau#          output using a curses/ncurses interface. Nothing is
131442176d77SMarc-André Lureau#          displayed when the graphics device is in graphical mode or
131542176d77SMarc-André Lureau#          if the graphics device does not support a text
131642176d77SMarc-André Lureau#          mode. Generally only the VGA device models support text
131742176d77SMarc-André Lureau#          mode.
131842176d77SMarc-André Lureau#
131942176d77SMarc-André Lureau# @cocoa: The Cocoa user interface.
132042176d77SMarc-André Lureau#
1321d8aec9d9SMarc-André Lureau# @spice-app: Set up a Spice server and run the default associated
1322d8aec9d9SMarc-André Lureau#             application to connect to it. The server will redirect
1323d8aec9d9SMarc-André Lureau#             the serial console and QEMU monitors. (Since 4.0)
1324d8aec9d9SMarc-André Lureau#
1325142ca628SMarc-André Lureau# @dbus: Start a D-Bus service for the display. (Since 7.0)
1326142ca628SMarc-André Lureau#
13270c8d7065SGerd Hoffmann# Since: 2.12
13280c8d7065SGerd Hoffmann#
13290c8d7065SGerd Hoffmann##
13300c8d7065SGerd Hoffmann{ 'enum'    : 'DisplayType',
133166c2207fSThomas Huth  'data'    : [
133266c2207fSThomas Huth    { 'name': 'default' },
133366c2207fSThomas Huth    { 'name': 'none' },
13348a9f1e1dSMarc-André Lureau    { 'name': 'gtk', 'if': 'CONFIG_GTK' },
13358a9f1e1dSMarc-André Lureau    { 'name': 'sdl', 'if': 'CONFIG_SDL' },
133666c2207fSThomas Huth    { 'name': 'egl-headless',
13378a9f1e1dSMarc-André Lureau              'if': { 'all': ['CONFIG_OPENGL', 'CONFIG_GBM'] } },
13388a9f1e1dSMarc-André Lureau    { 'name': 'curses', 'if': 'CONFIG_CURSES' },
13398a9f1e1dSMarc-André Lureau    { 'name': 'cocoa', 'if': 'CONFIG_COCOA' },
1340142ca628SMarc-André Lureau    { 'name': 'spice-app', 'if': 'CONFIG_SPICE' },
1341142ca628SMarc-André Lureau    { 'name': 'dbus', 'if': 'CONFIG_DBUS_DISPLAY' }
1342142ca628SMarc-André Lureau  ]
1343142ca628SMarc-André Lureau}
13440c8d7065SGerd Hoffmann
13450c8d7065SGerd Hoffmann##
13460c8d7065SGerd Hoffmann# @DisplayOptions:
13470c8d7065SGerd Hoffmann#
13480c8d7065SGerd Hoffmann# Display (user interface) options.
13490c8d7065SGerd Hoffmann#
13500c8d7065SGerd Hoffmann# @type:          Which DisplayType qemu should use.
13510c8d7065SGerd Hoffmann# @full-screen:   Start user interface in fullscreen mode (default: off).
13520c8d7065SGerd Hoffmann# @window-close:  Allow to quit qemu with window close button (default: on).
13537027bdd7SGerd Hoffmann# @show-cursor:   Force showing the mouse cursor (default: off).
13547027bdd7SGerd Hoffmann#                 (since: 5.0)
13550c8d7065SGerd Hoffmann# @gl:            Enable OpenGL support (default: off).
13560c8d7065SGerd Hoffmann#
13570c8d7065SGerd Hoffmann# Since: 2.12
13580c8d7065SGerd Hoffmann#
13590c8d7065SGerd Hoffmann##
13600c8d7065SGerd Hoffmann{ 'union'   : 'DisplayOptions',
13610c8d7065SGerd Hoffmann  'base'    : { 'type'           : 'DisplayType',
13620c8d7065SGerd Hoffmann                '*full-screen'   : 'bool',
13630c8d7065SGerd Hoffmann                '*window-close'  : 'bool',
13647027bdd7SGerd Hoffmann                '*show-cursor'   : 'bool',
136562f27922SElie Tournier                '*gl'            : 'DisplayGLMode' },
13660c8d7065SGerd Hoffmann  'discriminator' : 'type',
136766c2207fSThomas Huth  'data'    : {
13688a9f1e1dSMarc-André Lureau      'gtk': { 'type': 'DisplayGTK', 'if': 'CONFIG_GTK' },
136948941a52SCarwyn Ellis      'cocoa': { 'type': 'DisplayCocoa', 'if': 'CONFIG_COCOA' },
13708a9f1e1dSMarc-André Lureau      'curses': { 'type': 'DisplayCurses', 'if': 'CONFIG_CURSES' },
137166c2207fSThomas Huth      'egl-headless': { 'type': 'DisplayEGLHeadless',
1372142ca628SMarc-André Lureau                        'if': { 'all': ['CONFIG_OPENGL', 'CONFIG_GBM'] } },
1373142ca628SMarc-André Lureau      'dbus': { 'type': 'DisplayDBus', 'if': 'CONFIG_DBUS_DISPLAY' }
137466c2207fSThomas Huth  }
137566c2207fSThomas Huth}
1376e1ca8f7eSGerd Hoffmann
1377e1ca8f7eSGerd Hoffmann##
1378e1ca8f7eSGerd Hoffmann# @query-display-options:
1379e1ca8f7eSGerd Hoffmann#
1380e1ca8f7eSGerd Hoffmann# Returns information about display configuration
1381e1ca8f7eSGerd Hoffmann#
1382e1ca8f7eSGerd Hoffmann# Returns: @DisplayOptions
1383e1ca8f7eSGerd Hoffmann#
1384e1ca8f7eSGerd Hoffmann# Since: 3.1
1385e1ca8f7eSGerd Hoffmann#
1386e1ca8f7eSGerd Hoffmann##
1387e1ca8f7eSGerd Hoffmann{ 'command': 'query-display-options',
1388e1ca8f7eSGerd Hoffmann  'returns': 'DisplayOptions' }
13899cc07651SZihao Chang
13909cc07651SZihao Chang##
13919cc07651SZihao Chang# @DisplayReloadType:
13929cc07651SZihao Chang#
13939cc07651SZihao Chang# Available DisplayReload types.
13949cc07651SZihao Chang#
13959cc07651SZihao Chang# @vnc: VNC display
13969cc07651SZihao Chang#
13979cc07651SZihao Chang# Since: 6.0
13989cc07651SZihao Chang#
13999cc07651SZihao Chang##
14009cc07651SZihao Chang{ 'enum': 'DisplayReloadType',
14019cc07651SZihao Chang  'data': ['vnc'] }
14029cc07651SZihao Chang
14039cc07651SZihao Chang##
14049cc07651SZihao Chang# @DisplayReloadOptionsVNC:
14059cc07651SZihao Chang#
14069cc07651SZihao Chang# Specify the VNC reload options.
14079cc07651SZihao Chang#
14089cc07651SZihao Chang# @tls-certs: reload tls certs or not.
14099cc07651SZihao Chang#
14109cc07651SZihao Chang# Since: 6.0
14119cc07651SZihao Chang#
14129cc07651SZihao Chang##
14139cc07651SZihao Chang{ 'struct': 'DisplayReloadOptionsVNC',
14149cc07651SZihao Chang  'data': { '*tls-certs': 'bool' } }
14159cc07651SZihao Chang
14169cc07651SZihao Chang##
14179cc07651SZihao Chang# @DisplayReloadOptions:
14189cc07651SZihao Chang#
14199cc07651SZihao Chang# Options of the display configuration reload.
14209cc07651SZihao Chang#
14219cc07651SZihao Chang# @type: Specify the display type.
14229cc07651SZihao Chang#
14239cc07651SZihao Chang# Since: 6.0
14249cc07651SZihao Chang#
14259cc07651SZihao Chang##
14269cc07651SZihao Chang{ 'union': 'DisplayReloadOptions',
14279cc07651SZihao Chang  'base': {'type': 'DisplayReloadType'},
14289cc07651SZihao Chang  'discriminator': 'type',
14299cc07651SZihao Chang  'data': { 'vnc': 'DisplayReloadOptionsVNC' } }
14309cc07651SZihao Chang
14319cc07651SZihao Chang##
14329cc07651SZihao Chang# @display-reload:
14339cc07651SZihao Chang#
14349cc07651SZihao Chang# Reload display configuration.
14359cc07651SZihao Chang#
14369cc07651SZihao Chang# Returns: Nothing on success.
14379cc07651SZihao Chang#
14389cc07651SZihao Chang# Since: 6.0
14399cc07651SZihao Chang#
14409cc07651SZihao Chang# Example:
14419cc07651SZihao Chang#
14429cc07651SZihao Chang# -> { "execute": "display-reload",
14439cc07651SZihao Chang#      "arguments": { "type": "vnc", "tls-certs": true  } }
14449cc07651SZihao Chang# <- { "return": {} }
14459cc07651SZihao Chang#
14469cc07651SZihao Chang##
14479cc07651SZihao Chang{ 'command': 'display-reload',
14489cc07651SZihao Chang  'data': 'DisplayReloadOptions',
14499cc07651SZihao Chang  'boxed' : true }
1450