| blob | e5d6610b4aeae86749dcc72d9346fedc57377243 |
1 # -*- Mode: Python -*-
2 #
4 ##
5 # = Remote desktop
6 ##
8 { 'include': 'sockets.json' }
10 ##
11 # @set_password:
12 #
13 # Sets the password of a remote display session.
14 #
15 # @protocol: `vnc' to modify the VNC server password
16 # `spice' to modify the Spice server password
17 #
18 # @password: the new password
19 #
20 # @connected: how to handle existing clients when changing the
21 # password. If nothing is specified, defaults to `keep'
22 # `fail' to fail the command if clients are connected
23 # `disconnect' to disconnect existing clients
24 # `keep' to maintain existing clients
25 #
26 # Returns: Nothing on success
27 # If Spice is not enabled, DeviceNotFound
28 #
29 # Since: 0.14.0
30 #
31 # Example:
32 #
33 # -> { "execute": "set_password", "arguments": { "protocol": "vnc",
34 # "password": "secret" } }
35 # <- { "return": {} }
36 #
37 ##
38 { 'command': 'set_password',
39 'data': {'protocol': 'str', 'password': 'str', '*connected': 'str'} }
41 ##
42 # @expire_password:
43 #
44 # Expire the password of a remote display server.
45 #
46 # @protocol: the name of the remote display protocol `vnc' or `spice'
47 #
48 # @time: when to expire the password.
49 # `now' to expire the password immediately
50 # `never' to cancel password expiration
51 # `+INT' where INT is the number of seconds from now (integer)
52 # `INT' where INT is the absolute time in seconds
53 #
54 # Returns: Nothing on success
55 # If @protocol is `spice' and Spice is not active, DeviceNotFound
56 #
57 # Since: 0.14.0
58 #
59 # Notes: Time is relative to the server and currently there is no way to
60 # coordinate server time with client time. It is not recommended to
61 # use the absolute time version of the @time parameter unless you're
62 # sure you are on the same machine as the QEMU instance.
63 #
64 # Example:
65 #
66 # -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
67 # "time": "+60" } }
68 # <- { "return": {} }
69 #
70 ##
71 { 'command': 'expire_password', 'data': {'protocol': 'str', 'time': 'str'} }
73 ##
74 # @screendump:
75 #
76 # Write a PPM of the VGA screen to a file.
77 #
78 # @filename: the path of a new PPM file to store the image
79 #
80 # Returns: Nothing on success
81 #
82 # Since: 0.14.0
83 #
84 # Example:
85 #
86 # -> { "execute": "screendump",
87 # "arguments": { "filename": "/tmp/image" } }
88 # <- { "return": {} }
89 #
90 ##
91 { 'command': 'screendump', 'data': {'filename': 'str'} }
93 ##
94 # == Spice
95 ##
97 ##
98 # @SpiceBasicInfo:
99 #
100 # The basic information for SPICE network connection
101 #
102 # @host: IP address
103 #
104 # @port: port number
105 #
106 # @family: address family
107 #
108 # Since: 2.1
109 ##
110 { 'struct': 'SpiceBasicInfo',
111 'data': { 'host': 'str',
112 'port': 'str',
113 'family': 'NetworkAddressFamily' } }
115 ##
116 # @SpiceServerInfo:
117 #
118 # Information about a SPICE server
119 #
120 # @auth: authentication method
121 #
122 # Since: 2.1
123 ##
124 { 'struct': 'SpiceServerInfo',
125 'base': 'SpiceBasicInfo',
126 'data': { '*auth': 'str' } }
128 ##
129 # @SpiceChannel:
130 #
131 # Information about a SPICE client channel.
132 #
133 # @connection-id: SPICE connection id number. All channels with the same id
134 # belong to the same SPICE session.
135 #
136 # @channel-type: SPICE channel type number. "1" is the main control
137 # channel, filter for this one if you want to track spice
138 # sessions only
139 #
140 # @channel-id: SPICE channel ID number. Usually "0", might be different when
141 # multiple channels of the same type exist, such as multiple
142 # display channels in a multihead setup
143 #
144 # @tls: true if the channel is encrypted, false otherwise.
145 #
146 # Since: 0.14.0
147 ##
148 { 'struct': 'SpiceChannel',
149 'base': 'SpiceBasicInfo',
150 'data': {'connection-id': 'int', 'channel-type': 'int', 'channel-id': 'int',
151 'tls': 'bool'} }
153 ##
154 # @SpiceQueryMouseMode:
155 #
156 # An enumeration of Spice mouse states.
157 #
158 # @client: Mouse cursor position is determined by the client.
159 #
160 # @server: Mouse cursor position is determined by the server.
161 #
162 # @unknown: No information is available about mouse mode used by
163 # the spice server.
164 #
165 # Note: spice/enums.h has a SpiceMouseMode already, hence the name.
166 #
167 # Since: 1.1
168 ##
169 { 'enum': 'SpiceQueryMouseMode',
170 'data': [ 'client', 'server', 'unknown' ] }
172 ##
173 # @SpiceInfo:
174 #
175 # Information about the SPICE session.
176 #
177 # @enabled: true if the SPICE server is enabled, false otherwise
178 #
179 # @migrated: true if the last guest migration completed and spice
180 # migration had completed as well. false otherwise. (since 1.4)
181 #
182 # @host: The hostname the SPICE server is bound to. This depends on
183 # the name resolution on the host and may be an IP address.
184 #
185 # @port: The SPICE server's port number.
186 #
187 # @compiled-version: SPICE server version.
188 #
189 # @tls-port: The SPICE server's TLS port number.
190 #
191 # @auth: the current authentication type used by the server
192 # 'none' if no authentication is being used
193 # 'spice' uses SASL or direct TLS authentication, depending on command
194 # line options
195 #
196 # @mouse-mode: The mode in which the mouse cursor is displayed currently. Can
197 # be determined by the client or the server, or unknown if spice
198 # server doesn't provide this information. (since: 1.1)
199 #
200 # @channels: a list of @SpiceChannel for each active spice channel
201 #
202 # Since: 0.14.0
203 ##
204 { 'struct': 'SpiceInfo',
205 'data': {'enabled': 'bool', 'migrated': 'bool', '*host': 'str', '*port': 'int',
206 '*tls-port': 'int', '*auth': 'str', '*compiled-version': 'str',
207 'mouse-mode': 'SpiceQueryMouseMode', '*channels': ['SpiceChannel']} }
209 ##
210 # @query-spice:
211 #
212 # Returns information about the current SPICE server
213 #
214 # Returns: @SpiceInfo
215 #
216 # Since: 0.14.0
217 #
218 # Example:
219 #
220 # -> { "execute": "query-spice" }
221 # <- { "return": {
222 # "enabled": true,
223 # "auth": "spice",
224 # "port": 5920,
225 # "tls-port": 5921,
226 # "host": "0.0.0.0",
227 # "channels": [
228 # {
229 # "port": "54924",
230 # "family": "ipv4",
231 # "channel-type": 1,
232 # "connection-id": 1804289383,
233 # "host": "127.0.0.1",
234 # "channel-id": 0,
235 # "tls": true
236 # },
237 # {
238 # "port": "36710",
239 # "family": "ipv4",
240 # "channel-type": 4,
241 # "connection-id": 1804289383,
242 # "host": "127.0.0.1",
243 # "channel-id": 0,
244 # "tls": false
245 # },
246 # [ ... more channels follow ... ]
247 # ]
248 # }
249 # }
250 #
251 ##
252 { 'command': 'query-spice', 'returns': 'SpiceInfo' }
254 ##
255 # @SPICE_CONNECTED:
256 #
257 # Emitted when a SPICE client establishes a connection
258 #
259 # @server: server information
260 #
261 # @client: client information
262 #
263 # Since: 0.14.0
264 #
265 # Example:
266 #
267 # <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
268 # "event": "SPICE_CONNECTED",
269 # "data": {
270 # "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
271 # "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
272 # }}
273 #
274 ##
275 { 'event': 'SPICE_CONNECTED',
276 'data': { 'server': 'SpiceBasicInfo',
277 'client': 'SpiceBasicInfo' } }
279 ##
280 # @SPICE_INITIALIZED:
281 #
282 # Emitted after initial handshake and authentication takes place (if any)
283 # and the SPICE channel is up and running
284 #
285 # @server: server information
286 #
287 # @client: client information
288 #
289 # Since: 0.14.0
290 #
291 # Example:
292 #
293 # <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
294 # "event": "SPICE_INITIALIZED",
295 # "data": {"server": {"auth": "spice", "port": "5921",
296 # "family": "ipv4", "host": "127.0.0.1"},
297 # "client": {"port": "49004", "family": "ipv4", "channel-type": 3,
298 # "connection-id": 1804289383, "host": "127.0.0.1",
299 # "channel-id": 0, "tls": true}
300 # }}
301 #
302 ##
303 { 'event': 'SPICE_INITIALIZED',
304 'data': { 'server': 'SpiceServerInfo',
305 'client': 'SpiceChannel' } }
307 ##
308 # @SPICE_DISCONNECTED:
309 #
310 # Emitted when the SPICE connection is closed
311 #
312 # @server: server information
313 #
314 # @client: client information
315 #
316 # Since: 0.14.0
317 #
318 # Example:
319 #
320 # <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
321 # "event": "SPICE_DISCONNECTED",
322 # "data": {
323 # "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
324 # "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
325 # }}
326 #
327 ##
328 { 'event': 'SPICE_DISCONNECTED',
329 'data': { 'server': 'SpiceBasicInfo',
330 'client': 'SpiceBasicInfo' } }
332 ##
333 # @SPICE_MIGRATE_COMPLETED:
334 #
335 # Emitted when SPICE migration has completed
336 #
337 # Since: 1.3
338 #
339 # Example:
340 #
341 # <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
342 # "event": "SPICE_MIGRATE_COMPLETED" }
343 #
344 ##
345 { 'event': 'SPICE_MIGRATE_COMPLETED' }
347 ##
348 # == VNC
349 ##
351 ##
352 # @VncBasicInfo:
353 #
354 # The basic information for vnc network connection
355 #
356 # @host: IP address
357 #
358 # @service: The service name of the vnc port. This may depend on the host
359 # system's service database so symbolic names should not be relied
360 # on.
361 #
362 # @family: address family
363 #
364 # @websocket: true in case the socket is a websocket (since 2.3).
365 #
366 # Since: 2.1
367 ##
368 { 'struct': 'VncBasicInfo',
369 'data': { 'host': 'str',
370 'service': 'str',
371 'family': 'NetworkAddressFamily',
372 'websocket': 'bool' } }
374 ##
375 # @VncServerInfo:
376 #
377 # The network connection information for server
378 #
379 # @auth: authentication method used for
380 # the plain (non-websocket) VNC server
381 #
382 # Since: 2.1
383 ##
384 { 'struct': 'VncServerInfo',
385 'base': 'VncBasicInfo',
386 'data': { '*auth': 'str' } }
388 ##
389 # @VncClientInfo:
390 #
391 # Information about a connected VNC client.
392 #
393 # @x509_dname: If x509 authentication is in use, the Distinguished
394 # Name of the client.
395 #
396 # @sasl_username: If SASL authentication is in use, the SASL username
397 # used for authentication.
398 #
399 # Since: 0.14.0
400 ##
401 { 'struct': 'VncClientInfo',
402 'base': 'VncBasicInfo',
403 'data': { '*x509_dname': 'str', '*sasl_username': 'str' } }
405 ##
406 # @VncInfo:
407 #
408 # Information about the VNC session.
409 #
410 # @enabled: true if the VNC server is enabled, false otherwise
411 #
412 # @host: The hostname the VNC server is bound to. This depends on
413 # the name resolution on the host and may be an IP address.
414 #
415 # @family: 'ipv6' if the host is listening for IPv6 connections
416 # 'ipv4' if the host is listening for IPv4 connections
417 # 'unix' if the host is listening on a unix domain socket
418 # 'unknown' otherwise
419 #
420 # @service: The service name of the server's port. This may depends
421 # on the host system's service database so symbolic names should not
422 # be relied on.
423 #
424 # @auth: the current authentication type used by the server
425 # 'none' if no authentication is being used
426 # 'vnc' if VNC authentication is being used
427 # 'vencrypt+plain' if VEncrypt is used with plain text authentication
428 # 'vencrypt+tls+none' if VEncrypt is used with TLS and no authentication
429 # 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC authentication
430 # 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain text auth
431 # 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth
432 # 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth
433 # 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain text auth
434 # 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth
435 # 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL auth
436 #
437 # @clients: a list of @VncClientInfo of all currently connected clients
438 #
439 # Since: 0.14.0
440 ##
441 { 'struct': 'VncInfo',
442 'data': {'enabled': 'bool', '*host': 'str',
443 '*family': 'NetworkAddressFamily',
444 '*service': 'str', '*auth': 'str', '*clients': ['VncClientInfo']} }
446 ##
447 # @VncPrimaryAuth:
448 #
449 # vnc primary authentication method.
450 #
451 # Since: 2.3
452 ##
453 { 'enum': 'VncPrimaryAuth',
454 'data': [ 'none', 'vnc', 'ra2', 'ra2ne', 'tight', 'ultra',
455 'tls', 'vencrypt', 'sasl' ] }
457 ##
458 # @VncVencryptSubAuth:
459 #
460 # vnc sub authentication method with vencrypt.
461 #
462 # Since: 2.3
463 ##
464 { 'enum': 'VncVencryptSubAuth',
465 'data': [ 'plain',
466 'tls-none', 'x509-none',
467 'tls-vnc', 'x509-vnc',
468 'tls-plain', 'x509-plain',
469 'tls-sasl', 'x509-sasl' ] }
472 ##
473 # @VncServerInfo2:
474 #
475 # The network connection information for server
476 #
477 # @auth: The current authentication type used by the servers
478 #
479 # @vencrypt: The vencrypt sub authentication type used by the
480 # servers, only specified in case auth == vencrypt.
481 #
482 # Since: 2.9
483 ##
484 { 'struct': 'VncServerInfo2',
485 'base': 'VncBasicInfo',
486 'data': { 'auth' : 'VncPrimaryAuth',
487 '*vencrypt' : 'VncVencryptSubAuth' } }
490 ##
491 # @VncInfo2:
492 #
493 # Information about a vnc server
494 #
495 # @id: vnc server name.
496 #
497 # @server: A list of @VncBasincInfo describing all listening sockets.
498 # The list can be empty (in case the vnc server is disabled).
499 # It also may have multiple entries: normal + websocket,
500 # possibly also ipv4 + ipv6 in the future.
501 #
502 # @clients: A list of @VncClientInfo of all currently connected clients.
503 # The list can be empty, for obvious reasons.
504 #
505 # @auth: The current authentication type used by the non-websockets servers
506 #
507 # @vencrypt: The vencrypt authentication type used by the servers,
508 # only specified in case auth == vencrypt.
509 #
510 # @display: The display device the vnc server is linked to.
511 #
512 # Since: 2.3
513 ##
514 { 'struct': 'VncInfo2',
515 'data': { 'id' : 'str',
516 'server' : ['VncServerInfo2'],
517 'clients' : ['VncClientInfo'],
518 'auth' : 'VncPrimaryAuth',
519 '*vencrypt' : 'VncVencryptSubAuth',
520 '*display' : 'str' } }
522 ##
523 # @query-vnc:
524 #
525 # Returns information about the current VNC server
526 #
527 # Returns: @VncInfo
528 #
529 # Since: 0.14.0
530 #
531 # Example:
532 #
533 # -> { "execute": "query-vnc" }
534 # <- { "return": {
535 # "enabled":true,
536 # "host":"0.0.0.0",
537 # "service":"50402",
538 # "auth":"vnc",
539 # "family":"ipv4",
540 # "clients":[
541 # {
542 # "host":"127.0.0.1",
543 # "service":"50401",
544 # "family":"ipv4"
545 # }
546 # ]
547 # }
548 # }
549 #
550 ##
551 { 'command': 'query-vnc', 'returns': 'VncInfo' }
553 ##
554 # @query-vnc-servers:
555 #
556 # Returns a list of vnc servers. The list can be empty.
557 #
558 # Returns: a list of @VncInfo2
559 #
560 # Since: 2.3
561 ##
562 { 'command': 'query-vnc-servers', 'returns': ['VncInfo2'] }
564 ##
565 # @change-vnc-password:
566 #
567 # Change the VNC server password.
568 #
569 # @password: the new password to use with VNC authentication
570 #
571 # Since: 1.1
572 #
573 # Notes: An empty password in this command will set the password to the empty
574 # string. Existing clients are unaffected by executing this command.
575 ##
576 { 'command': 'change-vnc-password', 'data': {'password': 'str'} }
578 ##
579 # @VNC_CONNECTED:
580 #
581 # Emitted when a VNC client establishes a connection
582 #
583 # @server: server information
584 #
585 # @client: client information
586 #
587 # Note: This event is emitted before any authentication takes place, thus
588 # the authentication ID is not provided
589 #
590 # Since: 0.13.0
591 #
592 # Example:
593 #
594 # <- { "event": "VNC_CONNECTED",
595 # "data": {
596 # "server": { "auth": "sasl", "family": "ipv4",
597 # "service": "5901", "host": "0.0.0.0" },
598 # "client": { "family": "ipv4", "service": "58425",
599 # "host": "127.0.0.1" } },
600 # "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
601 #
602 ##
603 { 'event': 'VNC_CONNECTED',
604 'data': { 'server': 'VncServerInfo',
605 'client': 'VncBasicInfo' } }
607 ##
608 # @VNC_INITIALIZED:
609 #
610 # Emitted after authentication takes place (if any) and the VNC session is
611 # made active
612 #
613 # @server: server information
614 #
615 # @client: client information
616 #
617 # Since: 0.13.0
618 #
619 # Example:
620 #
621 # <- { "event": "VNC_INITIALIZED",
622 # "data": {
623 # "server": { "auth": "sasl", "family": "ipv4",
624 # "service": "5901", "host": "0.0.0.0"},
625 # "client": { "family": "ipv4", "service": "46089",
626 # "host": "127.0.0.1", "sasl_username": "luiz" } },
627 # "timestamp": { "seconds": 1263475302, "microseconds": 150772 } }
628 #
629 ##
630 { 'event': 'VNC_INITIALIZED',
631 'data': { 'server': 'VncServerInfo',
632 'client': 'VncClientInfo' } }
634 ##
635 # @VNC_DISCONNECTED:
636 #
637 # Emitted when the connection is closed
638 #
639 # @server: server information
640 #
641 # @client: client information
642 #
643 # Since: 0.13.0
644 #
645 # Example:
646 #
647 # <- { "event": "VNC_DISCONNECTED",
648 # "data": {
649 # "server": { "auth": "sasl", "family": "ipv4",
650 # "service": "5901", "host": "0.0.0.0" },
651 # "client": { "family": "ipv4", "service": "58425",
652 # "host": "127.0.0.1", "sasl_username": "luiz" } },
653 # "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
654 #
655 ##
656 { 'event': 'VNC_DISCONNECTED',
657 'data': { 'server': 'VncServerInfo',
658 'client': 'VncClientInfo' } }
660 ##
661 # = Input
662 ##
664 ##
665 # @MouseInfo:
666 #
667 # Information about a mouse device.
668 #
669 # @name: the name of the mouse device
670 #
671 # @index: the index of the mouse device
672 #
673 # @current: true if this device is currently receiving mouse events
674 #
675 # @absolute: true if this device supports absolute coordinates as input
676 #
677 # Since: 0.14.0
678 ##
679 { 'struct': 'MouseInfo',
680 'data': {'name': 'str', 'index': 'int', 'current': 'bool',
681 'absolute': 'bool'} }
683 ##
684 # @query-mice:
685 #
686 # Returns information about each active mouse device
687 #
688 # Returns: a list of @MouseInfo for each device
689 #
690 # Since: 0.14.0
691 #
692 # Example:
693 #
694 # -> { "execute": "query-mice" }
695 # <- { "return": [
696 # {
697 # "name":"QEMU Microsoft Mouse",
698 # "index":0,
699 # "current":false,
700 # "absolute":false
701 # },
702 # {
703 # "name":"QEMU PS/2 Mouse",
704 # "index":1,
705 # "current":true,
706 # "absolute":true
707 # }
708 # ]
709 # }
710 #
711 ##
712 { 'command': 'query-mice', 'returns': ['MouseInfo'] }
714 ##
715 # @QKeyCode:
716 #
717 # An enumeration of key name.
718 #
719 # This is used by the @send-key command.
720 #
721 # @unmapped: since 2.0
722 # @pause: since 2.0
723 # @ro: since 2.4
724 # @kp_comma: since 2.4
725 # @kp_equals: since 2.6
726 # @power: since 2.6
727 # @hiragana: since 2.9
728 # @henkan: since 2.9
729 # @yen: since 2.9
730 #
731 # @sleep: since 2.10
732 # @wake: since 2.10
733 # @audionext: since 2.10
734 # @audioprev: since 2.10
735 # @audiostop: since 2.10
736 # @audioplay: since 2.10
737 # @audiomute: since 2.10
738 # @volumeup: since 2.10
739 # @volumedown: since 2.10
740 # @mediaselect: since 2.10
741 # @mail: since 2.10
742 # @calculator: since 2.10
743 # @computer: since 2.10
744 # @ac_home: since 2.10
745 # @ac_back: since 2.10
746 # @ac_forward: since 2.10
747 # @ac_refresh: since 2.10
748 # @ac_bookmarks: since 2.10
749 # altgr, altgr_r: dropped in 2.10
750 #
751 # Since: 1.3.0
752 #
753 ##
754 { 'enum': 'QKeyCode',
755 'data': [ 'unmapped',
756 'shift', 'shift_r', 'alt', 'alt_r', 'ctrl',
757 'ctrl_r', 'menu', 'esc', '1', '2', '3', '4', '5', '6', '7', '8',
758 '9', '0', 'minus', 'equal', 'backspace', 'tab', 'q', 'w', 'e',
759 'r', 't', 'y', 'u', 'i', 'o', 'p', 'bracket_left', 'bracket_right',
760 'ret', 'a', 's', 'd', 'f', 'g', 'h', 'j', 'k', 'l', 'semicolon',
761 'apostrophe', 'grave_accent', 'backslash', 'z', 'x', 'c', 'v', 'b',
762 'n', 'm', 'comma', 'dot', 'slash', 'asterisk', 'spc', 'caps_lock',
763 'f1', 'f2', 'f3', 'f4', 'f5', 'f6', 'f7', 'f8', 'f9', 'f10',
764 'num_lock', 'scroll_lock', 'kp_divide', 'kp_multiply',
765 'kp_subtract', 'kp_add', 'kp_enter', 'kp_decimal', 'sysrq', 'kp_0',
766 'kp_1', 'kp_2', 'kp_3', 'kp_4', 'kp_5', 'kp_6', 'kp_7', 'kp_8',
767 'kp_9', 'less', 'f11', 'f12', 'print', 'home', 'pgup', 'pgdn', 'end',
768 'left', 'up', 'down', 'right', 'insert', 'delete', 'stop', 'again',
769 'props', 'undo', 'front', 'copy', 'open', 'paste', 'find', 'cut',
770 'lf', 'help', 'meta_l', 'meta_r', 'compose', 'pause',
771 'ro', 'hiragana', 'henkan', 'yen',
772 'kp_comma', 'kp_equals', 'power', 'sleep', 'wake',
773 'audionext', 'audioprev', 'audiostop', 'audioplay', 'audiomute',
774 'volumeup', 'volumedown', 'mediaselect',
775 'mail', 'calculator', 'computer',
776 'ac_home', 'ac_back', 'ac_forward', 'ac_refresh', 'ac_bookmarks' ] }
778 ##
779 # @KeyValue:
780 #
781 # Represents a keyboard key.
782 #
783 # Since: 1.3.0
784 ##
785 { 'union': 'KeyValue',
786 'data': {
787 'number': 'int',
788 'qcode': 'QKeyCode' } }
790 ##
791 # @send-key:
792 #
793 # Send keys to guest.
794 #
795 # @keys: An array of @KeyValue elements. All @KeyValues in this array are
796 # simultaneously sent to the guest. A @KeyValue.number value is sent
797 # directly to the guest, while @KeyValue.qcode must be a valid
798 # @QKeyCode value
799 #
800 # @hold-time: time to delay key up events, milliseconds. Defaults
801 # to 100
802 #
803 # Returns: Nothing on success
804 # If key is unknown or redundant, InvalidParameter
805 #
806 # Since: 1.3.0
807 #
808 # Example:
809 #
810 # -> { "execute": "send-key",
811 # "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
812 # { "type": "qcode", "data": "alt" },
813 # { "type": "qcode", "data": "delete" } ] } }
814 # <- { "return": {} }
815 #
816 ##
817 { 'command': 'send-key',
818 'data': { 'keys': ['KeyValue'], '*hold-time': 'int' } }
820 ##
821 # @InputButton:
822 #
823 # Button of a pointer input device (mouse, tablet).
824 #
825 # @side: front side button of a 5-button mouse (since 2.9)
826 #
827 # @extra: rear side button of a 5-button mouse (since 2.9)
828 #
829 # Since: 2.0
830 ##
831 { 'enum' : 'InputButton',
832 'data' : [ 'left', 'middle', 'right', 'wheel-up', 'wheel-down', 'side',
833 'extra' ] }
835 ##
836 # @InputAxis:
837 #
838 # Position axis of a pointer input device (mouse, tablet).
839 #
840 # Since: 2.0
841 ##
842 { 'enum' : 'InputAxis',
843 'data' : [ 'x', 'y' ] }
845 ##
846 # @InputKeyEvent:
847 #
848 # Keyboard input event.
849 #
850 # @key: Which key this event is for.
851 # @down: True for key-down and false for key-up events.
852 #
853 # Since: 2.0
854 ##
855 { 'struct' : 'InputKeyEvent',
856 'data' : { 'key' : 'KeyValue',
857 'down' : 'bool' } }
859 ##
860 # @InputBtnEvent:
861 #
862 # Pointer button input event.
863 #
864 # @button: Which button this event is for.
865 # @down: True for key-down and false for key-up events.
866 #
867 # Since: 2.0
868 ##
869 { 'struct' : 'InputBtnEvent',
870 'data' : { 'button' : 'InputButton',
871 'down' : 'bool' } }
873 ##
874 # @InputMoveEvent:
875 #
876 # Pointer motion input event.
877 #
878 # @axis: Which axis is referenced by @value.
879 # @value: Pointer position. For absolute coordinates the
880 # valid range is 0 -> 0x7ffff
881 #
882 # Since: 2.0
883 ##
884 { 'struct' : 'InputMoveEvent',
885 'data' : { 'axis' : 'InputAxis',
886 'value' : 'int' } }
888 ##
889 # @InputEvent:
890 #
891 # Input event union.
892 #
893 # @type: the input type, one of:
894 # - 'key': Input event of Keyboard
895 # - 'btn': Input event of pointer buttons
896 # - 'rel': Input event of relative pointer motion
897 # - 'abs': Input event of absolute pointer motion
898 #
899 # Since: 2.0
900 ##
901 { 'union' : 'InputEvent',
902 'data' : { 'key' : 'InputKeyEvent',
903 'btn' : 'InputBtnEvent',
904 'rel' : 'InputMoveEvent',
905 'abs' : 'InputMoveEvent' } }
907 ##
908 # @input-send-event:
909 #
910 # Send input event(s) to guest.
911 #
912 # @device: display device to send event(s) to.
913 # @head: head to send event(s) to, in case the
914 # display device supports multiple scanouts.
915 # @events: List of InputEvent union.
916 #
917 # Returns: Nothing on success.
918 #
919 # The @device and @head parameters can be used to send the input event
920 # to specific input devices in case (a) multiple input devices of the
921 # same kind are added to the virtual machine and (b) you have
922 # configured input routing (see docs/multiseat.txt) for those input
923 # devices. The parameters work exactly like the device and head
924 # properties of input devices. If @device is missing, only devices
925 # that have no input routing config are admissible. If @device is
926 # specified, both input devices with and without input routing config
927 # are admissible, but devices with input routing config take
928 # precedence.
929 #
930 # Since: 2.6
931 #
932 # Note: The consoles are visible in the qom tree, under
933 # /backend/console[$index]. They have a device link and head property,
934 # so it is possible to map which console belongs to which device and
935 # display.
936 #
937 # Example:
938 #
939 # 1. Press left mouse button.
940 #
941 # -> { "execute": "input-send-event",
942 # "arguments": { "device": "video0",
943 # "events": [ { "type": "btn",
944 # "data" : { "down": true, "button": "left" } } ] } }
945 # <- { "return": {} }
946 #
947 # -> { "execute": "input-send-event",
948 # "arguments": { "device": "video0",
949 # "events": [ { "type": "btn",
950 # "data" : { "down": false, "button": "left" } } ] } }
951 # <- { "return": {} }
952 #
953 # 2. Press ctrl-alt-del.
954 #
955 # -> { "execute": "input-send-event",
956 # "arguments": { "events": [
957 # { "type": "key", "data" : { "down": true,
958 # "key": {"type": "qcode", "data": "ctrl" } } },
959 # { "type": "key", "data" : { "down": true,
960 # "key": {"type": "qcode", "data": "alt" } } },
961 # { "type": "key", "data" : { "down": true,
962 # "key": {"type": "qcode", "data": "delete" } } } ] } }
963 # <- { "return": {} }
964 #
965 # 3. Move mouse pointer to absolute coordinates (20000, 400).
966 #
967 # -> { "execute": "input-send-event" ,
968 # "arguments": { "events": [
969 # { "type": "abs", "data" : { "axis": "x", "value" : 20000 } },
970 # { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } }
971 # <- { "return": {} }
972 #
973 ##
974 { 'command': 'input-send-event',
975 'data': { '*device': 'str',
976 '*head' : 'int',
977 'events' : [ 'InputEvent' ] } }