1# -*- Mode: Python -*- 2# vim: filetype=python 3# 4 5## 6# = Remote desktop 7## 8 9{ 'include': 'common.json' } 10{ 'include': 'sockets.json' } 11 12## 13# @DisplayProtocol: 14# 15# Display protocols which support changing password options. 16# 17# Since: 7.0 18# 19## 20{ 'enum': 'DisplayProtocol', 21 'data': [ 'vnc', 'spice' ] } 22 23## 24# @SetPasswordAction: 25# 26# An action to take on changing a password on a connection with active clients. 27# 28# @keep: maintain existing clients 29# 30# @fail: fail the command if clients are connected 31# 32# @disconnect: disconnect existing clients 33# 34# Since: 7.0 35# 36## 37{ 'enum': 'SetPasswordAction', 38 'data': [ 'keep', 'fail', 'disconnect' ] } 39 40## 41# @SetPasswordOptions: 42# 43# Options for set_password. 44# 45# @protocol: - 'vnc' to modify the VNC server password 46# - 'spice' to modify the Spice server password 47# 48# @password: the new password 49# 50# @connected: How to handle existing clients when changing the 51# password. If nothing is specified, defaults to 'keep'. 52# For VNC, only 'keep' is currently implemented. 53# 54# Since: 7.0 55# 56## 57{ 'union': 'SetPasswordOptions', 58 'base': { 'protocol': 'DisplayProtocol', 59 'password': 'str', 60 '*connected': 'SetPasswordAction' }, 61 'discriminator': 'protocol', 62 'data': { 'vnc': 'SetPasswordOptionsVnc' } } 63 64## 65# @SetPasswordOptionsVnc: 66# 67# Options for set_password specific to the VNC procotol. 68# 69# @display: The id of the display where the password should be changed. 70# Defaults to the first. 71# 72# Since: 7.0 73# 74## 75{ 'struct': 'SetPasswordOptionsVnc', 76 'data': { '*display': 'str' } } 77 78## 79# @set_password: 80# 81# Set the password of a remote display server. 82# 83# Returns: - Nothing on success 84# - If Spice is not enabled, DeviceNotFound 85# 86# Since: 0.14 87# 88# Example: 89# 90# -> { "execute": "set_password", "arguments": { "protocol": "vnc", 91# "password": "secret" } } 92# <- { "return": {} } 93# 94## 95{ 'command': 'set_password', 'boxed': true, 'data': 'SetPasswordOptions' } 96 97## 98# @ExpirePasswordOptions: 99# 100# General options for expire_password. 101# 102# @protocol: - 'vnc' to modify the VNC server expiration 103# - 'spice' to modify the Spice server expiration 104# 105# @time: when to expire the password. 106# 107# - 'now' to expire the password immediately 108# - 'never' to cancel password expiration 109# - '+INT' where INT is the number of seconds from now (integer) 110# - 'INT' where INT is the absolute time in seconds 111# 112# Notes: Time is relative to the server and currently there is no way to 113# coordinate server time with client time. It is not recommended to 114# use the absolute time version of the @time parameter unless you're 115# sure you are on the same machine as the QEMU instance. 116# 117# Since: 7.0 118# 119## 120{ 'union': 'ExpirePasswordOptions', 121 'base': { 'protocol': 'DisplayProtocol', 122 'time': 'str' }, 123 'discriminator': 'protocol', 124 'data': { 'vnc': 'ExpirePasswordOptionsVnc' } } 125 126## 127# @ExpirePasswordOptionsVnc: 128# 129# Options for expire_password specific to the VNC procotol. 130# 131# @display: The id of the display where the expiration should be changed. 132# Defaults to the first. 133# 134# Since: 7.0 135# 136## 137 138{ 'struct': 'ExpirePasswordOptionsVnc', 139 'data': { '*display': 'str' } } 140 141## 142# @expire_password: 143# 144# Expire the password of a remote display server. 145# 146# Returns: - Nothing on success 147# - If @protocol is 'spice' and Spice is not active, DeviceNotFound 148# 149# Since: 0.14 150# 151# Example: 152# 153# -> { "execute": "expire_password", "arguments": { "protocol": "vnc", 154# "time": "+60" } } 155# <- { "return": {} } 156# 157## 158{ 'command': 'expire_password', 'boxed': true, 'data': 'ExpirePasswordOptions' } 159 160## 161# @screendump: 162# 163# Write a PPM of the VGA screen to a file. 164# 165# @filename: the path of a new PPM file to store the image 166# 167# @device: ID of the display device that should be dumped. If this parameter 168# is missing, the primary display will be used. (Since 2.12) 169# 170# @head: head to use in case the device supports multiple heads. If this 171# parameter is missing, head #0 will be used. Also note that the head 172# can only be specified in conjunction with the device ID. (Since 2.12) 173# 174# Returns: Nothing on success 175# 176# Since: 0.14 177# 178# Example: 179# 180# -> { "execute": "screendump", 181# "arguments": { "filename": "/tmp/image" } } 182# <- { "return": {} } 183# 184## 185{ 'command': 'screendump', 186 'data': {'filename': 'str', '*device': 'str', '*head': 'int'}, 187 'coroutine': true } 188 189## 190# == Spice 191## 192 193## 194# @SpiceBasicInfo: 195# 196# The basic information for SPICE network connection 197# 198# @host: IP address 199# 200# @port: port number 201# 202# @family: address family 203# 204# Since: 2.1 205## 206{ 'struct': 'SpiceBasicInfo', 207 'data': { 'host': 'str', 208 'port': 'str', 209 'family': 'NetworkAddressFamily' }, 210 'if': 'CONFIG_SPICE' } 211 212## 213# @SpiceServerInfo: 214# 215# Information about a SPICE server 216# 217# @auth: authentication method 218# 219# Since: 2.1 220## 221{ 'struct': 'SpiceServerInfo', 222 'base': 'SpiceBasicInfo', 223 'data': { '*auth': 'str' }, 224 'if': 'CONFIG_SPICE' } 225 226## 227# @SpiceChannel: 228# 229# Information about a SPICE client channel. 230# 231# @connection-id: SPICE connection id number. All channels with the same id 232# belong to the same SPICE session. 233# 234# @channel-type: SPICE channel type number. "1" is the main control 235# channel, filter for this one if you want to track spice 236# sessions only 237# 238# @channel-id: SPICE channel ID number. Usually "0", might be different when 239# multiple channels of the same type exist, such as multiple 240# display channels in a multihead setup 241# 242# @tls: true if the channel is encrypted, false otherwise. 243# 244# Since: 0.14 245## 246{ 'struct': 'SpiceChannel', 247 'base': 'SpiceBasicInfo', 248 'data': {'connection-id': 'int', 'channel-type': 'int', 'channel-id': 'int', 249 'tls': 'bool'}, 250 'if': 'CONFIG_SPICE' } 251 252## 253# @SpiceQueryMouseMode: 254# 255# An enumeration of Spice mouse states. 256# 257# @client: Mouse cursor position is determined by the client. 258# 259# @server: Mouse cursor position is determined by the server. 260# 261# @unknown: No information is available about mouse mode used by 262# the spice server. 263# 264# Note: spice/enums.h has a SpiceMouseMode already, hence the name. 265# 266# Since: 1.1 267## 268{ 'enum': 'SpiceQueryMouseMode', 269 'data': [ 'client', 'server', 'unknown' ], 270 'if': 'CONFIG_SPICE' } 271 272## 273# @SpiceInfo: 274# 275# Information about the SPICE session. 276# 277# @enabled: true if the SPICE server is enabled, false otherwise 278# 279# @migrated: true if the last guest migration completed and spice 280# migration had completed as well. false otherwise. (since 1.4) 281# 282# @host: The hostname the SPICE server is bound to. This depends on 283# the name resolution on the host and may be an IP address. 284# 285# @port: The SPICE server's port number. 286# 287# @compiled-version: SPICE server version. 288# 289# @tls-port: The SPICE server's TLS port number. 290# 291# @auth: the current authentication type used by the server 292# 293# - 'none' if no authentication is being used 294# - 'spice' uses SASL or direct TLS authentication, depending on command 295# line options 296# 297# @mouse-mode: The mode in which the mouse cursor is displayed currently. Can 298# be determined by the client or the server, or unknown if spice 299# server doesn't provide this information. (since: 1.1) 300# 301# @channels: a list of @SpiceChannel for each active spice channel 302# 303# Since: 0.14 304## 305{ 'struct': 'SpiceInfo', 306 'data': {'enabled': 'bool', 'migrated': 'bool', '*host': 'str', '*port': 'int', 307 '*tls-port': 'int', '*auth': 'str', '*compiled-version': 'str', 308 'mouse-mode': 'SpiceQueryMouseMode', '*channels': ['SpiceChannel']}, 309 'if': 'CONFIG_SPICE' } 310 311## 312# @query-spice: 313# 314# Returns information about the current SPICE server 315# 316# Returns: @SpiceInfo 317# 318# Since: 0.14 319# 320# Example: 321# 322# -> { "execute": "query-spice" } 323# <- { "return": { 324# "enabled": true, 325# "auth": "spice", 326# "port": 5920, 327# "migrated":false, 328# "tls-port": 5921, 329# "host": "0.0.0.0", 330# "mouse-mode":"client", 331# "channels": [ 332# { 333# "port": "54924", 334# "family": "ipv4", 335# "channel-type": 1, 336# "connection-id": 1804289383, 337# "host": "127.0.0.1", 338# "channel-id": 0, 339# "tls": true 340# }, 341# { 342# "port": "36710", 343# "family": "ipv4", 344# "channel-type": 4, 345# "connection-id": 1804289383, 346# "host": "127.0.0.1", 347# "channel-id": 0, 348# "tls": false 349# }, 350# [ ... more channels follow ... ] 351# ] 352# } 353# } 354# 355## 356{ 'command': 'query-spice', 'returns': 'SpiceInfo', 357 'if': 'CONFIG_SPICE' } 358 359## 360# @SPICE_CONNECTED: 361# 362# Emitted when a SPICE client establishes a connection 363# 364# @server: server information 365# 366# @client: client information 367# 368# Since: 0.14 369# 370# Example: 371# 372# <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707}, 373# "event": "SPICE_CONNECTED", 374# "data": { 375# "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"}, 376# "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"} 377# }} 378# 379## 380{ 'event': 'SPICE_CONNECTED', 381 'data': { 'server': 'SpiceBasicInfo', 382 'client': 'SpiceBasicInfo' }, 383 'if': 'CONFIG_SPICE' } 384 385## 386# @SPICE_INITIALIZED: 387# 388# Emitted after initial handshake and authentication takes place (if any) 389# and the SPICE channel is up and running 390# 391# @server: server information 392# 393# @client: client information 394# 395# Since: 0.14 396# 397# Example: 398# 399# <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172}, 400# "event": "SPICE_INITIALIZED", 401# "data": {"server": {"auth": "spice", "port": "5921", 402# "family": "ipv4", "host": "127.0.0.1"}, 403# "client": {"port": "49004", "family": "ipv4", "channel-type": 3, 404# "connection-id": 1804289383, "host": "127.0.0.1", 405# "channel-id": 0, "tls": true} 406# }} 407# 408## 409{ 'event': 'SPICE_INITIALIZED', 410 'data': { 'server': 'SpiceServerInfo', 411 'client': 'SpiceChannel' }, 412 'if': 'CONFIG_SPICE' } 413 414## 415# @SPICE_DISCONNECTED: 416# 417# Emitted when the SPICE connection is closed 418# 419# @server: server information 420# 421# @client: client information 422# 423# Since: 0.14 424# 425# Example: 426# 427# <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707}, 428# "event": "SPICE_DISCONNECTED", 429# "data": { 430# "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"}, 431# "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"} 432# }} 433# 434## 435{ 'event': 'SPICE_DISCONNECTED', 436 'data': { 'server': 'SpiceBasicInfo', 437 'client': 'SpiceBasicInfo' }, 438 'if': 'CONFIG_SPICE' } 439 440## 441# @SPICE_MIGRATE_COMPLETED: 442# 443# Emitted when SPICE migration has completed 444# 445# Since: 1.3 446# 447# Example: 448# 449# <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172}, 450# "event": "SPICE_MIGRATE_COMPLETED" } 451# 452## 453{ 'event': 'SPICE_MIGRATE_COMPLETED', 454 'if': 'CONFIG_SPICE' } 455 456## 457# == VNC 458## 459 460## 461# @VncBasicInfo: 462# 463# The basic information for vnc network connection 464# 465# @host: IP address 466# 467# @service: The service name of the vnc port. This may depend on the host 468# system's service database so symbolic names should not be relied 469# on. 470# 471# @family: address family 472# 473# @websocket: true in case the socket is a websocket (since 2.3). 474# 475# Since: 2.1 476## 477{ 'struct': 'VncBasicInfo', 478 'data': { 'host': 'str', 479 'service': 'str', 480 'family': 'NetworkAddressFamily', 481 'websocket': 'bool' }, 482 'if': 'CONFIG_VNC' } 483 484## 485# @VncServerInfo: 486# 487# The network connection information for server 488# 489# @auth: authentication method used for 490# the plain (non-websocket) VNC server 491# 492# Since: 2.1 493## 494{ 'struct': 'VncServerInfo', 495 'base': 'VncBasicInfo', 496 'data': { '*auth': 'str' }, 497 'if': 'CONFIG_VNC' } 498 499## 500# @VncClientInfo: 501# 502# Information about a connected VNC client. 503# 504# @x509_dname: If x509 authentication is in use, the Distinguished 505# Name of the client. 506# 507# @sasl_username: If SASL authentication is in use, the SASL username 508# used for authentication. 509# 510# Since: 0.14 511## 512{ 'struct': 'VncClientInfo', 513 'base': 'VncBasicInfo', 514 'data': { '*x509_dname': 'str', '*sasl_username': 'str' }, 515 'if': 'CONFIG_VNC' } 516 517## 518# @VncInfo: 519# 520# Information about the VNC session. 521# 522# @enabled: true if the VNC server is enabled, false otherwise 523# 524# @host: The hostname the VNC server is bound to. This depends on 525# the name resolution on the host and may be an IP address. 526# 527# @family: - 'ipv6' if the host is listening for IPv6 connections 528# - 'ipv4' if the host is listening for IPv4 connections 529# - 'unix' if the host is listening on a unix domain socket 530# - 'unknown' otherwise 531# 532# @service: The service name of the server's port. This may depends 533# on the host system's service database so symbolic names should not 534# be relied on. 535# 536# @auth: the current authentication type used by the server 537# 538# - 'none' if no authentication is being used 539# - 'vnc' if VNC authentication is being used 540# - 'vencrypt+plain' if VEncrypt is used with plain text authentication 541# - 'vencrypt+tls+none' if VEncrypt is used with TLS and no authentication 542# - 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC authentication 543# - 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain text auth 544# - 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth 545# - 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth 546# - 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain text auth 547# - 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth 548# - 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL auth 549# 550# @clients: a list of @VncClientInfo of all currently connected clients 551# 552# Since: 0.14 553## 554{ 'struct': 'VncInfo', 555 'data': {'enabled': 'bool', '*host': 'str', 556 '*family': 'NetworkAddressFamily', 557 '*service': 'str', '*auth': 'str', '*clients': ['VncClientInfo']}, 558 'if': 'CONFIG_VNC' } 559 560## 561# @VncPrimaryAuth: 562# 563# vnc primary authentication method. 564# 565# Since: 2.3 566## 567{ 'enum': 'VncPrimaryAuth', 568 'data': [ 'none', 'vnc', 'ra2', 'ra2ne', 'tight', 'ultra', 569 'tls', 'vencrypt', 'sasl' ], 570 'if': 'CONFIG_VNC' } 571 572## 573# @VncVencryptSubAuth: 574# 575# vnc sub authentication method with vencrypt. 576# 577# Since: 2.3 578## 579{ 'enum': 'VncVencryptSubAuth', 580 'data': [ 'plain', 581 'tls-none', 'x509-none', 582 'tls-vnc', 'x509-vnc', 583 'tls-plain', 'x509-plain', 584 'tls-sasl', 'x509-sasl' ], 585 'if': 'CONFIG_VNC' } 586 587## 588# @VncServerInfo2: 589# 590# The network connection information for server 591# 592# @auth: The current authentication type used by the servers 593# 594# @vencrypt: The vencrypt sub authentication type used by the 595# servers, only specified in case auth == vencrypt. 596# 597# Since: 2.9 598## 599{ 'struct': 'VncServerInfo2', 600 'base': 'VncBasicInfo', 601 'data': { 'auth' : 'VncPrimaryAuth', 602 '*vencrypt' : 'VncVencryptSubAuth' }, 603 'if': 'CONFIG_VNC' } 604 605## 606# @VncInfo2: 607# 608# Information about a vnc server 609# 610# @id: vnc server name. 611# 612# @server: A list of @VncBasincInfo describing all listening sockets. 613# The list can be empty (in case the vnc server is disabled). 614# It also may have multiple entries: normal + websocket, 615# possibly also ipv4 + ipv6 in the future. 616# 617# @clients: A list of @VncClientInfo of all currently connected clients. 618# The list can be empty, for obvious reasons. 619# 620# @auth: The current authentication type used by the non-websockets servers 621# 622# @vencrypt: The vencrypt authentication type used by the servers, 623# only specified in case auth == vencrypt. 624# 625# @display: The display device the vnc server is linked to. 626# 627# Since: 2.3 628## 629{ 'struct': 'VncInfo2', 630 'data': { 'id' : 'str', 631 'server' : ['VncServerInfo2'], 632 'clients' : ['VncClientInfo'], 633 'auth' : 'VncPrimaryAuth', 634 '*vencrypt' : 'VncVencryptSubAuth', 635 '*display' : 'str' }, 636 'if': 'CONFIG_VNC' } 637 638## 639# @query-vnc: 640# 641# Returns information about the current VNC server 642# 643# Returns: @VncInfo 644# 645# Since: 0.14 646# 647# Example: 648# 649# -> { "execute": "query-vnc" } 650# <- { "return": { 651# "enabled":true, 652# "host":"0.0.0.0", 653# "service":"50402", 654# "auth":"vnc", 655# "family":"ipv4", 656# "clients":[ 657# { 658# "host":"127.0.0.1", 659# "service":"50401", 660# "family":"ipv4" 661# "websocket":false, 662# } 663# ] 664# } 665# } 666# 667## 668{ 'command': 'query-vnc', 'returns': 'VncInfo', 669 'if': 'CONFIG_VNC' } 670## 671# @query-vnc-servers: 672# 673# Returns a list of vnc servers. The list can be empty. 674# 675# Returns: a list of @VncInfo2 676# 677# Since: 2.3 678## 679{ 'command': 'query-vnc-servers', 'returns': ['VncInfo2'], 680 'if': 'CONFIG_VNC' } 681 682## 683# @change-vnc-password: 684# 685# Change the VNC server password. 686# 687# @password: the new password to use with VNC authentication 688# 689# Since: 1.1 690# 691# Notes: An empty password in this command will set the password to the empty 692# string. Existing clients are unaffected by executing this command. 693## 694{ 'command': 'change-vnc-password', 695 'data': { 'password': 'str' }, 696 'if': 'CONFIG_VNC' } 697 698## 699# @VNC_CONNECTED: 700# 701# Emitted when a VNC client establishes a connection 702# 703# @server: server information 704# 705# @client: client information 706# 707# Note: This event is emitted before any authentication takes place, thus 708# the authentication ID is not provided 709# 710# Since: 0.13 711# 712# Example: 713# 714# <- { "event": "VNC_CONNECTED", 715# "data": { 716# "server": { "auth": "sasl", "family": "ipv4", "websocket": false, 717# "service": "5901", "host": "0.0.0.0" }, 718# "client": { "family": "ipv4", "service": "58425", 719# "host": "127.0.0.1", "websocket": false } }, 720# "timestamp": { "seconds": 1262976601, "microseconds": 975795 } } 721# 722## 723{ 'event': 'VNC_CONNECTED', 724 'data': { 'server': 'VncServerInfo', 725 'client': 'VncBasicInfo' }, 726 'if': 'CONFIG_VNC' } 727 728## 729# @VNC_INITIALIZED: 730# 731# Emitted after authentication takes place (if any) and the VNC session is 732# made active 733# 734# @server: server information 735# 736# @client: client information 737# 738# Since: 0.13 739# 740# Example: 741# 742# <- { "event": "VNC_INITIALIZED", 743# "data": { 744# "server": { "auth": "sasl", "family": "ipv4", "websocket": false, 745# "service": "5901", "host": "0.0.0.0"}, 746# "client": { "family": "ipv4", "service": "46089", "websocket": false, 747# "host": "127.0.0.1", "sasl_username": "luiz" } }, 748# "timestamp": { "seconds": 1263475302, "microseconds": 150772 } } 749# 750## 751{ 'event': 'VNC_INITIALIZED', 752 'data': { 'server': 'VncServerInfo', 753 'client': 'VncClientInfo' }, 754 'if': 'CONFIG_VNC' } 755 756## 757# @VNC_DISCONNECTED: 758# 759# Emitted when the connection is closed 760# 761# @server: server information 762# 763# @client: client information 764# 765# Since: 0.13 766# 767# Example: 768# 769# <- { "event": "VNC_DISCONNECTED", 770# "data": { 771# "server": { "auth": "sasl", "family": "ipv4", "websocket": false, 772# "service": "5901", "host": "0.0.0.0" }, 773# "client": { "family": "ipv4", "service": "58425", "websocket": false, 774# "host": "127.0.0.1", "sasl_username": "luiz" } }, 775# "timestamp": { "seconds": 1262976601, "microseconds": 975795 } } 776# 777## 778{ 'event': 'VNC_DISCONNECTED', 779 'data': { 'server': 'VncServerInfo', 780 'client': 'VncClientInfo' }, 781 'if': 'CONFIG_VNC' } 782 783## 784# = Input 785## 786 787## 788# @MouseInfo: 789# 790# Information about a mouse device. 791# 792# @name: the name of the mouse device 793# 794# @index: the index of the mouse device 795# 796# @current: true if this device is currently receiving mouse events 797# 798# @absolute: true if this device supports absolute coordinates as input 799# 800# Since: 0.14 801## 802{ 'struct': 'MouseInfo', 803 'data': {'name': 'str', 'index': 'int', 'current': 'bool', 804 'absolute': 'bool'} } 805 806## 807# @query-mice: 808# 809# Returns information about each active mouse device 810# 811# Returns: a list of @MouseInfo for each device 812# 813# Since: 0.14 814# 815# Example: 816# 817# -> { "execute": "query-mice" } 818# <- { "return": [ 819# { 820# "name":"QEMU Microsoft Mouse", 821# "index":0, 822# "current":false, 823# "absolute":false 824# }, 825# { 826# "name":"QEMU PS/2 Mouse", 827# "index":1, 828# "current":true, 829# "absolute":true 830# } 831# ] 832# } 833# 834## 835{ 'command': 'query-mice', 'returns': ['MouseInfo'] } 836 837## 838# @QKeyCode: 839# 840# An enumeration of key name. 841# 842# This is used by the @send-key command. 843# 844# @unmapped: since 2.0 845# @pause: since 2.0 846# @ro: since 2.4 847# @kp_comma: since 2.4 848# @kp_equals: since 2.6 849# @power: since 2.6 850# @hiragana: since 2.9 851# @henkan: since 2.9 852# @yen: since 2.9 853# 854# @sleep: since 2.10 855# @wake: since 2.10 856# @audionext: since 2.10 857# @audioprev: since 2.10 858# @audiostop: since 2.10 859# @audioplay: since 2.10 860# @audiomute: since 2.10 861# @volumeup: since 2.10 862# @volumedown: since 2.10 863# @mediaselect: since 2.10 864# @mail: since 2.10 865# @calculator: since 2.10 866# @computer: since 2.10 867# @ac_home: since 2.10 868# @ac_back: since 2.10 869# @ac_forward: since 2.10 870# @ac_refresh: since 2.10 871# @ac_bookmarks: since 2.10 872# 873# @muhenkan: since 2.12 874# @katakanahiragana: since 2.12 875# 876# @lang1: since 6.1 877# @lang2: since 6.1 878# 879# 'sysrq' was mistakenly added to hack around the fact that 880# the ps2 driver was not generating correct scancodes sequences 881# when 'alt+print' was pressed. This flaw is now fixed and the 882# 'sysrq' key serves no further purpose. Any further use of 883# 'sysrq' will be transparently changed to 'print', so they 884# are effectively synonyms. 885# 886# Since: 1.3 887# 888## 889{ 'enum': 'QKeyCode', 890 'data': [ 'unmapped', 891 'shift', 'shift_r', 'alt', 'alt_r', 'ctrl', 892 'ctrl_r', 'menu', 'esc', '1', '2', '3', '4', '5', '6', '7', '8', 893 '9', '0', 'minus', 'equal', 'backspace', 'tab', 'q', 'w', 'e', 894 'r', 't', 'y', 'u', 'i', 'o', 'p', 'bracket_left', 'bracket_right', 895 'ret', 'a', 's', 'd', 'f', 'g', 'h', 'j', 'k', 'l', 'semicolon', 896 'apostrophe', 'grave_accent', 'backslash', 'z', 'x', 'c', 'v', 'b', 897 'n', 'm', 'comma', 'dot', 'slash', 'asterisk', 'spc', 'caps_lock', 898 'f1', 'f2', 'f3', 'f4', 'f5', 'f6', 'f7', 'f8', 'f9', 'f10', 899 'num_lock', 'scroll_lock', 'kp_divide', 'kp_multiply', 900 'kp_subtract', 'kp_add', 'kp_enter', 'kp_decimal', 'sysrq', 'kp_0', 901 'kp_1', 'kp_2', 'kp_3', 'kp_4', 'kp_5', 'kp_6', 'kp_7', 'kp_8', 902 'kp_9', 'less', 'f11', 'f12', 'print', 'home', 'pgup', 'pgdn', 'end', 903 'left', 'up', 'down', 'right', 'insert', 'delete', 'stop', 'again', 904 'props', 'undo', 'front', 'copy', 'open', 'paste', 'find', 'cut', 905 'lf', 'help', 'meta_l', 'meta_r', 'compose', 'pause', 906 'ro', 'hiragana', 'henkan', 'yen', 'muhenkan', 'katakanahiragana', 907 'kp_comma', 'kp_equals', 'power', 'sleep', 'wake', 908 'audionext', 'audioprev', 'audiostop', 'audioplay', 'audiomute', 909 'volumeup', 'volumedown', 'mediaselect', 910 'mail', 'calculator', 'computer', 911 'ac_home', 'ac_back', 'ac_forward', 'ac_refresh', 'ac_bookmarks', 912 'lang1', 'lang2' ] } 913 914## 915# @KeyValueKind: 916# 917# Since: 1.3 918## 919{ 'enum': 'KeyValueKind', 920 'data': [ 'number', 'qcode' ] } 921 922## 923# @IntWrapper: 924# 925# Since: 1.3 926## 927{ 'struct': 'IntWrapper', 928 'data': { 'data': 'int' } } 929 930## 931# @QKeyCodeWrapper: 932# 933# Since: 1.3 934## 935{ 'struct': 'QKeyCodeWrapper', 936 'data': { 'data': 'QKeyCode' } } 937 938## 939# @KeyValue: 940# 941# Represents a keyboard key. 942# 943# Since: 1.3 944## 945{ 'union': 'KeyValue', 946 'base': { 'type': 'KeyValueKind' }, 947 'discriminator': 'type', 948 'data': { 949 'number': 'IntWrapper', 950 'qcode': 'QKeyCodeWrapper' } } 951 952## 953# @send-key: 954# 955# Send keys to guest. 956# 957# @keys: An array of @KeyValue elements. All @KeyValues in this array are 958# simultaneously sent to the guest. A @KeyValue.number value is sent 959# directly to the guest, while @KeyValue.qcode must be a valid 960# @QKeyCode value 961# 962# @hold-time: time to delay key up events, milliseconds. Defaults 963# to 100 964# 965# Returns: - Nothing on success 966# - If key is unknown or redundant, InvalidParameter 967# 968# Since: 1.3 969# 970# Example: 971# 972# -> { "execute": "send-key", 973# "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" }, 974# { "type": "qcode", "data": "alt" }, 975# { "type": "qcode", "data": "delete" } ] } } 976# <- { "return": {} } 977# 978## 979{ 'command': 'send-key', 980 'data': { 'keys': ['KeyValue'], '*hold-time': 'int' } } 981 982## 983# @InputButton: 984# 985# Button of a pointer input device (mouse, tablet). 986# 987# @side: front side button of a 5-button mouse (since 2.9) 988# 989# @extra: rear side button of a 5-button mouse (since 2.9) 990# 991# Since: 2.0 992## 993{ 'enum' : 'InputButton', 994 'data' : [ 'left', 'middle', 'right', 'wheel-up', 'wheel-down', 'side', 995 'extra', 'wheel-left', 'wheel-right' ] } 996 997## 998# @InputAxis: 999# 1000# Position axis of a pointer input device (mouse, tablet). 1001# 1002# Since: 2.0 1003## 1004{ 'enum' : 'InputAxis', 1005 'data' : [ 'x', 'y' ] } 1006 1007## 1008# @InputKeyEvent: 1009# 1010# Keyboard input event. 1011# 1012# @key: Which key this event is for. 1013# @down: True for key-down and false for key-up events. 1014# 1015# Since: 2.0 1016## 1017{ 'struct' : 'InputKeyEvent', 1018 'data' : { 'key' : 'KeyValue', 1019 'down' : 'bool' } } 1020 1021## 1022# @InputBtnEvent: 1023# 1024# Pointer button input event. 1025# 1026# @button: Which button this event is for. 1027# @down: True for key-down and false for key-up events. 1028# 1029# Since: 2.0 1030## 1031{ 'struct' : 'InputBtnEvent', 1032 'data' : { 'button' : 'InputButton', 1033 'down' : 'bool' } } 1034 1035## 1036# @InputMoveEvent: 1037# 1038# Pointer motion input event. 1039# 1040# @axis: Which axis is referenced by @value. 1041# @value: Pointer position. For absolute coordinates the 1042# valid range is 0 -> 0x7ffff 1043# 1044# Since: 2.0 1045## 1046{ 'struct' : 'InputMoveEvent', 1047 'data' : { 'axis' : 'InputAxis', 1048 'value' : 'int' } } 1049 1050## 1051# @InputEventKind: 1052# 1053# Since: 2.0 1054## 1055{ 'enum': 'InputEventKind', 1056 'data': [ 'key', 'btn', 'rel', 'abs' ] } 1057 1058## 1059# @InputKeyEventWrapper: 1060# 1061# Since: 2.0 1062## 1063{ 'struct': 'InputKeyEventWrapper', 1064 'data': { 'data': 'InputKeyEvent' } } 1065 1066## 1067# @InputBtnEventWrapper: 1068# 1069# Since: 2.0 1070## 1071{ 'struct': 'InputBtnEventWrapper', 1072 'data': { 'data': 'InputBtnEvent' } } 1073 1074## 1075# @InputMoveEventWrapper: 1076# 1077# Since: 2.0 1078## 1079{ 'struct': 'InputMoveEventWrapper', 1080 'data': { 'data': 'InputMoveEvent' } } 1081 1082## 1083# @InputEvent: 1084# 1085# Input event union. 1086# 1087# @type: the input type, one of: 1088# 1089# - 'key': Input event of Keyboard 1090# - 'btn': Input event of pointer buttons 1091# - 'rel': Input event of relative pointer motion 1092# - 'abs': Input event of absolute pointer motion 1093# 1094# Since: 2.0 1095## 1096{ 'union' : 'InputEvent', 1097 'base': { 'type': 'InputEventKind' }, 1098 'discriminator': 'type', 1099 'data' : { 'key' : 'InputKeyEventWrapper', 1100 'btn' : 'InputBtnEventWrapper', 1101 'rel' : 'InputMoveEventWrapper', 1102 'abs' : 'InputMoveEventWrapper' } } 1103 1104## 1105# @input-send-event: 1106# 1107# Send input event(s) to guest. 1108# 1109# The @device and @head parameters can be used to send the input event 1110# to specific input devices in case (a) multiple input devices of the 1111# same kind are added to the virtual machine and (b) you have 1112# configured input routing (see docs/multiseat.txt) for those input 1113# devices. The parameters work exactly like the device and head 1114# properties of input devices. If @device is missing, only devices 1115# that have no input routing config are admissible. If @device is 1116# specified, both input devices with and without input routing config 1117# are admissible, but devices with input routing config take 1118# precedence. 1119# 1120# @device: display device to send event(s) to. 1121# @head: head to send event(s) to, in case the 1122# display device supports multiple scanouts. 1123# @events: List of InputEvent union. 1124# 1125# Returns: Nothing on success. 1126# 1127# Since: 2.6 1128# 1129# Note: The consoles are visible in the qom tree, under 1130# /backend/console[$index]. They have a device link and head property, 1131# so it is possible to map which console belongs to which device and 1132# display. 1133# 1134# Example: 1135# 1136# 1. Press left mouse button. 1137# 1138# -> { "execute": "input-send-event", 1139# "arguments": { "device": "video0", 1140# "events": [ { "type": "btn", 1141# "data" : { "down": true, "button": "left" } } ] } } 1142# <- { "return": {} } 1143# 1144# -> { "execute": "input-send-event", 1145# "arguments": { "device": "video0", 1146# "events": [ { "type": "btn", 1147# "data" : { "down": false, "button": "left" } } ] } } 1148# <- { "return": {} } 1149# 1150# 2. Press ctrl-alt-del. 1151# 1152# -> { "execute": "input-send-event", 1153# "arguments": { "events": [ 1154# { "type": "key", "data" : { "down": true, 1155# "key": {"type": "qcode", "data": "ctrl" } } }, 1156# { "type": "key", "data" : { "down": true, 1157# "key": {"type": "qcode", "data": "alt" } } }, 1158# { "type": "key", "data" : { "down": true, 1159# "key": {"type": "qcode", "data": "delete" } } } ] } } 1160# <- { "return": {} } 1161# 1162# 3. Move mouse pointer to absolute coordinates (20000, 400). 1163# 1164# -> { "execute": "input-send-event" , 1165# "arguments": { "events": [ 1166# { "type": "abs", "data" : { "axis": "x", "value" : 20000 } }, 1167# { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } } 1168# <- { "return": {} } 1169# 1170## 1171{ 'command': 'input-send-event', 1172 'data': { '*device': 'str', 1173 '*head' : 'int', 1174 'events' : [ 'InputEvent' ] } } 1175 1176## 1177# @DisplayGTK: 1178# 1179# GTK display options. 1180# 1181# @grab-on-hover: Grab keyboard input on mouse hover. 1182# @zoom-to-fit: Zoom guest display to fit into the host window. When 1183# turned off the host window will be resized instead. 1184# In case the display device can notify the guest on 1185# window resizes (virtio-gpu) this will default to "on", 1186# assuming the guest will resize the display to match 1187# the window size then. Otherwise it defaults to "off". 1188# Since 3.1 1189# 1190# Since: 2.12 1191# 1192## 1193{ 'struct' : 'DisplayGTK', 1194 'data' : { '*grab-on-hover' : 'bool', 1195 '*zoom-to-fit' : 'bool' } } 1196 1197## 1198# @DisplayEGLHeadless: 1199# 1200# EGL headless display options. 1201# 1202# @rendernode: Which DRM render node should be used. Default is the first 1203# available node on the host. 1204# 1205# Since: 3.1 1206# 1207## 1208{ 'struct' : 'DisplayEGLHeadless', 1209 'data' : { '*rendernode' : 'str' } } 1210 1211## 1212# @DisplayDBus: 1213# 1214# DBus display options. 1215# 1216# @addr: The D-Bus bus address (default to the session bus). 1217# 1218# @rendernode: Which DRM render node should be used. Default is the first 1219# available node on the host. 1220# 1221# @p2p: Whether to use peer-to-peer connections (accepted through 1222# ``add_client``). 1223# 1224# @audiodev: Use the specified DBus audiodev to export audio. 1225# 1226# Since: 7.0 1227# 1228## 1229{ 'struct' : 'DisplayDBus', 1230 'data' : { '*rendernode' : 'str', 1231 '*addr': 'str', 1232 '*p2p': 'bool', 1233 '*audiodev': 'str' } } 1234 1235 ## 1236 # @DisplayGLMode: 1237 # 1238 # Display OpenGL mode. 1239 # 1240 # @off: Disable OpenGL (default). 1241 # @on: Use OpenGL, pick context type automatically. 1242 # Would better be named 'auto' but is called 'on' for backward 1243 # compatibility with bool type. 1244 # @core: Use OpenGL with Core (desktop) Context. 1245 # @es: Use OpenGL with ES (embedded systems) Context. 1246 # 1247 # Since: 3.0 1248 # 1249 ## 1250{ 'enum' : 'DisplayGLMode', 1251 'data' : [ 'off', 'on', 'core', 'es' ] } 1252 1253## 1254# @DisplayCurses: 1255# 1256# Curses display options. 1257# 1258# @charset: Font charset used by guest (default: CP437). 1259# 1260# Since: 4.0 1261# 1262## 1263{ 'struct' : 'DisplayCurses', 1264 'data' : { '*charset' : 'str' } } 1265 1266## 1267# @DisplayCocoa: 1268# 1269# Cocoa display options. 1270# 1271# @left-command-key: Enable/disable forwarding of left command key to 1272# guest. Allows command-tab window switching on the 1273# host without sending this key to the guest when 1274# "off". Defaults to "on" 1275# 1276# @full-grab: Capture all key presses, including system combos. This 1277# requires accessibility permissions, since it performs 1278# a global grab on key events. (default: off) 1279# See https://support.apple.com/en-in/guide/mac-help/mh32356/mac 1280# 1281# @swap-opt-cmd: Swap the Option and Command keys so that their key codes match 1282# their position on non-Mac keyboards and you can use Meta/Super 1283# and Alt where you expect them. (default: off) 1284# 1285# Since: 7.0 1286## 1287{ 'struct': 'DisplayCocoa', 1288 'data': { 1289 '*left-command-key': 'bool', 1290 '*full-grab': 'bool', 1291 '*swap-opt-cmd': 'bool' 1292 } } 1293 1294## 1295# @DisplayType: 1296# 1297# Display (user interface) type. 1298# 1299# @default: The default user interface, selecting from the first available 1300# of gtk, sdl, cocoa, and vnc. 1301# 1302# @none: No user interface or video output display. The guest will 1303# still see an emulated graphics card, but its output will not 1304# be displayed to the QEMU user. 1305# 1306# @gtk: The GTK user interface. 1307# 1308# @sdl: The SDL user interface. 1309# 1310# @egl-headless: No user interface, offload GL operations to a local 1311# DRI device. Graphical display need to be paired with 1312# VNC or Spice. (Since 3.1) 1313# 1314# @curses: Display video output via curses. For graphics device 1315# models which support a text mode, QEMU can display this 1316# output using a curses/ncurses interface. Nothing is 1317# displayed when the graphics device is in graphical mode or 1318# if the graphics device does not support a text 1319# mode. Generally only the VGA device models support text 1320# mode. 1321# 1322# @cocoa: The Cocoa user interface. 1323# 1324# @spice-app: Set up a Spice server and run the default associated 1325# application to connect to it. The server will redirect 1326# the serial console and QEMU monitors. (Since 4.0) 1327# 1328# @dbus: Start a D-Bus service for the display. (Since 7.0) 1329# 1330# Since: 2.12 1331# 1332## 1333{ 'enum' : 'DisplayType', 1334 'data' : [ 1335 { 'name': 'default' }, 1336 { 'name': 'none' }, 1337 { 'name': 'gtk', 'if': 'CONFIG_GTK' }, 1338 { 'name': 'sdl', 'if': 'CONFIG_SDL' }, 1339 { 'name': 'egl-headless', 1340 'if': { 'all': ['CONFIG_OPENGL', 'CONFIG_GBM'] } }, 1341 { 'name': 'curses', 'if': 'CONFIG_CURSES' }, 1342 { 'name': 'cocoa', 'if': 'CONFIG_COCOA' }, 1343 { 'name': 'spice-app', 'if': 'CONFIG_SPICE' }, 1344 { 'name': 'dbus', 'if': 'CONFIG_DBUS_DISPLAY' } 1345 ] 1346} 1347 1348## 1349# @DisplayOptions: 1350# 1351# Display (user interface) options. 1352# 1353# @type: Which DisplayType qemu should use. 1354# @full-screen: Start user interface in fullscreen mode (default: off). 1355# @window-close: Allow to quit qemu with window close button (default: on). 1356# @show-cursor: Force showing the mouse cursor (default: off). 1357# (since: 5.0) 1358# @gl: Enable OpenGL support (default: off). 1359# 1360# Since: 2.12 1361# 1362## 1363{ 'union' : 'DisplayOptions', 1364 'base' : { 'type' : 'DisplayType', 1365 '*full-screen' : 'bool', 1366 '*window-close' : 'bool', 1367 '*show-cursor' : 'bool', 1368 '*gl' : 'DisplayGLMode' }, 1369 'discriminator' : 'type', 1370 'data' : { 1371 'gtk': { 'type': 'DisplayGTK', 'if': 'CONFIG_GTK' }, 1372 'cocoa': { 'type': 'DisplayCocoa', 'if': 'CONFIG_COCOA' }, 1373 'curses': { 'type': 'DisplayCurses', 'if': 'CONFIG_CURSES' }, 1374 'egl-headless': { 'type': 'DisplayEGLHeadless', 1375 'if': { 'all': ['CONFIG_OPENGL', 'CONFIG_GBM'] } }, 1376 'dbus': { 'type': 'DisplayDBus', 'if': 'CONFIG_DBUS_DISPLAY' } 1377 } 1378} 1379 1380## 1381# @query-display-options: 1382# 1383# Returns information about display configuration 1384# 1385# Returns: @DisplayOptions 1386# 1387# Since: 3.1 1388# 1389## 1390{ 'command': 'query-display-options', 1391 'returns': 'DisplayOptions' } 1392 1393## 1394# @DisplayReloadType: 1395# 1396# Available DisplayReload types. 1397# 1398# @vnc: VNC display 1399# 1400# Since: 6.0 1401# 1402## 1403{ 'enum': 'DisplayReloadType', 1404 'data': ['vnc'] } 1405 1406## 1407# @DisplayReloadOptionsVNC: 1408# 1409# Specify the VNC reload options. 1410# 1411# @tls-certs: reload tls certs or not. 1412# 1413# Since: 6.0 1414# 1415## 1416{ 'struct': 'DisplayReloadOptionsVNC', 1417 'data': { '*tls-certs': 'bool' } } 1418 1419## 1420# @DisplayReloadOptions: 1421# 1422# Options of the display configuration reload. 1423# 1424# @type: Specify the display type. 1425# 1426# Since: 6.0 1427# 1428## 1429{ 'union': 'DisplayReloadOptions', 1430 'base': {'type': 'DisplayReloadType'}, 1431 'discriminator': 'type', 1432 'data': { 'vnc': 'DisplayReloadOptionsVNC' } } 1433 1434## 1435# @display-reload: 1436# 1437# Reload display configuration. 1438# 1439# Returns: Nothing on success. 1440# 1441# Since: 6.0 1442# 1443# Example: 1444# 1445# -> { "execute": "display-reload", 1446# "arguments": { "type": "vnc", "tls-certs": true } } 1447# <- { "return": {} } 1448# 1449## 1450{ 'command': 'display-reload', 1451 'data': 'DisplayReloadOptions', 1452 'boxed' : true } 1453